mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
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:
co-authored by
Claude Fable 5.2
parent
77e675574f
commit
47d007e5b0
@@ -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
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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",
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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",
|
||||
};
|
||||
|
||||
@@ -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) {
|
||||
|
||||
@@ -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");
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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,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 } });
|
||||
}
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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)",
|
||||
});
|
||||
});
|
||||
});
|
||||
|
||||
@@ -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";
|
||||
}
|
||||
|
||||
|
||||
@@ -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");
|
||||
|
||||
Reference in New Issue
Block a user