craftdriver 1.3.0 → 1.5.0

package/dist/lib/electronDeeplink.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Validate a deep-link URL: it must parse and use a custom scheme (not
+ * http/https/file). Returns the URL unchanged on success.
+ */
+export declare function validateDeeplinkUrl(url: string): string;
+/**
+ * Append (or overwrite) a `userData` query parameter carrying the running app's
+ * user-data dir. On Windows and Linux a fresh `open` would spawn a *second*
+ * instance; the app reads this parameter to point the second instance at the same
+ * user-data dir so the single-instance lock routes the URL to the test instance.
+ */
+export declare function appendUserDataDir(url: string, userDataDir: string): string;
+/** OS launcher command + args for a deep-link URL, per platform. */
+export declare function getPlatformCommand(url: string, platform: NodeJS.Platform, appBinaryPath?: string): {
+    command: string;
+    args: string[];
+};
+/** Spawn the OS launcher detached (fire-and-forget); rejects only if the spawn itself fails. */
+export declare function executeDeeplinkCommand(command: string, args: string[]): Promise<void>;
+/** Resolve the final URL to hand to the OS launcher for the given platform. */
+export declare function resolveDeeplinkUrl(url: string, platform: NodeJS.Platform, userDataDir?: string): string;
+//# sourceMappingURL=electronDeeplink.d.ts.map

package/dist/lib/electronDeeplink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"electronDeeplink.d.ts","sourceRoot":"","sources":["../../src/lib/electronDeeplink.ts"],"names":[],"mappings":"AAeA;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAsBvD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAI1E;AAED,oEAAoE;AACpE,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,CAAC,QAAQ,EACzB,aAAa,CAAC,EAAE,MAAM,GACrB;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE,CA2BrC;AAcD,gGAAgG;AAChG,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAqCrF;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,CAAC,QAAQ,EACzB,WAAW,CAAC,EAAE,MAAM,GACnB,MAAM,CAQR"}

package/dist/lib/electronDeeplink.js

