feat(cli): add --json output to doctor

[Dylanwooo]

Summary

hyperframes doctor is one of the first commands users and agents run when something's off — remote bug reports (e.g. #294, #316, #317) typically include a doctor screenshot, which is painful to parse programmatically.

Every other CLI command that reports state already supports --json (info, lint, compositions, catalog, benchmark, validate, capture). This brings doctor in line so:

• CI pipelines can gate on hyperframes doctor --json without scraping terminal output (exits 1 when any check fails)
• AI agents consuming diagnostic data get structured input
• Bug report tooling can attach machine-readable doctor output

Human output is unchanged. This is purely additive.

Output schema

{
  "ok": false,
  "platform": "darwin",
  "arch": "arm64",
  "checks": [
    { "name": "Version",  "ok": true,  "detail": "0.4.4 (latest)" },
    { "name": "FFmpeg",   "ok": true,  "detail": "ffmpeg version 8.1 Copyright (c) 2000-2026 …" },
    { "name": "Docker",   "ok": false, "detail": "Not found",
      "hint": "https://docs.docker.com/get-docker/" },
    { "name": "Docker running", "ok": false, "detail": "Not running",
      "hint": "Start Docker Desktop or run: sudo systemctl start docker" }
  ],
  "_meta": {
    "version": "0.4.4",
    "latestVersion": "0.4.4",
    "updateAvailable": false
  }
}

Uses the existing withMeta() helper so the _meta envelope matches other --json commands.

Design notes

• Preserved check order. outcomes[] is populated in the same order checks run, so JSON consumers see the same ordering as the human view (Linux-only /dev/shm slots into the middle).
• Optional hint field. Only emitted when a check has a hint, matching the human mode which only prints hints on failures.
• Non-zero exit on --json failure. process.exitCode = 1 when any check fails so hyperframes doctor --json || handle_failure works as a CI gate. Human mode still exits 0 (unchanged behavior).
• No new dependencies. Reuses withMeta() from utils/updateCheck.js.

Test plan

• bunx oxlint packages/cli/src/commands/doctor.ts — clean
• bunx oxfmt --check packages/cli/src/commands/doctor.ts — clean
• Pre-commit typecheck hook passes
• bunx tsx packages/cli/src/cli.ts doctor — human output unchanged
• bunx tsx packages/cli/src/cli.ts doctor --json — valid JSON, correct schema
• bunx tsx packages/cli/src/cli.ts doctor --help — --json listed, new example appears
• Exit code 1 when checks fail, 0 when all pass (CI-gate verified)

Follow-ups (out of scope)

The doctor docs page could be updated to mention --json alongside other --json-aware commands. Happy to do that in a follow-up PR if merged.

[jrusso1020]

Thanks for this — direction is great and the change is well-scoped. A couple of things I'd like to see addressed before this merges:

1. Drop process.exitCode = 1 on check failure

Exit code should reflect whether the command succeeded, not whether the environment it inspected is healthy. doctor ran all its checks and produced valid output — that's a successful execution. Whether the result is "ok" is data in the payload, not a property of the run.

Two concrete problems with gating the exit code on allOk:

• checkVersion poisons the CI-gate use case. It returns ok: false whenever a newer npm version is available, so any pipeline doing hyperframes doctor --json || fail will start failing the next time a new version is published, even if the environment is perfectly fine.
• Asymmetry with human mode. Bare doctor exits 0 on failure; doctor --json exits 1. Surprising for anyone scripting against it.

Proposal: always exit 0 on successful execution (reserve non-zero for real errors — bad flags, JSON serialization failure, an uncaught exception in a check). Consumers who want to gate can do:

hyperframes doctor --json | jq -e '.ok' > /dev/null || handle_failure

Just as ergonomic, and no version-check footgun. Worth a one-liner in the doctor docs pointing at this pattern.

2. Lock the JSON schema with a test

The PR body publishes a schema that CI pipelines and AI agents are expected to parse. There's currently nothing preventing a future refactor from silently renaming a field, dropping hint, or reordering checks[]. A snapshot test — feed a known environment into the check runner and assert the JSON shape — would lock the contract cheaply. The current test plan is all manual.

Nice-to-haves (non-blocking)

• Privacy: paths in detail (notably the Chrome check) typically include /Users/<name>/ or /home/<name>/. Same was true in human mode, but JSON output is designed to be pasted into bug reports and agent contexts. Consider $HOME redaction in --json mode.
• Nit: import { freemem, platform } from "node:os" on line 9 sits below export const examples. Grouping imports at the top is the repo-wide convention.

Security-wise this is clean — all execSync calls are hardcoded, no user input reflected into shell or JSON.

[Dylanwooo]

Thanks for the thorough review — all four points addressed in 3079e8c.

1. Exit code no longer gated on check health ✅
You're right — the checkVersion poisoning of the CI-gate use case is a real bug. Dropped process.exitCode = 1 entirely. Exit code now strictly reflects whether the command executed. Added the jq -e '.ok' gating pattern to the doctor docs in docs/packages/cli.mdx.

2. Schema locked with snapshot test ✅
Extracted buildDoctorReport() as a pure function and added packages/cli/src/commands/doctor.test.ts (13 tests). Locks the top-level key set, shape of each CheckOutcome, ok-flag semantics, check-order preservation, hint field behavior, and the redact option. Any future refactor that silently renames a field or drops hint will fail the test before it ships.

3. $HOME redaction ✅
Added redactHome() — applied to detail/hint in --json mode only. Human mode still shows real paths (unchanged). Handles both POSIX $HOME and Windows %USERPROFILE%. Covered by 5 dedicated tests.

4. Import grouping ✅
Moved node:os and _examples imports up with the rest; export const examples now sits after all imports.

Re-run locally:

• bun run --filter @hyperframes/cli test -- doctor.test → 13 passed
• hyperframes doctor --json exits 0 on failure, 0 on success
• hyperframes doctor --json | jq -e '.ok' correctly gates on payload health