refactor(cli): registry-driven command dispatch module

[Wibias]

Summary

Extract command dispatch out of the entry module into a registry-driven runner table.

• Adds src/cli/dispatch.ts: dispatchCommand(head, deps) replaces the 61-case switch in src/cli/index.ts. Each command is a runner keyed by name; aliases (setup/eject/remove/model) resolve through the registry alias map.
• src/cli/index.ts becomes a thin main: it runs the head, then calls dispatchCommand with its local lifecycle helpers (handleStart, handleStop, handleEnsure, handleStatus, handleReady, …) passed as CliDispatchDeps.
• Source-level tests that read switch cases were migrated to read dispatch.ts (cli-registry, cli-ready, grok-lifecycle, stale-state-purge, update*, uninstall, windows-deploy-*, codex-retained-root-serialization).

Behavior is preserved: the restore, sync, sync-cache, claude, route, integration, health, ready, gui, codex-shim, and update runners match their original case bodies, including exit codes and the --help short-circuit.

Verification

• bun run typecheck — exit 0.
• CLI-focused suite — 211 pass; the only 4 failures are the known pre-existing cli-restore-back (2) and POST /api/sync Task Scheduler (2) cases, proven identical on clean upstream/dev and unrelated to this change.
• ocx --version — opencodex 2.10.2, exit 0.
• ocx help nosuch — exit 1, Unknown command: nosuch.
• ocx ready --timeout 5 — exit 64.
• ocx sync --help — Usage: ocx sync …, exit 0.

No GUI changes; no screenshot required.

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.

---

Review notes (stacked PR): this PR stacks on #1446 (codex/cli-registry). It does not target dev. The diff here is only the dispatch extraction (7feb16c42..0bb19e1e): 11 files, +585/−513. Merge only after #1444 and #1446 land; the base will be retargeted then.

Summary by CodeRabbit

• New Features

  • Expanded CLI command handling across lifecycle, integrations, maintenance, GUI, service, authentication, diagnostics, and background operations.
  • Added command aliases and consistent help and unknown-command handling.
  • Improved command reliability with structured errors, exit codes, health checks, and startup validation.

• Bug Fixes

  • Improved synchronization, restoration, update notifications, restart behavior, and GUI-related command flows.

• Tests

  • Updated CLI coverage to validate command registration, alias resolution, dispatch ordering, and regression scenarios.

[coderabbitai]

Note

Currently processing new changes in this PR. This may take a few minutes, please wait...

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 473cf018-8063-47e2-b881-b9db0963aae7

📥 Commits

Reviewing files that changed from the base of the PR and between 38c9b35 and 46b18f0.

📒 Files selected for processing (12)

• src/cli/dispatch.ts
• src/cli/index.ts
• tests/cli-ready.test.ts
• tests/cli-registry.test.ts
• tests/codex-app-server-processes.test.ts
• tests/codex-retained-root-serialization.test.ts
• tests/grok-lifecycle.test.ts
• tests/stale-state-purge.test.ts
• tests/uninstall.test.ts
• tests/update-notify.test.ts
• tests/update-stop-first.test.ts
• tests/windows-deploy-close-regressions.test.ts

 ________________________________________________________________
< KōdoUsagi Gundam is my Japanese cousin. He's a bit more mecha. >
 ----------------------------------------------------------------
  \
   \   (\__/)
       (•ㅅ•)
       / 　 づ

✨ 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-dispatch

---

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.}

[github-actions]

✅ Deterministic PR hygiene checks passed.

[Ingwannu]

I am deferring the content review because the stack no longer has reviewable ancestry after the root rewrite.

Current state:

• #1446 now has head 35628105 on current dev@87e3ff9f.
• #1451's head cb952c07 is 6 commits ahead and 8 behind that new base; GitHub reports mergeable: false, mergeable_state: dirty, and rebaseable: false.
• #1455, #1456, and #1457 are stacked on the old #1451 lineage. Their previously green jobs therefore do not validate the stack that would actually land after the #1446 rewrite.
• The new exact-head #1446 run is currently red in Linux shard 3 and macOS (with shard 4 still running at the time of review). #1457's old run also ended red because the aggregate test job was cancelled after shard 3 hit the 15-minute bound. Those failures should not be “fixed” on stale child heads.

Please rebuild the stack sequentially: rebase #1451 onto the current #1446 head, then #1455 onto the new #1451 head, #1456 onto the new #1455 head, and #1457 onto the new #1456 head. Resolve the root exact-head CI failure first, then rerun CI on every resulting child head. Once ancestry is linear and the exact commits are green, request review again; reviewing the current diverged diff would mostly review code that the rebase will discard or rewrite.