Write HTML. Render video. Built for agents.
JavaScript aiai-agentsanimationclaude-codeffmpegframeworkgsaphtmlhtml-to-videomcpmotion-graphicspuppeteerrenderingtypescriptvideo-editor
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.tsindex 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 chaindiff --git a/packages/cli/src/browser/manager.ts b/packages/cli/src/browser/manager.tsindex 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<BrowserRreturn 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<BrowserRthrow 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.tsindex 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.tsindex 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.tsindex 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-duplicationimport { 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: