@helix3/helix-cli 0.1.18-helix3.345 → 0.1.18-helix3.347

package/dist/browser/hostSlots.d.ts

@@ -0,0 +1,9 @@
+export declare function hostBrowserCap(env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): number;
+/** Pure-ish: is this slot file's owner gone? `raw` is returned so the caller can confirm the file did not change before reclaiming. */
+export declare function slotIsStale(file: string, alive?: (pid: number) => boolean | 'unknown'): {
+    stale: boolean;
+    raw: string | null;
+};
+/** Take this process's browser slot (idempotent) and wait while the host is at its cap. Resolves to the slot file, or undefined when uncapped. */
+export declare function acquireHostBrowserSlot(): Promise<string | undefined>;
+export declare function releaseHostBrowserSlot(): void;

package/dist/browser/hostSlots.js

@@ -0,0 +1,145 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hostBrowserCap = hostBrowserCap;
+exports.slotIsStale = slotIsStale;
+exports.acquireHostBrowserSlot = acquireHostBrowserSlot;
+exports.releaseHostBrowserSlot = releaseHostBrowserSlot;
+// Host-wide cap on concurrent automated browsers. 8-16 headless QA Chromes at once cost ~5 cores and up to 22 GB on the
+// Mac (docs/compute-offload-model.md in the HELIX workspace), and a single `helix item visual-qa` fan-out started four.
+// Every PROCESS that opens a browser takes ONE slot for its whole life (released at exit), so a run that opens several
+// browsers can never deadlock against itself. Slots are files in ~/.cache/helix-headless-slots/ — the same protocol as the
+// workspace's scripts/lib/headless-browser.mjs, so scripts and this CLI share one budget. A slot whose owner pid is dead (or
+// was reused: start time differs) is reclaimed; nothing is ever signalled.
+//   HELIX_HEADLESS_MAX=<n>        cap (default 4 on macOS; unlimited elsewhere and when CI is set; 0 = off)
+//   HELIX_HEADLESS_WAIT_MS=<ms>   give up waiting after this long (default 30 min) and throw
+//   HELIX_HEADLESS_SLOT_DIR=<dir> override the slot directory (tests)
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+let held;
+function hostBrowserCap(env = process.env, platform = process.platform) {
+    const v = env.HELIX_HEADLESS_MAX;
+    if (v !== undefined && v !== '') {
+        const n = Number(v);
+        return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+    }
+    return platform !== 'darwin' || env.CI ? 0 : 4;
+}
+function startStamp(pid) {
+    try {
+        return (0, node_child_process_1.execFileSync)('ps', ['-o', 'lstart=', '-p', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    }
+    catch {
+        return '';
+    }
+}
+/** Pure-ish: is this slot file's owner gone? `raw` is returned so the caller can confirm the file did not change before reclaiming. */
+function slotIsStale(file, alive = pidAlive) {
+    let raw;
+    try {
+        raw = node_fs_1.default.readFileSync(file, 'utf8');
+    }
+    catch {
+        return { stale: false, raw: null };
+    }
+    let owner;
+    try {
+        owner = JSON.parse(raw);
+    }
+    catch {
+        owner = null;
+    }
+    if (!owner || !Number.isInteger(owner.pid)) {
+        try {
+            return { stale: Date.now() - node_fs_1.default.statSync(file).mtimeMs > 5000, raw };
+        }
+        catch {
+            return { stale: false, raw };
+        }
+    }
+    const state = alive(owner.pid);
+    if (state === false)
+        return { stale: true, raw };
+    if (state === 'unknown')
+        return { stale: false, raw };
+    const now = startStamp(owner.pid);
+    return { stale: !!owner.start && !!now && owner.start !== now, raw };
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'ESRCH' ? false : 'unknown';
+    }
+}
+/** Take this process's browser slot (idempotent) and wait while the host is at its cap. Resolves to the slot file, or undefined when uncapped. */
+async function acquireHostBrowserSlot() {
+    if (held)
+        return held;
+    const cap = hostBrowserCap();
+    if (!cap)
+        return undefined;
+    const dir = process.env.HELIX_HEADLESS_SLOT_DIR ?? node_path_1.default.join(node_os_1.default.homedir(), '.cache/helix-headless-slots');
+    node_fs_1.default.mkdirSync(dir, { recursive: true });
+    const me = JSON.stringify({ pid: process.pid, start: startStamp(process.pid), script: process.argv[1] ?? null, at: new Date().toISOString() });
+    const waitMs = Number(process.env.HELIX_HEADLESS_WAIT_MS ?? 30 * 60_000);
+    const began = Date.now();
+    let lastNote = 0;
+    for (;;) {
+        const retries = {};
+        for (let k = 0; k < cap; k++) {
+            const file = node_path_1.default.join(dir, `slot-${k}`);
+            try {
+                node_fs_1.default.writeFileSync(file, me, { flag: 'wx' });
+                held = file;
+                process.once('exit', releaseHostBrowserSlot);
+                return file;
+            }
+            catch (e) {
+                if (e.code !== 'EEXIST')
+                    throw e;
+            }
+            const { stale, raw } = slotIsStale(file);
+            retries[k] = (retries[k] ?? 0) + 1;
+            if (stale && retries[k] <= 5) {
+                const tomb = `${file}.reclaimed-${process.pid}-${Date.now()}`;
+                try {
+                    if (node_fs_1.default.readFileSync(file, 'utf8') === raw)
+                        node_fs_1.default.renameSync(file, tomb);
+                    node_fs_1.default.rmSync(tomb, { force: true });
+                }
+                catch { /* another reclaimer won */ }
+                k -= 1;
+            }
+        }
+        for (const f of node_fs_1.default.readdirSync(dir))
+            if (f.includes('.reclaimed-'))
+                node_fs_1.default.rmSync(node_path_1.default.join(dir, f), { force: true });
+        if (Date.now() - began > waitMs)
+            throw new Error(`No browser slot free after ${Math.round(waitMs / 1000)}s (host cap ${cap} in ${dir}). Other QA runs hold them; wait, or raise HELIX_HEADLESS_MAX.`);
+        if (Date.now() - lastNote > 30_000) {
+            lastNote = Date.now();
+            console.error(`[visual-qa] waiting for a browser slot: host cap is ${cap} concurrent automated browsers (HELIX_HEADLESS_MAX overrides)`);
+        }
+        await new Promise((r) => setTimeout(r, 500));
+    }
+}
+function releaseHostBrowserSlot() {
+    if (!held)
+        return;
+    const file = held;
+    held = undefined;
+    try {
+        const owner = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+        if (owner.pid === process.pid)
+            node_fs_1.default.rmSync(file, { force: true });
+    }
+    catch { /* already gone */ }
+}
+//# sourceMappingURL=hostSlots.js.map

package/dist/browser/hostSlots.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hostSlots.js","sourceRoot":"","sources":["../../src/browser/hostSlots.ts"],"names":[],"mappings":"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"}

package/dist/browser/launch.d.ts

@@ -1,15 +1,16 @@
 import type { LaunchOptions } from 'playwright';
 export declare const HEADLESS_GL_ARGS: string[];
 export declare const GPU_GL_ARGS: string[];
-export type BrowserKey = 'bundled' | 'chrome' | 'msedge';
+export type BrowserKey = 'bundled' | 'chromium' | 'chrome' | 'msedge';
 export type BrowserCandidate = {
     key: BrowserKey;
     label: string;
     launchOptions: LaunchOptions;
 };
-export declare function browserCandidates(): BrowserCandidate[];
-export declare function gpuBrowserCandidates(): BrowserCandidate[];
-export declare function selectBrowserCandidates(browser: BrowserKey | undefined): BrowserCandidate[];
+export declare function cachedChromiumCandidate(args: string[], cached?: string | undefined): BrowserCandidate[];
+export declare function browserCandidates(cached?: string): BrowserCandidate[];
+export declare function gpuBrowserCandidates(cached?: string): BrowserCandidate[];
+export declare function selectBrowserCandidates(browser: BrowserKey | undefined, cached?: string): BrowserCandidate[];
 export type LaunchAttempt = {
     key: BrowserKey;
     label: string;

package/dist/browser/launch.js

@@ -1,37 +1,48 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GPU_GL_ARGS = exports.HEADLESS_GL_ARGS = void 0;
+exports.cachedChromiumCandidate = cachedChromiumCandidate;
 exports.browserCandidates = browserCandidates;
 exports.gpuBrowserCandidates = gpuBrowserCandidates;
 exports.selectBrowserCandidates = selectBrowserCandidates;
 exports.composeLaunchFailure = composeLaunchFailure;
 exports.composeTimeoutDiagnosisWith = composeTimeoutDiagnosisWith;
+const nonSystemChrome_1 = require("./nonSystemChrome");
 // Software-GL flags: headless Chromium has no real GPU, so WebGL must render via SwiftShader.
 exports.HEADLESS_GL_ARGS = ['--use-angle=swiftshader', '--enable-unsafe-swiftshader'];
 // Real-GPU flags: nothing forces software GL, and the blocklist is ignored so a headless run still gets the
 // hardware backend on the driver/VM combinations Chrome distrusts.
 exports.GPU_GL_ARGS = ['--ignore-gpu-blocklist'];
+// macOS only: a cached Playwright Chromium ("Google Chrome for Testing", its own bundle id) is tried before the user's
+// system Chrome, because an automated headless /Applications/Google Chrome.app registers as the user's own Chrome in
+// LaunchServices and hijacks their Dock icon and Cmd-Q. `cached` is injectable so the chain stays unit-testable.
+function cachedChromiumCandidate(args, cached = process.platform === 'darwin' ? (0, nonSystemChrome_1.findCachedAutomationChromium)() : undefined) {
+    return cached ? [{ key: 'chromium', label: 'Playwright Chromium (Chrome for Testing)', launchOptions: { headless: true, args, executablePath: cached } }] : [];
+}
 // Ordered fallback chain for `chromium.launch()`: the pinned bundled build first (most
-// deterministic), then whichever system browser is already installed — so first-run works
-// without the ~150 MB download on machines that already have Chrome or Edge.
-function browserCandidates() {
+// deterministic), then a cached Playwright Chromium on macOS, then whichever system browser is already
+// installed — so first-run works without the ~150 MB download on machines that already have Chrome or Edge.
+function browserCandidates(cached) {
     return [
         { key: 'bundled', label: 'bundled Chromium', launchOptions: { headless: true, args: exports.HEADLESS_GL_ARGS } },
+        ...cachedChromiumCandidate(exports.HEADLESS_GL_ARGS, cached),
         { key: 'chrome', label: 'system Chrome', launchOptions: { headless: true, args: exports.HEADLESS_GL_ARGS, channel: 'chrome' } },
         { key: 'msedge', label: 'system Edge', launchOptions: { headless: true, args: exports.HEADLESS_GL_ARGS, channel: 'msedge' } },
     ];
 }
-// The GPU chain: system browsers only. Playwright's bundled build is the headless SHELL, which carries no
-// hardware GL backend at all — it renders through SwiftShader whatever flags it is handed.
-function gpuBrowserCandidates() {
+// The GPU chain: full browsers only. Playwright's bundled build is the headless SHELL, which carries no
+// hardware GL backend at all — it renders through SwiftShader whatever flags it is handed. On macOS the cached
+// Chrome for Testing (full Chromium, real Metal/WebGPU) leads, so the user's own Chrome is only a last resort.
+function gpuBrowserCandidates(cached) {
     return [
+        ...cachedChromiumCandidate(exports.GPU_GL_ARGS, cached),
         { key: 'chrome', label: 'system Chrome', launchOptions: { headless: true, args: exports.GPU_GL_ARGS, channel: 'chrome' } },
         { key: 'msedge', label: 'system Edge', launchOptions: { headless: true, args: exports.GPU_GL_ARGS, channel: 'msedge' } },
     ];
 }
 // Pure so the "forced candidate, no fallback" plan is unit-testable without Playwright.
-function selectBrowserCandidates(browser) {
-    return browser ? browserCandidates().filter((c) => c.key === browser) : browserCandidates();
+function selectBrowserCandidates(browser, cached) {
+    return browser ? browserCandidates(cached).filter((c) => c.key === browser) : browserCandidates(cached);
 }
 // Pure so the "everything failed" message is unit-testable without Playwright. The install hint only
 // makes sense when the bundled build was among the attempts — forcing a system browser that's simply

package/dist/browser/launch.js.map

@@ -1 +1 @@
-{"version":3,"file":"launch.js","sourceRoot":"","sources":["../../src/browser/launch.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"launch.js","sourceRoot":"","sources":["../../src/browser/launch.ts"],"names":[],"mappings":"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"}

package/dist/browser/nonSystemChrome.d.ts

@@ -0,0 +1,15 @@
+/** Throws when an executable path or Playwright channel would launch the user's branded Chrome. */
+export declare function assertNotSystemChrome(executablePath?: string, channel?: string, platform?: NodeJS.Platform): void;
+/** Newest Chrome for Testing / Chromium in the Playwright browser cache, regardless of which Playwright installed it. */
+export declare function findCachedAutomationChromium(home?: string, env?: NodeJS.ProcessEnv): string | undefined;
+/**
+ * The browser a macOS automated run should use: HELIX_VQA_CHROME, else the Playwright build's own Chromium, else any
+ * cached Chrome for Testing. Never the system Chrome. Returns undefined off macOS (callers keep their platform default).
+ */
+export declare function resolveAutomationChromium(opts?: {
+    override?: string;
+    playwrightDefault?: string;
+    platform?: NodeJS.Platform;
+    home?: string;
+    env?: NodeJS.ProcessEnv;
+}): string | undefined;

package/dist/browser/nonSystemChrome.js

@@ -0,0 +1,79 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertNotSystemChrome = assertNotSystemChrome;
+exports.findCachedAutomationChromium = findCachedAutomationChromium;
+exports.resolveAutomationChromium = resolveAutomationChromium;
+// On macOS an automated headless /Applications/Google Chrome.app registers with LaunchServices under the
+// user's own bundle id (com.google.Chrome) and can be promoted to the Foreground app: the Dock icon and
+// Cmd-Q then target an invisible headless instance and the user's real Chrome "is active" with no UI and
+// will not quit. Automation therefore runs on a binary with a different bundle id — Playwright's Chromium,
+// which on macOS is "Google Chrome for Testing" (com.google.chrome.for.testing) and, unlike the headless
+// shell, has a real Metal/WebGPU adapter.
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const SYSTEM_CHROME_MARKERS = ['/Applications/Google Chrome.app', '/Google Chrome.app/'];
+/** Throws when an executable path or Playwright channel would launch the user's branded Chrome. */
+function assertNotSystemChrome(executablePath, channel, platform = process.platform) {
+    if (platform !== 'darwin')
+        return; // the LaunchServices hijack is macOS-only; Linux/Windows hosts keep their own browsers
+    if (channel && /^chrome/i.test(channel)) {
+        throw new Error(`Refusing Playwright channel '${channel}': it launches the system Google Chrome and hijacks the Dock Chrome. Use Playwright's Chromium (npx playwright install chromium).`);
+    }
+    if (executablePath && SYSTEM_CHROME_MARKERS.some((m) => executablePath.includes(m))) {
+        throw new Error(`Refusing to automate ${executablePath}: never launch /Applications/Google Chrome.app for automation. Use Playwright's Chromium / Chrome for Testing (npx playwright install chromium).`);
+    }
+}
+const CFT_REL = [
+    'chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+    'chrome-mac-x64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing',
+    'chrome-mac/Chromium.app/Contents/MacOS/Chromium',
+];
+/** Newest Chrome for Testing / Chromium in the Playwright browser cache, regardless of which Playwright installed it. */
+function findCachedAutomationChromium(home = node_os_1.default.homedir(), env = process.env) {
+    const roots = [env.PLAYWRIGHT_BROWSERS_PATH && env.PLAYWRIGHT_BROWSERS_PATH !== '0' ? env.PLAYWRIGHT_BROWSERS_PATH : undefined, node_path_1.default.join(home, 'Library/Caches/ms-playwright')].filter((r) => !!r);
+    for (const root of roots) {
+        let dirs = [];
+        try {
+            dirs = node_fs_1.default.readdirSync(root).filter((n) => /^chromium-\d+$/.test(n));
+        }
+        catch {
+            continue;
+        }
+        dirs.sort((a, b) => Number(b.slice('chromium-'.length)) - Number(a.slice('chromium-'.length)));
+        for (const d of dirs)
+            for (const rel of CFT_REL) {
+                const p = node_path_1.default.join(root, d, rel);
+                if (node_fs_1.default.existsSync(p))
+                    return p;
+            }
+    }
+    return undefined;
+}
+/**
+ * The browser a macOS automated run should use: HELIX_VQA_CHROME, else the Playwright build's own Chromium, else any
+ * cached Chrome for Testing. Never the system Chrome. Returns undefined off macOS (callers keep their platform default).
+ */
+function resolveAutomationChromium(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const env = opts.env ?? process.env;
+    const override = opts.override ?? env.HELIX_VQA_CHROME;
+    if (override) {
+        assertNotSystemChrome(override, undefined, platform);
+        return override;
+    }
+    if (platform !== 'darwin')
+        return undefined;
+    if (opts.playwrightDefault && node_fs_1.default.existsSync(opts.playwrightDefault)) {
+        assertNotSystemChrome(opts.playwrightDefault, undefined, platform);
+        return opts.playwrightDefault;
+    }
+    const cached = findCachedAutomationChromium(opts.home, env);
+    if (cached)
+        return cached;
+    throw new Error('No Playwright Chromium / Chrome for Testing found. Run `npx playwright install chromium` (the system Google Chrome is never used for automation on macOS).');
+}
+//# sourceMappingURL=nonSystemChrome.js.map

package/dist/browser/nonSystemChrome.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonSystemChrome.js","sourceRoot":"","sources":["../../src/browser/nonSystemChrome.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+import './stdioBlocking';

package/dist/index.js

@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+require("./stdioBlocking");
 const baseColorGuard_1 = require("./character/baseColorGuard");
 const normalMapGuard_1 = require("./character/normalMapGuard");
 const itemSetVersion_1 = require("./itemSetVersion");
@@ -1766,7 +1767,7 @@ item
     .option('--host <id...>', 'only fit onto these host/base item ids (add-ons, wearables)')
     .option('--package-version <version>', 'render this version of the item\'s pinned package instead of the pin: a version move judged before the pointer moves (vehicles, avatars, add-ons, wearables)')
     .option('--vehicle-package <file>', 'with --package-version on a vehicle: the version move\'s vehicle package JSON, served by Try Now after server-side preparation')
-    .option('--chrome <path>', 'Chrome/Chromium executable (default: system Chrome, headless)')
+    .option('--chrome <path>', 'Chromium executable (default: Playwright Chromium / Chrome for Testing, headless; the macOS system Chrome is refused)')
     .option('--api-url <url>', 'platform API base URL')
     .option('--web-url <url>', 'website base URL (default: the site that serves --api-url)')
     .option('--json', 'print the outcome as JSON')
@@ -1777,6 +1778,9 @@ item
         const flagError = validateCandidateFlags({ packageVersion: opts.packageVersion, vehiclePackageFile: opts.vehiclePackage, submitHosted: !!(opts.hosted || opts.status || opts.hostedWorker) });
         if (flagError)
             fail(`✖ ${flagError}`);
+        if (process.platform === 'darwin' && !opts.hosted && !opts.status && !opts.hostedWorker && !opts.packageVersion && !opts.json) {
+            console.error('tip: a published version can render on the platform GPU with --hosted (no local Chrome); local renders share this Mac\'s cap of 4 concurrent automated browsers.');
+        }
         const vehiclePackage = opts.vehiclePackage ? parseVehiclePackage((0, node_fs_1.readFileSync)(opts.vehiclePackage, 'utf8'), opts.vehiclePackage) : null;
         const creds = opts.submit || opts.hosted ? requireAuth() : (0, config_1.loadCredentials)();
         const apiBase = opts.apiUrl ?? creds?.apiUrl ?? config_1.DEFAULT_API_URL;