refactor(codex-manager): dispatch through a command registry (phase 2) - #535

Summary

Phase 2 of the codex-manager.ts decomposition — audit roadmap §4.1.1 (docs/audits/AUDIT_2026-06-10.md, PR #522): the if (command === …) dispatch chains become a CLI_COMMAND_HANDLERS: ReadonlyMap<string, CliCommandHandler> registry. Zero behavior change; the extensive CLI suites are the safety net (811 passing).

Stacked on #525 (formatter extraction, phase 1) — merge that first; this PR then shows only the registry commit.

Design

• type CliCommandHandler = (rest: string[]) => number | Promise<number> — rest is the parsed argument tail, the return is the exit code. No heavier context object was needed.
• The registry lives in codex-manager.ts, not a separate module: every handler closure-captures module-scope deps (persistAndSyncSelectedAccount, runAuthLogin, repair-deps factory, traced selection, storage fns); an adjacent file would have meant exporting ~30 internals from the entrypoint and inviting a cycle.
• 28 keys = 27 commands + 1 alias (status/list share a handler), exactly matching ACCOUNT_MANAGER_COMMANDS (the routing test asserts alignment).

Dispatch quirks preserved exactly

• auth-prefix compatibility rewrite; default subcommand login; --help/-h short-circuits ahead of registry lookup; non-auth root → usage + exit 1
• --json/-j detection inside the shared list/status handler; nested config/debug sub-dispatch with their exact unknown-subcommand stderr + exit 1
• Unknown command → stderr + usage + exit 1; repair deps still constructed per dispatch, not at module load
• No order-shadowing existed in the chains, so the map is semantically identical

Validation

• npm run typecheck; eslint --max-warnings=0
• All 63 suites matching codex-manager/runCodexMultiAuthCli: 811 passed, 6 skipped, 3 failed — the 3 are the known Windows-path environment cases, identical on the base branch
• Independently re-verified: codex-manager-cli + codex-routing, 205/205

Risk / Rollback

Dispatch-only refactor (+38 lines net, from registry doc comments); handler bodies untouched. Revert the single commit. Phase 3 (moving remaining handler bodies into commands/) follows the roadmap.

https://claude.ai/code/session_01XNtnkLbBiXZxfQQYLMpucB

Generated by Claude Code

note: greptile review for oc-chatgpt-multi-auth. cite files like lib/foo.ts:123. confirm regression tests + windows concurrency/token redaction coverage.

Greptile Summary

phase 2 of the codex-manager.ts decomposition: the if (command === …) dispatch chain (~200 lines) is replaced by a CLI_COMMAND_HANDLERS: ReadonlyMap<string, CliCommandHandler> with 28 entries, and the formatter helpers extracted in phase 1 are moved into lib/codex-manager/formatters/ with a new vitest suite covering the newly-public contracts.

• CLI_COMMAND_HANDLERS map mirrors all 27 commands + 1 alias exactly; per-dispatch factories (createRepairCommandDeps, buildSelectAccountTraced) remain lazy inside handler closures, preserving the original evaluation order.
• Four formatter modules (text-style, quota-formatters, model-formatters, account-formatters) and a barrel index.ts promote previously-private helpers to exported symbols; codex-manager.ts re-exports only the two symbols that had prior external consumers.
• test/codex-manager-formatters.test.ts adds unit contracts for the extracted helpers, including edge cases for cyclic log args, clamped quota percentages, and structured error payloads.

Confidence Score: 5/5

safe to merge — purely mechanical dispatch refactor with no handler body changes and 811 passing CLI tests as the safety net.

the dispatch change is a direct key-lookup substitution for a sequential if/else chain; all 28 entries are verified against ACCOUNT_MANAGER_COMMANDS by the routing test. per-dispatch factories remain lazy inside handler closures. the two style nits (type-only import, stale test reference in a comment) have no runtime impact.

no files require special attention; the two nits are in lib/codex-manager/formatters/quota-formatters.ts (import style) and lib/codex-manager/formatters/account-formatters.ts (comment pointer).

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["runCodexMultiAuthCli(rawArgs)"] --> B{auth-prefix\ncompat rewrite}
    B --> C[normalize command]
    C --> D{"--help / -h?"}
    D -->|yes| E[printUsage → exit 0]
    D -->|no| F{"non-auth root?"}
    F -->|yes| G[usage + exit 1]
    F -->|no| H["CLI_COMMAND_HANDLERS.get(command)"]
    H -->|found| I["handler(rest) → exit code"]
    H -->|not found| J["stderr + usage + exit 1"]
    I --> K["lazy factories at dispatch time\n(createRepairCommandDeps, buildSelectAccountTraced)"]

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
lib/codex-manager/formatters/quota-formatters.ts:3-7
`fetchCodexQuotaSnapshot` value import used only as a type

`fetchCodexQuotaSnapshot` is imported as a value but only ever appears in a `typeof` type annotation (`Awaited<ReturnType<typeof fetchCodexQuotaSnapshot>>`). this pulls the runtime value into the module graph unnecessarily; if the project ever enables `verbatimModuleSyntax` in tsconfig it will become a compile error. mark it `type` alongside `CodexQuotaSnapshot`.

```suggestion
import {
	type CodexQuotaSnapshot,
	type fetchCodexQuotaSnapshot,
	formatQuotaSnapshotLine,
} from "../../quota-probe.js";
```

### Issue 2 of 2
lib/codex-manager/formatters/account-formatters.ts:959-961
Comment references a test file that does not exist

The doc-comment says `// See test/codex-manager-detail-tone.test.ts` but that file is absent from both this PR and the repo. `test/codex-manager-formatters.test.ts` is the new suite, but it does not cover `styleAccountDetailText` at all. the reference will send future contributors on a dead-end search; either add the missing suite or update the pointer to the actual test file.

_{Reviews (2): Last reviewed commit: "test(codex-manager): unit-pin the extrac..." | Re-trigger Greptile}