steipete--codexbar/docs/refactor/cli.md

summary, read_when

summary	read_when
CLI refactor plan: JSON-only errors, config validation, SettingsStore split.	Refactoring CodexBar CLI error handling or config parsing. Splitting SettingsStore into smaller files. Adding config validation or CLI config commands.

CLI Refactor Plan

Goals

• JSON-only: every error is valid JSON on stdout (no mixed stderr).
• Per-provider errors: provider failures yield provider-scoped error payloads.
• Config validation: warn on invalid fields, unsupported source modes, bad regions.
• Config parity: add CLI command to validate (and optionally dump) config.
• SettingsStore split: files <500 LOC; clear separation (defaults vs config).

Constraints (keep)

• Provider ordering stays driven by config providers[] order.
• Provider enable/disable stays in config (enabled).
• No Keychain persistence for provider secrets.
• CLI still supports text output for non-JSON use.

Error JSON shape

• JSON output remains an array for usage and cost commands.
• Errors appear as payload entries with error set.
• Global/CLI errors use provider: "cli" and source: "cli".

{
  "provider": "cli",
  "source": "cli",
  "error": { "code": 1, "message": "...", "kind": "config" }
}

Config validation rules

• source must be in provider descriptor fetchPlan.sourceModes.
• apiKey only valid when provider supports .api.
• cookieSource only valid when provider supports .web/.auto.
• region only for zai or minimax with known values.
• workspaceID only for opencode.
• tokenAccounts only for providers in TokenAccountSupportCatalog.

CLI commands

• codexbar config validate
  • Prints JSON issues (or text summary).
  • Exit non-zero if any errors.
• (Optional) codexbar config dump
  • Prints normalized config JSON.

Step-by-step implementation guide

1. Add validation types
   • CodexBarConfigIssue + CodexBarConfigValidator in CodexBarCore/Config.
   • Keep file <500 LOC.
2. Hook validation into CLI
   • New config validate command.
   • --json-only emits JSON array of issues.
3. Unify CLI error reporting
   • Parse --json-only early.
   • Route all exits through a JSON-aware reporter.
   • Use provider-scoped errors where possible.
4. Split CLIEntry.swift
   • Extract helpers + payload structs into dedicated files (<500 LOC each).
5. Split SettingsStore.swift
   • Move config-backed computed properties to SettingsStore+Config.swift.
   • Move defaults-backed computed properties to SettingsStore+Defaults.swift.
   • Move provider detection to SettingsStore+ProviderDetection.swift.
6. Provider toggles cleanup
   • Remove unused ProviderToggleStore + tests; keep migrator path for legacy toggles.
7. Tests
   • CLI json-only error payloads (invalid source, invalid provider selection).
   • Config validation (bad region/source/apiKey field).
   • SettingsStore order/toggle invariants still pass.
8. Verification
   • make test, swiftformat Sources Tests, swiftlint --strict, make check.
   • ./Scripts/compile_and_run.sh.
   • CLI e2e: codexbar --json-only ..., codexbar config validate.