Skip to content

feat: add ataegina doctor --json (structured diagnostics)#32

Merged
noahhyden merged 1 commit into
mainfrom
feat/doctor-json
Jul 20, 2026
Merged

feat: add ataegina doctor --json (structured diagnostics)#32
noahhyden merged 1 commit into
mainfrom
feat/doctor-json

Conversation

@noahhyden

Copy link
Copy Markdown
Owner

What & why

doctor already gates via its exit code (nonzero on a hard [fail]), but an agent doing health-based remediation wants to know which check failed, not just pass/fail. doctor --json emits a structured report:

{"status":"pass","summary":{"ok":6,"warn":2,"fail":0},"checks":[{"level":"ok","message":"worktree: index #0 …"}, ]}
  • Human [ok]/[warn]/[fail] lines and the urls/hook chatter go to stderr; stdout is pure JSON.
  • status mirrors the exit code (fail iff a hard [fail]).
  • dok/dwarn/dfail now also record each row, so a config-defined ate_doctor hook that calls them is captured in the report — and a hook calling dfail flips status to fail and the exit code nonzero (a real, tested path, since nothing in the built-in checks fails by default).
  • Plain doctor is unchanged.

Discipline

  • Spec: docs/design/agent-native.md (§6).
  • Tests-first: tests/doctor_json.bats — 7 hermetic tests: stdout purity (stdout/stderr captured separately), summary counts == len(checks), the none port-tool warn row, a failing ate_doctor hook flipping status+exit code (and its dok/dfail rows captured), human-output regression, arg validation, completion. doctor.bats regression clean.
  • Live verification: drove the binary; parsed the report with python -m json.tool; confirmed exit 0 healthy and the hook-fail path.
  • Mutation red-teaming: status-always-pass, drop-stdout-restore, and _doctor_record no-op — each caught.
  • Docs: README, man page, CHANGELOG, bash+zsh completion, in-script --help. Checksum regenerated.

Rounds out the read-only JSON surface (ports/status/list/doctor) alongside #27#31.

🤖 Generated with Claude Code

doctor already gates via its exit code, but an agent doing health-based
remediation wants to know WHICH check failed. --json emits
{status, summary:{ok,warn,fail}, checks:[{level,message}]} on stdout, with
the human [ok]/[warn]/[fail] lines and urls/hook chatter routed to stderr
(fd 3 swap). `status` mirrors the exit code (fail iff a hard [fail]).

The dok/dwarn/dfail helpers now also record each row (via _doctor_record)
when DOCTOR_JSON=1, so a config-defined ate_doctor hook that calls them is
captured in the report — and a hook calling dfail flips status to fail and
the exit code nonzero. Plain `doctor` is unchanged.

Spec: docs/design/agent-native.md. Completion (bash+zsh), man page, README,
CHANGELOG, and in-script --help updated. New hermetic suite
tests/doctor_json.bats (7 tests): stdout purity, summary counts == checks
length, the 'none' port-tool warn, a failing ate_doctor hook flipping
status+exit code (and its dok/dfail rows captured), human-output regression,
arg validation, completion.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@noahhyden
noahhyden merged commit 41b3b8c into main Jul 20, 2026
8 checks passed
@noahhyden
noahhyden deleted the feat/doctor-json branch July 20, 2026 00:59
@noahhyden noahhyden mentioned this pull request Jul 20, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant