browser-debugger-cli 0.7.2 → 0.9.0

package/dist/connection/chromeIdentity.js

@@ -0,0 +1,143 @@
+/**
+ * Identity of the Chrome bdg launched.
+ *
+ * chrome-launcher only waits until something answers on 127.0.0.1:<port>. That
+ * may be another process: when 127.0.0.1:<port> is taken, Chrome listens on
+ * [::1]:<port> instead and the readiness check is answered by the other one.
+ *
+ * Chrome prints `DevTools listening on ws://<host>:<port>/devtools/browser/<id>`
+ * to stderr (chrome-launcher writes it to `chrome-err.log` in the profile).
+ * The browser path is unique per browser, so comparing it with the one
+ * 127.0.0.1:<port> reports tells whether that is the launched Chrome.
+ * (Chrome's `DevToolsActivePort` file holds the same, but Chrome writes it only
+ * for `--remote-debugging-port=0`.)
+ *
+ * A Chrome whose output lacks the line (stderr redirected, a Chromium build
+ * that does not print it) is accepted with a warning when its browser answers
+ * on 127.0.0.1 and nothing listens on [::1]: the port was free on both right
+ * before the launch, and a second listener is how a conflict shows.
+ */
+import { createLogger } from '../ui/logging/index.js';
+import { delay } from '../utils/async.js';
+import { fetchBrowserWsUrl } from '../utils/http.js';
+import { isProcessAlive } from '../utils/process.js';
+import { ChromeLaunchError } from './errors.js';
+import { acceptsConnections } from './portReservation.js';
+import { readStartupLines } from './startupExit.js';
+/** Chrome's stderr line announcing its debugging endpoint */
+const LISTENING_PATTERN = /^DevTools listening on (ws:\/\/\S+)/;
+/** How long to wait for Chrome to announce its endpoint after the port answered */
+const ENDPOINT_WAIT_MS = 10000;
+const ENDPOINT_POLL_MS = 50;
+const log = createLogger('chrome');
+/**
+ * Find the endpoint Chrome announced in its output (the last announcement).
+ *
+ * @param lines - Chrome's output lines
+ * @returns Endpoint, or null if there is no complete announcement
+ */
+export function parseDevToolsListening(lines) {
+    for (const line of [...lines].reverse()) {
+        const match = LISTENING_PATTERN.exec(line.trim());
+        if (!match?.[1])
+            continue;
+        try {
+            const url = new URL(match[1]);
+            const port = Number(url.port);
+            if (!port || !url.pathname.startsWith('/devtools/browser/'))
+                continue;
+            return { host: url.hostname, port, browserPath: url.pathname };
+        }
+        catch (error) {
+            log.debug(`Ignoring malformed DevTools announcement: ${String(error)}`);
+        }
+    }
+    return null;
+}
+/**
+ * Wait for Chrome to announce its endpoint.
+ *
+ * @param logs - Chrome's log positions from before the launch
+ * @param isRunning - Whether Chrome is still running (waiting stops when not)
+ * @param timeoutMs - Longest wait
+ * @returns Endpoint, or null if Chrome exited or announced none in time
+ */
+export async function waitForDevToolsEndpoint(logs, isRunning, timeoutMs = ENDPOINT_WAIT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const endpoint = parseDevToolsListening(readStartupLines(logs));
+        if (endpoint || !isRunning() || Date.now() >= deadline)
+            return endpoint;
+        await delay(ENDPOINT_POLL_MS);
+    }
+}
+/**
+ * Check that the Chrome answering on 127.0.0.1:<port> is the one just
+ * launched, so bdg never drives another session's browser.
+ *
+ * @param options - Chrome's log positions from before the launch, requested
+ *   port (free on 127.0.0.1 and ::1 right before the launch), Chrome's PID and
+ *   longest wait for its announcement
+ * @throws ChromeLaunchError: CHROME_DIED_AFTER_LAUNCH if Chrome exits first;
+ *   PORT_IN_USE if another browser or process answers on the port;
+ *   CHROME_LAUNCH_FAILED if Chrome announced nothing and nothing answers
+ */
+export async function verifyLaunchedChrome(options) {
+    const { logs, port, pid, timeoutMs } = options;
+    const isRunning = () => isProcessAlive(pid);
+    const endpoint = await waitForDevToolsEndpoint(logs, isRunning, timeoutMs);
+    if (!endpoint && !isRunning()) {
+        throw new ChromeLaunchError(`Chrome died immediately after launch (PID: ${pid})`, {
+            issue: { code: 'CHROME_DIED_AFTER_LAUNCH', context: { port, pid } },
+        });
+    }
+    if (!endpoint)
+        return acceptUnannouncedChrome(logs, port);
+    if (endpoint.port !== port) {
+        throw portTakenError(port, `Chrome listens on port ${endpoint.port} instead`);
+    }
+    const answering = await fetchBrowserWsUrl(port, log);
+    if (!answering || new URL(answering).pathname !== endpoint.browserPath) {
+        throw portTakenError(port, `another process answers on 127.0.0.1 (Chrome listens on ${endpoint.host})`);
+    }
+    log.debug(`Chrome on port ${port} is the launched one (${endpoint.browserPath})`);
+}
+/**
+ * Accept a Chrome that did not announce its endpoint, if a browser answers on
+ * 127.0.0.1:<port> and nothing listens on [::1]:<port> (two listeners mean a
+ * conflict).
+ *
+ * @param logs - Chrome's log positions (the stderr log is named in messages)
+ * @param port - Requested port
+ * @throws ChromeLaunchError: PORT_IN_USE for a second listener;
+ *   CHROME_LAUNCH_FAILED if no browser answers
+ */
+async function acceptUnannouncedChrome(logs, port) {
+    const errLog = logs.files[0]?.file ?? 'chrome-err.log';
+    const missing = `Chrome did not print "DevTools listening on" to ${errLog}`;
+    if (!(await fetchBrowserWsUrl(port, log))) {
+        throw new ChromeLaunchError(`${missing}, and no browser answers on port ${port}`, {
+            issue: {
+                code: 'CHROME_LAUNCH_FAILED',
+                context: { port, reason: `${missing}, and no browser answers on port ${port}` },
+            },
+        });
+    }
+    if (await acceptsConnections(port, '::1')) {
+        throw portTakenError(port, `${missing}, and both 127.0.0.1 and [::1] answer`);
+    }
+    log.info(`Warning: ${missing}; using the browser on 127.0.0.1:${port}, which was free before the launch`);
+}
+/**
+ * The error for a port another process answers on.
+ *
+ * @param port - Requested port
+ * @param reason - What was found
+ * @returns Launch error with the PORT_IN_USE issue
+ */
+function portTakenError(port, reason) {
+    return new ChromeLaunchError(`Port ${port} is already in use: ${reason}`, {
+        issue: { code: 'PORT_IN_USE', context: { port, reason } },
+    });
+}
+//# sourceMappingURL=chromeIdentity.js.map

