refactor(cli): move CLI head dispatch into src/cli/root.ts

[Wibias]

Summary

• Phase 1 of the CLI deepening: moved the CLI head (version/help early exits, ocx ready pre-parse with exit 64, and the Codex-shim auto-restore preflight) from src/cli/index.ts into the new src/cli/root.ts.
• parseCliHead is pure (no I/O, no process access), so head ordering and the single-parse contract are unit-testable without subprocesses. runCli owns the exit paths and shim preflight, then returns the dispatchable head; the command switch stays in src/cli/index.ts.
• Behavior is unchanged: two independent reviews compared 18 argv forms — including ocx <cmd> --help, ocx help <sub>, ready --help, and invalid ready → exit 64 — and found identical exit codes and help text vs the pre-change head.

Verification

• bun run typecheck — pass (exit 0)
• bun test tests/cli-head.test.ts tests/cli-ready.test.ts tests/cli-help.test.ts — 74 pass / 0 fail
• bun run privacy:scan — pass
• bun test tests/repo-hygiene.test.ts — 11 pass
• Behavior parity — 18 argv forms, identical exit codes and help text vs pre-change head, verified by two independent reviews.

Review notes

• Review focus: parseCliHead ordering (help/version exits before the ready pre-parse, pre-parse before the shim preflight) and the single-parse contract. The source-level P1 guards in tests/cli-ready.test.ts were relocated to pin the new src/cli/root.ts head.
• No GUI, docs, or release-note changes: internal refactor with no user-visible behavior change.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed.
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults.

Summary by CodeRabbit

• New Features

  • Improved command-line startup handling for version, help, and command dispatch.
  • Added support for targeting help for specific subcommands.
  • Added safer handling of ready command arguments, including validation before execution.

• Bug Fixes

  • Invalid ready arguments now fail safely with exit code 64 without performing I/O.

• Tests

  • Added coverage for CLI parsing, help behavior, command dispatch, and readiness validation.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 4e9c6e01-a080-4b5e-a73e-ae22ba5bdc54

📥 Commits

Reviewing files that changed from the base of the PR and between 4b34a55 and 2c9694d.

📒 Files selected for processing (1)

• tests/cli-head.test.ts

---

📝 Walkthrough

Walkthrough

The CLI now delegates argument classification, help and version exits, ready validation, and Codex-shim restoration to runCli. Command dispatch receives the returned state, including pre-parsed readyArgs.

Changes

CLI orchestration

Layer / File(s)	Summary
CLI head contract and parsing src/cli/root.ts, tests/cli-head.test.ts	Adds CliHead and parseCliHead. The parser handles version, help, subcommand help, command help flags, valid and invalid ready arguments, and ordinary commands.
Preflight and command dispatch src/cli/root.ts, src/cli/index.ts, tests/cli-ready.test.ts	Adds runCli orchestration. It performs exits and fail-closed validation before auto-restore, then returns dispatch state. index.ts awaits runCli and uses stashed readyArgs for the readiness handler. Tests verify ordering and single parsing.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLIIndex
  participant runCli
  participant parseCliHead
  participant CodexShimRestore
  participant ReadyHandler
  CLIIndex->>runCli: argv
  runCli->>parseCliHead: classify argv
  parseCliHead-->>runCli: CliHead with readyArgs
  runCli->>CodexShimRestore: auto-restore
  CodexShimRestore-->>runCli: completion
  runCli-->>CLIIndex: dispatch state
  CLIIndex->>ReadyHandler: handleReady(readyArgs)

Loading

Possibly related PRs

• lidge-jun/opencodex#359: Modifies src/cli/index.ts and changes ready handling and command argument forwarding.
• lidge-jun/opencodex#568: Adds the opencode command through shared CLI dispatch logic.
• lidge-jun/opencodex#569: Changes ready argument parsing and dispatch in src/cli/index.ts.

Suggested reviewers: ingwannu, lidge-jun

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes moving CLI head dispatch into the new src/cli/root.ts module.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/cli-deepening

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/cli-head.test.ts`:
- Around line 37-50: Extend the existing “help flag after position 0” test
around parseCliHead to also assert that parseCliHead(["sync", "help"]) returns
the help result for command “sync”, preserving the matching args and helpTarget
values. Keep the new regression assertion alongside the existing --help and -h
cases.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 92717d41-d61c-43dc-b0ad-559e78ec5de9

📥 Commits

Reviewing files that changed from the base of the PR and between 8ab41d3 and 4b34a55.

📒 Files selected for processing (4)

• src/cli/index.ts
• src/cli/root.ts
• tests/cli-head.test.ts
• tests/cli-ready.test.ts

[Ingwannu]

The Phase 1 extraction is directionally sound: the version/help exits, ready pre-parse, and shim preflight preserve the original ordering, and I did not find a behavioral change in the current diff.

I am not approving the current head yet for two state reasons:

• the branch is 33 commits behind current dev (7779c0574), so the exact integration result has not been reviewed;
• the Linux shard failed before normal completion with Bun 1.3.14 EEXIST: file already exists, epoll_ctl, followed by after-test-run errors. This appears to be a Bun/runtime failure rather than a CLI assertion, but required CI is still red.

Please rebase #1444 onto current dev, then refresh stacked #1446 and rerun exact-head CI. I will re-review the rebased parent rather than asking for a product-code change based on this infrastructure failure.