From 577bdf67013236e02fd5c8c1fc4c00905101ead2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miguel=20=C3=81ngel?= Date: Fri, 9 Oct 2026 16:21:46 +0000 Subject: [PATCH] fix(cli): browser ensure fails when the unzip leaves no Chrome executable (#5329) * fix(cli): browser ensure fails when the unzip leaves no Chrome executable * refactor(cli): keep install debug output and report only the last unzip attempt * fix(cli): browser ensure exits after a failure or a --force download * fix(cli): browser checks name why Chrome could not be installed * fix(cli): render shows why its setup step failed instead of a crash dump * refactor(cli): build the browser download label and staged test path once * refactor(cli): one owner for the render setup result line * fix(cli): render setup failures report through one error line * refactor(cli): one reader and writer for both render setup lines --- packages/cli/src/browser/manager.test.ts | 95 ++++++++++++++++--- packages/cli/src/browser/manager.ts | 37 +++++++- packages/cli/src/browser/preflight.test.ts | 1 + packages/cli/src/browser/preflight.ts | 7 +- packages/cli/src/commands/browser.test.ts | 73 ++++++++++++++ packages/cli/src/commands/browser.ts | 85 ++++++----------- packages/cli/src/renderSetupWorker.test.ts | 41 +++++++- packages/cli/src/renderSetupWorker.ts | 49 ++++++---- .../cli/src/renderSetupWorkerLifecycle.ts | 44 +++++++++ .../cli/src/utils/cancellableProcess.test.ts | 17 +++- packages/cli/src/utils/cancellableProcess.ts | 23 ++--- 11 files changed, 363 insertions(+), 109 deletions(-) create mode 100644 packages/cli/src/commands/browser.test.ts 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 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 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>; + 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 { clack.intro(c.bold("hyperframes browser ensure")); @@ -32,10 +41,7 @@ async function runEnsure(options?: { force?: boolean }): Promise { 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 { // 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 { 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 { 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 { + 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( mode: "browser" | "lint" | "orphan-cleanup", @@ -216,16 +223,10 @@ export async function runRenderSetupWorker( ); } 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; }