Skip to content

Write HTML. Render video. Built for agents.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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;
}