castle-web-cli 0.4.80 → 0.4.81

package/dist/native/playtest-browser.d.ts

@@ -2,6 +2,7 @@ import type { Browser } from "playwright-core";
 import type { PlaytestInstallEvent } from "./playtest.js";
 export declare const INSTALL_START_LABEL = "Downloading playtest browser (one-time, ~250MB)\u2026";
 export declare const INSTALL_WAIT_LABEL = "Waiting for browser download (shared)\u2026";
+export declare const DEPS_REPAIR_LABEL = "Installing missing browser system libraries (one-time)\u2026";
 export interface PlaywrightChromiumLike {
     executablePath(): string;
     launch(options?: {
@@ -14,6 +15,8 @@ export interface PlaywrightModuleLike {
 export interface PlaytestBrowserSeams {
     loadPlaywright?: () => Promise<PlaywrightModuleLike>;
     runInstall?: (onLine: (line: string) => void) => Promise<void>;
+    runInstallDeps?: () => Promise<void>;
+    platform?: NodeJS.Platform;
 }
 export interface BrowserInstallHooks {
     onProgress?: (label: string) => void;

package/dist/native/playtest-browser.js

@@ -44,18 +44,39 @@ const LAUNCH_ARGS = [
 ];
 const MISSING_PLAYWRIGHT_MESSAGE = "playwright-core is not installed in this CLI (run `npm install` from the repo root).";
 const MANUAL_INSTALL_HINT = "install manually with `npx playwright install chromium`";
+const MANUAL_DEPS_HINT = "install manually with `npx playwright install-deps chromium` (needs root/apt)";
 export const INSTALL_START_LABEL = "Downloading playtest browser (one-time, ~250MB)\u2026";
 export const INSTALL_WAIT_LABEL = "Waiting for browser download (shared)\u2026";
+export const DEPS_REPAIR_LABEL = "Installing missing browser system libraries (one-time)\u2026";
 // Progress labels are throttled to 20-point steps: every onProgress string
 // becomes a task-feed ROW (see runTaskAgentIn's onActivity wiring in
 // agent.ts), so per-percent updates would flood the feed with ~100 rows.
 const PROGRESS_STEP = 20;
+// The Chromium binary and the OS shared libraries it dynamically links
+// (libnspr4, libnss3, libatk-1.0, libgbm, ...) are two SEPARATE things: the
+// on-demand download above only fetches the former. A box whose base image
+// never baked in the latter (e.g. an E2B sandbox built from a pre-fix
+// template -- see castle-cloud-cli/template.mjs) downloads Chromium fine but
+// then fails to LAUNCH it with a linker error naming the missing .so. This
+// regex is how launchBrowser tells "the binary can't find a system library"
+// apart from any other launch failure (crash, bad args, OOM, ...) so it only
+// attempts the apt-get repair below for the failure mode that repair can
+// actually fix.
+const MISSING_SHARED_LIBRARY_RE = /error while loading shared libraries|cannot open shared object file|\blib[\w.+-]+\.so\b/i;
+function looksLikeMissingSharedLibrary(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return MISSING_SHARED_LIBRARY_RE.test(message);
+}
 function launchFailureMessage(err) {
     const message = err instanceof Error ? err.message : String(err);
     const looksLikeMissingBrowser = /executable doesn't exist|download.*chromium/i.test(message);
-    return looksLikeMissingBrowser
-        ? `chromium is not installed for playwright -- ${MANUAL_INSTALL_HINT}. (${message})`
-        : `could not launch chromium: ${message}`;
+    if (looksLikeMissingBrowser) {
+        return `chromium is not installed for playwright -- ${MANUAL_INSTALL_HINT}. (${message})`;
+    }
+    if (looksLikeMissingSharedLibrary(err)) {
+        return `chromium is missing OS-level system libraries -- ${MANUAL_DEPS_HINT}. (${message})`;
+    }
+    return `could not launch chromium: ${message}`;
 }
 async function loadPlaywrightReal() {
     return (await import("playwright-core"));
@@ -114,6 +135,36 @@ function runInstallReal(onLine) {
         });
     });
 }
+// Same install CLI, `install-deps` instead of `install` -- apt-get's the OS
+// shared libraries Chromium links (sudo internally if not already root; see
+// the module header). No progress-line parsing: apt-get's output doesn't
+// carry a percent, and this is a rare repair path, not the common-case
+// download bar `runInstallReal` throttles updates for.
+function runInstallDepsReal() {
+    return new Promise((resolve, reject) => {
+        const cliPath = resolveInstallCli();
+        if (!cliPath) {
+            reject(new Error(MISSING_PLAYWRIGHT_MESSAGE));
+            return;
+        }
+        const child = spawn(process.execPath, [cliPath, "install-deps", "chromium"], {
+            env: process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let output = "";
+        child.stdout.on("data", (chunk) => (output += chunk.toString("utf8")));
+        child.stderr.on("data", (chunk) => (output += chunk.toString("utf8")));
+        child.on("error", (err) => reject(err));
+        child.on("exit", (code, signal) => {
+            if (code === 0)
+                resolve();
+            else {
+                const tail = output.trim().split("\n").slice(-5).join(" | ");
+                reject(new Error(`install-deps exited with ${signal ? `signal ${signal}` : `code ${code}`}${tail ? ` (${tail})` : ""}`));
+            }
+        });
+    });
+}
 // MODULE-level (not per-manager): one Chromium download per process, no
 // matter how many managers/serves/prewarms race for it. Reset to null when
 // the flight settles -- on success the fs existence check gates any future
@@ -206,9 +257,67 @@ async function ensureInstalled(runInstall, hooks, getCachePath) {
         flight.progressListeners.delete(listener);
     }
 }
+// -- deps repair (retrofits EXISTING sandboxes booted from a pre-fix image) ------
+// Chromium DOWNLOAD (above) and Chromium's OS-level LAUNCH dependencies are
+// fixed at two different times for two different populations: a template
+// rebuild (castle-cloud-cli/template.mjs) bakes the libs in for sandboxes
+// created AFTER the fix, but does nothing for already-running sandboxes that
+// booted from the old image and may have already downloaded Chromium (so
+// `missingExecutable` is false for them -- ensureInstalled's branch never
+// runs again). This is the fallback for that population: attempted lazily,
+// ONLY on an actual launch failure that looks like a missing shared library
+// (see MISSING_SHARED_LIBRARY_RE), ONLY on linux (never on a local macOS
+// dev machine), and at MOST ONCE per process -- a repair that fails (no
+// sudo, no apt, offline) is not worth retrying on every subsequent playtest
+// call. Module-level (not per-manager) for the same reason installFlight is:
+// one apt-get for the whole process, no matter how many managers/callers hit
+// a broken launch concurrently.
+let depsRepairFlight = null;
+let depsRepairSettled = null;
+function logDepsRepairStart() {
+    console.error("[playtest] chromium launch failed on a missing OS library -- attempting one-time repair (apt-get via playwright install-deps)...");
+}
+function logDepsRepairResult(ok, elapsedMs, err) {
+    const elapsedS = (elapsedMs / 1000).toFixed(1);
+    if (ok) {
+        console.error(`[playtest] system library repair succeeded in ${elapsedS}s -- retrying browser launch`);
+    }
+    else {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[playtest] system library repair failed after ${elapsedS}s: ${message}`);
+    }
+}
+function attemptDepsRepair(runInstallDeps, onProgress) {
+    if (depsRepairSettled) {
+        // Already tried once this process: a success means the retry that
+        // follows should just work (no need to repeat), a failure means
+        // repeating would just fail again the same way (no sudo/apt/network) --
+        // either way, don't re-run apt-get on every subsequent broken launch.
+        return Promise.resolve(depsRepairSettled.ok ? { ok: true } : { ok: false, error: "system library repair already failed once this process" });
+    }
+    if (depsRepairFlight)
+        return depsRepairFlight;
+    const startedAt = Date.now();
+    logDepsRepairStart();
+    onProgress?.(DEPS_REPAIR_LABEL);
+    depsRepairFlight = runInstallDeps().then(() => {
+        depsRepairSettled = { ok: true };
+        logDepsRepairResult(true, Date.now() - startedAt);
+        return { ok: true };
+    }, (err) => {
+        depsRepairSettled = { ok: false };
+        logDepsRepairResult(false, Date.now() - startedAt, err);
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }).finally(() => {
+        depsRepairFlight = null;
+    });
+    return depsRepairFlight;
+}
 export function createPlaytestBrowserManager(seams) {
     const loadPlaywright = seams?.loadPlaywright ?? loadPlaywrightReal;
     const runInstall = seams?.runInstall ?? runInstallReal;
+    const runInstallDeps = seams?.runInstallDeps ?? runInstallDepsReal;
+    const platform = seams?.platform ?? process.platform;
     let browser = null;
     let idleTimer = null;
     let launching = null;
@@ -243,7 +352,7 @@ export function createPlaytestBrowserManager(seams) {
             return true;
         }
     }
-    async function launchBrowser(playwright) {
+    async function tryLaunch(playwright) {
         try {
             const launched = await playwright.chromium.launch({ args: LAUNCH_ARGS });
             launched.on("disconnected", () => {
@@ -254,8 +363,28 @@ export function createPlaytestBrowserManager(seams) {
             return { ok: true, browser: launched };
         }
         catch (err) {
-            return { ok: false, error: launchFailureMessage(err) };
+            return { ok: false, error: err };
+        }
+    }
+    async function launchBrowser(playwright, hooks) {
+        const first = await tryLaunch(playwright);
+        if (first.ok)
+            return first;
+        // Self-heal path for sandboxes that already have the Chromium BINARY
+        // (so ensureInstalled's download branch never re-runs) but are missing
+        // the OS libraries it links -- see the module header above
+        // attemptDepsRepair for why this is gated to linux + this specific
+        // failure shape + at most one attempt per process.
+        if (platform === "linux" && looksLikeMissingSharedLibrary(first.error)) {
+            const repaired = await attemptDepsRepair(runInstallDeps, hooks?.onProgress);
+            if (repaired.ok) {
+                const retry = await tryLaunch(playwright);
+                if (retry.ok)
+                    return retry;
+                return { ok: false, error: launchFailureMessage(retry.error) };
+            }
         }
+        return { ok: false, error: launchFailureMessage(first.error) };
     }
     // Two DIFFERENT single-flights, deliberately layered: the install check
     // runs per caller (so every concurrent caller passes its OWN hooks through
@@ -301,7 +430,7 @@ export function createPlaytestBrowserManager(seams) {
         if (existing?.isConnected())
             return { ok: true, browser: existing, installedMs };
         if (!launching) {
-            launching = launchBrowser(playwright).finally(() => {
+            launching = launchBrowser(playwright, hooks).finally(() => {
                 launching = null;
             });
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "castle-web-cli",
-  "version": "0.4.80",
+  "version": "0.4.81",
   "type": "module",
   "bin": {
     "castle-web": "./dist/index.js"