Skip to content

Write HTML. Render video. Built for agents.

fix(cli): a first render on a nearly full disk refuses at once instead of hanging (#6006)

Miguel Ángel6cb9ce096f80
diff --git a/packages/cli/src/browser/manager.test.ts b/packages/cli/src/browser/manager.test.ts
index 1164d0ecd6..b94afa9802 100644
--- a/packages/cli/src/browser/manager.test.ts
+++ b/packages/cli/src/browser/manager.test.ts
@@ -1415,6 +1415,77 @@ describe("downloadBrowser — install failure surfaces HYPERFRAMES_BROWSER_PATH
);
});
+describe("downloadBrowser — too little disk for the browser", () => {
+ beforeEach(() => {
+ vi.resetModules();
+ delete process.env["HYPERFRAMES_BROWSER_PATH"];
+ delete process.env["PRODUCER_HEADLESS_SHELL_PATH"];
+ installChildProcessMocks();
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ vi.doUnmock("node:fs");
+ vi.doUnmock("node:os");
+ vi.doUnmock("node:child_process");
+ vi.doUnmock("@puppeteer/browsers");
+ vi.doUnmock("../telemetry/system.js");
+ });
+
+ // On a disk that fills mid-unzip, unzip waits on a "Continue? (y/n)" nobody answers, holding the install lock.
+ it.each([
+ { freeMb: 400, downloads: false },
+ { freeMb: 4096, downloads: true },
+ { freeMb: null, downloads: true },
+ ])("downloads only with room for it: $freeMb MB free", async ({ freeMb, downloads }) => {
+ installFsMocks({ existing: new Set([CACHE_ROOT]) });
+ const install = vi.fn(async () => ({ executablePath: HF_BINARY }));
+ installPuppeteerBrowsersMock({ installedInHfCache: [], installImpl: install });
+ const freeDiskMb = vi.fn((): number | null => freeMb);
+ vi.doMock("../telemetry/system.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("../telemetry/system.js")>()),
+ getFreeDiskMb: freeDiskMb,
+ }));
+
+ const { ensureBrowser } = await import("./manager.js");
+ const result = await ensureBrowser().catch((error: Error) => error);
+
+ expect(freeDiskMb).toHaveBeenCalledWith(CACHE_ROOT);
+ expect(install).toHaveBeenCalledTimes(downloads ? 1 : 0);
+ if (downloads) expect(result).toMatchObject({ source: "download" });
+ else
+ expect((result as Error).message).toMatch(
+ /^Low disk space: .*needs about 512 MB.*400 MB free/,
+ );
+ });
+
+ it("removes a killed install's leftovers before reading free space, so they never count against it", async () => {
+ const home = useRealCacheHome();
+ installPuppeteerBrowsersMock({ installedInHfCache: [] });
+ const staging = join(home, ".cache", "hyperframes", ".chrome-staging-dead");
+ let leftoverWhenRead: boolean | undefined;
+ vi.doMock("../telemetry/system.js", async (importOriginal) => ({
+ ...(await importOriginal<typeof import("../telemetry/system.js")>()),
+ getFreeDiskMb: () => {
+ leftoverWhenRead = existsSync(staging);
+ return 400;
+ },
+ }));
+ try {
+ const { ensureBrowser, sweepKilledInstalls } = await import("./manager.js");
+ mkdirSync(join(staging, "partial"), { recursive: true });
+ await expect(ensureBrowser({ force: true })).rejects.toThrow(/^Low disk space/);
+ expect(leftoverWhenRead).toBe(false);
+
+ mkdirSync(join(staging, "partial"), { recursive: true });
+ await sweepKilledInstalls();
+ expect(existsSync(staging)).toBe(false);
+ } finally {
+ rmSync(home, { recursive: true, force: true });
+ }
+ });
+});
+
// Regression guard for HF#2103: `hyperframes render` hung forever on macOS
// (Apple Silicon) under Node >= 24.16. Root cause was NOT in this file — it was
// the extractor `@puppeteer/browsers` <3.0.2 shells out to. That chain
diff --git a/packages/cli/src/browser/manager.ts b/packages/cli/src/browser/manager.ts
index cf59e7d1d5..7468b05e13 100644
--- a/packages/cli/src/browser/manager.ts
+++ b/packages/cli/src/browser/manager.ts
@@ -20,6 +20,7 @@ import {
managedChromeVersion,
pickSharedShell,
} from "@hyperframes/engine/chrome-host-ceiling";
+import { getFreeDiskMb } from "../telemetry/system.js";
import { normalizeErrorMessage } from "../utils/errorMessage.js";
import { runRenderSetupWorker } from "../utils/cancellableProcess.js";
@@ -39,6 +40,7 @@ async function loadPuppeteerBrowsers(): Promise<PuppeteerBrowsers> {
const CACHE_ROOT_DIR = join(homedir(), ".cache", "hyperframes");
const CACHE_DIR = join(homedir(), ".cache", "hyperframes", "chrome");
+const ARCHIVE_PLUS_UNPACKED_SHELL_MB = 512;
// Puppeteer's managed cache — where `@puppeteer/browsers install
// chrome-headless-shell` (and `puppeteer install`) drop binaries. The engine's
// `resolveHeadlessShellPath` scans the same directory; the CLI must look here
@@ -696,6 +698,15 @@ async function downloadBrowser(options?: EnsureBrowserOptions): Promise<BrowserR
return ensureLinuxArmBrowser(options);
}
+ // Callers hold the install lock, so every leftover belongs to an install that was killed mid-way.
+ removeInstallLeftovers();
+ const freeMb = getFreeDiskMb(CACHE_ROOT_DIR);
+ if (freeMb !== null && freeMb < ARCHIVE_PLUS_UNPACKED_SHELL_MB) {
+ throw new Error(
+ `Low disk space: Chrome Headless Shell needs about ${ARCHIVE_PLUS_UNPACKED_SHELL_MB} MB to download, ` +
+ `${freeMb} MB free at ${CACHE_ROOT_DIR}. Free disk space, then retry.`,
+ );
+ }
const { Browser, detectBrowserPlatform, install } = await loadPuppeteerBrowsers();
const platform = detectBrowserPlatform();
@@ -703,8 +714,6 @@ async function downloadBrowser(options?: EnsureBrowserOptions): Promise<BrowserR
throw new Error(`Unsupported platform: ${process.platform} ${process.arch}`);
}
- // Callers hold the install lock, so every leftover belongs to an install that was killed mid-way.
- removeInstallLeftovers();
// 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 });
@@ -801,6 +810,9 @@ const STAGING_PREFIX = ".chrome-staging-";
const REPLACED_PREFIX = ".chrome-replaced-";
// Staging and set-aside dirs outlive an install killed by a signal, since `finally` never runs.
+const isInstallLeftover = (name: string) =>
+ name.startsWith(STAGING_PREFIX) || name.startsWith(REPLACED_PREFIX);
+
function removeInstallLeftovers(): boolean {
let names: string[];
try {
@@ -809,14 +821,18 @@ function removeInstallLeftovers(): boolean {
if (isErrno(err, "ENOENT")) return false;
throw err;
}
- const leftovers = names.filter(
- (name) => name.startsWith(STAGING_PREFIX) || name.startsWith(REPLACED_PREFIX),
- );
+ const leftovers = names.filter(isInstallLeftover);
for (const name of leftovers)
rmSync(join(CACHE_ROOT_DIR, name), { recursive: true, force: true });
return leftovers.length > 0;
}
+export async function sweepKilledInstalls(): Promise<void> {
+ const names = existsSync(CACHE_ROOT_DIR) ? readdirSync(CACHE_ROOT_DIR) : [];
+ if (!names.some(isInstallLeftover)) return;
+ await withInstallLock(async () => removeInstallLeftovers());
+}
+
// Deletes the managed Chrome cache and interrupted-install leftovers; true when any of them existed.
export function clearBrowser(): boolean {
const removedLeftovers = removeInstallLeftovers();
diff --git a/packages/cli/src/commands/render.test.ts b/packages/cli/src/commands/render.test.ts
index 292098a6b0..47b3398c61 100644
--- a/packages/cli/src/commands/render.test.ts
+++ b/packages/cli/src/commands/render.test.ts
@@ -227,6 +227,7 @@ vi.mock("../browser/ffmpeg.js", async (importOriginal) => {
});
vi.mock("../browser/preflight.js", () => ({
+ checkDisk: vi.fn(() => ({ name: "Disk", ok: true, level: "ok", detail: "mock" })),
runEnvironmentChecks: vi.fn(async () => {
preflightState.onRun?.();
return preflightState.result;
@@ -241,6 +242,7 @@ vi.mock("../browser/preflight.js", () => ({
// the shared `~/.cache/hyperframes/chrome`, racing other packages' browser
// tests in CI.
vi.mock("../browser/manager.js", () => ({
+ sweepKilledInstalls: vi.fn(async () => {}),
ensureBrowser: vi.fn(async (options?: { signal?: AbortSignal }) => {
await browserManagerState.onEnsure?.(options?.signal);
return { executablePath: "/mock/chrome", source: "cache" };
diff --git a/packages/cli/src/commands/render/execute.test.ts b/packages/cli/src/commands/render/execute.test.ts
index f67b3e7e69..33b05ef242 100644
--- a/packages/cli/src/commands/render/execute.test.ts
+++ b/packages/cli/src/commands/render/execute.test.ts
@@ -3,7 +3,9 @@ import { tmpdir } from "node:os";
import { join } from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
import { createRenderPlan } from "./plan.js";
-import { batchRowRenderOptions, renderOptionsFromPlan } from "./execute.js";
+import { batchRowRenderOptions, executeRenderPlan, renderOptionsFromPlan } from "./execute.js";
+import * as manager from "../../browser/manager.js";
+import * as system from "../../telemetry/system.js";
import { wantsDesktopHint } from "../render.js";
describe("renderOptionsFromPlan", () => {
@@ -56,3 +58,43 @@ describe("the desktop-app line after a render", () => {
}
});
});
+
+describe("a render on a nearly full disk", () => {
+ let projectDir: string;
+
+ beforeEach(() => {
+ projectDir = mkdtempSync(join(tmpdir(), "hf-render-disk-"));
+ writeFileSync(join(projectDir, "index.html"), '<main data-composition-id="main"></main>');
+ vi.spyOn(console, "error").mockImplementation(() => {});
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ rmSync(projectDir, { recursive: true, force: true });
+ });
+
+ // A first render downloads its browser; on a disk that fills mid-unzip, unzip waits on a prompt forever.
+ it.each([
+ { freeMb: 400, downloads: false },
+ { freeMb: 4096, downloads: true },
+ ])(
+ "checks the disk before getting the browser: $freeMb MB free",
+ async ({ freeMb, downloads }) => {
+ const sweep = vi.spyOn(manager, "sweepKilledInstalls").mockResolvedValue();
+ const freeDisk = vi.spyOn(system, "getFreeDiskMb").mockReturnValue(freeMb);
+ const ensureBrowser = vi
+ .spyOn(manager, "ensureBrowser")
+ .mockRejectedValue(new Error("offline"));
+ const plan = createRenderPlan({ dir: projectDir, quiet: true });
+
+ await expect(executeRenderPlan(plan, {} as never)).rejects.toThrow("Command failed");
+
+ expect(ensureBrowser).toHaveBeenCalledTimes(downloads ? 1 : 0);
+ expect(sweep.mock.invocationCallOrder[0]).toBeLessThan(
+ freeDisk.mock.invocationCallOrder[0] ?? 0,
+ );
+ const said = vi.mocked(console.error).mock.calls.flat().join("\n");
+ expect(said.includes("Low disk space")).toBe(!downloads);
+ },
+ );
+});
diff --git a/packages/cli/src/commands/render/execute.ts b/packages/cli/src/commands/render/execute.ts
index f85a55cbe5..fae94c1c99 100644
--- a/packages/cli/src/commands/render/execute.ts
+++ b/packages/cli/src/commands/render/execute.ts
@@ -1,5 +1,6 @@
// fallow-ignore-file code-duplication
import { mkdirSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
import type { CanvasResolution, OutputResolutionIssueKind } from "@hyperframes/core";
import { c } from "../../ui/colors.js";
import { errorBox, formatBytes } from "../../ui/format.js";
@@ -89,6 +90,7 @@ export async function executeRenderPlan(
}
}
+ if (!plan.useDocker) await refuseLowDiskBeforeBrowserDownload(plan);
const browserPath = plan.useDocker
? undefined
: await ensureRenderBrowser(plan, cancellation?.signal);
@@ -180,6 +182,16 @@ function assertRenderActive(cancellation?: RenderCancellationScope): void {
cancellation?.signal.throwIfAborted();
}
+async function refuseLowDiskBeforeBrowserDownload(plan: RenderPlan): Promise<void> {
+ const { checkDisk } = await import("../../browser/preflight.js");
+ await (await import("../../browser/manager.js")).sweepKilledInstalls();
+ const paths = new Set([tmpdir(), renderOutputDirectory(plan)]);
+ const low = [...paths].map((path) => checkDisk(path)).filter((outcome) => !outcome.ok);
+ if (low.length === 0) return;
+ for (const check of low) errorBox(check.title ?? "Low disk space", check.detail, check.hint);
+ failCommand();
+}
+
async function ensureRenderBrowser(plan: RenderPlan, signal?: AbortSignal): Promise<string> {
const { ensureBrowser } = await import("../../browser/manager.js");
let browserSpinner: