feat: add ataegina doctor --json (structured diagnostics)#32
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
doctoralready 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 --jsonemits a structured report:{"status":"pass","summary":{"ok":6,"warn":2,"fail":0},"checks":[{"level":"ok","message":"worktree: index #0 …"}, …]}[ok]/[warn]/[fail]lines and the urls/hook chatter go to stderr; stdout is pure JSON.statusmirrors the exit code (failiff a hard[fail]).dok/dwarn/dfailnow also record each row, so a config-definedate_doctorhook that calls them is captured in the report — and a hook callingdfailflipsstatustofailand the exit code nonzero (a real, tested path, since nothing in the built-in checks fails by default).doctoris unchanged.Discipline
docs/design/agent-native.md(§6).tests/doctor_json.bats— 7 hermetic tests: stdout purity (stdout/stderr captured separately),summarycounts ==len(checks), thenoneport-tool warn row, a failingate_doctorhook flippingstatus+exit code (and itsdok/dfailrows captured), human-output regression, arg validation, completion.doctor.batsregression clean.python -m json.tool; confirmed exit 0 healthy and the hook-fail path._doctor_recordno-op — each caught.--help. Checksum regenerated.Rounds out the read-only JSON surface (
ports/status/list/doctor) alongside #27–#31.🤖 Generated with Claude Code