feat(opencode): add opencode doctor diagnostic command

[katipally]

Issue for this PR

Closes #21269

Type of change

• Bug fix
• New feature
• Refactor / code improvement
• Documentation

What does this PR do?

Adds opencode doctor — a diagnostic command that checks your entire OpenCode setup and reports issues with color-coded output.

The problem: OpenCode supports 100+ providers, MCP/LSP servers, agents, formatters, and plugins. When something breaks, users have to run debug config, debug lsp, check env vars manually, etc. There is no single command to verify everything works.

The solution: opencode doctor runs 13 independent diagnostic sections across the full stack:

Section	What it checks
Environment	Version, Bun, Git, binary path
Updates	Auto-update status, latest version
Configuration	Config loading, schema validation
Providers & Models	Multi-provider auth matrix, default model resolution, models.dev database
Agents	Native/custom agents, model binding validation
Tools & Permissions	Tool count, disabled tools, permission rules
LSP Servers	Connection status per server
MCP Servers	Status, tool count, error messages
Formatters	Active formatters and file extensions
Plugins	Load count, errors
Context Analysis	Agent description sizes, MCP tool count (context pressure)
Environment Variables	Active OPENCODE_* flags, experimental flag detection
Paths	Global directory existence and write permissions

Each section is independently error-handled — one failure never blocks the rest.

Flags: --json for machine-readable output, --verbose for full details.

Scope: 2 files only.

• NEW packages/opencode/src/cli/cmd/doctor.ts (~500 lines)
• EDIT packages/opencode/src/index.ts (2 lines: import + command registration)

Not a duplicate of #17164 — that issue proposed a narrow opencode config doctor focused only on config merge precedence and was closed as not_planned. This is a full-stack diagnostic.

How did you verify your code works?

$ bun dev doctor        # default mode
$ bun dev doctor --json # structured JSON output
$ bun dev doctor --verbose # full details (all providers, tools, paths)

All three variants produce expected output. bun typecheck confirms zero new type errors. Ran ./script/format.ts and ./script/generate.ts — no changes needed.

Screenshots / recordings

Default output (opencode doctor):

Environment
  • OpenCode v1.3.2 (latest channel)
  ✓ Installed via bun
  ✓ Bun v1.3.11
  ✓ Git v2.53.0

Updates
  ✓ Auto-update enabled
  ✓ Up to date

Configuration
  ✓ Config loaded and valid

Providers & Models
  ✓ Model database: 4165 models from 110 providers
  ✓ anthropic - API key (env: ANTHROPIC_API_KEY)
  ✓ openai - API key (stored)
  ✗ google - no credentials
  ✓ Default model: anthropic/claude-sonnet-4-20250514

Agents
  ✓ 4 agents (3 native, 1 custom)
  ✓ All agent models resolvable

Tools & Permissions
  ✓ 27 tools available
  ⚠ 2 tools disabled by permission rules

LSP Servers
  ✓ typescript - connected
  ✗ pyright - error

MCP Servers
  ✓ filesystem - connected (12 tools)
  ⚠ slack - needs authentication

Formatters
  ✓ 4 formatters active: prettier, gofmt, ruff, biome

Plugins
  ✓ 2 plugins loaded

Paths
  ✓ data    ~/.local/share/opencode
  ✓ config  ~/.config/opencode
  ✓ cache   ~/.cache/opencode
  ✓ state   ~/.local/state/opencode

17 passed, 4 warnings

JSON output (opencode doctor --json):

{
  "version": "1.3.2",
  "channel": "latest",
  "summary": { "pass": 17, "warn": 4, "fail": 0 },
  "sections": [
    { "title": "Environment", "checks": [...] },
    { "title": "Providers & Models", "checks": [...] },
    ...
  ]
}

Checklist

• I have tested my changes locally
• I have not included unrelated changes in this PR

[github-actions]

Thanks for updating your PR! It now meets our contributing guidelines. 👍

[katipally]

Rebased on latest dev (clean, no conflicts). All CI checks should re-run now.

Quick summary for reviewers:

• 2 files changed: 1 new (doctor.ts ~500 lines) + 2 lines added to index.ts
• Zero new type errors — all pre-existing on dev
• Tested locally: bun dev doctor, --json, --verbose all work
• Not a duplicate of enhancement(core): add config resolve and doctor commands #17164 — that was a narrow config-only proposal (closed as not_planned). This is a full-stack 13-section diagnostic

Ready for review whenever convenient. Happy to address any feedback!