Refactor: Extract headless runner from create-expert CLI

[FL4TLiN3]

Summary

• Extract headless execution logic to src/lib/headless-runner.ts (159 lines)
• Reduce CLI file size from 377 to 230 lines (39% reduction)
• CLI now only handles argument parsing and validation
• Enable unit testing of headless execution logic

Closes #344

Test plan

• pnpm typecheck passes
• pnpm test passes
• pnpm build succeeds
• Headless mode works correctly: npx create-expert --headless --description "test"

🤖 Generated with Claude Code

---

Note

Refactors headless mode into a reusable module and simplifies the CLI.

• New src/lib/headless-runner.ts encapsulates headless execution: spawns perstack run, supports JSON vs human-readable output, parses events, aggregates result/errors, and returns a structured status
• bin/cli.ts now focuses on arg parsing/validation, project generation for new projects, query construction, and delegates execution to runHeadlessExecution; exits based on returned success
• Exposes runHeadlessExecution and its types via src/index.ts
• Reduces CLI size and enables unit testing of headless logic

^{Written by Cursor Bugbot for commit e10a126. This will update automatically on new commits. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cursor]

Inconsistent exitCode returned between JSON and non-JSON modes

The exitCode field in HeadlessRunnerResult behaves inconsistently between code paths. When jsonOutput is true, the actual process exit code is returned. When jsonOutput is false, the value is normalized to 0 or 1 via failed ? 1 : 0. This means the same API returns different data depending on the output mode. Additionally, the log at line 145 displays the actual exit code while the returned result contains a different normalized value, creating a debugging mismatch.

Additional Locations (1)

• apps/create-expert/src/lib/headless-runner.ts#L42-L43

 

[cursor]

JSON mode no longer preserves actual process exit codes

The original JSON mode used process.exit(code || 0) which preserved actual non-zero exit codes from the child process (e.g., 137 for OOM kills). After the refactoring, the CLI does process.exit(result.success ? 0 : 1), which normalizes all failures to exit code 1. Users relying on specific exit codes to detect different failure modes (such as signal-killed processes or specific error conditions) will now always receive 1 for any failure.