@rightkit/qa 0.2.2 → 0.2.3

package/dist/chrome.d.ts

@@ -1,99 +1 @@
-/**
- * Chrome for Testing for repository QA: one resolver, one launcher, one graceful close.
- *
- * Regular Google Chrome on macOS makes an APFS clone of its app bundle per instance
- * (`<DARWIN_USER_TEMP_DIR>/../X/com.google.Chrome.code_sign_clone/`). A normal shutdown
- * removes it; SIGKILL or a crash leaves it behind. Chrome for Testing does not create the
- * clone, and a graceful close (CDP `Browser.close`, then SIGTERM, then SIGKILL last) lets
- * any browser clean up. Harnesses never fall back to regular Chrome silently.
- *
- * This is for repo-owned web/CDP harnesses only. The native lane (`native.ts`) drives the
- * app's own Tauri WebView and is unaffected.
- */
-import { type ChildProcess } from 'node:child_process';
-/** Environment variable naming an explicit Chrome for Testing executable. */
-export declare const CHROME_FOR_TESTING_ENV = "RIGHTKIT_CHROME_FOR_TESTING";
-export declare const CHROME_FOR_TESTING_INSTALL_HINT: string;
-export declare class ChromeForTestingNotFoundError extends Error {
-    readonly searched: string[];
-    constructor(message: string, searched: string[]);
-}
-export interface ResolveChromeForTestingOptions {
-    /** Explicit executable; wins over the environment and known locations. */
-    executablePath?: string;
-    env?: NodeJS.ProcessEnv;
-    platform?: NodeJS.Platform;
-    arch?: string;
-    homedir?: string;
-}
-/**
- * Known Chrome for Testing install locations in resolution order (after the explicit option
- * and the environment variable): app installs, then Puppeteer's cache, then Playwright's
- * cache, newest version first within each cache.
- */
-export declare function chromeForTestingCandidates(options?: ResolveChromeForTestingOptions): string[];
-/**
- * Resolve the Chrome for Testing executable: `executablePath`, then `RIGHTKIT_CHROME_FOR_TESTING`,
- * then the known install locations. Throws {@link ChromeForTestingNotFoundError} with install
- * instructions when none exists; never falls back to regular Chrome.
- */
-export declare function resolveChromeForTesting(options?: ResolveChromeForTestingOptions): string;
-/** Non-throwing form for test skips: `{ path }` or `{ reason }`. */
-export declare function findChromeForTesting(options?: ResolveChromeForTestingOptions): {
-    path?: string;
-    reason?: string;
-};
-export interface LaunchChromeOptions extends ResolveChromeForTestingOptions {
-    /** Default true (`--headless=new`). */
-    headless?: boolean;
-    /** Default true. */
-    muteAudio?: boolean;
-    /** Extra flags. The launcher owns `--user-data-dir` and `--remote-debugging-port`. */
-    args?: string[];
-    /** Temp profile directory prefix. */
-    profilePrefix?: string;
-    /** Initial URL. Default `about:blank`. */
-    url?: string;
-    /** DevTools endpoint wait. Default 20s. */
-    startTimeoutMs?: number;
-}
-export type ChromeCloseStep = 'cdp' | 'sigterm' | 'sigkill' | 'already-exited';
-export interface ChromeCloseReport {
-    /** The step after which the whole browser process tree was gone. */
-    step: ChromeCloseStep;
-    exited: boolean;
-    profileRemoved: boolean;
-    durationMs: number;
-}
-export interface CloseChromeOptions {
-    /** Per-step grace before escalating. Default 5000 ms. */
-    graceMs?: number;
-}
-export interface ChromeForTestingBrowser {
-    executablePath: string;
-    process: ChildProcess;
-    pid: number;
-    /** Browser-level DevTools WebSocket URL. */
-    wsEndpoint: string;
-    port: number;
-    /** Harness-owned temp profile, removed by {@link ChromeForTestingBrowser.close}. */
-    profileDir: string;
-    /** Graceful close; idempotent. */
-    close(options?: CloseChromeOptions): Promise<ChromeCloseReport>;
-}
-/** Launch Chrome for Testing with a fresh temp profile and a DevTools endpoint. */
-export declare function launchChromeForTesting(options?: LaunchChromeOptions): Promise<ChromeForTestingBrowser>;
-/**
- * Close a Chrome process tree gracefully: CDP `Browser.close`, wait; SIGTERM the process
- * group, wait; SIGKILL only last. Then remove the harness-owned profile directory.
- */
-export declare function closeChromeGracefully(options: {
-    child: ChildProcess;
-    wsEndpoint?: string;
-    profileDir?: string;
-    graceMs?: number;
-}): Promise<ChromeCloseReport>;
-/** macOS per-user `X` directories that hold browser code-sign clones (deduplicated). */
-export declare function codeSignCloneRoots(): string[];
-/** Every entry under every `*.code_sign_clone` directory (e.g. `com.google.Chrome.code_sign_clone`). */
-export declare function codeSignCloneEntries(): string[];
+export * from '@rightkit/qa-chrome';

