Skip to content

Add a doctor health-check for environment and setup #5

Description

@aorumbayev

Summary

Add a self-diagnostic doctor health-check that verifies a user's environment and Kagan
setup and prints clear pass / warn / fail results with remediation. Today the onboarding flow
assumes a working environment; when something is off (wrong OpenCode version, plugin not
registered, missing provider auth, un-writable worktree base) the failure surfaces late and
opaquely as a broken board or a helper that never starts.

Proposal

A diagnostic that runs a set of independent checks and reports each with a status and an
actionable next step. Runnable standalone and suitable for embedding in onboarding.

Candidate checks:

  • Bun present and a supported version.
  • OpenCode version within the manifest engines.opencode range (>=1.17.13 <1.18.0).
  • Kagan is registered in the project opencode.json plugin array.
  • git is available and the repo has a work tree.
  • The worktree base directory is writable (worktrees are created there).
  • At least one model provider is authenticated.

Design notes

  • Uniform contract so the runner/formatter stay generic: each check is a
    { id, name, category, run(): Promise<Result> }; a Result is
    { status: "pass" | "warn" | "fail", message, details?, remediation? }.
  • Runner isolates each check in try/catch so one throwing check cannot abort the run; it
    tallies results and exits non-zero if any check fails.
  • Human output plus a --json mode; failing checks carry a concrete remediation line
    (e.g. the exact command to run).
  • Test each check as a pure map from gathered inputs to a Result (split the impure
    "gather" from the pure "classify"), so checks are unit-testable without hitting the
    network or filesystem.

Acceptance criteria

  • Running the doctor on a healthy setup reports all pass and exits 0.
  • Each failable condition has a check that returns fail with a remediation line, and a
    unit test covering its pass / warn / fail branches.
  • One throwing check does not crash the run.

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions