browser-debugger-cli 0.7.1 → 0.8.0

package/dist/utils/errorMapping.js

@@ -10,7 +10,7 @@
  * consistent, maintainable error handling.
  */
 import { IPCErrorCode } from '../ipc/index.js';
-import { EXIT_CODES } from '../utils/exitCodes.js';
+import { EXIT_CODES } from './exitCodes.js';
 /**
  * Map IPC error codes to semantic exit codes.
  *
@@ -29,14 +29,22 @@ export function getExitCodeForIPCError(errorCode) {
             return EXIT_CODES.RESOURCE_NOT_FOUND;
         case IPCErrorCode.SESSION_ALREADY_RUNNING:
             return EXIT_CODES.RESOURCE_ALREADY_EXISTS;
+        case IPCErrorCode.SESSION_TARGET_MISMATCH:
+            return EXIT_CODES.RESOURCE_CONFLICT;
         case IPCErrorCode.CHROME_LAUNCH_FAILED:
             return EXIT_CODES.CHROME_LAUNCH_FAILURE;
         case IPCErrorCode.CDP_TIMEOUT:
             return EXIT_CODES.CDP_TIMEOUT;
         case IPCErrorCode.SESSION_KILL_FAILED:
             return EXIT_CODES.SESSION_FILE_ERROR;
-        case IPCErrorCode.WORKER_START_FAILED:
-            return EXIT_CODES.CDP_CONNECTION_FAILURE;
+        case IPCErrorCode.NAVIGATION_FAILED:
+            return EXIT_CODES.INVALID_URL;
+        case IPCErrorCode.SESSION_START_FAILED:
+            return EXIT_CODES.SESSION_START_FAILURE;
+        case IPCErrorCode.SESSION_START_CANCELLED:
+            return EXIT_CODES.RESOURCE_CONFLICT;
+        case IPCErrorCode.SESSION_SHUTTING_DOWN:
+            return EXIT_CODES.RESOURCE_BUSY;
         case IPCErrorCode.DAEMON_ERROR:
             return EXIT_CODES.SOFTWARE_ERROR;
         case undefined:
@@ -47,7 +55,7 @@ export function getExitCodeForIPCError(errorCode) {
  * Check if error indicates socket connection failure (daemon not running).
  */
 function isSocketConnectionError(lowerMessage) {
-    return lowerMessage.includes('enoent') || lowerMessage.includes('econnrefused');
+    return /ipc .+ connection error|\bconnect (enoent|econnrefused)\b/.test(lowerMessage);
 }
 /**
  * Map connection error messages to semantic exit codes.
@@ -76,6 +84,9 @@ export function getExitCodeForConnectionError(errorMessage) {
     if (lowerMessage.includes('no active session')) {
         return EXIT_CODES.RESOURCE_NOT_FOUND;
     }
+    if (lowerMessage.includes('still starting')) {
+        return EXIT_CODES.RESOURCE_BUSY;
+    }
     if (lowerMessage.includes('timeout')) {
         return EXIT_CODES.CDP_TIMEOUT;
     }

package/dist/utils/errors.d.ts

@@ -25,4 +25,17 @@
  * ```
  */
 export declare function getErrorMessage(error: unknown): string;
+/**
+ * Read the semantic exit code carried by an error, if any.
+ *
+ * Error classes across bdg (CommandError, IPCError, DaemonError, ...) expose a
+ * numeric `exitCode`. Only integers in 1..255 are trusted, so a foreign error
+ * carrying `exitCode: 0` (or garbage) can never turn a failure into success.
+ * Anything else gets the fallback.
+ *
+ * @param error - Caught error
+ * @param fallback - Exit code when the error carries none
+ * @returns Exit code
+ */
+export declare function getErrorExitCode(error: unknown, fallback: number): number;
 //# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.js

@@ -30,4 +30,25 @@ export function getErrorMessage(error) {
     }
     return String(error);
 }
+/**
+ * Read the semantic exit code carried by an error, if any.
+ *
+ * Error classes across bdg (CommandError, IPCError, DaemonError, ...) expose a
+ * numeric `exitCode`. Only integers in 1..255 are trusted, so a foreign error
+ * carrying `exitCode: 0` (or garbage) can never turn a failure into success.
+ * Anything else gets the fallback.
+ *
+ * @param error - Caught error
+ * @param fallback - Exit code when the error carries none
+ * @returns Exit code
+ */
+export function getErrorExitCode(error, fallback) {
+    if (error instanceof Error && 'exitCode' in error) {
+        const code = error.exitCode;
+        if (typeof code === 'number' && Number.isInteger(code) && code >= 1 && code <= 255) {
+            return code;
+        }
+    }
+    return fallback;
+}
 //# sourceMappingURL=errors.js.map

package/dist/utils/exitCodes.d.ts

@@ -44,13 +44,18 @@ export declare const EXIT_CODES: {
     readonly STALE_CACHE: 87;
     readonly NO_FORMS_FOUND: 88;
     readonly FORM_IN_IFRAME: 89;
+    readonly RESOURCE_CONFLICT: 90;
+    readonly SCRIPT_ERROR: 91;
     readonly CHROME_LAUNCH_FAILURE: 100;
     readonly CDP_CONNECTION_FAILURE: 101;
     readonly CDP_TIMEOUT: 102;
     readonly SESSION_FILE_ERROR: 103;
     readonly UNHANDLED_EXCEPTION: 104;
     readonly SIGNAL_HANDLER_ERROR: 105;
+    readonly SESSION_START_FAILURE: 106;
     readonly SOFTWARE_ERROR: 110;
+    readonly INTERRUPTED: 130;
+    readonly TERMINATED: 143;
 };
 /**
  * Exit code registry entry with code, name, and description.

package/dist/utils/exitCodes.js

@@ -44,13 +44,18 @@ export const EXIT_CODES = {
     STALE_CACHE: 87,
     NO_FORMS_FOUND: 88,
     FORM_IN_IFRAME: 89,
+    RESOURCE_CONFLICT: 90,
+    SCRIPT_ERROR: 91,
     CHROME_LAUNCH_FAILURE: 100,
     CDP_CONNECTION_FAILURE: 101,
     CDP_TIMEOUT: 102,
     SESSION_FILE_ERROR: 103,
     UNHANDLED_EXCEPTION: 104,
     SIGNAL_HANDLER_ERROR: 105,
+    SESSION_START_FAILURE: 106,
     SOFTWARE_ERROR: 110,
+    INTERRUPTED: 130,
+    TERMINATED: 143,
 };
 /**
  * Exit code registry - provides documentation for all exit codes.
@@ -93,7 +98,7 @@ export const EXIT_CODE_REGISTRY = [
     {
         code: EXIT_CODES.RESOURCE_BUSY,
         name: 'RESOURCE_BUSY',
-        description: 'Resource is locked or busy',
+        description: 'Resource is locked or busy (e.g., a session still shutting down)',
     },
     {
         code: EXIT_CODES.DAEMON_ALREADY_RUNNING,
@@ -115,6 +120,16 @@ export const EXIT_CODE_REGISTRY = [
         name: 'FORM_IN_IFRAME',
         description: 'Form is inside an iframe (cross-origin or same-origin)',
     },
+    {
+        code: EXIT_CODES.RESOURCE_CONFLICT,
+        name: 'RESOURCE_CONFLICT',
+        description: 'Request conflicts with current state (e.g., session attached to different target, start cancelled by bdg stop)',
+    },
+    {
+        code: EXIT_CODES.SCRIPT_ERROR,
+        name: 'SCRIPT_ERROR',
+        description: 'The JavaScript passed to bdg dom eval threw an exception',
+    },
     {
         code: EXIT_CODES.CHROME_LAUNCH_FAILURE,
         name: 'CHROME_LAUNCH_FAILURE',
@@ -125,7 +140,11 @@ export const EXIT_CODE_REGISTRY = [
         name: 'CDP_CONNECTION_FAILURE',
         description: 'Failed to connect to Chrome DevTools Protocol',
     },
-    { code: EXIT_CODES.CDP_TIMEOUT, name: 'CDP_TIMEOUT', description: 'CDP operation timed out' },
+    {
+        code: EXIT_CODES.CDP_TIMEOUT,
+        name: 'CDP_TIMEOUT',
+        description: 'CDP operation timed out, or the session did not respond',
+    },
     {
         code: EXIT_CODES.SESSION_FILE_ERROR,
         name: 'SESSION_FILE_ERROR',
@@ -141,10 +160,25 @@ export const EXIT_CODE_REGISTRY = [
         name: 'SIGNAL_HANDLER_ERROR',
         description: 'Signal handler error',
     },
+    {
+        code: EXIT_CODES.SESSION_START_FAILURE,
+        name: 'SESSION_START_FAILURE',
+        description: 'Session failed to start (Chrome launch or CDP connection)',
+    },
     {
         code: EXIT_CODES.SOFTWARE_ERROR,
         name: 'SOFTWARE_ERROR',
         description: 'Generic software error (use specific codes when possible)',
     },
+    {
+        code: EXIT_CODES.INTERRUPTED,
+        name: 'INTERRUPTED',
+        description: 'Interrupted by Ctrl-C (128 + SIGINT); a start in progress is cancelled',
+    },
+    {
+        code: EXIT_CODES.TERMINATED,
+        name: 'TERMINATED',
+        description: 'Stopped by SIGTERM (128 + 15); a start in progress is cancelled',
+    },
 ];
 //# sourceMappingURL=exitCodes.js.map

package/dist/utils/http.d.ts

@@ -1,5 +1,16 @@
-import type { CDPTarget } from '../types';
+import type { CDPTarget } from '../types.js';
 import type { Logger } from '../ui/logging/index.js';
+/**
+ * Options for CDP HTTP target fetch.
+ */
+export interface FetchCDPTargetsOptions {
+    /** Host to reach Chrome on (defaults to HTTP_LOCALHOST). */
+    host?: string;
+    /** Request timeout in milliseconds (defaults to CDP_HTTP_TIMEOUT_MS). */
+    timeoutMs?: number;
+    /** Use HTTPS (Chrome behind a TLS proxy, reached via a `wss:` URL). */
+    secure?: boolean;
+}
 /**
  * Fetch CDP targets from Chrome's HTTP API.
  *
@@ -9,15 +20,25 @@ import type { Logger } from '../ui/logging/index.js';
  *
  * @param port - Chrome debugging port (defaults to centralized DEFAULT_CDP_PORT)
  * @param logger - Optional logger for debug output
+ * @param options - Optional host override and custom timeout (for liveness probes against remote Chrome)
  * @returns Promise resolving to array of CDP targets, or empty array on error
  *
  * @remarks
- * - Uses HTTP_LOCALHOST constant for consistent host addressing
+ * - Uses HTTP_LOCALHOST constant by default for host addressing
  * - Returns empty array on HTTP errors, but logs details for debugging
- * - 5-second timeout prevents hanging when Chrome is unreachable
+ * - Default 5-second timeout; override via `options.timeoutMs` for fast probes
  * - Network errors are logged to help diagnose Chrome connectivity issues
  */