package/dist/chrome.js

@@ -1,357 +1 @@
-/**
- * Chrome for Testing for repository QA: one resolver, one launcher, one graceful close.
- *
- * Regular Google Chrome on macOS makes an APFS clone of its app bundle per instance
- * (`<DARWIN_USER_TEMP_DIR>/../X/com.google.Chrome.code_sign_clone/`). A normal shutdown
- * removes it; SIGKILL or a crash leaves it behind. Chrome for Testing does not create the
- * clone, and a graceful close (CDP `Browser.close`, then SIGTERM, then SIGKILL last) lets
- * any browser clean up. Harnesses never fall back to regular Chrome silently.
- *
- * This is for repo-owned web/CDP harnesses only. The native lane (`native.ts`) drives the
- * app's own Tauri WebView and is unaffected.
- */
-import { spawn, spawnSync } from 'node:child_process';
-import { existsSync, mkdtempSync, readdirSync, rmSync, statSync } from 'node:fs';
-import { homedir, tmpdir } from 'node:os';
-import path from 'node:path';
-/** Environment variable naming an explicit Chrome for Testing executable. */
-export const CHROME_FOR_TESTING_ENV = 'RIGHTKIT_CHROME_FOR_TESTING';
-export const CHROME_FOR_TESTING_INSTALL_HINT = [
-    'Install Chrome for Testing (any one of):',
-    '  pnpm dlx @puppeteer/browsers install chrome@stable --path ~/.cache/puppeteer',
-    '  pnpm exec playwright install chromium',
-    `or point ${CHROME_FOR_TESTING_ENV} at its executable, e.g.`,
-    `  ${CHROME_FOR_TESTING_ENV}="$HOME/.cache/puppeteer/chrome/mac_arm-<version>/chrome-mac-arm64/Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing"`,
-    'Regular Google Chrome is never used as a fallback: on macOS each killed instance leaks a code-sign clone.',
-].join('\n');
-export class ChromeForTestingNotFoundError extends Error {
-    searched;
-    constructor(message, searched) {
-        super(`${message}\nSearched:\n${searched.map((p) => `  ${p}`).join('\n') || '  (nothing)'}\n${CHROME_FOR_TESTING_INSTALL_HINT}`);
-        this.name = 'ChromeForTestingNotFoundError';
-        this.searched = searched;
-    }
-}
-const MAC_APP = 'Google Chrome for Testing.app/Contents/MacOS/Google Chrome for Testing';
-/** Numeric sort key from a versioned cache dir name (`mac_arm-152.0.7977.75`, `chromium-1243`). */
-function versionKey(name) {
-    return (name.match(/\d+/g) ?? []).map(Number);
-}
-function newestFirst(a, b) {
-    const ka = versionKey(a);
-    const kb = versionKey(b);
-    for (let i = 0; i < Math.max(ka.length, kb.length); i++) {
-        const d = (kb[i] ?? -1) - (ka[i] ?? -1);
-        if (d !== 0)
-            return d;
-    }
-    return b.localeCompare(a);
-}
-function versionedChildren(root, prefix) {
-    try {
-        return readdirSync(root).filter((name) => prefix.test(name)).sort(newestFirst).map((name) => path.join(root, name));
-    }
-    catch {
-        return [];
-    }
-}
-/**
- * Known Chrome for Testing install locations in resolution order (after the explicit option
- * and the environment variable): app installs, then Puppeteer's cache, then Playwright's
- * cache, newest version first within each cache.
- */
-export function chromeForTestingCandidates(options = {}) {
-    const env = options.env ?? process.env;
-    const platform = options.platform ?? process.platform;
-    const arch = options.arch ?? process.arch;
-    const home = options.homedir ?? homedir();
-    const puppeteerRoot = path.join(env.PUPPETEER_CACHE_DIR || path.join(home, '.cache', 'puppeteer'), 'chrome');
-    const out = [];
-    if (platform === 'darwin') {
-        out.push(path.join('/Applications', MAC_APP), path.join(home, 'Applications', MAC_APP));
-        const macDirs = arch === 'arm64' ? ['chrome-mac-arm64', 'chrome-mac-x64'] : ['chrome-mac-x64', 'chrome-mac-arm64'];
-        for (const dir of versionedChildren(puppeteerRoot, /^mac(_arm)?-/)) {
-            for (const sub of macDirs)
-                out.push(path.join(dir, sub, MAC_APP));
-        }
-        const playwrightRoot = env.PLAYWRIGHT_BROWSERS_PATH || path.join(home, 'Library', 'Caches', 'ms-playwright');
-        for (const dir of versionedChildren(playwrightRoot, /^chromium-\d/)) {
-            for (const sub of macDirs)
-                out.push(path.join(dir, sub, MAC_APP));
-        }
-    }
-    else if (platform === 'win32') {
-        const local = env.LOCALAPPDATA || path.join(home, 'AppData', 'Local');
-        for (const dir of versionedChildren(puppeteerRoot, /^win(32|64)-/)) {
-            out.push(path.join(dir, 'chrome-win64', 'chrome.exe'), path.join(dir, 'chrome-win32', 'chrome.exe'));
-        }
-        const playwrightRoot = env.PLAYWRIGHT_BROWSERS_PATH || path.join(local, 'ms-playwright');
-        for (const dir of versionedChildren(playwrightRoot, /^chromium-\d/)) {
-            out.push(path.join(dir, 'chrome-win64', 'chrome.exe'));
-        }
-    }
-    else {
-        for (const dir of versionedChildren(puppeteerRoot, /^linux(_arm)?-/)) {
-            out.push(path.join(dir, 'chrome-linux64', 'chrome'), path.join(dir, 'chrome-linux-arm64', 'chrome'));
-        }
-        const playwrightRoot = env.PLAYWRIGHT_BROWSERS_PATH || path.join(home, '.cache', 'ms-playwright');
-        for (const dir of versionedChildren(playwrightRoot, /^chromium-\d/)) {
-            out.push(path.join(dir, 'chrome-linux64', 'chrome'));
-        }
-    }
-    return out;
-}
-/**
- * Resolve the Chrome for Testing executable: `executablePath`, then `RIGHTKIT_CHROME_FOR_TESTING`,
- * then the known install locations. Throws {@link ChromeForTestingNotFoundError} with install
- * instructions when none exists; never falls back to regular Chrome.
- */
-export function resolveChromeForTesting(options = {}) {
-    const env = options.env ?? process.env;
-    if (options.executablePath) {
-        if (existsSync(options.executablePath))
-            return options.executablePath;
-        throw new ChromeForTestingNotFoundError(`explicit Chrome for Testing executable does not exist: ${options.executablePath}`, [options.executablePath]);
-    }
-    const fromEnv = env[CHROME_FOR_TESTING_ENV];
-    if (fromEnv) {
-        if (existsSync(fromEnv))
-            return fromEnv;
-        throw new ChromeForTestingNotFoundError(`${CHROME_FOR_TESTING_ENV} points at a missing file: ${fromEnv}`, [fromEnv]);
-    }
-    const candidates = chromeForTestingCandidates(options);
-    const found = candidates.find((candidate) => existsSync(candidate));
-    if (found)
-        return found;
-    throw new ChromeForTestingNotFoundError('Chrome for Testing is not installed', candidates);
-}
-/** Non-throwing form for test skips: `{ path }` or `{ reason }`. */
-export function findChromeForTesting(options = {}) {
-    try {
-        return { path: resolveChromeForTesting(options) };
-    }
-    catch (error) {
-        return { reason: error.message };
-    }
-}
-const MANAGED_FLAGS = /^--(user-data-dir|remote-debugging-port|remote-debugging-pipe)(=|$)/;
-/** Launch Chrome for Testing with a fresh temp profile and a DevTools endpoint. */
-export async function launchChromeForTesting(options = {}) {
-    const executablePath = resolveChromeForTesting(options);
-    const extra = options.args ?? [];
-    const managed = extra.find((arg) => MANAGED_FLAGS.test(arg));
-    if (managed)
-        throw new Error(`${managed} is managed by launchChromeForTesting`);
-    const profileDir = mkdtempSync(path.join(tmpdir(), options.profilePrefix ?? 'rk-qa-chrome-'));
-    const args = [
-        ...(options.headless === false ? [] : ['--headless=new']),
-        ...(options.muteAudio === false ? [] : ['--mute-audio']),
-        '--no-first-run',
-        '--no-default-browser-check',
-        '--disable-breakpad',
-        '--password-store=basic',
-        '--use-mock-keychain',
-        ...extra,
-        `--user-data-dir=${profileDir}`,
-        '--remote-debugging-port=0',
-        options.url ?? 'about:blank',
-    ];
-    // Own process group on Unix so the whole tree can be signalled together.
-    const child = spawn(executablePath, args, {
-        stdio: ['ignore', 'ignore', 'pipe'],
-        detached: process.platform !== 'win32',
-        windowsHide: true,
-    });
-    const pid = child.pid;
-    if (!pid) {
-        rmSync(profileDir, { recursive: true, force: true });
-        throw new Error(`failed to start Chrome for Testing: ${executablePath}`);
-    }
-    let closing;
-    // A harness that exits without closing still asks Chrome to shut down gracefully.
-    const onHostExit = () => signalTree(child, 'SIGTERM');
-    process.once('exit', onHostExit);
-    const close = (closeOptions = {}) => {
-        process.removeListener('exit', onHostExit);
-        closing ??= closeChromeGracefully({ child, wsEndpoint, profileDir, ...closeOptions });
-        return closing;
-    };
-    let wsEndpoint;
-    try {
-        wsEndpoint = await new Promise((resolve, reject) => {
-            const timer = setTimeout(() => reject(new Error('Chrome for Testing did not expose a DevTools endpoint')), options.startTimeoutMs ?? 20_000);
-            let buf = '';
-            child.stderr.setEncoding('utf8');
-            // Keep draining after the endpoint line so Chrome never blocks on a full pipe.
-            child.stderr.on('data', (chunk) => {
-                if (wsEndpoint)
-                    return;
-                buf += chunk;
-                const match = buf.match(/DevTools listening on (ws:\/\/\S+)/);
-                if (match) {
-                    clearTimeout(timer);
-                    resolve(match[1]);
-                }
-            });
-            child.once('exit', (code, signal) => {
-                clearTimeout(timer);
-                reject(new Error(`Chrome for Testing exited early (code ${code}, signal ${signal})\n${buf.slice(-2000)}`));
-            });
-            child.once('error', (error) => {
-                clearTimeout(timer);
-                reject(error);
-            });
-        });
-    }
-    catch (error) {
-        await close();
-        throw error;
-    }
-    return {
-        executablePath,
-        process: child,
-        pid,
-        wsEndpoint,
-        port: Number(new URL(wsEndpoint).port),
-        profileDir,
-        close,
-    };
-}
-function treeAlive(child) {
-    const pid = child.pid;
-    if (!pid)
-        return false;
-    if (process.platform === 'win32')
-        return child.exitCode === null && child.signalCode === null;
-    try {
-        process.kill(-pid, 0);
-        return true;
-    }
-    catch (error) {
-        return error.code === 'EPERM';
-    }
-}
-async function waitGone(child, timeoutMs) {
-    const deadline = Date.now() + timeoutMs;
-    while (treeAlive(child)) {
-        if (Date.now() >= deadline)
-            return false;
-        await new Promise((resolve) => setTimeout(resolve, 25));
-    }
-    return true;
-}
-function signalTree(child, signal) {
-    const pid = child.pid;
-    if (!pid)
-        return;
-    if (process.platform === 'win32') {
-        spawnSync('taskkill.exe', ['/PID', String(pid), '/T', ...(signal === 'SIGKILL' ? ['/F'] : [])], { stdio: 'ignore', windowsHide: true });
-        return;
-    }
-    try {
-        process.kill(-pid, signal);
-    }
-    catch {
-        try {
-            child.kill(signal);
-        }
-        catch { /* gone */ }
-    }
-}
-async function sendBrowserClose(wsEndpoint, timeoutMs) {
-    await new Promise((resolve) => {
-        let ws;
-        const done = () => {
-            clearTimeout(timer);
-            try {
-                ws.close();
-            }
-            catch { /* closed */ }
-            resolve();
-        };
-        const timer = setTimeout(done, timeoutMs);
-        try {
-            ws = new WebSocket(wsEndpoint);
-        }
-        catch {
-            clearTimeout(timer);
-            resolve();
-            return;
-        }
-        ws.onopen = () => ws.send(JSON.stringify({ id: 1, method: 'Browser.close' }));
-        ws.onmessage = done;
-        ws.onclose = done;
-        ws.onerror = done;
-    });
-}
-/**
- * Close a Chrome process tree gracefully: CDP `Browser.close`, wait; SIGTERM the process
- * group, wait; SIGKILL only last. Then remove the harness-owned profile directory.
- */
-export async function closeChromeGracefully(options) {
-    const started = Date.now();
-    const grace = options.graceMs ?? 5_000;
-    let step = 'already-exited';
-    let exited = !treeAlive(options.child);
-    if (!exited && options.wsEndpoint) {
-        step = 'cdp';
-        await sendBrowserClose(options.wsEndpoint, Math.min(grace, 2_000));
-        exited = await waitGone(options.child, grace);
-    }
-    if (!exited) {
-        step = 'sigterm';
-        signalTree(options.child, 'SIGTERM');
-        exited = await waitGone(options.child, grace);
-    }
-    if (!exited) {
-        step = 'sigkill';
-        signalTree(options.child, 'SIGKILL');
-        exited = await waitGone(options.child, 2_000);
-    }
-    let profileRemoved = true;
-    if (options.profileDir) {
-        rmSync(options.profileDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 });
-        profileRemoved = !existsSync(options.profileDir);
-    }
-    return { step, exited, profileRemoved, durationMs: Date.now() - started };
-}
-/** macOS per-user `X` directories that hold browser code-sign clones (deduplicated). */
-export function codeSignCloneRoots() {
-    if (process.platform !== 'darwin')
-        return [];
-    const temps = new Set();
-    const conf = spawnSync('getconf', ['DARWIN_USER_TEMP_DIR'], { encoding: 'utf8' });
-    if (conf.status === 0 && conf.stdout.trim())
-        temps.add(path.resolve(conf.stdout.trim()));
-    if (process.env.TMPDIR)
-        temps.add(path.resolve(process.env.TMPDIR));
-    return [...new Set([...temps].map((t) => path.join(path.dirname(t), 'X')))].filter((x) => {
-        try {
-            return statSync(x).isDirectory();
-        }
-        catch {
-            return false;
-        }
-    });
-}
-/** Every entry under every `*.code_sign_clone` directory (e.g. `com.google.Chrome.code_sign_clone`). */
-export function codeSignCloneEntries() {
-    const out = [];
-    for (const root of codeSignCloneRoots()) {
-        let names = [];
-        try {
-            names = readdirSync(root);
-        }
-        catch {
-            continue;
-        }
-        for (const dir of names.filter((n) => n.endsWith('code_sign_clone'))) {
-            try {
-                for (const entry of readdirSync(path.join(root, dir)))
-                    out.push(path.join(root, dir, entry));
-            }
-            catch { /* unreadable */ }
-        }
-    }
-    return out.sort();
-}
+export * from '@rightkit/qa-chrome';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rightkit/qa",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Shared native QA runner, evidence, ownership, and release-backdoor guards for Right Suite apps.",
   "license": "MIT OR Apache-2.0",
   "type": "module",
@@ -27,6 +27,7 @@
   ],
   "sideEffects": false,
   "dependencies": {
+    "@rightkit/qa-chrome": "0.1.0",
     "@wdio/cli": "9.27.1",
     "@wdio/local-runner": "9.27.1",
     "@wdio/mocha-framework": "9.27.1",