From 143af6aec3fbf04bd3c76a6daa1ae6dd5f204c98 Mon Sep 17 00:00:00 2001 From: Dylan woo <13128589345@163.com> Date: Sat, 18 Apr 2026 23:58:38 +0800 Subject: [PATCH] feat(cli): add --json output to doctor MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `doctor` is one of the first commands users and agents run when something is 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 with that convention so: - CI pipelines can gate on `hyperframes doctor --json` (exit 1 on failure) without scraping terminal output - AI agents consuming telemetry / diagnostic data get structured input - Bug report tooling can attach machine-readable doctor output Schema: { "ok": boolean, "platform": "darwin" | "linux" | "win32", "arch": "arm64" | "x64" | ..., "checks": [ { "name": "FFmpeg", "ok": true, "detail": "ffmpeg version 8.1 …" }, { "name": "Docker", "ok": false, "detail": "Not found", "hint": "https://docs.docker.com/get-docker/" } ], "_meta": { "version", "latestVersion", "updateAvailable" } } Uses the existing `withMeta()` helper so the `_meta` envelope matches other `--json` commands. Human output format is unchanged. --- packages/cli/src/commands/doctor.ts | 70 ++++++++++++++++++++++------- 1 file changed, 54 insertions(+), 16 deletions(-) diff --git a/packages/cli/src/commands/doctor.ts b/packages/cli/src/commands/doctor.ts index ccf332be83..434ac8e295 100644 --- a/packages/cli/src/commands/doctor.ts +++ b/packages/cli/src/commands/doctor.ts @@ -2,13 +2,16 @@ import { defineCommand } from "citty"; import type { Example } from "./_examples.js"; import { execSync } from "node:child_process"; -export const examples: Example[] = [["Check system dependencies", "hyperframes doctor"]]; +export const examples: Example[] = [ + ["Check system dependencies", "hyperframes doctor"], + ["Output as JSON for CI / agents", "hyperframes doctor --json"], +]; import { freemem, platform } from "node:os"; import { c } from "../ui/colors.js"; import { findBrowser } from "../browser/manager.js"; import { findFFmpeg } from "../browser/ffmpeg.js"; import { VERSION } from "../version.js"; -import { getUpdateMeta } from "../utils/updateCheck.js"; +import { getUpdateMeta, withMeta } from "../utils/updateCheck.js"; import { getSystemMeta, getShmSizeMb, getFreeDiskMb, bytesToMb } from "../telemetry/system.js"; interface Check { @@ -178,14 +181,19 @@ function checkEnvironment(): CheckResult { return { ok: true, detail: parts.join(" \u00B7 ") }; } +interface CheckOutcome { + name: string; + ok: boolean; + detail: string; + hint?: string; +} + export default defineCommand({ meta: { name: "doctor", description: "Check system dependencies and environment" }, - args: {}, - async run() { - console.log(); - console.log(c.bold("hyperframes doctor")); - console.log(); - + args: { + json: { type: "boolean", description: "Output as JSON", default: false }, + }, + async run({ args }) { const checks: Check[] = [ { name: "Version", run: checkVersion }, { name: "Node.js", run: checkNode }, @@ -208,19 +216,49 @@ export default defineCommand({ { name: "Docker running", run: checkDockerRunning }, ); - let allOk = true; - + const outcomes: CheckOutcome[] = []; for (const check of checks) { const result = await check.run(); - const icon = result.ok ? c.success("\u2713") : c.error("\u2717"); - const name = check.name.padEnd(16); + outcomes.push({ + name: check.name, + ok: result.ok, + detail: result.detail, + ...(result.hint ? { hint: result.hint } : {}), + }); + } + const allOk = outcomes.every((o) => o.ok); + + if (args.json) { console.log( - ` ${icon} ${c.bold(name)} ${result.ok ? c.dim(result.detail) : c.error(result.detail)}`, + JSON.stringify( + withMeta({ + ok: allOk, + platform: process.platform, + arch: process.arch, + checks: outcomes, + }), + null, + 2, + ), ); - if (!result.ok && result.hint) { - console.log(` ${" ".repeat(19)}${c.accent(result.hint)}`); + // Non-zero exit so `hyperframes doctor --json` is usable as a CI gate. + if (!allOk) process.exitCode = 1; + return; + } + + console.log(); + console.log(c.bold("hyperframes doctor")); + console.log(); + + for (const outcome of outcomes) { + const icon = outcome.ok ? c.success("\u2713") : c.error("\u2717"); + const name = outcome.name.padEnd(16); + console.log( + ` ${icon} ${c.bold(name)} ${outcome.ok ? c.dim(outcome.detail) : c.error(outcome.detail)}`, + ); + if (!outcome.ok && outcome.hint) { + console.log(` ${" ".repeat(19)}${c.accent(outcome.hint)}`); } - if (!result.ok) allOk = false; } console.log();