chore: import upstream snapshot with attribution

2026-07-13 12:22:33 +08:00
commit fc4fcbab58
1848 changed files with 472303 additions and 0 deletions
@@ -0,0 +1,78 @@
+---
+summary: "CLI refactor plan: JSON-only errors, config validation, SettingsStore split."
+read_when:
+  - "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"`.
+
+```json
+{
+  "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`.