fix(cli): purge stale/partial browser installs instead of wedging retries (#1913)

* fix(cli): purge stale/partial browser installs instead of wedging retries

Two independent reports of the same failure: a `chrome-headless-shell`
zip extraction gets interrupted (Windows AV lock, sleep/wake, ctrl-C)
and leaves only the alphabetically-early files (ABOUT/LICENSE) in the
target directory, no executable. Every subsequent `browser ensure` (or
implicit re-download from `findBrowser`/`ensureBrowser`) sees the
directory already exists and hands it straight to @puppeteer/browsers'
install(), which throws "folder exists but the executable is missing"
without re-extracting -- permanently wedging the machine until someone
manually deletes the directory. `--force` didn't help because it was a
phantom flag: `browser.ts` never declared it, so it silently did
nothing (mentioned only in an error-message string).

Root cause: `findFromCache()` already detects this exact case (dir
exists, exe missing) and returns it as `staleHyperframesCachePath`, but
`findBrowser()`/`ensureBrowser()` fed that straight into a re-download
without ever deleting the stale directory first, so install() hit the
same "exists" branch every time.

Fix:
- `findFromCache()` also returns `staleInstallPath` (InstalledBrowser's
  `.path` -- the actual install-folder root, not the missing
  executablePath) for the stale case.
- Both `findBrowser()` and `ensureBrowser()` now purge that directory
  (`rmSync`, inside the existing `withInstallLock` mutex from #1866 so
  a purge can't race a concurrent installer) before retrying, so
  install() actually re-extracts instead of erroring.
- Wired up a real `--force` flag on `hyperframes browser ensure`: it
  purges the whole HF-managed cache (reusing the already-tested
  `clearBrowser()`) and skips every cache/system shortcut, so it always
  gets a fresh download regardless of what's currently on disk --
  matching what the existing (previously false) help text already
  claimed it did.

Not fixed here (separate root cause, flagged for later): neither
report's machine had a usable auto-detected system Chrome fallback on
Windows -- `SYSTEM_CHROME_PATHS` only lists macOS/Linux paths, so
`findFromSystem()` can never succeed on win32. Both reporters worked
around this manually via HYPERFRAMES_BROWSER_PATH, which still works
fine; adding real Windows system-Chrome detection is a distinct,
larger change.

Test: extended manager.test.ts's existing stale-cache-redownload test
to include a populated stale install directory and assert it's gone
before the mocked install() is called (was previously only asserting
the redownload happened, not that the fix's purge step ran). Added a
new test for `ensureBrowser({force: true})` purging the cache and
bypassing a healthy cache/system-Chrome shortcut. Also fixed the shared
fs mock's `rmSync` to actually simulate recursive deletion (drop
nested tracked paths too), which the new tests need and the old ones
never exercised. Full CLI suite (1222 tests) passes.

* fix(cli): serialize force browser cache purge

packages/cli/src/commands/browser.ts

@@ -5,6 +5,7 @@ import { c } from "../ui/colors.js";
 
 export const examples: Example[] = [
   ["Find or download Chrome for rendering", "hyperframes browser ensure"],
+  ["Purge a stale/partial download and re-download", "hyperframes browser ensure --force"],
   ["Print the Chrome executable path", "hyperframes browser path"],
   ["Remove cached Chrome download", "hyperframes browser clear"],
 ];
@@ -19,11 +20,11 @@ import {
 } from "../browser/manager.js";
 import { trackBrowserInstall, trackCommandFailure } from "../telemetry/events.js";
 
-async function runEnsure(): Promise<void> {
+async function runEnsure(options?: { force?: boolean }): Promise<void> {
   clack.intro(c.bold("hyperframes browser ensure"));
 
-  // ARM64 Linux: Chrome headless shell is not available.
-  // Try to find system Chromium first, then attempt auto-install via apt.
+  // ARM64 Linux: Chrome headless shell is not available (apt-get/system-only
+  // install flow, no download cache to force a purge of) — --force is a no-op here.
   if (isLinuxArm()) {
     const s = clack.spinner();
     s.start("Linux ARM64 detected — looking for system Chromium...");
@@ -61,26 +62,31 @@ async function runEnsure(): Promise<void> {
   }
 
   const s = clack.spinner();
-  s.start("Looking for an existing browser...");
+  if (!options?.force) {
+    s.start("Looking for an existing browser...");
 
-  const existing = await findBrowser();
-  if (existing) {
-    s.stop(c.success("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;
+    const existing = await findBrowser();
+    if (existing) {
+      s.stop(c.success("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;
+    }
+
+    s.stop("No browser found — downloading");
+  } else {
+    s.start("Purging cached download and re-downloading...");
   }
 
-  s.stop("No browser found — downloading");
-
   const downloadSpinner = clack.spinner();
   downloadSpinner.start(`Downloading Chrome Headless Shell ${c.dim("v" + CHROME_VERSION)}...`);
 
   let lastPct = -1;
   const result = await ensureBrowser({
+    force: options?.force,
     onProgress: (downloaded, total) => {
       if (total <= 0) return;
       const pct = Math.floor((downloaded / total) * 100);
@@ -141,6 +147,12 @@ export default defineCommand({
         "ensure = find or download Chrome, path = print executable path, clear = remove cached download",
       required: false,
     },
+    force: {
+      type: "boolean",
+      description:
+        "ensure only: purge any cached download (including a stale/partial one) and re-download from scratch",
+      default: false,
+    },
   },
   async run({ args }) {
     const subcommand = args.subcommand;
@@ -157,16 +169,17 @@ ${c.bold("SUBCOMMANDS:")}
   ${c.accent("clear")}    ${c.dim("Remove cached Chrome download")}
 
 ${c.bold("EXAMPLES:")}
-  ${c.accent("npx hyperframes browser ensure")}   ${c.dim("Download Chrome if needed")}
-  ${c.accent("npx hyperframes browser path")}     ${c.dim("Print path for scripts")}
-  ${c.accent("npx hyperframes browser clear")}    ${c.dim("Remove cached browser")}
+  ${c.accent("npx hyperframes browser ensure")}           ${c.dim("Download Chrome if needed")}
+  ${c.accent("npx hyperframes browser ensure --force")}   ${c.dim("Purge a stale/partial download and re-download")}
+  ${c.accent("npx hyperframes browser path")}             ${c.dim("Print path for scripts")}
+  ${c.accent("npx hyperframes browser clear")}            ${c.dim("Remove cached browser")}
 `);
       return;
     }
 
     switch (subcommand) {
       case "ensure":
-        return runEnsure();
+        return runEnsure({ force: args.force });
       case "path":
         return runPath();
       case "clear":