wehub-resource-sync
79 lines
3.1 KiB
Markdown
79 lines
3.1 KiB
Markdown
---
|
|
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`.
|