@melaya/runner 1.0.118 → 1.1.0

package/dist/browserProvisioner.js

@@ -0,0 +1,266 @@
+// packages/runner/src/browserProvisioner.ts
+//
+// Melaya Browser, Phase 1 (plan Section 7): discovery + provisioning of
+// controllable browser engines on the operator's box. Brave is a
+// FIRST-CLASS, user-selectable engine alongside Chrome and Edge (user
+// decision, plan Section 7). The runner ships NO browser binaries; this
+// module only discovers what is installed, reports versions, and (only
+// behind an explicit flag) provisions the Playwright-bundled Chromium.
+// It never silently downloads anything.
+//
+// Brave quirks the capability report surfaces (plan Section 7): Shields
+// can block or rewrite page requests, which may alter snapshots and
+// trip origin policy in ways Chrome would not; Brave Rewards/Wallet
+// surfaces add browser-internal pages; Brave uses a distinct
+// user-data-dir layout. All three engines are Chromium-based, so CDP
+// launch + connectOverCDP work identically.
+import { existsSync, readdirSync } from "node:fs";
+import { execFile } from "node:child_process";
+import { join } from "node:path";
+import os from "node:os";
+const BRAVE_QUIRKS = [
+    "brave_shields_may_alter_requests_and_snapshots",
+    "brave_internal_surfaces_rewards_wallet",
+    "brave_distinct_user_data_dir",
+];
+// ---------------------------------------------------------------------
+// Per-OS well-known install paths
+// ---------------------------------------------------------------------
+function windowsCandidates() {
+    const pf = process.env["ProgramFiles"] || "C:\\Program Files";
+    const pf86 = process.env["ProgramFiles(x86)"] || "C:\\Program Files (x86)";
+    const local = process.env["LOCALAPPDATA"] || join(os.homedir(), "AppData", "Local");
+    return [
+        { engine: "chrome", path: join(pf, "Google", "Chrome", "Application", "chrome.exe"), channel: "chrome", quirks: [] },
+        { engine: "chrome", path: join(pf86, "Google", "Chrome", "Application", "chrome.exe"), channel: "chrome", quirks: [] },
+        { engine: "chrome", path: join(local, "Google", "Chrome", "Application", "chrome.exe"), channel: "chrome", quirks: [] },
+        { engine: "edge", path: join(pf86, "Microsoft", "Edge", "Application", "msedge.exe"), channel: "msedge", quirks: [] },
+        { engine: "edge", path: join(pf, "Microsoft", "Edge", "Application", "msedge.exe"), channel: "msedge", quirks: [] },
+        { engine: "brave", path: join(pf, "BraveSoftware", "Brave-Browser", "Application", "brave.exe"), channel: null, quirks: BRAVE_QUIRKS },
+        { engine: "brave", path: join(pf86, "BraveSoftware", "Brave-Browser", "Application", "brave.exe"), channel: null, quirks: BRAVE_QUIRKS },
+        { engine: "brave", path: join(local, "BraveSoftware", "Brave-Browser", "Application", "brave.exe"), channel: null, quirks: BRAVE_QUIRKS },
+    ];
+}
+function macCandidates() {
+    const userApps = join(os.homedir(), "Applications");
+    return [
+        // System-wide installs (/Applications) then per-user installs (~/Applications)
+        // for every engine, not just Brave: a user can install any of the three
+        // into their own Applications folder without admin rights.
+        { engine: "chrome", path: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome", channel: "chrome", quirks: [] },
+        { engine: "chrome", path: join(userApps, "Google Chrome.app", "Contents", "MacOS", "Google Chrome"), channel: "chrome", quirks: [] },
+        { engine: "edge", path: "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge", channel: "msedge", quirks: [] },
+        { engine: "edge", path: join(userApps, "Microsoft Edge.app", "Contents", "MacOS", "Microsoft Edge"), channel: "msedge", quirks: [] },
+        { engine: "brave", path: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser", channel: null, quirks: BRAVE_QUIRKS },
+        { engine: "brave", path: join(userApps, "Brave Browser.app", "Contents", "MacOS", "Brave Browser"), channel: null, quirks: BRAVE_QUIRKS },
+    ];
+}
+function linuxCandidates() {
+    const bins = [
+        ["chrome", "google-chrome", "chrome", []],
+        ["chrome", "google-chrome-stable", "chrome", []],
+        ["edge", "microsoft-edge", "msedge", []],
+        ["edge", "microsoft-edge-stable", "msedge", []],
+        ["brave", "brave", null, BRAVE_QUIRKS],
+        ["brave", "brave-browser", null, BRAVE_QUIRKS],
+    ];
+    const dirs = ["/usr/bin", "/usr/local/bin", "/opt/brave.com/brave", "/snap/bin"];
+    const out = [];
+    for (const [engine, bin, channel, quirks] of bins) {
+        for (const d of dirs)
+            out.push({ engine, path: join(d, bin), channel, quirks });
+    }
+    return out;
+}
+// ---------------------------------------------------------------------
+// Version detection
+// ---------------------------------------------------------------------
+/** Windows:  read the version-named subdirectory next to the executable
+ *            (e.g. Application/139.0.7258.67/).
+ *  macOS:    try reading CFBundleShortVersionString from the bundle's
+ *            Info.plist (reliable, no subprocess), then fall back to
+ *            running the binary with --version if the plist is absent or
+ *            malformed. Both paths avoid spawning a headed browser window.
+ *  Linux:    `<exe> --version` prints "Google Chrome 139.0...".
+ *
+ *  On all platforms a best-effort empty string is returned rather than
+ *  throwing, because a missing version must not block engine discovery. */
+async function detectVersion(exePath) {
+    if (process.platform === "win32") {
+        try {
+            const appDir = exePath.replace(/[\\/][^\\/]+$/, "");
+            const versionDirs = readdirSync(appDir)
+                .filter((n) => /^\d+\.\d+\.\d+\.\d+$/.test(n))
+                .sort((a, b) => compareVersions(b, a));
+            return versionDirs[0] || "";
+        }
+        catch {
+            return "";
+        }
+    }
+    if (process.platform === "darwin") {
+        // Primary: read Info.plist inside the .app bundle. The executable is at
+        // <Bundle>.app/Contents/MacOS/<Binary>; the plist is at
+        // <Bundle>.app/Contents/Info.plist. No subprocess needed.
+        try {
+            // Walk up from the binary to the .app Contents/ directory.
+            // exePath = /Applications/Brave Browser.app/Contents/MacOS/Brave Browser
+            // plistPath = /Applications/Brave Browser.app/Contents/Info.plist
+            const contentsDir = join(exePath, "..", ".."); // MacOS/../.. = Contents/
+            const plistPath = join(contentsDir, "Info.plist");
+            const { readFileSync: _readFileSync } = await import("node:fs");
+            const plist = _readFileSync(plistPath, "utf-8");
+            // Scan for the key/string pair in the XML plist without a full parser.
+            const keyIdx = plist.indexOf("<key>CFBundleShortVersionString</key>");
+            if (keyIdx !== -1) {
+                const after = plist.slice(keyIdx + "<key>CFBundleShortVersionString</key>".length);
+                const m = after.match(/<string>([^<]+)<\/string>/);
+                if (m) {
+                    const v = m[1].trim();
+                    if (/^\d+/.test(v))
+                        return v;
+                }
+            }
+        }
+        catch {
+            // Fall through to --version subprocess below.
+        }
+        // Fallback: run the binary with --version. Some Chromium builds print
+        // "Chromium 139.0.7258.67" or "Google Chrome 139.0.7258.67" to stdout.
+        return new Promise((resolve) => {
+            execFile(exePath, ["--version"], { timeout: 5000 }, (err, stdout) => {
+                if (err)
+                    return resolve("");
+                const m = String(stdout || "").match(/(\d+\.\d+\.\d+(?:\.\d+)?)/);
+                resolve(m ? m[1] : "");
+            });
+        });
+    }
+    // Linux (and any other POSIX platform).
+    return new Promise((resolve) => {
+        execFile(exePath, ["--version"], { timeout: 5000 }, (err, stdout) => {
+            if (err)
+                return resolve("");
+            const m = String(stdout || "").match(/(\d+\.\d+\.\d+(?:\.\d+)?)/);
+            resolve(m ? m[1] : "");
+        });
+    });
+}
+function compareVersions(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const d = (pa[i] || 0) - (pb[i] || 0);
+        if (d !== 0)
+            return d;
+    }
+    return 0;
+}
+// ---------------------------------------------------------------------
+// Discovery (cached; a runner's install set changes rarely)
+// ---------------------------------------------------------------------
+let _discoveryCache = null;
+export function discoverEngines(forceRefresh = false) {
+    if (_discoveryCache && !forceRefresh)
+        return _discoveryCache;
+    _discoveryCache = (async () => {
+        const candidates = process.platform === "win32" ? windowsCandidates()
+            : process.platform === "darwin" ? macCandidates()
+                : linuxCandidates();
+        const found = new Map();
+        for (const c of candidates) {
+            if (found.has(c.engine))
+                continue; // first hit per engine wins
+            if (!existsSync(c.path))
+                continue;
+            const version = await detectVersion(c.path);
+            found.set(c.engine, {
+                engine: c.engine,
+                executablePath: c.path,
+                version,
+                channel: c.channel,
+                quirks: c.quirks,
+            });
+        }
+        // Playwright-bundled Chromium, when already provisioned on disk.
+        try {
+            const playwright = await import("playwright");
+            const p = playwright.chromium.executablePath();
+            if (p && existsSync(p)) {
+                found.set("chromium", {
+                    engine: "chromium",
+                    executablePath: p,
+                    version: "",
+                    channel: null,
+                    quirks: [],
+                });
+            }
+        }
+        catch { /* playwright unavailable -> no bundled engine */ }
+        return [...found.values()];
+    })();
+    return _discoveryCache;
+}
+export async function capabilityReport() {
+    return {
+        engines: await discoverEngines(),
+        cdp: true,
+        provisioner: "v1",
+        platform: process.platform,
+    };
+}
+// ---------------------------------------------------------------------
+// Provisioning
+// ---------------------------------------------------------------------
+export class ProvisionError extends Error {
+    code;
+    instructions;
+    constructor(code, message, instructions) {
+        super(message);
+        this.name = "ProvisionError";
+        this.code = code;
+        this.instructions = instructions;
+    }
+}
+/** Resolve an engine to a launchable executable. NEVER downloads unless
+ *  allowDownload is explicitly true, and even then only the
+ *  Playwright-bundled Chromium is downloadable (Chrome/Edge/Brave are
+ *  user-installed products we will not fetch on the user's behalf). */
+export async function ensureEngine(engine, opts = {}) {
+    const engines = await discoverEngines();
+    const hit = engines.find((e) => e.engine === engine);
+    if (hit)
+        return hit;
+    if (engine !== "chromium") {
+        const urls = {
+            chrome: "https://www.google.com/chrome/",
+            edge: "https://www.microsoft.com/edge",
+            brave: "https://brave.com/download/",
+        };
+        throw new ProvisionError("engine_not_installed", `${engine} is not installed on this machine`, `Install ${engine} from ${urls[engine]} and reconnect the runner.`);
+    }
+    if (!opts.allowDownload) {
+        throw new ProvisionError("download_not_authorized", "bundled Chromium is not on disk and download was not authorized", "Re-run with the download flag enabled, or run: npx playwright install chromium");
+    }
+    // Explicitly authorized: install the bundled Chromium via Playwright's
+    // own installer (respects HTTPS_PROXY, resumable, disk-space checked
+    // by the installer itself).
+    opts.log?.("Downloading Playwright Chromium (explicitly authorized)...");
+    await new Promise((resolve, reject) => {
+        const child = execFile(process.execPath, [join("node_modules", "playwright", "cli.js"), "install", "chromium"], { cwd: packageRootGuess(), timeout: 10 * 60 * 1000 }, (err) => (err ? reject(err) : resolve()));
+        child.stdout?.on("data", (d) => opts.log?.(String(d).trim()));
+    }).catch((e) => {
+        throw new ProvisionError("download_failed", `Chromium download failed: ${e?.message || e}`);
+    });
+    const refreshed = await discoverEngines(true);
+    const post = refreshed.find((e) => e.engine === "chromium");
+    if (!post)
+        throw new ProvisionError("download_failed", "Chromium installed but executable not found");
+    return post;
+}
+function packageRootGuess() {
+    // dist/ layout: this file compiles to dist/browserProvisioner.js; the
+    // package root (with node_modules/playwright) is one level up. In the
+    // dev tree it is two up from src/, which the fallback covers.
+    return join(new URL(".", import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, "$1"), "..");
+}

package/dist/codeWorker.d.ts

@@ -0,0 +1,49 @@
+/** Facade the BRIDGE provides: executes one governed op. The bridge
+ *  performs authz + tracing; the worker only ever sees op names. */
+export type GovernedFacade = (op: string, args: Record<string, unknown>) => Promise<unknown>;
+export interface CodeWorkerLimits {
+    wallClockMs: number;
+    maxOps: number;
+    maxArgBytes: number;
+    maxConsoleLines: number;
+    maxOutputBytes: number;
+    maxScreenshots: number;
+    maxNavigations: number;
+    /** Heap cap (MB) passed as --max-old-space-size. Also controls the
+     *  OS-level rlimit on Linux (bwrap --rlimit) and macOS (ulimit -v).
+     *  Default 256 MB; hard cap 512 MB to prevent OOM on the host. */
+    maxMemoryMb: number;
+    /** CPU time limit in seconds for the macOS ulimit -t wrapper.
+     *  Ignored on other platforms (wall-clock timer is the backstop).
+     *  Default 60 (matches wallClockMs default). */
+    maxCpuSeconds: number;
+}
+export declare const DEFAULT_LIMITS: CodeWorkerLimits;
+export interface SubActionTrace {
+    seq: number;
+    op: string;
+    ok: boolean;
+    ms: number;
+    error?: string;
+}
+export interface CodeRunResult {
+    ok: boolean;
+    result?: unknown;
+    console: string[];
+    traces: SubActionTrace[];
+    error?: {
+        code: string;
+        message: string;
+    };
+    /** Which OS sandbox actually wrapped the child. */
+    sandbox: "bubblewrap" | "seatbelt" | "node-permission-only" | "none";
+    killVerified: boolean;
+}
+export declare function runSandboxedScript(opts: {
+    script: string;
+    scratchDir: string;
+    facade: GovernedFacade;
+    limits?: Partial<CodeWorkerLimits>;
+    onTrace?: (t: SubActionTrace) => void;
+    log?: (m: string) => void;
+}): Promise<CodeRunResult>;