test(cli): pin machine-readable output contracts - #533

Summary

Pins the CLI's machine-readable output contracts in test/cli-output-contracts.test.ts — a cheap regression net so JSON key sets, help text, and exit codes can't drift silently. Audit roadmap §4.4.3 (docs/audits/AUDIT_2026-06-10.md, PR #522). Test-only; 686 lines, 8 tests.

Surfaces pinned

Leak assertions on every surface: stdout/stderr never contain the fixture token secrets and never match an email pattern (fixtures deliberately omit emails since status echoes stored emails by design; the invariant pinned is no token material and no email fabricated from token claims).

Deterministic by construction: reuses the codex-manager-cli.test.ts mock harness, fixed two-account V3 fixture, Date frozen via fake timers, refresh/probe mocks reject and are asserted un-called (no network possible).

Deliberately skipped (already covered)

status/list --json plumbing, why-selected field semantics, fix/verify-flagged --json, config explain --json, rotation reset-runtime --json — each has a dedicated suite; this pass pins the envelope contracts that had none.

Validation

• npm run typecheck; eslint clean at --max-warnings=0
• 8/8 passing across 3 consecutive runs (determinism)
• test/codex-manager-cli.test.ts still 201/201 (shared harness unbroken)
• Independently re-verified: 8/8

Risk / Rollback

Pure test addition; revert the commit. If a future PR intentionally changes a JSON contract, the failing assertion names the exact key delta to update.

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

adds test/cli-output-contracts.test.ts — a pure test addition (no production code changed) that pins machine-readable output contracts for six cli surfaces: --help, status --json, report --json, doctor --json, forecast --json (with and without --explain), and why-selected --json. this closes the audit roadmap §4.4.3 gap and also addresses two gaps flagged in the previous review round (missing forecast --explain coverage and missing key-set guards on why-selected candidate/selected records).

• frozen clock, rejected-network mocks, and distinctive token secrets ensure the suite is deterministic and any accidental network call or token leak fails loudly.
• the --explain considered rows use an exact key-set check (sortedKeys(row).toEqual([...])) that excludes primaryReason, while the regular forecast --json account loop uses an allowed-keys whitelist that includes primaryReason as optional — this inconsistency could cause a misleading failure if any considered row ever carries a primaryReason.
• no windows filesystem operations are performed (everything is mocked), so no ebusy/eperm risk here.

Confidence Score: 5/5

pure test addition with no production code changes; all mocks reject network calls and token values never reach output.

the change adds only a new test file. no production logic is modified, mocks are scoped tightly to the test, and the frozen clock + rejected-network mocks prevent non-determinism or accidental outbound calls. the one asymmetry in key-set checking style for --explain considered rows is a test-design nuance, not a runtime defect.

test/cli-output-contracts.test.ts — specifically the forecast --explain considered rows key-set assertion (lines 650-661).

Important Files Changed

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[runCli args] --> B[spy console.log / console.error]
    B --> C[import codex-manager.js fresh via resetModules]
    C --> D[runCodexMultiAuthCli]
    D --> E{command}
    E -->|--help / bare / -h| F[usage text assertions]
    E -->|status --json| G[exact 9-key top-level]
    E -->|report --json| H[exact 14-key envelope]
    E -->|doctor --json| I[exact 5-key envelope]
    E -->|forecast --json| J[exact 8-key envelope]
    E -->|forecast --json --explain| K[explanation.considered exact 9-key row set]
    E -->|why-selected --json populated| L[exact 8-key envelope]
    E -->|why-selected --json null pool| M[exit 1 ok=false selected=null]
    F & G & H & I & J & K & L & M --> N[expectNoSecretOrEmailLeak]

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

---

### Issue 1 of 1
test/cli-output-contracts.test.ts:650-662
`--explain` considered rows use exact key-set matching, but regular `forecast` accounts use a whitelist that allows the optional `primaryReason` field. If `buildForecastExplanation` (or its shared builder) ever populates `primaryReason` for any account — e.g. when an account has a cooldown or rate-limit reason — this assertion fails with a key-set mismatch rather than a meaningful contract regression. Either switch to the same allowed-keys whitelist used for forecast accounts (and add `"primaryReason"` to it), or add a comment stating that `considered` rows intentionally omit `primaryReason` and the implementation enforces that invariant.

_{Reviews (2): Last reviewed commit: "test(cli): pin why-selected record keys ..." | Re-trigger Greptile}