package/dist/connection/diagnostics.d.ts

@@ -13,13 +13,4 @@ export interface ChromeDiagnostics {
  * @returns Chrome diagnostics information
  */
 export declare function getChromeDiagnostics(): ChromeDiagnostics;
-/**
- * Get formatted Chrome diagnostics for error messages.
- *
- * Retrieves Chrome installation information and formats it for display
- * in error messages. Uses cached diagnostics to avoid repeated filesystem scans.
- *
- * @returns Array of formatted diagnostic strings
- */
-export declare function getFormattedDiagnostics(): string[];
 //# sourceMappingURL=diagnostics.d.ts.map

package/dist/connection/diagnostics.js

@@ -1,6 +1,5 @@
 import * as chromeLauncher from 'chrome-launcher';
 import { createLogger } from '../ui/logging/index.js';
-import { formatDiagnosticsForError } from '../ui/messages/chrome.js';
 import { getErrorMessage } from '../utils/errors.js';
 const log = createLogger('diagnostics');
 /**
@@ -38,16 +37,4 @@ export function getChromeDiagnostics() {
     };
     return cachedDiagnostics;
 }
-/**
- * Get formatted Chrome diagnostics for error messages.
- *
- * Retrieves Chrome installation information and formats it for display
- * in error messages. Uses cached diagnostics to avoid repeated filesystem scans.
- *
- * @returns Array of formatted diagnostic strings
- */
-export function getFormattedDiagnostics() {
-    const diagnostics = getChromeDiagnostics();
-    return formatDiagnosticsForError(diagnostics);
-}
 //# sourceMappingURL=diagnostics.js.map

package/dist/connection/errors.d.ts

@@ -3,16 +3,29 @@
  *
  * Provides structured error handling for CDP connections and Chrome launches.
  */
+import type { IssueDetails } from '../errors/issues.js';
+/**
+ * Options accepted by ConnectionError subclasses.
+ */
+export interface ConnectionErrorOptions {
+    /** Underlying error that triggered this one. */
+    cause?: Error;
+    /** Structured issue payload for boundary formatters. */
+    issue?: IssueDetails;
+}
 /**
  * Base error class for all connection-related errors.
  *
  * Extends native Error with error codes for programmatic handling,
  * exit codes for semantic exit codes, and cause chaining for nested errors.
+ * Optionally carries a structured {@link IssueDetails} payload so callers at
+ * the UI boundary can format messages deterministically.
  */
 export declare abstract class ConnectionError extends Error {
     abstract readonly code: string;
     abstract readonly exitCode: number;
-    constructor(message: string, cause?: Error);
+    readonly issue?: IssueDetails;
+    constructor(message: string, options?: ConnectionErrorOptions | Error);
 }
 /**
  * CDP connection failed (network/protocol issues).
@@ -49,4 +62,26 @@ export declare class CDPTimeoutError extends ConnectionError {
     readonly code = "CDP_TIMEOUT_ERROR";
     readonly exitCode: 102;
 }
+/**
+ * An error Chrome returned for a CDP command (e.g. invalid parameters, no
+ * node with the given id), with its JSON-RPC code and detail.
+ */
+export declare class CDPProtocolError extends Error {
+    readonly code: number | undefined;
+    readonly data: string | undefined;
+    readonly name = "CDPProtocolError";
+    /**
+     * @param message - Chrome's error message
+     * @param code - JSON-RPC error code
+     * @param data - Chrome's detail (e.g. which parameter is missing)
+     */
+    constructor(message: string, code: number | undefined, data: string | undefined);
+    /**
+     * Whether the command itself was wrong (method or parameters), as opposed
+     * to failing on the page's state.
+     *
+     * @returns True for a user error
+     */
+    isRequestError(): boolean;
+}
 //# sourceMappingURL=errors.d.ts.map

package/dist/connection/errors.js

@@ -9,13 +9,23 @@ import { EXIT_CODES } from '../utils/exitCodes.js';
  *
  * Extends native Error with error codes for programmatic handling,
  * exit codes for semantic exit codes, and cause chaining for nested errors.
+ * Optionally carries a structured {@link IssueDetails} payload so callers at
+ * the UI boundary can format messages deterministically.
  */
 export class ConnectionError extends Error {
-    constructor(message, cause) {
+    issue;
+    constructor(message, options) {
         super(message);
         this.name = this.constructor.name;
-        if (cause) {
-            this.cause = cause;
+        if (options instanceof Error) {
+            this.cause = options;
+            return;
+        }
+        if (options?.cause) {
+            this.cause = options.cause;
+        }
+        if (options?.issue) {
+            this.issue = options.issue;
         }
     }
 }
@@ -54,4 +64,34 @@ export class CDPTimeoutError extends ConnectionError {
     code = 'CDP_TIMEOUT_ERROR';
     exitCode = EXIT_CODES.CDP_TIMEOUT;
 }
+/** JSON-RPC error codes that mean the request itself was wrong */
+const REQUEST_ERROR_CODES = new Set([-32600, -32601, -32602]);
+/**
+ * An error Chrome returned for a CDP command (e.g. invalid parameters, no
+ * node with the given id), with its JSON-RPC code and detail.
+ */
+export class CDPProtocolError extends Error {
+    code;
+    data;
+    name = 'CDPProtocolError';
+    /**
+     * @param message - Chrome's error message
+     * @param code - JSON-RPC error code
+     * @param data - Chrome's detail (e.g. which parameter is missing)
+     */
+    constructor(message, code, data) {
+        super(data ? `${message}: ${data}` : message);
+        this.code = code;
+        this.data = data;
+    }
+    /**
+     * Whether the command itself was wrong (method or parameters), as opposed
+     * to failing on the page's state.
+     *
+     * @returns True for a user error
+     */
+    isRequestError() {
+        return this.code !== undefined && REQUEST_ERROR_CODES.has(this.code);
+    }
+}
 //# sourceMappingURL=errors.js.map

package/dist/connection/handlers.d.ts

@@ -1,6 +1,6 @@
-import type ProtocolMapping from 'devtools-protocol/types/protocol-mapping';
-import type { CDPConnection } from '../connection/cdp.js';
-import type { EventParams, TypedCDPConnection } from '../connection/typed-cdp.js';
+import type { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js';
+import type { CDPConnection } from './cdp.js';
+import type { EventParams, TypedCDPConnection } from './typed-cdp.js';
 /**
  * Registry for managing CDP event handlers with automatic cleanup.
  *
@@ -26,7 +26,7 @@ export declare class CDPHandlerRegistry {
      *
      * @param typed - Typed CDP connection instance
      * @param event - CDP event name (autocomplete available)
-     * @param handler - Event handler with type-safe parameters
+     * @param handler - Event handler with type-safe parameters and the session id of attached targets
      *
      * @example
      * ```typescript
@@ -39,7 +39,7 @@ export declare class CDPHandlerRegistry {
      * });
      * ```
      */
-    registerTyped<T extends keyof ProtocolMapping.Events>(typed: TypedCDPConnection, event: T, handler: (params: EventParams<T>) => void): void;
+    registerTyped<T extends keyof ProtocolMapping.Events>(typed: TypedCDPConnection, event: T, handler: (params: EventParams<T>, sessionId?: string) => void): void;
     /**
      * Remove all registered event handlers and clear the registry.
      */

package/dist/connection/handlers.js

@@ -26,7 +26,7 @@ export class CDPHandlerRegistry {
      *
      * @param typed - Typed CDP connection instance
      * @param event - CDP event name (autocomplete available)
-     * @param handler - Event handler with type-safe parameters
+     * @param handler - Event handler with type-safe parameters and the session id of attached targets
      *
      * @example
      * ```typescript

package/dist/connection/inFlightRequests.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Track network requests in flight, keyed by requestId.
+ *
+ * A plain counter breaks on redirects (Chrome sends `requestWillBeSent` once
+ * per hop but `loadingFinished` once per chain, so the count never returns to
+ * zero) and on requests that started before tracking began (their completion
+ * drives the count negative). A set of request ids has neither problem.
+ */
+import type { CDPConnection } from './cdp.js';
+/**
+ * Live view of in-flight requests.
+ */
+export interface InFlightRequests {
+    /** Number of requests currently in flight */
+    readonly count: number;
+    /** Distinct requests started since tracking began */
+    readonly started: number;
+    /** Timestamp (ms) of the last request start or completion */
+    readonly lastActivity: number;
+    /** Stop listening to CDP events */
+    dispose: () => void;
+}
+/**
+ * Start tracking in-flight requests on a CDP connection.
+ *
+ * The caller is responsible for `Network.enable`.
+ *
+ * @param cdp - CDP connection
+ * @param onChange - Called after every start or completion
+ * @returns Live tracker
+ */
+export declare function trackInFlightRequests(cdp: CDPConnection, onChange?: () => void): InFlightRequests;
+//# sourceMappingURL=inFlightRequests.d.ts.map

package/dist/connection/inFlightRequests.js

@@ -0,0 +1,52 @@
+/**
+ * Track network requests in flight, keyed by requestId.
+ *
+ * A plain counter breaks on redirects (Chrome sends `requestWillBeSent` once
+ * per hop but `loadingFinished` once per chain, so the count never returns to
+ * zero) and on requests that started before tracking began (their completion
+ * drives the count negative). A set of request ids has neither problem.
+ */
+/**
+ * Start tracking in-flight requests on a CDP connection.
+ *
+ * The caller is responsible for `Network.enable`.
+ *
+ * @param cdp - CDP connection
+ * @param onChange - Called after every start or completion
+ * @returns Live tracker
+ */
+export function trackInFlightRequests(cdp, onChange) {
+    const inFlight = new Set();
+    const seen = new Set();
+    let lastActivity = Date.now();
+    const onStarted = (params) => {
+        inFlight.add(params.requestId);
+        seen.add(params.requestId);
+        lastActivity = Date.now();
+        onChange?.();
+    };
+    const onFinished = (params) => {
+        if (!inFlight.delete(params.requestId))
+            return;
+        lastActivity = Date.now();
+        onChange?.();
+    };
+    const cleanups = [
+        cdp.on('Network.requestWillBeSent', onStarted),
+        cdp.on('Network.loadingFinished', onFinished),
+        cdp.on('Network.loadingFailed', onFinished),
+    ];
+    return {
+        get count() {
+            return inFlight.size;
+        },
+        get started() {
+            return seen.size;
+        },
+        get lastActivity() {
+            return lastActivity;
+        },
+        dispose: () => cleanups.forEach((cleanup) => cleanup()),
+    };
+}
+//# sourceMappingURL=inFlightRequests.js.map

package/dist/connection/launcher/binaryResolver.js

@@ -5,9 +5,7 @@
  * and validates that the binary exists and is executable.
  */
 import * as fs from 'fs';
-import { getFormattedDiagnostics } from '../../connection/diagnostics.js';
-import { ChromeLaunchError } from '../../connection/errors.js';
-import { chromeBinaryOverrideNotFound, chromeBinaryOverrideNotExecutable, chromeBinaryOverrideIsDirectory, } from '../../ui/messages/chrome.js';
+import { ChromeLaunchError } from '../errors.js';
 import { getErrorMessage } from '../../utils/errors.js';
 /**
  * Resolve Chrome binary path from options or environment variable.
@@ -45,13 +43,22 @@ export function resolveChromeBinary(options) {
     }
     const sourceLabel = options.chromePath ? 'chromePath option' : 'CHROME_PATH';
     if (!fs.existsSync(chromePath)) {
-        const diagnostics = getFormattedDiagnostics();
-        throw new ChromeLaunchError(`${chromeBinaryOverrideNotFound(chromePath, sourceLabel)}\n\n${diagnostics.join('\n')}`);
+        throw new ChromeLaunchError(`Chrome binary override (${sourceLabel}) points to "${chromePath}", but that file does not exist.`, {
+            issue: {
+                code: 'CHROME_BINARY_NOT_FOUND',
+                context: { chromePath, source: sourceLabel },
+            },
+        });
     }
     try {
         const stats = fs.statSync(chromePath);
         if (stats.isDirectory()) {
-            throw new ChromeLaunchError(chromeBinaryOverrideIsDirectory(chromePath, sourceLabel));
+            throw new ChromeLaunchError(`Chrome binary override (${sourceLabel}) points to "${chromePath}", which is a directory.`, {
+                issue: {
+                    code: 'CHROME_BINARY_IS_DIRECTORY',
+                    context: { chromePath, source: sourceLabel },
+                },
+            });
         }
         fs.accessSync(chromePath, fs.constants.X_OK);
     }
@@ -59,7 +66,13 @@ export function resolveChromeBinary(options) {
         if (error instanceof ChromeLaunchError) {
             throw error;
         }
-        throw new ChromeLaunchError(`${chromeBinaryOverrideNotExecutable(chromePath, sourceLabel)}\n\n${getErrorMessage(error)}`, error instanceof Error ? error : undefined);
+        throw new ChromeLaunchError(`Chrome binary override (${sourceLabel}) points to "${chromePath}", but it is not executable.`, {
+            ...(error instanceof Error && { cause: error }),
+            issue: {
+                code: 'CHROME_BINARY_NOT_EXECUTABLE',
+                context: { chromePath, source: sourceLabel, reason: getErrorMessage(error) },
+            },
+        });
     }
     return chromePath;
 }

package/dist/connection/launcher/flagsBuilder.d.ts

@@ -19,72 +19,42 @@ export interface FlagsBuilderOptions {
     headless?: boolean | undefined;
     /** Additional Chrome command-line flags */
     chromeFlags?: string[] | undefined;
+    /** bdg session directory; adds a marker flag used to verify the process during crash cleanup */
+    sessionDir?: string | undefined;
 }
 /**
- * Check if running inside a Docker container.
+ * Marker flag identifying a Chrome launched by bdg for a given session directory.
  *
- * Detects Docker environment by checking for:
- * 1. /.dockerenv file (standard Docker indicator)
- * 2. "docker" or "containerd" in /proc/self/cgroup
+ * Chrome ignores unknown switches; crash cleanup matches this exact string in a
+ * process's command line before killing it, so a reused PID (or the user's own
+ * debugging Chrome) is never mistaken for a bdg Chrome.
  *
- * @returns True if running in Docker, false otherwise
+ * @param sessionDir - bdg session directory
+ * @returns Marker flag
  */
-export declare function isDocker(): boolean;
+export declare function chromeSessionMarkerFlag(sessionDir: string): string;
 /**
- * Parse custom Chrome flags from BDG_CHROME_FLAGS environment variable.
- *
- * NOTE: This function is deprecated for use in the daemon/worker. The env var
- * is now parsed by the CLI (src/commands/start.ts) and passed via IPC to ensure
- * the env var set when running `bdg` reaches the worker process.
+ * Whether Chrome must run with `--no-sandbox`.
  *
- * Supports space-separated flags, with proper handling of flags containing
- * equals signs (e.g., --window-size=1920,1080).
+ * Only where the sandbox cannot work, so it stays on everywhere else
+ * (including Podman-based dev containers such as toolbox/distrobox):
+ * - Docker: the default seccomp profile blocks the user namespaces the
+ *   sandbox needs, for root and non-root users alike
+ * - root on Linux: Chrome refuses to start sandboxed as root
+ * - `BDG_NO_SANDBOX=1`: explicit opt-in for other restricted environments
  *
- * @returns Array of Chrome flags parsed from environment variable
- * @deprecated Use CLI parsing instead - kept for test compatibility
- *
- * @example
- * ```bash
- * # Single flag
- * BDG_CHROME_FLAGS="--ignore-certificate-errors" bdg https://localhost:5173
- *
- * # Multiple flags
- * BDG_CHROME_FLAGS="--ignore-certificate-errors --disable-web-security" bdg https://localhost:5173
- * ```
+ * @returns True if `--no-sandbox` should be added
  */
-export declare function getEnvChromeFlags(): string[];
+export declare function needsNoSandbox(): boolean;
 /**
- * Build Chrome flags array from launch options.
- *
- * Uses chrome-launcher default flags as base (unless ignoreDefaultFlags is true)
- * and layers bdg-specific overrides on top. Headless mode uses the new headless
- * implementation for better compatibility.
- *
- * When running in Docker, automatically adds GPU-disabling flags to work around
- * graphics limitations in containerized environments.
- *
- * Custom flags are passed via the chromeFlags option. The BDG_CHROME_FLAGS env var
- * is parsed by the CLI and merged into chromeFlags before reaching this function.
- *
- * @param options - Launch options containing flag preferences
- * @returns Array of Chrome command-line flags
- *
- * @example
- * ```typescript
- * // Standard flags
- * const flags = buildChromeFlags({ port: 9222 });
+ * Check if running inside a Docker container.
  *
- * // Headless with custom flags
- * const flags = buildChromeFlags({
- *   port: 9222,
- *   headless: true,
- *   chromeFlags: ['--window-size=1920,1080']
- * });
+ * Detects a container by checking for:
+ * 1. /.dockerenv (Docker) or /run/.containerenv (Podman)
+ * 2. "docker" or "containerd" in /proc/self/cgroup (cgroup v1 hosts)
  *
- * // Docker environment (auto-detects)
- * const flags = buildChromeFlags({ port: 9222 });
- * // Includes --disable-gpu, --no-sandbox if in Docker
- * ```
+ * @returns True if running in Docker, false otherwise
  */
+export declare function isDocker(): boolean;
 export declare function buildChromeFlags(options: FlagsBuilderOptions): string[];
 //# sourceMappingURL=flagsBuilder.d.ts.map