Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
fix(cli): browser ensure fails when the unzip leaves no Chrome executable (#5329)
Miguel Ángel577bdf670132
diff --git a/packages/cli/src/browser/manager.test.ts b/packages/cli/src/browser/manager.test.tsindex e576f7d7aa..34e8d67520 100644--- a/packages/cli/src/browser/manager.test.ts+++ b/packages/cli/src/browser/manager.test.ts@@ -71,8 +71,12 @@ function useRealCacheHome(): string {return home;}+function stagedVersionDir(cacheDir: string, buildId: string): string {+ return join(cacheDir, "chrome-headless-shell", `linux-${buildId}`);+}+function writeStagedInstall(cacheDir: string, buildId: string, content: string) {- const path = join(cacheDir, "chrome-headless-shell", `linux-${buildId}`);+ const path = stagedVersionDir(cacheDir, buildId);const executablePath = join(path, "chrome-headless-shell-linux64", "chrome-headless-shell");mkdirSync(dirname(executablePath), { recursive: true });writeFileSync(executablePath, content);@@ -149,13 +153,14 @@ function installFsMocks({paths.add(to + p.slice(from.length));}},- statSync: (p: string) => {+ statSync: (p: string, opts?: { throwIfNoEntry?: boolean }) => {if (!paths.has(p)) {+ if (opts?.throwIfNoEntry === false) return undefined;const err = new Error(`ENOENT: no such file or directory, stat '${p}'`);(err as NodeJS.ErrnoException).code = "ENOENT";throw err;}- return { mtimeMs: mtimes.get(p) ?? 0 };+ return { mtimeMs: mtimes.get(p) ?? 0, size: 1 };},utimesSync: (p: string, _atime: Date, mtime: Date) => {if (touchError) throw touchError;@@ -189,6 +194,12 @@ function installFsMocks({return paths;}+interface InstallMockOptions {+ buildId: string;+ cacheDir: string;+ logger?: (prefix: string) => ((...args: unknown[]) => void) | undefined;+}+function installPuppeteerBrowsersMock(opts: {installedInHfCache?: Array<{@@ -201,16 +212,15 @@ function installPuppeteerBrowsersMock(browserPlatform?: string;installedInHfCacheError?: Error;installResult?: { executablePath: string; path?: string };- installImpl?: (options: {- buildId: string;- cacheDir: string;- }) => Promise<{ executablePath: string; path?: string }>;+ installImpl?: (+ options: InstallMockOptions,+ ) => Promise<{ executablePath: string; path?: string }>;} = {},) {const impl =opts.installImpl ?? (async () => opts.installResult ?? { executablePath: HF_BINARY });// Fixtures name the binary where it lands in HF_CACHE; install() really writes it under its own cacheDir.- const stagedInstall = async (options: { buildId: string; cacheDir: string }) => {+ const stagedInstall = async (options: InstallMockOptions) => {const result = await impl(options);if (result.path || !result.executablePath.startsWith(HF_CACHE + sep)) return result;const rel = relative(HF_CACHE, result.executablePath);@@ -425,7 +435,7 @@ describe("findBrowser — cache resolution", () => {"chrome-headless-shell-linux64","redownloaded-chrome-headless-shell",);- const staleInstallDir = join(HF_CACHE, "chrome-headless-shell", "linux-131.0.6778.85");+ const staleInstallDir = stagedVersionDir(HF_CACHE, "131.0.6778.85");// The stale install DIR is present (extraction got partway through, e.g. an// ABOUT/LICENSE-only extract) even though the exe itself is missing —// exercises the purge-before-redownload fix, not just the redownload path.@@ -461,7 +471,7 @@ describe("findBrowser — cache resolution", () => {});it("ensureBrowser({force: true}) re-downloads without purging the cache, bypassing any cache/system shortcut", async () => {- const staleInstallDir = join(HF_CACHE, "chrome-headless-shell", "linux-131.0.6778.85");+ const staleInstallDir = stagedVersionDir(HF_CACHE, "131.0.6778.85");const downloadedBinary = join(HF_CACHE, "chrome-headless-shell", "force-downloaded");// A HEALTHY cached binary AND system Chrome are both present — force must// ignore both shortcuts and always re-download, which is the whole point@@ -506,7 +516,7 @@ describe("findBrowser — cache resolution", () => {});try {const { ensureBrowser, CACHE_DIR } = await import("./manager.js");- const otherVersion = join(CACHE_DIR, "chrome-headless-shell", "linux-1.0.0", "marker");+ const otherVersion = join(stagedVersionDir(CACHE_DIR, "1.0.0"), "marker");mkdirSync(dirname(otherVersion), { recursive: true });writeFileSync(otherVersion, "other");@@ -528,9 +538,13 @@ describe("findBrowser — cache resolution", () => {let stageNothing = false;installPuppeteerBrowsersMock({installImpl: async ({ cacheDir, buildId }) => {- const staged = writeStagedInstall(cacheDir, buildId, "old");- if (stageNothing) rmSync(staged.path, { recursive: true, force: true });- return staged;+ if (!stageNothing) return writeStagedInstall(cacheDir, buildId, "old");+ // A real executable passes the unzip check, but its version dir is gone, so only the move fails.+ const elsewhere = writeStagedInstall(join(cacheDir, "elsewhere"), buildId, "new");+ return {+ executablePath: elsewhere.executablePath,+ path: stagedVersionDir(cacheDir, buildId),+ };},});try {@@ -545,6 +559,59 @@ describe("findBrowser — cache resolution", () => {}});+ it.each([+ { label: "missing", unpacked: undefined, state: "is missing" },+ { label: "empty", unpacked: "", state: "is empty" },+ ])("fails instead of reporting a browser the unzip left $label", async ({ unpacked, state }) => {+ const home = useRealCacheHome();+ installPuppeteerBrowsersMock({+ installImpl: async ({ cacheDir, buildId, logger }) => {+ const staged = writeStagedInstall(cacheDir, buildId, "");+ rmSync(staged.executablePath);+ if (unpacked !== undefined) writeFileSync(staged.executablePath, unpacked);+ logger?.("puppeteer:browsers:fileUtil")?.("tar.exe extraction failed: Error: boom");+ return staged;+ },+ });+ try {+ const { ensureBrowser, CACHE_DIR } = await import("./manager.js");++ const ensured = ensureBrowser({ preferManagedChrome: true });++ await expect(ensured).rejects.toThrow(`chrome-headless-shell ${state} after unzipping`);+ await expect(ensured).rejects.toThrow("tar.exe extraction failed: Error: boom");+ expect(existsSync(CACHE_DIR)).toBe(false);+ } finally {+ rmSync(home, { recursive: true, force: true });+ }+ });++ it("reports only the last attempt's unzip errors after a corrupt-archive retry", async () => {+ const home = useRealCacheHome();+ let attempt = 0;+ installPuppeteerBrowsersMock({+ installImpl: async ({ cacheDir, buildId, logger }) => {+ attempt += 1;+ logger?.("puppeteer:browsers:fileUtil")?.(`tar.exe extraction failed: attempt ${attempt}`);+ if (attempt === 1) throw new Error("invalid end of central directory");+ const staged = writeStagedInstall(cacheDir, buildId, "");+ rmSync(staged.executablePath);+ return staged;+ },+ });+ vi.spyOn(console, "warn").mockImplementation(() => {});+ try {+ const { ensureBrowser } = await import("./manager.js");++ const error = await ensureBrowser({ force: true }).catch((err: unknown) => err);++ expect(String(error)).toContain("tar.exe extraction failed: attempt 2");+ expect(String(error)).not.toContain("attempt 1");+ } finally {+ rmSync(home, { recursive: true, force: true });+ }+ });+it("sweeps dirs leaked by a killed install on the next install and on clear", async () => {const home = useRealCacheHome();installPuppeteerBrowsersMock({diff --git a/packages/cli/src/browser/manager.ts b/packages/cli/src/browser/manager.tsindex 6c19d2ba79..f75b80b3f7 100644--- a/packages/cli/src/browser/manager.ts+++ b/packages/cli/src/browser/manager.ts@@ -13,6 +13,7 @@ import {writeFileSync,} from "node:fs";import { homedir } from "node:os";+import { debuglog } from "node:util";import { basename, dirname, join, relative } from "node:path";import { chromeMajorCeiling, exceedsChromeCeiling } from "@hyperframes/engine/chrome-host-ceiling";import { normalizeErrorMessage } from "../utils/errorMessage.js";@@ -782,7 +783,7 @@ function wrapDownloadFailureWithBrowserPathHint(cause: unknown): Error {const original = normalizeErrorMessage(cause);const example = browserPathHintForPlatform();const message =- `Failed to download chrome-headless-shell ${managedChromeVersion()}: ${original}\n\n` ++ `Failed to install chrome-headless-shell ${managedChromeVersion()}: ${original}\n\n` +`Point hyperframes at an already-installed Chrome/Chromium instead:\n\n` +` export HYPERFRAMES_BROWSER_PATH="${example}"\n\n` +`Then re-run your command. Any Chrome build works for the screenshot ` +@@ -809,14 +810,28 @@ async function downloadBrowser(options?: EnsureBrowserOptions): Promise<BrowserR// Same filesystem as CACHE_DIR so the final rename is atomic.const stagingDir = join(CACHE_ROOT_DIR, `${STAGING_PREFIX}${randomUUID()}`);const clearStaging = () => rmSync(stagingDir, { recursive: true, force: true });- const runInstall = () =>- install({+ // install() only debug-logs each failed unzip tool before trying the next one; keep those lines.+ let unzipLog: string[] = [];+ const runInstall = () => {+ unzipLog = [];+ return install({cacheDir: stagingDir,browser: Browser.CHROMEHEADLESSSHELL,buildId: managedChromeVersion(),platform,downloadProgressCallback: options?.onProgress,+ logger: (prefix) => {+ const debug = debuglog(prefix);+ const isUnzip = prefix === "puppeteer:browsers:fileUtil";+ if (!isUnzip && !debug.enabled) return undefined;+ return (...args) => {+ const line = args.join(" ");+ if (isUnzip) unzipLog.push(line);+ if (debug.enabled) debug(line);+ };+ },});+ };try {const staged = await installWithCorruptArchiveRecovery(runInstall, clearStaging, (err) =>@@ -824,6 +839,7 @@ async function downloadBrowser(options?: EnsureBrowserOptions): Promise<BrowserR`[hyperframes] Downloaded browser archive was corrupt (${normalizeErrorMessage(err)}); re-downloading.`,),);+ assertExecutableUnpacked(stagingDir, staged.executablePath, unzipLog);return { executablePath: moveStagedInstallIntoCache(stagingDir, staged), source: "download" };} catch (err) {throw wrapDownloadFailureWithBrowserPathHint(err);@@ -832,6 +848,21 @@ async function downloadBrowser(options?: EnsureBrowserOptions): Promise<BrowserR}}+// install() returns without checking that the unzip produced the executable.+function assertExecutableUnpacked(+ stagingDir: string,+ executablePath: string,+ unzipLog: readonly string[],+): void {+ const size = statSync(executablePath, { throwIfNoEntry: false })?.size;+ if (size) return;+ const state = size === 0 ? "is empty" : "is missing";+ const log = unzipLog.length > 0 ? ` Unzip errors: ${unzipLog.join("; ")}` : "";+ throw new Error(+ `the archive downloaded, but ${relative(stagingDir, executablePath)} ${state} after unzipping.${log}`,+ );+}+// Swap one staged version dir into CACHE_DIR by rename, never deleting the cache under live users:// a running old binary keeps its inode, and a stale partial extract (exe missing) is replaced too.function moveStagedInstallIntoCache(diff --git a/packages/cli/src/browser/preflight.test.ts b/packages/cli/src/browser/preflight.test.tsindex 13ef3a2b32..12a3dfedc2 100644--- a/packages/cli/src/browser/preflight.test.ts+++ b/packages/cli/src/browser/preflight.test.ts@@ -224,6 +224,7 @@ describe("runEnvironmentChecks", () => {expect(result.outcomes.find((outcome) => outcome.name === "Chrome")).toMatchObject({ok: false,title: "Chrome not found",+ detail: "ENOTDIR: not a directory, scandir 'chrome-headless-shell'",hint: "Run: npx hyperframes browser ensure",});expect(result.browser).toBeUndefined();diff --git a/packages/cli/src/browser/preflight.ts b/packages/cli/src/browser/preflight.tsindex d706192baa..14c86e9f16 100644--- a/packages/cli/src/browser/preflight.ts+++ b/packages/cli/src/browser/preflight.ts@@ -12,6 +12,7 @@ import {} from "./linuxDeps.js";import { getFreeDiskMb } from "../telemetry/system.js";import { runCancellableProcess } from "../utils/cancellableProcess.js";+import { normalizeErrorMessage } from "../utils/errorMessage.js";export type EnvironmentCheckLevel = "ok" | "warn" | "error";@@ -314,13 +315,15 @@ async function checkChrome(// failure as "Chrome not found" rather than letting it crash the caller// (notably `doctor`, which is documented to exit 0 even when checks fail).let info: Awaited<ReturnType<typeof findBrowser>>;+ let failure: string | undefined;try {info = signal? await ensureBrowser({ preferManagedChrome: true, signal }): await findBrowser();- } catch {+ } catch (error) {if (signal?.aborted) signal.throwIfAborted();info = undefined;+ failure = normalizeErrorMessage(error);}if (info) {return chromeLaunchOutcome(@@ -341,7 +344,7 @@ async function checkChrome(ok: false,level: "error",title: "Chrome not found",- detail: "Chrome Headless Shell is required for local rendering.",+ detail: failure ?? "Chrome Headless Shell is required for local rendering.",hint: "Run: npx hyperframes browser ensure",};}diff --git a/packages/cli/src/commands/browser.test.ts b/packages/cli/src/commands/browser.test.tsnew file mode 100644index 0000000000..3d125573bb--- /dev/null+++ b/packages/cli/src/commands/browser.test.ts@@ -0,0 +1,73 @@+import { beforeEach, describe, expect, it, vi } from "vitest";++const spinners: Array<{ running: boolean }> = [];+const logError = vi.fn();+vi.mock("@clack/prompts", () => ({+ intro: vi.fn(),+ outro: vi.fn(),+ log: { error: (...args: unknown[]) => logError(...args) },+ spinner: () => {+ const state = { running: false };+ spinners.push(state);+ return {+ start: () => (state.running = true),+ message: vi.fn(),+ stop: () => (state.running = false),+ };+ },+}));++const ensureBrowser = vi.fn();+vi.mock("../browser/manager.js", () => ({+ ensureBrowser: (...args: unknown[]) => ensureBrowser(...args),+ findBrowser: vi.fn(),+ clearBrowser: vi.fn(),+ managedChromeVersion: () => "152.0.7977.30",+ CACHE_DIR: "/cache",+ isLinuxArm: () => false,+}));+vi.mock("../telemetry/events.js", () => ({ trackBrowserInstall: vi.fn() }));++const { default: browserCommand } = await import("./browser.js");++function runEnsure(force: boolean) {+ return browserCommand.run!({+ args: { _: [], subcommand: "ensure", force },+ rawArgs: [],+ cmd: browserCommand,+ });+}++// A spinner left running keeps Node's event loop alive, so the CLI never exits.+describe("browser ensure", () => {+ beforeEach(() => {+ spinners.length = 0;+ logError.mockReset();+ ensureBrowser.mockReset();+ vi.spyOn(console, "log").mockImplementation(() => {});+ });++ it.each([false, true])(+ "stops its spinner and fails when ensure throws (force=%s)",+ async (force) => {+ ensureBrowser.mockRejectedValue(+ new Error("chrome-headless-shell is missing after unzipping"),+ );++ await expect(runEnsure(force)).rejects.toThrow("Command failed");++ expect(logError).toHaveBeenCalledWith("chrome-headless-shell is missing after unzipping");+ expect(spinners.length).toBeGreaterThan(0);+ expect(spinners.filter((s) => s.running)).toEqual([]);+ },+ );++ it.each([false, true])("leaves no spinner running after success (force=%s)", async (force) => {+ ensureBrowser.mockResolvedValue({ executablePath: "/chrome", source: "download" });++ await runEnsure(force);++ expect(spinners.length).toBeGreaterThan(0);+ expect(spinners.filter((s) => s.running)).toEqual([]);+ });+});diff --git a/packages/cli/src/commands/browser.ts b/packages/cli/src/commands/browser.tsindex 47bc922582..9bb65263c2 100644--- a/packages/cli/src/commands/browser.ts+++ b/packages/cli/src/commands/browser.ts@@ -18,8 +18,17 @@ import {managedChromeVersion,CACHE_DIR,isLinuxArm,+ type BrowserResult,} from "../browser/manager.js";import { trackBrowserInstall } from "../telemetry/events.js";+import { normalizeErrorMessage } from "../utils/errorMessage.js";++function printBrowser(browser: BrowserResult): void {+ console.log();+ console.log(` ${c.dim("Source:")} ${c.bold(browser.source)}`);+ console.log(` ${c.dim("Path:")} ${c.bold(browser.executablePath)}`);+ console.log();+}async function runEnsure(options?: { force?: boolean }): Promise<void> {clack.intro(c.bold("hyperframes browser ensure"));@@ -32,10 +41,7 @@ async function runEnsure(options?: { force?: boolean }): Promise<void> {const existing = await findBrowser();if (existing) {s.stop(c.success("System Chromium found"));- console.log();- console.log(` ${c.dim("Source:")} ${c.bold(existing.source)}`);- console.log(` ${c.dim("Path:")} ${c.bold(existing.executablePath)}`);- console.log();+ printBrowser(existing);clack.outro(c.success("Ready to render."));return;}@@ -46,10 +52,7 @@ async function runEnsure(options?: { force?: boolean }): Promise<void> {// Delegate to ensureBrowser which handles the full ARM64 install flow.try {const result = await ensureBrowser();- console.log();- console.log(` ${c.dim("Source:")} ${c.bold(result.source)}`);- console.log(` ${c.dim("Path:")} ${c.bold(result.executablePath)}`);- console.log();+ printBrowser(result);clack.outro(c.success("Chromium ready. You can now render on ARM64."));} catch (err) {// The ARM64 auto-install failed: the browser is NOT ready, so this is a@@ -61,15 +64,17 @@ async function runEnsure(options?: { force?: boolean }): Promise<void> {return;}+ // Every exit path stops the spinner: a running one keeps the process alive after a failure.+ const downloading = `Downloading Chrome Headless Shell ${c.dim("v" + managedChromeVersion())}`;const s = clack.spinner();- if (!options?.force) {- // Resolve with `preferManagedChrome` so this reports what `render`- // actually uses — a system Chrome without our pinned HF cache still- // downloads on the next render, so it shouldn't be reported as "found".- s.start("Looking for an existing browser...");-- let lastPct = -1;- const existing = await ensureBrowser({+ s.start(options?.force ? `${downloading}...` : "Looking for an existing browser...");+ let lastPct = -1;+ let result: BrowserResult;+ try {+ // `preferManagedChrome` reports what `render` actually uses: a system Chrome+ // without our pinned build still downloads on the next render.+ result = await ensureBrowser({+ force: options?.force,preferManagedChrome: true,onProgress: (downloaded, total) => {if (total <= 0) return;@@ -77,52 +82,20 @@ async function runEnsure(options?: { force?: boolean }): Promise<void> {if (pct > lastPct) {lastPct = pct;s.message(- `Downloading Chrome Headless Shell ${c.dim("v" + managedChromeVersion())} — ${c.progress(pct + "%")} ${c.dim("(" + formatBytes(downloaded) + " / " + formatBytes(total) + ")")}`,+ `${downloading} — ${c.progress(pct + "%")} ${c.dim("(" + formatBytes(downloaded) + " / " + formatBytes(total) + ")")}`,);}},});-- if (existing.source === "download") trackBrowserInstall();- s.stop(c.success(existing.source === "download" ? "Download complete" : "Browser found"));- console.log();- console.log(` ${c.dim("Source:")} ${c.bold(existing.source)}`);- console.log(` ${c.dim("Path:")} ${c.bold(existing.executablePath)}`);- console.log();- clack.outro(c.success("Ready to render."));- return;+ } catch (err) {+ s.stop(c.error("Browser not available"));+ clack.log.error(normalizeErrorMessage(err));+ failCommand(1, err);}- s.start("Re-downloading the managed browser...");-- const downloadSpinner = clack.spinner();- downloadSpinner.start(- `Downloading Chrome Headless Shell ${c.dim("v" + managedChromeVersion())}...`,- );-- let lastPct = -1;- const result = await ensureBrowser({- force: options?.force,- onProgress: (downloaded, total) => {- if (total <= 0) return;- const pct = Math.floor((downloaded / total) * 100);- if (pct > lastPct) {- lastPct = pct;- downloadSpinner.message(- `Downloading Chrome Headless Shell ${c.dim("v" + managedChromeVersion())} — ${c.progress(pct + "%")} ${c.dim("(" + formatBytes(downloaded) + " / " + formatBytes(total) + ")")}`,- );- }- },- });-- downloadSpinner.stop(c.success("Download complete"));- trackBrowserInstall();-- console.log();- console.log(` ${c.dim("Source:")} ${c.bold(result.source)}`);- console.log(` ${c.dim("Path:")} ${c.bold(result.executablePath)}`);- console.log();-+ if (result.source === "download") trackBrowserInstall();+ s.stop(c.success(result.source === "download" ? "Download complete" : "Browser found"));+ printBrowser(result);clack.outro(c.success("Ready to render."));}diff --git a/packages/cli/src/renderSetupWorker.test.ts b/packages/cli/src/renderSetupWorker.test.tsindex e8f101c4c7..0fd8ce4499 100644--- a/packages/cli/src/renderSetupWorker.test.ts+++ b/packages/cli/src/renderSetupWorker.test.ts@@ -1,5 +1,11 @@import { describe, expect, it, vi } from "vitest";-import { installRenderSetupSignalHandlers } from "./renderSetupWorkerLifecycle.js";+import {+ installRenderSetupSignalHandlers,+ renderSetupFailureFrom,+ renderSetupErrorLine,+ renderSetupResultFrom,+ renderSetupResultLine,+} from "./renderSetupWorkerLifecycle.js";describe("render setup worker signal lifecycle", () => {function collectHandlers(handleHangup = true) {@@ -53,3 +59,36 @@ describe("render setup worker signal lifecycle", () => {},);});++describe("render setup worker failure line", () => {+ it("carries the whole reason past the crash output around it", () => {+ const reason =+ "Failed to install chrome-headless-shell: missing.\n\n export HYPERFRAMES_BROWSER_PATH=x";+ const failure = new Error(reason, { cause: new Error("tar.exe extraction failed") });+ const stderr = [+ "warning before",+ renderSetupErrorLine(failure).trimEnd(),+ "/worker.ts:20",+ " throw error;",+ "Error: Failed to install chrome-headless-shell: missing.",+ " at downloadBrowser (manager.ts:845:11)",+ ].join("\n");++ expect(renderSetupFailureFrom(stderr)).toEqual({ reason, earlierOutput: "warning before" });+ });++ it.each([+ ["a worker that crashed without one", "Error: boom\n at x (y.ts:1:1)"],+ ["a cut-off line", 'HYPERFRAMES_RENDER_SETUP_ERROR:"Failed to ins'],+ ["an empty message", renderSetupErrorLine(new Error(""))],+ ])("finds no reason in %s, so the parent shows the raw output", (_label, stderr) => {+ expect(renderSetupFailureFrom(stderr)).toBeUndefined();+ });++ it("reads back the result line the worker writes", () => {+ const result = { executablePath: "/chrome", source: "cache" };++ expect(renderSetupResultFrom(`noise\n${renderSetupResultLine(result)}`)).toEqual(result);+ expect(renderSetupResultFrom("noise only")).toBeUndefined();+ });+});diff --git a/packages/cli/src/renderSetupWorker.ts b/packages/cli/src/renderSetupWorker.tsindex b55364aaa8..5a12ab0405 100644--- a/packages/cli/src/renderSetupWorker.ts+++ b/packages/cli/src/renderSetupWorker.ts@@ -2,9 +2,12 @@ import { constants, setPriority } from "node:os";import { ensureBrowser, releaseOwnedBrowserInstallLock } from "./browser/manager.js";import { lintProject } from "./utils/lintProject.js";import { killOrphanedProcesses } from "./utils/orphanCleanup.js";-import { installRenderSetupSignalHandlers } from "./renderSetupWorkerLifecycle.js";+import {+ installRenderSetupSignalHandlers,+ renderSetupErrorLine,+ renderSetupResultLine,+} from "./renderSetupWorkerLifecycle.js";-const RESULT_PREFIX = "HYPERFRAMES_RENDER_SETUP_RESULT:";const mode = process.argv[2];const input = JSON.parse(process.env.HYPERFRAMES_RENDER_SETUP_INPUT ?? "{}");@@ -15,24 +18,30 @@ const disposeSignalHandlers = installRenderSetupSignalHandlers(process.env.HYPERFRAMES_RENDER_DETACHED !== "1",);-let result: unknown;-if (mode === "browser") {- result = await ensureBrowser(input);-} else if (mode === "lint") {- // Nobody waits on a background lint the way they wait on a Studio boot, so it takes idle CPU only.- setPriority(constants.priority.PRIORITY_LOW);- result = await lintProject(- input.projectDir,- input.entryFile,- input.host ? { host: input.host } : undefined,- );-} else if (mode === "orphan-cleanup") {- const killed = killOrphanedProcesses();- result = killed;- if (killed > 0) await new Promise((resolve) => setTimeout(resolve, 600));-} else {+async function runMode(): Promise<unknown> {+ if (mode === "browser") return ensureBrowser(input);+ if (mode === "lint") {+ // Nobody waits on a background lint the way they wait on a Studio boot, so it takes idle CPU only.+ setPriority(constants.priority.PRIORITY_LOW);+ return lintProject(+ input.projectDir,+ input.entryFile,+ input.host ? { host: input.host } : undefined,+ );+ }+ if (mode === "orphan-cleanup") {+ const killed = killOrphanedProcesses();+ if (killed > 0) await new Promise((resolve) => setTimeout(resolve, 600));+ return killed;+ }throw new Error(`Unknown render setup mode: ${mode}`);}-disposeSignalHandlers();-process.stdout.write(RESULT_PREFIX + JSON.stringify(result) + "\n");+try {+ const result = await runMode().finally(disposeSignalHandlers);+ process.stdout.write(renderSetupResultLine(result));+} catch (error) {+ process.stderr.write(renderSetupErrorLine(error), () => {+ throw error;+ });+}diff --git a/packages/cli/src/renderSetupWorkerLifecycle.ts b/packages/cli/src/renderSetupWorkerLifecycle.tsindex 5bdb80a7b0..751acdfbe9 100644--- a/packages/cli/src/renderSetupWorkerLifecycle.ts+++ b/packages/cli/src/renderSetupWorkerLifecycle.ts@@ -1,4 +1,8 @@+import { normalizeErrorMessage } from "./utils/errorMessage.js";+const RENDER_SETUP_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const;+const RENDER_SETUP_RESULT_PREFIX = "HYPERFRAMES_RENDER_SETUP_RESULT:";+const RENDER_SETUP_ERROR_PREFIX = "HYPERFRAMES_RENDER_SETUP_ERROR:";type RenderSetupSignal = (typeof RENDER_SETUP_SIGNALS)[number];@@ -30,3 +34,43 @@ export function installRenderSetupSignalHandlers(for (const [signal, handler] of handlers) signalTarget.off(signal, handler);};}++function prefixedLine(prefix: string, value: unknown): string {+ return prefix + JSON.stringify(value) + "\n";+}++function parseJson(text: string): unknown {+ try {+ return JSON.parse(text);+ } catch {+ return undefined;+ }+}++function prefixedValue(output: string, prefix: string): unknown {+ const line = output.split(/\r?\n/).find((text) => text.startsWith(prefix));+ return line === undefined ? undefined : parseJson(line.slice(prefix.length));+}++export function renderSetupResultLine(result: unknown): string {+ return prefixedLine(RENDER_SETUP_RESULT_PREFIX, result);+}++export function renderSetupResultFrom(stdout: string): unknown {+ return prefixedValue(stdout, RENDER_SETUP_RESULT_PREFIX);+}++export function renderSetupErrorLine(error: unknown): string {+ return prefixedLine(RENDER_SETUP_ERROR_PREFIX, normalizeErrorMessage(error));+}++export function renderSetupFailureFrom(+ stderr: string,+): { reason: string; earlierOutput: string } | undefined {+ const lines = stderr.split(/\r?\n/);+ const at = lines.findIndex((text) => text.startsWith(RENDER_SETUP_ERROR_PREFIX));+ const reason =+ at === -1 ? undefined : parseJson(lines[at]!.slice(RENDER_SETUP_ERROR_PREFIX.length));+ if (typeof reason !== "string" || reason === "") return undefined;+ return { reason, earlierOutput: lines.slice(0, at).join("\n") };+}diff --git a/packages/cli/src/utils/cancellableProcess.test.ts b/packages/cli/src/utils/cancellableProcess.test.tsindex 4c868f11d6..92a937c8b7 100644--- a/packages/cli/src/utils/cancellableProcess.test.ts+++ b/packages/cli/src/utils/cancellableProcess.test.ts@@ -1,8 +1,8 @@import { existsSync, mkdtempSync, readFileSync, rmSync } from "node:fs";import { tmpdir } from "node:os";import { join } from "node:path";-import { describe, expect, it } from "vitest";-import { runCancellableProcess } from "./cancellableProcess.js";+import { describe, expect, it, vi } from "vitest";+import { runCancellableProcess, runRenderSetupWorker } from "./cancellableProcess.js";import { testProcessIsAlive, waitForTestCondition } from "./processTestUtils.js";const IS_POSIX = process.platform !== "win32";@@ -79,3 +79,16 @@ describe.skipIf(!IS_POSIX)("cancellable process tree teardown", () => {}}, 5_000);});++describe("render setup worker failure", () => {+ it("rejects with only the worker's reason, not its crash output", async () => {+ const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);+ try {+ const failure = runRenderSetupWorker("bogus" as "lint", {}, {});++ await expect(failure).rejects.toThrow(/^Unknown render setup mode: bogus$/);+ } finally {+ stderr.mockRestore();+ }+ });+});diff --git a/packages/cli/src/utils/cancellableProcess.ts b/packages/cli/src/utils/cancellableProcess.tsindex 32bfa27772..4195070268 100644--- a/packages/cli/src/utils/cancellableProcess.ts+++ b/packages/cli/src/utils/cancellableProcess.ts@@ -1,6 +1,7 @@import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process";import { fileURLToPath } from "node:url";import { terminateProcessTree } from "./processTree.js";+import { renderSetupFailureFrom, renderSetupResultFrom } from "../renderSetupWorkerLifecycle.js";export interface CancellableProcessResult {stdout: string;@@ -187,7 +188,13 @@ export function runCancellableProcess(});}-const SETUP_RESULT_PREFIX = "HYPERFRAMES_RENDER_SETUP_RESULT:";+function renderSetupError(error: unknown): unknown {+ if (!(error instanceof CancellableProcessError)) return error;+ const failure = renderSetupFailureFrom(error.stderr);+ if (failure?.earlierOutput.trim()) process.stderr.write(`${failure.earlierOutput.trimEnd()}\n`);+ const reason = failure?.reason ?? error.stderr.trim();+ return reason ? new Error(reason, { cause: error }) : error;+}export async function runRenderSetupWorker<T>(mode: "browser" | "lint" | "orphan-cleanup",@@ -216,16 +223,10 @@ export async function runRenderSetupWorker<T>();} catch (error) {if (options.signal?.aborted) options.signal.throwIfAborted();- if (error instanceof CancellableProcessError && error.stderr.trim()) {- throw new Error(error.stderr.trim(), { cause: error });- }- throw error;+ throw renderSetupError(error);}if (result.stderr) process.stderr.write(result.stderr);- const encoded = result.stdout- .split(/\r?\n/)- .find((line) => line.startsWith(SETUP_RESULT_PREFIX))- ?.slice(SETUP_RESULT_PREFIX.length);- if (!encoded) throw new Error(`${mode} setup process exited without a result`);- return JSON.parse(encoded) as T;+ const value = renderSetupResultFrom(result.stdout);+ if (value === undefined) throw new Error(`${mode} setup process exited without a result`);+ return value as T;}