@@ -0,0 +1,118 @@
+/**
+ * Deep-link (custom protocol) triggering for Electron — the pure, testable logic
+ * behind `browser.electron.triggerDeeplink(url)`. It opens a `myapp://…` URL the
+ * way an external app would (macOS `open`, Linux `gio open`, Windows `rundll32`),
+ * so the running app's real `open-url` / `second-instance` handler fires.
+ *
+ * The OS launcher and platform routing are separated from the transport so they
+ * can be unit-tested without a live app (see tests/electron-deeplink.test.ts).
+ */
+import { spawn } from 'node:child_process';
+import { CraftdriverError, ErrorCode } from './errors.js';
+/** Protocols that are *not* custom deep links — routing these would hit a browser/FS, not the app. */
+const DISALLOWED_PROTOCOLS = new Set(['http:', 'https:', 'file:']);
+/**
+ * Validate a deep-link URL: it must parse and use a custom scheme (not
+ * http/https/file). Returns the URL unchanged on success.
+ */
+export function validateDeeplinkUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw new CraftdriverError(ErrorCode.INVALID_ARGUMENT, `triggerDeeplink(url): "${url}" is not a valid URL.`, { hint: 'Pass a custom-protocol URL such as myapp://open?file=test.txt.' });
+    }
+    if (DISALLOWED_PROTOCOLS.has(parsed.protocol)) {
+        throw new CraftdriverError(ErrorCode.INVALID_ARGUMENT, `triggerDeeplink(url): "${parsed.protocol.slice(0, -1)}" is not a deep-link protocol.`, {
+            hint: 'Use your app’s registered custom protocol (e.g. myapp://), not http/https/file.',
+            detail: { protocol: parsed.protocol.slice(0, -1) },
+        });
+    }
+    return url;
+}
+/**
+ * Append (or overwrite) a `userData` query parameter carrying the running app's
+ * user-data dir. On Windows and Linux a fresh `open` would spawn a *second*
+ * instance; the app reads this parameter to point the second instance at the same
+ * user-data dir so the single-instance lock routes the URL to the test instance.
+ */
+export function appendUserDataDir(url, userDataDir) {
+    const parsed = new URL(url);
+    parsed.searchParams.set('userData', userDataDir);
+    return parsed.toString();
+}
+/** OS launcher command + args for a deep-link URL, per platform. */
+export function getPlatformCommand(url, platform, appBinaryPath) {
+    switch (platform) {
+        case 'darwin':
+            // `open` re-encodes the query when handing off to the protocol handler, so
+            // decode our appended query once to avoid double-encoding.
+            return { command: 'open', args: [decodeQueryOnce(url)] };
+        case 'linux':
+            return { command: 'gio', args: ['open', url] };
+        case 'win32':
+            if (!appBinaryPath) {
+                throw new CraftdriverError(ErrorCode.ELECTRON_DEEPLINK_FAILED, 'triggerDeeplink requires the app binary path on Windows to route the deep link.', {
+                    hint: 'Launch via Browser.launch({ electron: { appBinaryPath } }) so the running instance is targeted.',
+                });
+            }
+            // rundll32's FileProtocolHandler avoids cmd.exe metacharacter interpretation (e.g. &).
+            return { command: 'rundll32.exe', args: ['url.dll,FileProtocolHandler', url] };
+        default:
+            throw new CraftdriverError(ErrorCode.ELECTRON_DEEPLINK_FAILED, `triggerDeeplink does not support platform "${platform}".`, { hint: 'Supported platforms are macOS (darwin), Linux, and Windows (win32).' });
+    }
+}
+/** Decode the query component once so `open` re-encodes it exactly once on hand-off. */
+function decodeQueryOnce(url) {
+    const q = url.indexOf('?');
+    if (q === -1)
+        return url;
+    const base = url.slice(0, q);
+    try {
+        return `${base}?${decodeURIComponent(url.slice(q + 1))}`;
+    }
+    catch {
+        return url;
+    }
+}
+/** Spawn the OS launcher detached (fire-and-forget); rejects only if the spawn itself fails. */
+export function executeDeeplinkCommand(command, args) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        try {
+            const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+            child.unref();
+            child.on('error', (error) => {
+                if (settled)
+                    return;
+                settled = true;
+                reject(new CraftdriverError(ErrorCode.ELECTRON_DEEPLINK_FAILED, `Failed to run the deep-link launcher "${command}": ${error.message}`, { cause: error, detail: { command } }));
+            });
+            // The launcher exits quickly; resolve on next tick once no synchronous error fired.
+            process.nextTick(() => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve();
+            });
+        }
+        catch (error) {
+            if (settled)
+                return;
+            settled = true;
+            reject(new CraftdriverError(ErrorCode.ELECTRON_DEEPLINK_FAILED, `Failed to run the deep-link launcher "${command}": ${error instanceof Error ? error.message : String(error)}`, { cause: error, detail: { command } }));
+        }
+    });
+}
+/** Resolve the final URL to hand to the OS launcher for the given platform. */
+export function resolveDeeplinkUrl(url, platform, userDataDir) {
+    const validated = validateDeeplinkUrl(url);
+    // Only Windows/Linux need the second-instance routing hint; macOS `open-url`
+    // reaches the running instance directly.
+    if ((platform === 'win32' || platform === 'linux') && userDataDir) {
+        return appendUserDataDir(validated, userDataDir);
+    }
+    return validated;
+}
+//# sourceMappingURL=electronDeeplink.js.map

package/dist/lib/electronDeeplink.js.map

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

package/dist/lib/electronDiagnostics.d.ts

@@ -0,0 +1,49 @@
+export type BinaryArch = 'x64' | 'arm64';
+/**
+ * Best-effort CPU arch of an executable, read from its Mach-O / ELF header
+ * (no child process). Returns `undefined` for a universal/fat binary (no single
+ * arch), a Windows PE (not parsed here), or anything unrecognized — callers then
+ * skip the arch check rather than guess.
+ */
+export declare function readBinaryArch(filePath: string): BinaryArch | undefined;
+/**
+ * Fail before spawning when the chromedriver's CPU arch can't match the runtime
+ * that has to exec it (e.g. an x64 electron-chromedriver on an arm64 host). A
+ * pure header read; skips silently when the arch can't be determined.
+ */
+export declare function assertDriverArchCompatible(driverPath: string): void;
+/**
+ * Fail before session creation when the resolved chromedriver's major doesn't
+ * match the Chromium the app's Electron version bundles — the exact mismatch
+ * that otherwise surfaces as an opaque "session not created" deep in startup.
+ * Only meaningful when the app's Electron version is known (explicit or detected)
+ * AND the driver reports a version; skips otherwise.
+ */
+export declare function assertDriverChromiumMajorCompatible(driverPath: string, electronVersion: string): void;
+export type MacSigningState = 'unsigned' | 'adhoc' | 'signed' | 'unknown';
+/**
+ * Probe an app binary's code signature via `codesign -dv`. An unsigned or
+ * ad-hoc-signed app is what Gatekeeper/AMFI kills on locked-down macOS, which
+ * chromedriver reports only as "Chrome instance exited". macOS-only; returns
+ * `'unknown'` on any other platform or probe failure.
+ */
+export declare function probeMacAppSigning(appBinaryPath: string): MacSigningState;
+/** Heuristic: did session creation fail because the app process exited/crashed? */
+export declare function isElectronInstanceExitedError(error: unknown): boolean;
+export interface ElectronLaunchDiagnosticsInput {
+    appBinaryPath: string;
+    /** Chromium/app args passed at launch (checked for `--no-sandbox`). */
+    args?: string[];
+    /** Bounded chromedriver stdout/stderr tail, e.g. `ElectronService#getOutputTail()`. */
+    driverOutputTail?: string;
+    /** Override the host platform (tests exercise both branches on one host). */
+    platform?: NodeJS.Platform;
+}
+/**
+ * Enrich a session-creation failure on the Electron path with the diagnosed
+ * likely cause and the chromedriver output tail. Returns the original error
+ * unchanged when it isn't the app-exited class (so unrelated failures aren't
+ * mislabeled).
+ */
+export declare function diagnoseElectronLaunchFailure(cause: unknown, input: ElectronLaunchDiagnosticsInput): unknown;
+//# sourceMappingURL=electronDiagnostics.d.ts.map

package/dist/lib/electronDiagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"electronDiagnostics.d.ts","sourceRoot":"","sources":["../../src/lib/electronDiagnostics.ts"],"names":[],"mappings":"AAcA,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,OAAO,CAAC;AAEzC;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS,CAgCvE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAgBnE;AAED;;;;;;GAMG;AACH,wBAAgB,mCAAmC,CACjD,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,MAAM,GACtB,IAAI,CA0BN;AAED,MAAM,MAAM,eAAe,GAAG,UAAU,GAAG,OAAO,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE1E;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,aAAa,EAAE,MAAM,GAAG,eAAe,CAgBzE;AAED,mFAAmF;AACnF,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CASrE;AAED,MAAM,WAAW,8BAA8B;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,uEAAuE;IACvE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,OAAO,EACd,KAAK,EAAE,8BAA8B,GACpC,OAAO,CAgDT"}

package/dist/lib/electronDiagnostics.js

@@ -0,0 +1,195 @@
+/**
+ * Electron launch diagnostics: turn opaque "Chrome instance exited" / mismatched
+ * driver failures into actionable {@link CraftdriverError}s, either before the
+ * driver spawns (arch / Chromium-major mismatch) or when session creation dies
+ * (macOS signing/Gatekeeper, Linux sandbox). See docs/electron.md "Troubleshooting".
+ */
+import fs from 'fs';
+import os from 'os';
+import { spawnSync } from 'child_process';
+import { CraftdriverError, ErrorCode } from './errors.js';
+import { chromiumMajorForElectron } from './electronVersions.js';
+import { readChromeDriverVersion } from './driverManager.js';
+import { PATH_PROBE_TIMEOUT_MS } from './timing.js';
+/**
+ * Best-effort CPU arch of an executable, read from its Mach-O / ELF header
+ * (no child process). Returns `undefined` for a universal/fat binary (no single
+ * arch), a Windows PE (not parsed here), or anything unrecognized — callers then
+ * skip the arch check rather than guess.
+ */
+export function readBinaryArch(filePath) {
+    let fd;
+    try {
+        fd = fs.openSync(filePath, 'r');
+        const buf = Buffer.alloc(20);
+        const read = fs.readSync(fd, buf, 0, 20, 0);
+        if (read < 20)
+            return undefined;
+        // Mach-O 64-bit, little-endian (MH_MAGIC_64 = 0xFEEDFACF on disk as CF FA ED FE).
+        if (buf.readUInt32LE(0) === 0xfeedfacf) {
+            const cpuType = buf.readInt32LE(4);
+            if (cpuType === 0x01000007)
+                return 'x64'; // CPU_TYPE_X86_64
+            if (cpuType === 0x0100000c)
+                return 'arm64'; // CPU_TYPE_ARM64
+            return undefined;
+        }
+        // Fat/universal (0xCAFEBABE, big-endian): multiple arches, no single answer.
+        if (buf.readUInt32BE(0) === 0xcafebabe)
+            return undefined;
+        // ELF: 0x7F 'E' 'L' 'F'.
+        if (buf[0] === 0x7f && buf[1] === 0x45 && buf[2] === 0x4c && buf[3] === 0x46) {
+            const littleEndian = buf[5] === 1; // EI_DATA: 1 = LE, 2 = BE
+            const machine = littleEndian ? buf.readUInt16LE(18) : buf.readUInt16BE(18);
+            if (machine === 0x3e)
+                return 'x64'; // EM_X86_64
+            if (machine === 0xb7)
+                return 'arm64'; // EM_AARCH64
+            return undefined;
+        }
+        return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+/**
+ * Fail before spawning when the chromedriver's CPU arch can't match the runtime
+ * that has to exec it (e.g. an x64 electron-chromedriver on an arm64 host). A
+ * pure header read; skips silently when the arch can't be determined.
+ */
+export function assertDriverArchCompatible(driverPath) {
+    const driverArch = readBinaryArch(driverPath);
+    const runtimeArch = os.arch();
+    if (!driverArch || (runtimeArch !== 'x64' && runtimeArch !== 'arm64'))
+        return;
+    if (driverArch === runtimeArch)
+        return;
+    throw new CraftdriverError(ErrorCode.ELECTRON_DRIVER_MISMATCH, `The chromedriver at "${driverPath}" is ${driverArch}, but this process is ${runtimeArch} — ` +
+        'it cannot launch and the Electron session would fail to start.', {
+        detail: { kind: 'arch', driverPath, driverArch, runtimeArch },
+        hint: `Install/point at a ${runtimeArch} chromedriver (electron-chromedriver for your arch, ` +
+            'or let craftdriver download one via electron.version).',
+    });
+}
+/**
+ * Fail before session creation when the resolved chromedriver's major doesn't
+ * match the Chromium the app's Electron version bundles — the exact mismatch
+ * that otherwise surfaces as an opaque "session not created" deep in startup.
+ * Only meaningful when the app's Electron version is known (explicit or detected)
+ * AND the driver reports a version; skips otherwise.
+ */
+export function assertDriverChromiumMajorCompatible(driverPath, electronVersion) {
+    const expectedMajor = chromiumMajorForElectron(electronVersion);
+    if (expectedMajor === undefined)
+        return; // unknown mapping — nothing to assert against
+    const driverVersion = readChromeDriverVersion(driverPath);
+    if (!driverVersion)
+        return; // couldn't read — let the real spawn surface any error
+    const driverMajor = Number.parseInt(driverVersion.split('.')[0], 10);
+    if (!Number.isFinite(driverMajor) || driverMajor === expectedMajor)
+        return;
+    throw new CraftdriverError(ErrorCode.ELECTRON_DRIVER_MISMATCH, `chromedriver ${driverVersion} (major ${driverMajor}) does not match Electron ` +
+        `${electronVersion}, which bundles Chromium ${expectedMajor} — the session would fail to start.`, {
+        detail: {
+            kind: 'chromium-major',
+            driverPath,
+            driverVersion,
+            driverMajor,
+            electronVersion,
+            expectedChromiumMajor: expectedMajor,
+        },
+        hint: `Use a chromedriver matching Chromium ${expectedMajor} (pin ` +
+            `electron-chromedriver@${electronVersion.split('.')[0]}, or set electron.version so ` +
+            'craftdriver downloads the matching Chrome-for-Testing driver).',
+    });
+}
+/**
+ * Probe an app binary's code signature via `codesign -dv`. An unsigned or
+ * ad-hoc-signed app is what Gatekeeper/AMFI kills on locked-down macOS, which
+ * chromedriver reports only as "Chrome instance exited". macOS-only; returns
+ * `'unknown'` on any other platform or probe failure.
+ */
+export function probeMacAppSigning(appBinaryPath) {
+    if (os.platform() !== 'darwin')
+        return 'unknown';
+    const result = spawnSync('codesign', ['-dv', appBinaryPath], {
+        encoding: 'utf8',
+        timeout: PATH_PROBE_TIMEOUT_MS,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.error)
+        return 'unknown';
+    const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`;
+    if (/code object is not signed at all/i.test(output))
+        return 'unsigned';
+    // Ad-hoc shows up as `flags=0x2(adhoc)` and `Signature=adhoc`; check before the
+    // generic signed signal since ad-hoc binaries also carry a CodeDirectory.
+    if (/\badhoc\b/i.test(output))
+        return 'adhoc';
+    if (result.status === 0 && /(CodeDirectory|Signature size=|Authority=)/i.test(output))
+        return 'signed';
+    return 'unknown';
+}
+/** Heuristic: did session creation fail because the app process exited/crashed? */
+export function isElectronInstanceExitedError(error) {
+    const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+    return (message.includes('chrome instance exited') ||
+        message.includes('session not created') ||
+        message.includes('chrome failed to start') ||
+        message.includes('crashed') ||
+        message.includes('devtoolsactiveport'));
+}
+/**
+ * Enrich a session-creation failure on the Electron path with the diagnosed
+ * likely cause and the chromedriver output tail. Returns the original error
+ * unchanged when it isn't the app-exited class (so unrelated failures aren't
+ * mislabeled).
+ */
+export function diagnoseElectronLaunchFailure(cause, input) {
+    if (!isElectronInstanceExitedError(cause))
+        return cause;
+    const platform = input.platform ?? os.platform();
+    const causeMessage = cause instanceof Error ? cause.message : String(cause);
+    const hints = [];
+    const detail = {
+        platform: `${platform}-${os.arch()}`,
+        appBinaryPath: input.appBinaryPath,
+    };
+    if (platform === 'darwin') {
+        const signing = probeMacAppSigning(input.appBinaryPath);
+        detail.macSigning = signing;
+        if (signing === 'unsigned' || signing === 'adhoc') {
+            hints.push(`The app at "${input.appBinaryPath}" is ${signing === 'adhoc' ? 'only ad-hoc' : 'not'} ` +
+                'code-signed. macOS Gatekeeper/AMFI can kill it before a window opens, which chromedriver ' +
+                'reports as "Chrome instance exited". Sign or notarize the app for a real test target, or ' +
+                'open it once via Finder to clear quarantine for a throwaway.');
+        }
+    }
+    if (platform === 'linux') {
+        const hasNoSandbox = (input.args ?? []).includes('--no-sandbox');
+        detail.sandboxDisabled = hasNoSandbox;
+        if (!hasNoSandbox) {
+            hints.push('On Linux CI the unzipped chrome-sandbox helper loses its root-owned SUID bit, so the ' +
+                'sandbox cannot start and the app exits. Pass electron.args: ["--no-sandbox"] for a ' +
+                'throwaway fixture.');
+        }
+    }
+    const tail = input.driverOutputTail?.trim();
+    const sections = [causeMessage];
+    if (hints.length > 0) {
+        sections.push('Electron launch diagnostics:\n' + hints.map((h) => `  • ${h}`).join('\n'));
+    }
+    if (tail)
+        sections.push(`chromedriver output (tail):\n${tail}`);
+    return new CraftdriverError(ErrorCode.ELECTRON_LAUNCH_FAILED, sections.join('\n\n'), {
+        detail,
+        hint: hints[0],
+        cause,
+    });
+}
+//# sourceMappingURL=electronDiagnostics.js.map

package/dist/lib/electronDiagnostics.js.map

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

package/dist/lib/electronDialogMock.d.ts

@@ -0,0 +1,51 @@
+export type ElectronDialogMethod = 'showOpenDialog' | 'showSaveDialog' | 'showMessageBox';
+/** Scripted result for Electron's asynchronous `dialog.showOpenDialog()`. */
+export interface ElectronOpenDialogResult {
+    canceled: boolean;
+    filePaths: string[];
+    bookmarks?: string[];
+}
+/** Scripted result for Electron's asynchronous `dialog.showSaveDialog()`. */
+export interface ElectronSaveDialogResult {
+    canceled: boolean;
+    filePath: string;
+    bookmark?: string;
+}
+/** Scripted result for Electron's asynchronous `dialog.showMessageBox()`. */
+export interface ElectronMessageBoxResult {
+    response: number;
+    checkboxChecked: boolean;
+}
+export type ElectronDialogResult = ElectronOpenDialogResult | ElectronSaveDialogResult | ElectronMessageBoxResult;
+/** One native-dialog invocation. `options` excludes the optional parent window. */
+export interface ElectronDialogCall {
+    options: unknown;
+}
+interface MainExecutor {
+    executeMain<T = unknown>(fn: (electron: unknown, ...args: unknown[]) => T | Promise<T>, ...args: unknown[]): Promise<T>;
+}
+/** A native-dialog replacement returned by `browser.electron.mockDialog()`. */
+export interface ElectronDialogMock {
+    readonly method: ElectronDialogMethod;
+    getCalls(): Promise<ElectronDialogCall[]>;
+    getCallCount(): Promise<number>;
+    clearCalls(): Promise<void>;
+    restore(): Promise<void>;
+}
+/** Internal implementation; users receive the public interface above. */
+export declare class ElectronDialogMockHandle implements ElectronDialogMock {
+    #private;
+    readonly method: ElectronDialogMethod;
+    constructor(executor: MainExecutor, method: ElectronDialogMethod, id: string, onRestore: () => void);
+    /** Return the JSON-safe options received by every call. */
+    getCalls(): Promise<ElectronDialogCall[]>;
+    /** Return how many times the mocked dialog was called. */
+    getCallCount(): Promise<number>;
+    /** Clear recorded calls without changing the scripted result. */
+    clearCalls(): Promise<void>;
+    /** Restore Electron's original dialog function. Safe to call more than once. */
+    restore(): Promise<void>;
+}
+export declare function validateDialogResult(method: ElectronDialogMethod, result: ElectronDialogResult): void;
+export {};
+//# sourceMappingURL=electronDialogMock.d.ts.map

package/dist/lib/electronDialogMock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"electronDialogMock.d.ts","sourceRoot":"","sources":["../../src/lib/electronDialogMock.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,GAAG,gBAAgB,GAAG,gBAAgB,CAAC;AAE1F,6EAA6E;AAC7E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,6EAA6E;AAC7E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,6EAA6E;AAC7E,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,oBAAoB,GAC5B,wBAAwB,GACxB,wBAAwB,GACxB,wBAAwB,CAAC;AAE7B,mFAAmF;AACnF,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,UAAU,YAAY;IACpB,WAAW,CAAC,CAAC,GAAG,OAAO,EACrB,EAAE,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAC7D,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,CAAC,CAAC,CAAC;CACf;AAED,+EAA+E;AAC/E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;IACtC,QAAQ,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAAC;IAC1C,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAChC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,yEAAyE;AACzE,qBAAa,wBAAyB,YAAW,kBAAkB;;IACjE,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC;gBAOpC,QAAQ,EAAE,YAAY,EACtB,MAAM,EAAE,oBAAoB,EAC5B,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,MAAM,IAAI;IAQvB,2DAA2D;IACrD,QAAQ,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAoB/C,0DAA0D;IACpD,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAIrC,iEAAiE;IAC3D,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBjC,gFAAgF;IAC1E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAkC/B;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,oBAAoB,EAC5B,MAAM,EAAE,oBAAoB,GAC3B,IAAI,CAoCN"}

package/dist/lib/electronDialogMock.js

@@ -0,0 +1,106 @@
+import { CraftdriverError, ErrorCode } from './errors.js';
+/** Internal implementation; users receive the public interface above. */
+export class ElectronDialogMockHandle {
+    method;
+    #id;
+    #executor;
+    #onRestore;
+    #restored = false;
+    constructor(executor, method, id, onRestore) {
+        this.#executor = executor;
+        this.method = method;
+        this.#id = id;
+        this.#onRestore = onRestore;
+    }
+    /** Return the JSON-safe options received by every call. */
+    async getCalls() {
+        this.#assertActive();
+        return this.#executor.executeMain((_electron, method, id) => {
+            const methodName = method;
+            const mockId = id;
+            const key = Symbol.for('craftdriver.electron.dialogMocks');
+            const registry = globalThis[key];
+            const entry = registry?.[methodName];
+            if (!entry || entry.id !== mockId)
+                throw new Error(`Dialog mock ${methodName} is no longer active.`);
+            return entry.calls;
+        }, this.method, this.#id);
+    }
+    /** Return how many times the mocked dialog was called. */
+    async getCallCount() {
+        return (await this.getCalls()).length;
+    }
+    /** Clear recorded calls without changing the scripted result. */
+    async clearCalls() {
+        this.#assertActive();
+        await this.#executor.executeMain((_electron, method, id) => {
+            const methodName = method;
+            const mockId = id;
+            const key = Symbol.for('craftdriver.electron.dialogMocks');
+            const registry = globalThis[key];
+            const entry = registry?.[methodName];
+            if (!entry || entry.id !== mockId)
+                throw new Error(`Dialog mock ${methodName} is no longer active.`);
+            entry.calls.length = 0;
+        }, this.method, this.#id);
+    }
+    /** Restore Electron's original dialog function. Safe to call more than once. */
+    async restore() {
+        if (this.#restored)
+            return;
+        await this.#executor.executeMain((electron, method, id) => {
+            const methodName = method;
+            const mockId = id;
+            const key = Symbol.for('craftdriver.electron.dialogMocks');
+            const registry = globalThis[key];
+            const entry = registry?.[methodName];
+            if (!entry || entry.id !== mockId)
+                return;
+            const dialog = electron.dialog;
+            if (dialog[methodName] === entry.replacement)
+                dialog[methodName] = entry.original;
+            delete registry[methodName];
+        }, this.method, this.#id);
+        this.#restored = true;
+        this.#onRestore();
+    }
+    #assertActive() {
+        if (this.#restored) {
+            throw new CraftdriverError(ErrorCode.STATE_INVALID, `The ${this.method} dialog mock has already been restored.`);
+        }
+    }
+}
+export function validateDialogResult(method, result) {
+    if (!result || typeof result !== 'object' || Array.isArray(result)) {
+        throw invalidResult(method, 'result must be an object');
+    }
+    if (method === 'showOpenDialog') {
+        const value = result;
+        if (typeof value.canceled !== 'boolean' ||
+            !Array.isArray(value.filePaths) ||
+            !value.filePaths.every((path) => typeof path === 'string') ||
+            (value.bookmarks !== undefined &&
+                (!Array.isArray(value.bookmarks) ||
+                    !value.bookmarks.every((bookmark) => typeof bookmark === 'string')))) {
+            throw invalidResult(method, 'expected { canceled: boolean, filePaths: string[] }');
+        }
+        return;
+    }
+    if (method === 'showSaveDialog') {
+        const value = result;
+        if (typeof value.canceled !== 'boolean' ||
+            typeof value.filePath !== 'string' ||
+            (value.bookmark !== undefined && typeof value.bookmark !== 'string')) {
+            throw invalidResult(method, 'expected { canceled: boolean, filePath: string }');
+        }
+        return;
+    }
+    const value = result;
+    if (!Number.isInteger(value.response) || typeof value.checkboxChecked !== 'boolean') {
+        throw invalidResult(method, 'expected { response: integer, checkboxChecked: boolean }');
+    }
+}
+function invalidResult(method, expected) {
+    return new CraftdriverError(ErrorCode.INVALID_ARGUMENT, `Invalid result for electron.mockDialog('${method}', result): ${expected}.`, { detail: { method } });
+}
+//# sourceMappingURL=electronDialogMock.js.map

package/dist/lib/electronDialogMock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"electronDialogMock.js","sourceRoot":"","sources":["../../src/lib/electronDialogMock.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAkD1D,yEAAyE;AACzE,MAAM,OAAO,wBAAwB;IAC1B,MAAM,CAAuB;IAC7B,GAAG,CAAS;IACZ,SAAS,CAAe;IACxB,UAAU,CAAa;IAChC,SAAS,GAAG,KAAK,CAAC;IAElB,YACE,QAAsB,EACtB,MAA4B,EAC5B,EAAU,EACV,SAAqB;QAErB,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;QAC1B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QACd,IAAI,CAAC,UAAU,GAAG,SAAS,CAAC;IAC9B,CAAC;IAED,2DAA2D;IAC3D,KAAK,CAAC,QAAQ;QACZ,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC,SAAS,CAAC,WAAW,CAC/B,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE;YACxB,MAAM,UAAU,GAAG,MAAgB,CAAC;YACpC,MAAM,MAAM,GAAG,EAAY,CAAC;YAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;YAC3D,MAAM,QAAQ,GAAI,UAAsD,CAAC,GAAG,CAE/D,CAAC;YACd,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC,UAAU,CAAC,CAAC;YACrC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,EAAE,KAAK,MAAM;gBAC/B,MAAM,IAAI,KAAK,CAAC,eAAe,UAAU,uBAAuB,CAAC,CAAC;YACpE,OAAO,KAAK,CAAC,KAAK,CAAC;QACrB,CAAC,EACD,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,GAAG,CACT,CAAC;IACJ,CAAC;IAED,0DAA0D;IAC1D,KAAK,CAAC,YAAY;QAChB,OAAO,CAAC,MAAM,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;IACxC,CAAC;IAED,iEAAiE;IACjE,KAAK,CAAC,UAAU;QACd,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,MAAM,IAAI,CAAC,SAAS,CAAC,WAAW,CAC9B,CAAC,SAAS,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE;YACxB,MAAM,UAAU,GAAG,MAAgB,CAAC;YACpC,MAAM,MAAM,GAAG,EAAY,CAAC;YAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;YAC3D,MAAM,QAAQ,GAAI,UAAsD,CAAC,GAAG,CAE/D,CAAC;YACd,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC,UAAU,CAAC,CAAC;YACrC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,EAAE,KAAK,MAAM;gBAC/B,MAAM,IAAI,KAAK,CAAC,eAAe,UAAU,uBAAuB,CAAC,CAAC;YACpE,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC;QACzB,CAAC,EACD,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,GAAG,CACT,CAAC;IACJ,CAAC;IAED,gFAAgF;IAChF,KAAK,CAAC,OAAO;QACX,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAC3B,MAAM,IAAI,CAAC,SAAS,CAAC,WAAW,CAC9B,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE;YACvB,MAAM,UAAU,GAAG,MAAgB,CAAC;YACpC,MAAM,MAAM,GAAG,EAAY,CAAC;YAC5B,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,CAAC,kCAAkC,CAAC,CAAC;YAC3D,MAAM,QAAQ,GAAI,UAAsD,CAAC,GAAG,CAK/D,CAAC;YACd,MAAM,KAAK,GAAG,QAAQ,EAAE,CAAC,UAAU,CAAC,CAAC;YACrC,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,EAAE,KAAK,MAAM;gBAAE,OAAO;YAC1C,MAAM,MAAM,GAAI,QAAgD,CAAC,MAAM,CAAC;YACxE,IAAI,MAAM,CAAC,UAAU,CAAC,KAAK,KAAK,CAAC,WAAW;gBAAE,MAAM,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC;YAClF,OAAO,QAAS,CAAC,UAAU,CAAC,CAAC;QAC/B,CAAC,EACD,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,GAAG,CACT,CAAC;QACF,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,UAAU,EAAE,CAAC;IACpB,CAAC;IAED,aAAa;QACX,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,gBAAgB,CACxB,SAAS,CAAC,aAAa,EACvB,OAAO,IAAI,CAAC,MAAM,yCAAyC,CAC5D,CAAC;QACJ,CAAC;IACH,CAAC;CACF;AAED,MAAM,UAAU,oBAAoB,CAClC,MAA4B,EAC5B,MAA4B;IAE5B,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACnE,MAAM,aAAa,CAAC,MAAM,EAAE,0BAA0B,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,MAAM,KAAK,gBAAgB,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,MAAkC,CAAC;QACjD,IACE,OAAO,KAAK,CAAC,QAAQ,KAAK,SAAS;YACnC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC;YAC/B,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,CAAC;YAC1D,CAAC,KAAK,CAAC,SAAS,KAAK,SAAS;gBAC5B,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC;oBAC9B,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,EACxE,CAAC;YACD,MAAM,aAAa,CAAC,MAAM,EAAE,qDAAqD,CAAC,CAAC;QACrF,CAAC;QACD,OAAO;IACT,CAAC;IAED,IAAI,MAAM,KAAK,gBAAgB,EAAE,CAAC;QAChC,MAAM,KAAK,GAAG,MAAkC,CAAC;QACjD,IACE,OAAO,KAAK,CAAC,QAAQ,KAAK,SAAS;YACnC,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ;YAClC,CAAC,KAAK,CAAC,QAAQ,KAAK,SAAS,IAAI,OAAO,KAAK,CAAC,QAAQ,KAAK,QAAQ,CAAC,EACpE,CAAC;YACD,MAAM,aAAa,CAAC,MAAM,EAAE,kDAAkD,CAAC,CAAC;QAClF,CAAC;QACD,OAAO;IACT,CAAC;IAED,MAAM,KAAK,GAAG,MAAkC,CAAC;IACjD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,OAAO,KAAK,CAAC,eAAe,KAAK,SAAS,EAAE,CAAC;QACpF,MAAM,aAAa,CAAC,MAAM,EAAE,0DAA0D,CAAC,CAAC;IAC1F,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,MAA4B,EAAE,QAAgB;IACnE,OAAO,IAAI,gBAAgB,CACzB,SAAS,CAAC,gBAAgB,EAC1B,2CAA2C,MAAM,eAAe,QAAQ,GAAG,EAC3E,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,CACvB,CAAC;AACJ,CAAC"}

package/dist/lib/electronFuses.d.ts

@@ -0,0 +1,13 @@
+export type InspectFuseStatus = 'enabled' | 'disabled' | 'removed' | 'unknown';
+/**
+ * The binary that actually carries the fuse wire for a given app executable. On
+ * macOS that's the Electron Framework inside the `.app`; elsewhere it's the
+ * executable itself.
+ */
+export declare function fuseCarrierBinary(appBinaryPath: string): string;
+/**
+ * Read the `EnableNodeCliInspectArguments` fuse straight from the packaged binary.
+ * Returns `'unknown'` for any older/unfused binary or on any read problem.
+ */
+export declare function readInspectArgumentsFuse(appBinaryPath: string | undefined): InspectFuseStatus;
+//# sourceMappingURL=electronFuses.d.ts.map

package/dist/lib/electronFuses.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"electronFuses.d.ts","sourceRoot":"","sources":["../../src/lib/electronFuses.ts"],"names":[],"mappings":"AA4BA,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAE/E;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAU/D;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,iBAAiB,CAqC7F"}