-export declare function fetchCDPTargets(port?: number, logger?: Logger): Promise<CDPTarget[]>;
+export declare function fetchCDPTargets(port?: number, logger?: Logger, options?: FetchCDPTargetsOptions): Promise<CDPTarget[]>;
+/**
+ * The browser-level DevTools WebSocket URL of a Chrome (`/json/version`).
+ *
+ * @param port - Chrome debugging port
+ * @param logger - Optional logger for debug output
+ * @param options - Host and HTTPS
+ * @returns The URL, or null if Chrome could not be reached
+ */
+export declare function fetchBrowserWsUrl(port: number, logger?: Logger, options?: Pick<FetchCDPTargetsOptions, 'host' | 'secure'>): Promise<string | null>;
 /**
  * Fetch specific CDP target by ID from Chrome's HTTP API.
  *
@@ -36,4 +57,14 @@ export declare function fetchCDPTargets(port?: number, logger?: Logger): Promise
  * - Inherits timeout and error logging from fetchCDPTargets
  */
 export declare function fetchCDPTargetById(targetId: string, port?: number, logger?: Logger): Promise<CDPTarget | null>;
+/**
+ * Open a new blank page in a Chrome reached over its DevTools HTTP endpoint.
+ *
+ * @param host - Chrome host
+ * @param port - Chrome debugging port
+ * @param logger - Optional logger for debug output
+ * @param options - `secure`: use HTTPS
+ * @returns The new page target, or null if Chrome could not be reached
+ */
+export declare function createPageTarget(host: string, port: number, logger?: Logger, options?: Pick<FetchCDPTargetsOptions, 'secure'>): Promise<CDPTarget | null>;
 //# sourceMappingURL=http.d.ts.map

