refactor(cli): fold internal-dispatch and pin help banner

[Wibias]

Summary

Fold the internal CLI dispatcher and pin the help banner to the registry.

• Fold internal-dispatch.ts: the three internal runners (__tray-start, __tray-restart, __startup-health) are now explicit entries in src/cli/dispatch.ts that use the injected deps directly. Deletes src/cli/internal-dispatch.ts and its dedicated test.
• Pin the help banner: adds a banner-coverage test to tests/cli-registry.test.ts asserting every visible registry command appears in the printUsage banner, and fixes the drift it caught — route, logs, and api-key were visible commands missing from the banner and are now listed.

Behavior is unchanged except the banner now lists those three previously-omitted commands.

Verification

• bun run typecheck — exit 0.
• CLI-focused suite — 144 pass; the only 4 failures are the known pre-existing cli-restore-back (2) and POST /api/sync ownership (2) environmental cases.
• ocx --version — exit 0.
• ocx help nosuch — exit 1, Unknown command.
• ocx ready --timeout 5 — exit 64.
• ocx --help — contains opencodex (ocx), ocx route, ocx logs, ocx api-key, exit 0.
• No remaining references to internal-dispatch in src/ or tests/.

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): stacks on #1455 (codex/cli-exit). Does not target dev. Diff is only the internal-dispatch fold + banner pin (300c9cda..e897d990): 5 files, +61/−72. Merge only after #1444, #1446, #1451, #1455 land.

Summary by CodeRabbit

• New Features

  • Added help entries for the route, logs, usage, storage, memory, and api-key commands, including aliases and descriptions.
  • Updated CLI usage information to include all visible commands.

• Bug Fixes

  • Improved handling of tray startup, restart, and startup health-check operations.
  • Ensured internal commands remain hidden from standard command listings.
  • Improved validation that visible commands appear consistently in CLI help output.

[coderabbitai]

📝 Walkthrough

Walkthrough

The CLI removes the internal dispatcher, inlines tray and startup-health runners, adds help entries for route, logs, usage, storage, memory, and api-key, and expands registry tests for hidden runners and visible help coverage.

Changes

CLI dispatch and help alignment

Layer / File(s)	Summary
Explicit internal command runners src/cli/dispatch.ts, src/cli/internal-dispatch.ts, tests/internal-cli-dispatch.test.ts	Registry runners now execute tray start, tray restart, and startup-health logic directly. The internal dispatcher and its dedicated tests are removed.
Registry and help validation src/cli/help.ts, tests/cli-registry.test.ts	Help now documents route, logs, usage, storage, memory, and api-key. Tests verify hidden internal runners and visible canonical command coverage.

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

Possibly related PRs

• lidge-jun/opencodex#306: Introduced the internal dispatcher that this PR removes.
• lidge-jun/opencodex#1446: Introduced the registry and help architecture extended here.
• lidge-jun/opencodex#1451: Modified the registry-driven dispatch implementation updated here.

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 summarizes the two main changes: removing internal dispatch and adding stable CLI help banner coverage.
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-help

---

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.

[coderabbitai]

Actionable comments posted: 2

🤖 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 `@src/cli/dispatch.ts`:
- Around line 319-321: Update the "__tray-start" command handler to use the
boolean result from deps.handleTrayProxyStart() when determining the command
status, returning a nonzero status when it returns false and preserving success
when startup succeeds.

In `@tests/cli-registry.test.ts`:
- Around line 121-123: Update the coverage check in the test’s help-source
matching logic to recognize a command only when `ocx <canonical-name>` appears
at the start of a banner line, while retaining the full `entry.usage` match.
Escape `entry.name` before constructing the regular expression so command names
cannot alter the pattern.

🪄 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: 8a1c1759-6eba-4bdd-8863-d3ef1177873c

📥 Commits

Reviewing files that changed from the base of the PR and between 316f675 and f9865ea.

📒 Files selected for processing (5)

• src/cli/dispatch.ts
• src/cli/help.ts
• src/cli/internal-dispatch.ts
• tests/cli-registry.test.ts
• tests/internal-cli-dispatch.test.ts

💤 Files with no reviewable changes (2)

• src/cli/internal-dispatch.ts
• tests/internal-cli-dispatch.test.ts

[coderabbitai]

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)

tests/cli-registry.test.ts (1)

81-95: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add a focused regression test for the __tray-start exit status.

This new block checks registry parity only. It does not execute commandRunners["__tray-start"]. The changed runner in src/cli/dispatch.ts Line 320 maps false from deps.handleTrayProxyStart() to status 1. Add a Bun test that asserts the failure path returns 1 and the success path returns 0. This protects the corrected exit-code contract after the dedicated internal-dispatch test was removed.

As per path instructions, a behavior change in src/ should have a focused regression test near the existing tests for that subsystem.

🤖 Prompt for 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.

In `@tests/cli-registry.test.ts` around lines 81 - 95, Add a focused Bun
regression test near the existing CLI dispatch tests that invokes
commandRunners["__tray-start"] with mocked deps.handleTrayProxyStart results.
Assert the runner returns status 1 when the handler returns false and status 0
when it returns true, preserving the corrected exit-code contract.

Source: Path instructions

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

Outside diff comments:
In `@tests/cli-registry.test.ts`:
- Around line 81-95: Add a focused Bun regression test near the existing CLI
dispatch tests that invokes commandRunners["__tray-start"] with mocked
deps.handleTrayProxyStart results. Assert the runner returns status 1 when the
handler returns false and status 0 when it returns true, preserving the
corrected exit-code contract.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 5a84942d-bbba-4421-81c2-384cd07c6e22

📥 Commits

Reviewing files that changed from the base of the PR and between f9865ea and 3cd51f8.

📒 Files selected for processing (3)

• src/cli/dispatch.ts
• src/cli/help.ts
• tests/cli-registry.test.ts