feat(scripts): doctor.ps1 — health, updates, and self-repair in one command

[abdout]

Summary

Implements spec #26. One command, three answers: is my config healthy, is it up to date, what's fixable?

& "$env:USERPROFILE\.claude\scripts\doctor.ps1"

Output (verified on a real machine):

🔄 1 updates available · unknown @ HOSTNAME · 2026-05-16 16:42

UPDATES
  🔄 claude CLI             v2.1.143 available (current 2.1.140) — winget upgrade Anthropic.ClaudeCode

What's in the PR

• ~/.claude/scripts/doctor.ps1 — main entry point (188 lines)
• 7 check modules under lib/:
  • Common.ps1 — shared New-CheckResult accumulator, role detection, file freshness
  • Check-Core.ps1 — CLAUDE.md, settings.json, mcp.json, .env, agent/command counts
  • Check-Shell.ps1 — c function in $PROFILE, ~/.claude/bin on PATH
  • Check-Identity.ps1 — gh auth status, claude CLI signed-in heuristic
  • Check-Repos.ps1 — org repos cloned, branch, dirtiness (reads repositories.json if present)
  • Check-Updates.ps1 — claude CLI vs latest GitHub release, kun + codebase ahead/behind
  • Check-Scheduled.ps1 — kun-maintain task armed (next-run + last-run + exit code)
  • Check-IDE.ps1 — WebStorm version + Claude Code [Beta] plugin loaded
• 1 fix module: Fix-Shell.ps1 — idempotent $PROFILE block append, double-applies safely
• health.ps1 demoted to a 5-line back-compat shim → doctor.ps1. Existing callers of health.ps1 -Report keep working unchanged.
• install.ps1 updated to copy lib/ recursively and reference doctor in post-install steps

Flags

Flag	What
(none)	Full audit, exit 0/1/2/3
-Report	Post result as a comment on databayt/kun#config-health
-Fix	Repair fixable issues (right now: $PROFILE c function append)
-Update	Pull ~/.claude + ~/codebase; prints (doesn't run) winget upgrade for claude CLI
-Json	JSON output instead of table
-Quiet	Suppress passes, show only warn/fail/update/paused rows
-Deep	Reserved for future expensive checks (no-op today)

Exit codes

Code	Meaning
0	All green
1	At least one error
2	Warnings only
3	Updates available, no errors or warnings

Precedence: errors > warnings > updates.

Test plan

• doctor runs on a configured machine and exits 0
• doctor on this machine (no ~/.claude/) exits 1 and surfaces every missing piece
• doctor -Fix on a machine with no c function appends the block to $PROFILE; second run is no-op
• doctor -Json | ConvertFrom-Json parses correctly
• health.ps1 -Report still posts to databayt/kun#config-health (back-compat shim works)
• install.ps1 copies lib/ to ~/.claude/scripts/lib/ on a fresh install
• All 11 PowerShell files parse cleanly (Parser::ParseFile) — verified locally

Open items not blocking this PR

These are noted in spec #26 and don't block merge:

• repositories.json is read if present; today's install.ps1 already creates it. Migrating sync-repos.ps1 to use the same JSON instead of the hardcoded hashtable is a follow-up.
• macOS/Linux equivalents are follow-up work (Windows-only for v1).
• databayt/codebase/.claude/scripts/install.ps1 tombstone is a separate cross-repo PR.

Sample run

This is real output captured against a machine that hasn't run install.ps1 yet — every error/warning is accurate:

❌ 13 errors · unknown @ HOSTNAME · 2026-05-16 16:42

CORE FILES
  ❌ CLAUDE.md              missing — run install.ps1
  ❌ mcp.json               missing — run install.ps1
  ⚠️  .env                  missing — run secrets.ps1
  ❌ agents/                empty
  ❌ commands/              empty

IDE
  ⚠️  Claude Code [Beta]    not loaded — install from Marketplace or bootstrap.ps1

ORG REPOS
  ❌ codebase               not cloned
  ... (11 repos)

SCHEDULED
  ⏸  kun-maintain           not armed — install via maintain -Install or bootstrap.ps1

SHELL
  ❌ $PROFILE               missing — run doctor -Fix

UPDATES
  🔄 claude CLI             v2.1.143 available (current 2.1.140) — winget upgrade Anthropic.ClaudeCode

Run 'doctor -Fix' to repair 13 fixable issue(s).
Run 'doctor -Update' to apply 1 update(s).

Closes #26

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
kun	Ready	Preview, Comment	May 16, 2026 3:18pm