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 <noreply@anthropic.com>

* 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 <noreply@anthropic.com>
This commit is contained in:
wonjang
2026-11-16 18:16:11 +00:00
committed by GitHub
co-authored by Claude Fable 5.2
parent 77e675574f
commit 47d007e5b0
14 changed files with 83 additions and 11 deletions
+12
View File
@@ -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
+3 -1
View File
@@ -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.
+1 -1
View File
@@ -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"),
@@ -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",
});
});
});
+7
View File
@@ -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<EnvironmentCheckOutcom
ok: false,
level: "error",
title: "FFmpeg not found",
code: "ffmpeg_not_found",
detail: missingConfigured,
hint: getFFmpegInstallHint(),
};
@@ -163,6 +165,7 @@ async function checkFFmpeg(signal?: AbortSignal): Promise<EnvironmentCheckOutcom
ok: false,
level: "error",
title: "FFmpeg not found",
code: "ffmpeg_not_found",
// Second sentence dropped: "the render cannot proceed" is already said by
// the error this accompanies, and in Studio by the disabled Export button.
detail: "FFmpeg is required to encode video.",
@@ -178,6 +181,7 @@ async function checkFFprobe(signal?: AbortSignal): Promise<EnvironmentCheckOutco
ok: false,
level: "error",
title: "FFprobe not found",
code: "ffprobe_not_found",
detail: missingConfigured,
hint: getFFmpegInstallHint(),
};
@@ -194,6 +198,7 @@ async function checkFFprobe(signal?: AbortSignal): Promise<EnvironmentCheckOutco
ok: false,
level: "error",
title: "FFprobe not found",
code: "ffprobe_not_found",
detail:
"FFprobe is required to probe media assets. It ships with FFmpeg but was not found on PATH.",
hint: getFFmpegInstallHint(),
@@ -354,6 +359,7 @@ async function checkChrome(
ok: false,
level: "error",
title: "Chrome not found",
code: "chrome_not_found",
detail: `Chrome binary not found at "${browserPath}".`,
hint: "Run: npx hyperframes browser ensure",
};
@@ -394,6 +400,7 @@ async function checkChrome(
ok: false,
level: "error",
title: "Chrome not found",
code: "chrome_not_found",
detail: failure ?? "Chrome Headless Shell is required for local rendering.",
hint: "Run: npx hyperframes browser ensure",
};
+1 -1
View File
@@ -1072,7 +1072,7 @@ async function executeLocalRender(
for (const check of failedChecks) {
errorBox(check.title ?? `${check.name} check failed`, check.detail, check.hint);
}
failCommand();
failCommand(1, undefined, failedChecks.at(-1)?.code);
}
if (!options.quiet) {
for (const outcome of preflight.outcomes) {
+1 -1
View File
@@ -276,7 +276,7 @@ async function ensureRenderBrowser(plan: RenderPlan, signal?: AbortSignal): Prom
normalizeErrorMessage(error),
"Run: npx hyperframes browser ensure",
);
failCommand();
failCommand(1, undefined, "chrome_not_found");
}
}
@@ -50,6 +50,6 @@ export async function acquireRenderSlot(
"Rerun without --no-wait to start when it finishes, or set HYPERFRAMES_RENDER_LOCK=off to render side by side. " +
"Set HYPERFRAMES_RENDER_LOCK_DIR to one folder in every account to share the slot across user accounts.",
);
return failCommand(1, error);
return failCommand(1, error, "render_locked");
}
}
+16 -1
View File
@@ -1,5 +1,5 @@
import { describe, expect, it } from "vitest";
import { runtimeVersionError } from "./runtimeVersion.js";
import { runtimeVersionError, runtimeVersionJson } from "./runtimeVersion.js";
describe("runtimeVersionError", () => {
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();
});
});
+5
View File
@@ -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 } });
}
+5 -3
View File
@@ -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 {
+25
View File
@@ -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)",
});
});
});
+1 -1
View File
@@ -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";
}
+1 -1
View File
@@ -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");