package/dist/utils/http.js

@@ -1,4 +1,5 @@
 import { DEFAULT_CDP_PORT, HTTP_LOCALHOST } from '../constants.js';
+import { getErrorMessage } from './errors.js';
 /**
  * Timeout for CDP HTTP requests in milliseconds.
  *
@@ -15,19 +16,22 @@ const CDP_HTTP_TIMEOUT_MS = 5000;
  *
  * @param port - Chrome debugging port (defaults to centralized DEFAULT_CDP_PORT)
  * @param logger - Optional logger for debug output
+ * @param options - Optional host override and custom timeout (for liveness probes against remote Chrome)
  * @returns Promise resolving to array of CDP targets, or empty array on error
  *
  * @remarks
- * - Uses HTTP_LOCALHOST constant for consistent host addressing
+ * - Uses HTTP_LOCALHOST constant by default for host addressing
  * - Returns empty array on HTTP errors, but logs details for debugging
- * - 5-second timeout prevents hanging when Chrome is unreachable
+ * - Default 5-second timeout; override via `options.timeoutMs` for fast probes
  * - Network errors are logged to help diagnose Chrome connectivity issues
  */
-export async function fetchCDPTargets(port = DEFAULT_CDP_PORT, logger) {
-    const url = `http://${HTTP_LOCALHOST}:${port}/json/list`;
+export async function fetchCDPTargets(port = DEFAULT_CDP_PORT, logger, options) {
+    const host = options?.host ?? HTTP_LOCALHOST;
+    const timeoutMs = options?.timeoutMs ?? CDP_HTTP_TIMEOUT_MS;
+    const url = `${options?.secure ? 'https' : 'http'}://${host}:${port}/json/list`;
     try {
         const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), CDP_HTTP_TIMEOUT_MS);
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
         try {
             const response = await fetch(url, { signal: controller.signal });
             clearTimeout(timeoutId);
@@ -49,7 +53,7 @@ export async function fetchCDPTargets(port = DEFAULT_CDP_PORT, logger) {
     catch (error) {
         if (error instanceof Error) {
             if (error.name === 'AbortError') {
-                logger?.debug(`CDP HTTP request timeout after ${CDP_HTTP_TIMEOUT_MS}ms (${url})`);
+                logger?.debug(`CDP HTTP request timeout after ${timeoutMs}ms (${url})`);
             }
             else {
                 logger?.debug(`CDP HTTP request error: ${error.message} (${url})`);
@@ -58,6 +62,28 @@ export async function fetchCDPTargets(port = DEFAULT_CDP_PORT, logger) {
         return [];
     }
 }
+/**
+ * The browser-level DevTools WebSocket URL of a Chrome (`/json/version`).
+ *
+ * @param port - Chrome debugging port
+ * @param logger - Optional logger for debug output
+ * @param options - Host and HTTPS
+ * @returns The URL, or null if Chrome could not be reached
+ */
+export async function fetchBrowserWsUrl(port, logger, options) {
+    const url = `${options?.secure ? 'https' : 'http'}://${options?.host ?? HTTP_LOCALHOST}:${port}/json/version`;
+    try {
+        const response = await fetch(url, { signal: AbortSignal.timeout(CDP_HTTP_TIMEOUT_MS) });
+        if (!response.ok)
+            return null;
+        const data = (await response.json());
+        return typeof data.webSocketDebuggerUrl === 'string' ? data.webSocketDebuggerUrl : null;
+    }
+    catch (error) {
+        logger?.debug(`Chrome version request failed: ${getErrorMessage(error)} (${url})`);
+        return null;
+    }
+}
 /**
  * Fetch specific CDP target by ID from Chrome's HTTP API.
  *
@@ -79,4 +105,31 @@ export async function fetchCDPTargetById(targetId, port = DEFAULT_CDP_PORT, logg
     const targets = await fetchCDPTargets(port, logger);
     return targets.find((t) => t.id === targetId) ?? null;
 }
+/**
+ * Open a new blank page in a Chrome reached over its DevTools HTTP endpoint.
+ *
+ * @param host - Chrome host
+ * @param port - Chrome debugging port
+ * @param logger - Optional logger for debug output
+ * @param options - `secure`: use HTTPS
+ * @returns The new page target, or null if Chrome could not be reached
+ */
+export async function createPageTarget(host, port, logger, options) {
+    const url = `${options?.secure ? 'https' : 'http'}://${host}:${port}/json/new?about:blank`;
+    try {
+        const response = await fetch(url, {
+            method: 'PUT',
+            signal: AbortSignal.timeout(CDP_HTTP_TIMEOUT_MS),
+        });
+        if (!response.ok) {
+            logger?.debug(`Opening a page failed: ${response.status} (${url})`);
+            return null;
+        }
+        return (await response.json());
+    }
+    catch (error) {
+        logger?.debug(`Opening a page failed: ${getErrorMessage(error)} (${url})`);
+        return null;
+    }
+}
 //# sourceMappingURL=http.js.map

package/dist/utils/packageRoot.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Package root resolution.
+ *
+ * Paths to package files (package.json, dist/daemon.js) are resolved from the
+ * package root rather than relative to the calling module, so they stay
+ * correct whether the code runs from tsc output, the bundled CLI, or source.
+ */
+/** Absolute path of the bdg package root. */
+export declare const PACKAGE_ROOT: string;
+/** Absolute path of the daemon entry script. */
+export declare const DAEMON_SCRIPT_PATH: string;
+//# sourceMappingURL=packageRoot.d.ts.map

package/dist/utils/packageRoot.js

@@ -0,0 +1,33 @@
+/**
+ * Package root resolution.
+ *
+ * Paths to package files (package.json, dist/daemon.js) are resolved from the
+ * package root rather than relative to the calling module, so they stay
+ * correct whether the code runs from tsc output, the bundled CLI, or source.
+ */
+import { existsSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+/**
+ * Walk up from a directory to the nearest one containing package.json.
+ *
+ * @param startDir - Directory to start searching from
+ * @returns Absolute path of the package root
+ * @throws Error when no package.json exists in any ancestor
+ */
+function findPackageRoot(startDir) {
+    let dir = startDir;
+    while (!existsSync(join(dir, 'package.json'))) {
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new Error(`package.json not found above ${startDir}`);
+        }
+        dir = parent;
+    }
+    return dir;
+}
+/** Absolute path of the bdg package root. */
+export const PACKAGE_ROOT = findPackageRoot(dirname(fileURLToPath(import.meta.url)));
+/** Absolute path of the daemon entry script. */
+export const DAEMON_SCRIPT_PATH = join(PACKAGE_ROOT, 'dist', 'daemon.js');
+//# sourceMappingURL=packageRoot.js.map

package/dist/utils/process.d.ts

@@ -42,4 +42,14 @@ export declare function isProcessAlive(pid: number): boolean;
  * ```
  */
 export declare function killChromeProcess(pid: number, signal?: NodeJS.Signals): void;
+/**
+ * Read a process's full command line.
+ *
+ * Uses `/proc/<pid>/cmdline` where available (Linux, including minimal
+ * containers whose BusyBox `ps` lacks `-o`/`-p`), and `ps` elsewhere (macOS).
+ *
+ * @param pid - Process ID
+ * @returns Command line, or null if unavailable (process gone, or unsupported platform)
+ */
+export declare function getProcessCommand(pid: number): string | null;
 //# sourceMappingURL=process.d.ts.map

package/dist/utils/process.js

@@ -4,7 +4,9 @@
  * Pure utility functions for process operations - no dependencies on domain modules.
  */
 import { spawnSync } from 'child_process';
-import { taskkillStderr, taskkillFailedError } from '../ui/messages/internal.js';
+import * as fs from 'fs';
+import { createLogger } from '../ui/logging/index.js';
+const log = createLogger('chrome');
 /**
  * Check if a process with the given PID is alive.
  *
@@ -73,10 +75,10 @@ export function killChromeProcess(pid, signal = 'SIGTERM') {
         }
         if (result.status !== 0 && result.status !== null) {
             const errorMsg = (result.stderr ?? result.stdout).trim() || 'Unknown error';
-            throw new Error(taskkillFailedError(result.status, errorMsg));
+            throw new Error(`taskkill failed (exit code ${result.status}): ${errorMsg}`);
         }
         if (result.stderr?.trim()) {
-            console.error(taskkillStderr(result.stderr.trim()));
+            log.debug(`taskkill stderr: ${result.stderr.trim()}`);
         }
     }
     else {
@@ -88,4 +90,34 @@ export function killChromeProcess(pid, signal = 'SIGTERM') {
         }
     }
 }
+/**
+ * Read a process's full command line.
+ *
+ * Uses `/proc/<pid>/cmdline` where available (Linux, including minimal
+ * containers whose BusyBox `ps` lacks `-o`/`-p`), and `ps` elsewhere (macOS).
+ *
+ * @param pid - Process ID
+ * @returns Command line, or null if unavailable (process gone, or unsupported platform)
+ */
+export function getProcessCommand(pid) {
+    if (process.platform === 'win32')
+        return null;
+    const procCmdline = `/proc/${pid}/cmdline`;
+    if (fs.existsSync('/proc/self/cmdline')) {
+        try {
+            const command = fs.readFileSync(procCmdline, 'utf-8').replace(/\0/g, ' ').trim();
+            return command.length > 0 ? command : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    const result = spawnSync('ps', ['-ww', '-o', 'command=', '-p', String(pid)], {
+        encoding: 'utf-8',
+    });
+    if (result.error || result.status !== 0)
+        return null;
+    const command = result.stdout.trim();
+    return command.length > 0 ? command : null;
+}
 //# sourceMappingURL=process.js.map

package/dist/utils/selectorFilters.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Playwright-style selector filters: `:has-text("…")`, `:text-is("…")` and
+ * `:visible`.
+ *
+ * They are not CSS, so the selector is split here (in Node) into the CSS the
+ * browser runs and the filters the page applies to its matches. They are only
+ * supported at the end of the last compound of each selector in a list
+ * (`li.item:has-text("x"):visible`, `a:text-is("Home"), button:visible`):
+ * there they narrow down the elements the CSS part matched. Anywhere else
+ * (`div:has-text("x") > button`, `:not(:visible)`) they would have to be
+ * evaluated inside the browser's selector matching, which bdg cannot do.
+ */
+/** Filter applied in the page to the elements the CSS part matched. */
+export type SelectorFilter = {
+    kind: 'has-text';
+    text: string;
+} | {
+    kind: 'text-is';
+    text: string;
+} | {
+    kind: 'visible';
+};
+/** One selector of a selector list: the CSS to run and the filters for its matches. */
+export interface SelectorPart {
+    css: string;
+    filters: SelectorFilter[];
+}
+/**
+ * Split a selector into the CSS part and filters of each selector of its
+ * list.
+ *
+ * @param selector - Selector as the user gave it
+ * @returns The parts, or null for plain CSS (no filters anywhere), which runs unchanged
+ * @throws CommandError (81) for a filter that is not at the end, or a malformed one
+ */
+export declare function parseSelectorFilters(selector: string): SelectorPart[] | null;
+/**
+ * Split a selector list at its top-level commas (not inside quotes,
+ * attribute brackets or parentheses).
+ *
+ * @param selector - Selector list
+ * @returns The selectors, untrimmed
+ */
+export declare function splitSelectorList(selector: string): string[];
+//# sourceMappingURL=selectorFilters.d.ts.map