Skip to content

Write HTML. Render video. Built for agents.

fix(cli): the browser download unpacks on machines without an unzip command (#5433)

Miguel Ángel9e9b613ccf86
diff --git a/.fallowrc.jsonc b/.fallowrc.jsonc
index 07d33873a9..56bf9eafd0 100644
--- a/.fallowrc.jsonc
+++ b/.fallowrc.jsonc
@@ -426,6 +426,8 @@
// as a direct dep to guarantee installation even when transitive
// resolution fails (corrupted cache, dedup edge cases).
"debug",
+ // @puppeteer/browsers' optional peer: its zip fallback when no system `unzip` exists.
+ "yauzl",
// Loaded through the optional package loader for Gemini vision captioning.
"@google/genai",
"puppeteer",
diff --git a/bun.lock b/bun.lock
index a047d11b09..8a63fadcea 100644
--- a/bun.lock
+++ b/bun.lock
@@ -81,6 +81,7 @@
"prettier": "^3.8.1",
"puppeteer-core": "^25.10.0",
"sharp": "^0.35.0",
+ "yauzl": "^3.4.0",
},
"devDependencies": {
"@clack/prompts": "^1.1.0",
@@ -1848,6 +1849,8 @@
"pathe": ["[email protected]", "", {}, "sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w=="],
+ "pend": ["[email protected]", "", {}, "sha512-F3asv42UuXchdzt+xXqfW1OGlVBe+mxa2mqI0pg5yAHZPvFmY3Y6drSf/GQ1A86WgWEN9Kzh/WrgKa6iGcHXLg=="],
+
"picocolors": ["[email protected]", "", {}, "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA=="],
"picomatch": ["[email protected]", "", {}, "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A=="],
@@ -2130,6 +2133,8 @@
"yargs-parser": ["[email protected]", "", {}, "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw=="],
+ "yauzl": ["[email protected]", "", { "dependencies": { "pend": "~1.2.0" } }, "sha512-jIH9yLR9wqr0wOS0TpBvo/g/2UgZH5qePVbjgRliiF0BYvOZyaBknKsF+x9Iht0O6sqgnB93rCICdOZFecJuDw=="],
+
"yocto-queue": ["[email protected]", "", {}, "sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q=="],
"zod": ["[email protected]", "", {}, "sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ=="],
diff --git a/packages/cli/package.json b/packages/cli/package.json
index 487e9d87dd..315a0c2683 100644
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -47,7 +47,8 @@
"postcss": "^8.5.8",
"prettier": "^3.8.1",
"puppeteer-core": "^25.10.0",
- "sharp": "^0.35.0"
+ "sharp": "^0.35.0",
+ "yauzl": "^3.4.0"
},
"devDependencies": {
"@clack/prompts": "^1.1.0",
diff --git a/packages/cli/src/browser/unzipFallback.test.ts b/packages/cli/src/browser/unzipFallback.test.ts
new file mode 100644
index 0000000000..6e1d0999a0
--- /dev/null
+++ b/packages/cli/src/browser/unzipFallback.test.ts
@@ -0,0 +1,49 @@
+import { existsSync, mkdtempSync, rmSync } from "node:fs";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { tmpdir } from "node:os";
+import { join, relative } from "node:path";
+import {
+ Browser,
+ computeExecutablePath,
+ detectBrowserPlatform,
+ install,
+} from "@puppeteer/browsers";
+import AdmZip from "adm-zip";
+import { afterEach, expect, it, vi } from "vitest";
+
+afterEach(() => {
+ vi.unstubAllEnvs();
+});
+
+// Windows unzips with tar.exe by absolute path, so an empty PATH only hides `unzip` elsewhere.
+it.skipIf(process.platform === "win32")(
+ "unpacks the browser download on a machine without an unzip command",
+ async () => {
+ const root = mkdtempSync(join(tmpdir(), "hf-unzip-fallback-"));
+ const platform = detectBrowserPlatform();
+ if (!platform) throw new Error("unsupported test platform");
+ const cacheDir = join(root, "cache");
+ const options = { cacheDir, browser: Browser.CHROMEHEADLESSSHELL, buildId: "1.0.0", platform };
+ const executablePath = computeExecutablePath(options);
+ const archive = new AdmZip();
+ archive.addFile(
+ relative(join(cacheDir, Browser.CHROMEHEADLESSSHELL, `${platform}-1.0.0`), executablePath),
+ Buffer.from("browser"),
+ );
+ const zipBytes = archive.toBuffer();
+ const server = createServer((_request, response) => response.end(zipBytes));
+ await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+ vi.stubEnv("PATH", join(root, "empty-bin"));
+ try {
+ const { port } = server.address() as AddressInfo;
+
+ await install({ ...options, baseUrl: `http://127.0.0.1:${port}` });
+
+ expect(existsSync(executablePath)).toBe(true);
+ } finally {
+ server.close();
+ rmSync(root, { recursive: true, force: true });
+ }
+ },
+);