AGENTS.md

1# src/cli/doctor/ — Health Diagnostics (25 Check Files)
2 
3**Generated:** 2026-08-10 / 38d268995
4 
5## OVERVIEW
6 
7`bunx oh-my-opencode doctor` — parallel diagnostic checks. `getAllCheckDefinitions()` registers **8** checks; a second function `getCodexCheckDefinitions()` registers **3** Codex-only checks. Four of the eight are category aggregators (System, Config, Tools, Models); the rest register standalone. Catches broken installs, config typos, missing dependencies, provider misconfigurations before they become runtime errors.
8 
9## COMMAND FLAGS
10 
11```bash
12bunx oh-my-opencode doctor              # Full diagnostics
13bunx oh-my-opencode doctor --status     # Compact dashboard (status only)
14bunx oh-my-opencode doctor --verbose    # Deep details (model resolution traces)
15bunx oh-my-opencode doctor --json       # Machine-readable output
16```
17 
18## CHECK CATEGORIES
19 
20Registered by `getAllCheckDefinitions()` (8):
21 
22| Check | File | Validates |
23|----------|------|-----------|
24| **SYSTEM** | `checks/system.ts` | OpenCode binary found + version >= `MIN_OPENCODE_VERSION` (`1.4.0`), plugin registered in opencode.json, loaded plugin version matches installed |
25| **CONFIG** | `checks/config.ts` | JSONC validity, Zod schema passes, no unknown keys, model override syntax correct |
26| **TUI_PLUGIN** | `checks/tui-plugin-config.ts` | TUI sidebar plugin entry resolvable |
27| `deprecated-reasoning-keys` | `checks/deprecated-reasoning-keys.ts` | Scans `~/.omo/omo.json[c]` for deprecated `variant` / `reasoningEffort` / `thinking` / `textVerbosity` / `fallback_models` keys, reporting file + dotted path and a `config migrate` hint. Skips the `[opencode]` block and passthrough containers (`provider_options`). Registered with a literal id, NOT in `CHECK_IDS`. |
28| **TOOLS** | `checks/tools.ts` | AST-Grep CLI + NAPI, comment-checker binary, LSP servers reachable, GitHub CLI auth, built-in MCP reachability |
29| **MODELS** | `checks/model-resolution.ts` | models.json cache exists, per-agent fallback resolution, category overrides valid, provider availability |
30| **TELEMETRY** | `checks/telemetry.ts` | Telemetry configuration state |
31| **TEAM_MODE** | `checks/team-mode.ts` | Team-mode dependencies |
32 
33Registered by `getCodexCheckDefinitions()` (3): **CODEX** (critical, `checks/codex.ts`), **CODEX_COMPONENTS** (`checks/codex-components.ts`), `codex-runtime-wrapper` (literal id, `checks/codex-runtime-wrapper.ts`).
34 
35`checks/legacy-config-leftovers.ts` is not registered standalone; the Config aggregator invokes it.
36 
37## SUPPORTING CHECK FILES (25 total)
38 
39```
40checks/
41├── index.ts                               # Registration
42├── system.ts                              # Main System aggregator
43├── system-binary.ts                       # OpenCode binary discovery (PATH + desktop app)
44├── system-plugin.ts                       # opencode.json plugin entry detection
45├── system-loaded-version.ts               # Cache vs npm latest
46├── config.ts                              # Main Config aggregator
47├── tools.ts                               # Main Tools aggregator
48├── dependencies.ts                        # AST-Grep CLI/NAPI + comment-checker presence
49├── tools-gh.ts                            # gh cli install + auth status
50├── tools-lsp.ts                           # LSP server enumeration
51├── tools-mcp.ts                           # Built-in + user MCP reachability
52├── model-resolution.ts                    # Main Models aggregator
53├── model-resolution-cache.ts              # models.json presence + freshness
54├── model-resolution-config.ts             # unified OMO config resolution
55├── model-resolution-effective-model.ts    # Per-agent fallback chain trace
56├── model-resolution-variant.ts            # Model variant (max, high, medium) handling
57├── model-resolution-details.ts            # Verbose output formatter
58├── model-resolution-types.ts              # Shared types
59├── tui-plugin-config.ts                   # TUI sidebar plugin entry
60├── deprecated-reasoning-keys.ts           # Deprecated ~/.omo config keys
61├── telemetry.ts                           # Telemetry state
62├── team-mode.ts                           # Team-mode dependencies
63├── legacy-config-leftovers.ts             # Invoked by the Config aggregator, not registered
64├── codex.ts                               # Codex install (critical)
65├── codex-components.ts                    # Codex plugin components
66└── codex-runtime-wrapper.ts               # Codex runtime wrapper bins
67```
68 
69## EXECUTION FLOW
70 
71```
72doctor command
73  → runner.ts: parallel check execution with 30s per-check timeout
74  → checks/index.ts: getAllCheckDefinitions() (8) + getCodexCheckDefinitions() (3)
75  → each check returns CheckResult: { name, status, message, details?, issues, duration? }
76  → formatter.ts: render to stdout (text/status/json)
77  → exit code: EXIT_CODES.SUCCESS (0) | EXIT_CODES.FAILURE (1)
78```
79 
80`CheckStatus` is `pass` / `warn` (`STATUS_COLORS` also carries `fail` / `skip`). There is no `"ok"` or `"error"` status and no `detail` string field.
81 
82## KEY FILES
83 
84| File | Purpose |
85|------|---------|
86| `index.ts` | CLI command entry, flag parsing |
87| `runner.ts` | Parallel `Promise.allSettled()` orchestration, 30s timeout per check |
88| `formatter.ts` | Pretty printing: colored status, hierarchical output |
89| `types.ts` | `DoctorCheck`, `CheckResult`, `DoctorReport` types |
90 
91## HOW TO ADD A CHECK
92 
931. Create `src/cli/doctor/checks/{name}.ts` exporting check function matching `DoctorCheck`
942. Register in `checks/index.ts` — either standalone in `getAllCheckDefinitions()`, or have a category aggregator (system/config/tools/model-resolution) invoke it
953. Return a `CheckResult` (`{ name, status, message, issues }`) — no throws, all errors caught by runner
964. Add the id/name to `framework/constants.ts` `CHECK_IDS`/`CHECK_NAMES` unless registering with a literal id
97 
98## EXIT CODES
99 
100`framework/constants.ts` `EXIT_CODES` defines only:
101 
102- `SUCCESS: 0` — all checks passed
103- `FAILURE: 1` — one or more failures
104