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.
Summary
Add a self-diagnostic
doctorhealth-check that verifies a user's environment and Kagansetup 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:
engines.opencoderange (>=1.17.13 <1.18.0).opencode.jsonpluginarray.gitis available and the repo has a work tree.Design notes
{ id, name, category, run(): Promise<Result> }; aResultis{ status: "pass" | "warn" | "fail", message, details?, remediation? }.tallies results and exits non-zero if any check fails.
--jsonmode; failing checks carry a concrete remediation line(e.g. the exact command to run).
Result(split the impure"gather" from the pure "classify"), so checks are unit-testable without hitting the
network or filesystem.
Acceptance criteria
failwith a remediation line, and aunit test covering its pass / warn / fail branches.