From 47d007e5b04c13d54d5617c2f02d06d91ffaf6fb Mon Sep 17 00:00:00 2001 From: wonjang <48057918+wonjangcloud9@users.noreply.github.com> Date: Mon, 16 Nov 2026 18:16:11 +0000 Subject: [PATCH] fix(cli): render --json gives each missing tool, a held slot and an old Node its own code (#7842) * fix(cli): render --json gives each missing tool, a held slot and an old Node its own code Every failed `render --json` answered with `error.code: "runtime_error"`, so a script could only tell a missing FFmpeg from a busy render slot by matching the human message. A CliRuntimeError now carries a code, as CliUsageError does, and the envelope reports it: chrome_not_found, ffmpeg_not_found, ffprobe_not_found, render_locked. A Node older than 22 prints the envelope too (node_version_unsupported) when the run asked for --json. Other failures keep runtime_error. Refs #7408 Co-Authored-By: Claude Fable 5.2 * test(cli): give the bin entry test's runtimeVersion stub the new JSON export bin/hyperframes.mjs now imports runtimeVersionJson, so the stub dist file binEntry.test.ts writes must export it too, or the bin fails to load. --------- Co-authored-by: Claude Fable 5.2 --- docs/packages/cli.mdx | 12 +++++++++ packages/cli/bin/hyperframes.mjs | 4 ++- packages/cli/src/binEntry.test.ts | 2 +- packages/cli/src/browser/preflight.test.ts | 4 +++ packages/cli/src/browser/preflight.ts | 7 ++++++ packages/cli/src/commands/render.ts | 2 +- packages/cli/src/commands/render/execute.ts | 2 +- .../cli/src/commands/render/renderSlot.ts | 2 +- packages/cli/src/runtimeVersion.test.ts | 17 ++++++++++++- packages/cli/src/runtimeVersion.ts | 5 ++++ packages/cli/src/utils/commandResult.ts | 8 +++--- packages/cli/src/utils/jsonError.test.ts | 25 +++++++++++++++++++ packages/cli/src/utils/jsonError.ts | 2 +- packages/cli/src/utils/renderLock.test.ts | 2 +- 14 files changed, 83 insertions(+), 11 deletions(-) diff --git a/docs/packages/cli.mdx b/docs/packages/cli.mdx index 39d7f8eb74..40e0e5a7f2 100644 --- a/docs/packages/cli.mdx +++ b/docs/packages/cli.mdx @@ -113,6 +113,18 @@ machine-readable `code` and, when there is a next step, a `hint`: Some commands add their own fields next to `error`, such as `findings` from `lint` or `reason` and `fix` from a refused `timeline` edit. +A failure with no code of its own is `runtime_error`, or `usage_error` for a bad +command line. These causes have their own, so a script can branch without reading +`message`: + +| `code` | Cause | +| --- | --- | +| `chrome_not_found` | `render` found no Chrome to use, or could not install one | +| `ffmpeg_not_found` | `render` found no FFmpeg | +| `ffprobe_not_found` | `render` found no FFprobe | +| `render_locked` | `render --no-wait` while another render holds this account's slot | +| `node_version_unsupported` | The CLI was started on a Node.js older than 22 | + **The project `.env`.** The `.env` in the current directory sets only the CLI's own settings: `HEYGEN_API_KEY`, `HYPERFRAMES_API_KEY`, `ELEVENLABS_API_KEY`, `FIGMA_TOKEN`, and the vision keys, models, Vertex settings and timeout, and the telemetry opt-outs `HYPERFRAMES_NO_TELEMETRY` and `DO_NOT_TRACK`. A variable already in your environment wins. Any diff --git a/packages/cli/bin/hyperframes.mjs b/packages/cli/bin/hyperframes.mjs index aae934a7f1..bc21f7ccb1 100644 --- a/packages/cli/bin/hyperframes.mjs +++ b/packages/cli/bin/hyperframes.mjs @@ -1,7 +1,7 @@ #!/usr/bin/env node import module from "node:module"; -import { runtimeVersionError } from "../dist/runtimeVersion.js"; +import { runtimeVersionError, runtimeVersionJson } from "../dist/runtimeVersion.js"; // The plugin launcher starts npx outside the project so npm cannot pick the CLI from it, // and names the project here. Nested CLI runs keep the working folder their caller gives them. @@ -16,6 +16,8 @@ if (projectDir) { const error = runtimeVersionError(process.versions.node); if (error) { console.error(error); + const json = runtimeVersionJson(error, process.argv.slice(2)); + if (json) console.log(json); process.exitCode = 1; } else { // Reuses V8 bytecode across runs (os.tmpdir()/node-compile-cache); Node 22.0 has no such API. diff --git a/packages/cli/src/binEntry.test.ts b/packages/cli/src/binEntry.test.ts index 24147fcdd1..d684b006db 100644 --- a/packages/cli/src/binEntry.test.ts +++ b/packages/cli/src/binEntry.test.ts @@ -22,7 +22,7 @@ function runBin(handover: (project: string) => string | undefined) { copyFileSync(fileURLToPath(new URL("../bin/hyperframes.mjs", import.meta.url)), bin); writeFileSync( join(root, "pkg/dist/runtimeVersion.js"), - "export const runtimeVersionError = () => null;\n", + "export const runtimeVersionError = () => null;\nexport const runtimeVersionJson = () => null;\n", ); writeFileSync( join(root, "pkg/dist/cli.js"), diff --git a/packages/cli/src/browser/preflight.test.ts b/packages/cli/src/browser/preflight.test.ts index 7ecbe6e7a5..0e3700f5fc 100644 --- a/packages/cli/src/browser/preflight.test.ts +++ b/packages/cli/src/browser/preflight.test.ts @@ -130,6 +130,7 @@ describe("runEnvironmentChecks", () => { ok: false, level: "error", title: "FFprobe not found", + code: "ffprobe_not_found", }), ); expect(result.ffprobePath).toBeUndefined(); @@ -143,6 +144,7 @@ describe("runEnvironmentChecks", () => { expect(ffmpeg).toMatchObject({ ok: false, + code: "ffmpeg_not_found", detail: 'Configured path does not exist: HYPERFRAMES_FFMPEG_PATH="/missing/ffmpeg.exe"', }); }); @@ -289,6 +291,7 @@ describe("runEnvironmentChecks", () => { expect(result.outcomes.find((outcome) => outcome.name === "Chrome")).toMatchObject({ ok: false, title: "Chrome not found", + code: "chrome_not_found", detail: "ENOTDIR: not a directory, scandir 'chrome-headless-shell'", hint: "Run: npx hyperframes browser ensure", }); @@ -341,6 +344,7 @@ describe("runEnvironmentChecks", () => { expect(result.outcomes.find((outcome) => outcome.name === "Chrome")).toMatchObject({ ok: false, title: "Chrome not found", + code: "chrome_not_found", }); }); }); diff --git a/packages/cli/src/browser/preflight.ts b/packages/cli/src/browser/preflight.ts index fca46eb9ea..48779d2ea0 100644 --- a/packages/cli/src/browser/preflight.ts +++ b/packages/cli/src/browser/preflight.ts @@ -28,6 +28,7 @@ export interface EnvironmentCheckOutcome { detail: string; level: EnvironmentCheckLevel; title?: string; + code?: string; hint?: string; path?: string; /** Major version parsed from the tool's own `-version`/`--version` output, when available. */ @@ -126,6 +127,7 @@ async function checkFFmpeg(signal?: AbortSignal): Promise { it("rejects Node 20 before the bundled CLI is imported", () => { @@ -17,3 +17,18 @@ describe("runtimeVersionError", () => { expect(runtimeVersionError("unknown")).toContain("requires Node.js >= 22"); }); }); + +describe("runtimeVersionJson", () => { + const message = "HyperFrames requires Node.js >= 22 (current: 20.11.1)."; + + it("answers a --json run with the failure envelope", () => { + expect(JSON.parse(runtimeVersionJson(message, ["render", ".", "--json"]) ?? "")).toEqual({ + ok: false, + error: { code: "node_version_unsupported", message }, + }); + }); + + it("stays out of a run that did not ask for JSON", () => { + expect(runtimeVersionJson(message, ["render", "."])).toBeNull(); + }); +}); diff --git a/packages/cli/src/runtimeVersion.ts b/packages/cli/src/runtimeVersion.ts index b9af1717b7..5f09988c0c 100644 --- a/packages/cli/src/runtimeVersion.ts +++ b/packages/cli/src/runtimeVersion.ts @@ -5,3 +5,8 @@ export function runtimeVersionError(version: string): string | null { if (Number.isFinite(major) && major >= MINIMUM_NODE_MAJOR) return null; return `HyperFrames requires Node.js >= ${MINIMUM_NODE_MAJOR} (current: ${version}). Switch Node versions and retry.`; } + +export function runtimeVersionJson(message: string, argv: readonly string[]): string | null { + if (!argv.includes("--json")) return null; + return JSON.stringify({ ok: false, error: { code: "node_version_unsupported", message } }); +} diff --git a/packages/cli/src/utils/commandResult.ts b/packages/cli/src/utils/commandResult.ts index 50e4910433..23e2c2736b 100644 --- a/packages/cli/src/utils/commandResult.ts +++ b/packages/cli/src/utils/commandResult.ts @@ -37,13 +37,15 @@ export class CliUsageError extends Error { export class CliRuntimeError extends Error { readonly result: CommandResult; + readonly code: string; constructor( message = "Command failed", - options: { exitCode?: number; presented?: boolean; cause?: unknown } = {}, + options: { exitCode?: number; presented?: boolean; cause?: unknown; code?: string } = {}, ) { super(message, options.cause === undefined ? undefined : { cause: options.cause }); this.name = "CliRuntimeError"; + this.code = options.code ?? "runtime_error"; this.result = { exitCode: options.exitCode ?? 1, kind: "runtime_error", @@ -63,8 +65,8 @@ export class CliResultSignal extends Error { } } -export function failCommand(exitCode = 1, cause?: unknown): never { - throw new CliRuntimeError("Command failed", { exitCode, presented: true, cause }); +export function failCommand(exitCode = 1, cause?: unknown, code?: string): never { + throw new CliRuntimeError("Command failed", { exitCode, presented: true, cause, code }); } export function failUsage(exitCode = USAGE_EXIT_CODE): never { diff --git a/packages/cli/src/utils/jsonError.test.ts b/packages/cli/src/utils/jsonError.test.ts index 5bba09c903..0f68a47773 100644 --- a/packages/cli/src/utils/jsonError.test.ts +++ b/packages/cli/src/utils/jsonError.test.ts @@ -57,4 +57,29 @@ describe("jsonErrorBody", () => { hint: "Run npx hyperframes init", }); }); + + it("keeps a runtime error's own code next to the failure the command reported", () => { + recordFailure("FFmpeg not found", "Configured path does not exist"); + const error = new CliRuntimeError("Command failed", { + presented: true, + code: "ffmpeg_not_found", + }); + expect(jsonErrorBody(error, runtime, "x")).toEqual({ + code: "ffmpeg_not_found", + message: "FFmpeg not found", + hint: "Configured path does not exist", + }); + }); + + it("keeps a runtime error's own code when the message comes from its cause", () => { + const error = new CliRuntimeError("Command failed", { + presented: true, + cause: new Error("Another render is running (pid 7)"), + code: "render_locked", + }); + expect(jsonErrorBody(error, runtime, "x")).toEqual({ + code: "render_locked", + message: "Another render is running (pid 7)", + }); + }); }); diff --git a/packages/cli/src/utils/jsonError.ts b/packages/cli/src/utils/jsonError.ts index b21f2d678d..d40917e46e 100644 --- a/packages/cli/src/utils/jsonError.ts +++ b/packages/cli/src/utils/jsonError.ts @@ -132,7 +132,7 @@ function withHint(body: CliErrorBody, hint: string | undefined): CliErrorBody { } function errorCode(error: unknown, result: CommandResult): string { - if (error instanceof CliUsageError) return error.code; + if (error instanceof CliUsageError || error instanceof CliRuntimeError) return error.code; return result.kind === "usage_error" ? "usage_error" : "runtime_error"; } diff --git a/packages/cli/src/utils/renderLock.test.ts b/packages/cli/src/utils/renderLock.test.ts index fe1adff6ed..ed171629e0 100644 --- a/packages/cli/src/utils/renderLock.test.ts +++ b/packages/cli/src/utils/renderLock.test.ts @@ -499,7 +499,7 @@ describe("acquireRenderSlot", () => { undefined, { path, env: {} }, ), - ).rejects.toThrow("Command failed"); + ).rejects.toMatchObject({ message: "Command failed", code: "render_locked" }); const said = vi.mocked(console.error).mock.calls.flat().join("\n"); expect(said).toContain("Another render is running for this user account");