browser-debugger-cli 0.7.2 → 0.9.0

package/dist/connection/startupExit.js

@@ -0,0 +1,116 @@
+/**
+ * Notice when Chrome exits while bdg waits for its debugging port.
+ *
+ * chrome-launcher only polls the port (about 25 s) and then reports a refused
+ * connection, which reads like a port conflict. Chrome that exits right away
+ * (an unknown flag taken as a URL, a profile already open in another Chrome)
+ * says why on stderr: that is reported instead, as soon as it exits.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { ChromeLaunchError } from './errors.js';
+/** How often to look for the spawned Chrome process */
+const PROCESS_POLL_MS = 100;
+/** Lines of Chrome's output kept for the error */
+const OUTPUT_LINES = 5;
+/** Chrome's output when another Chrome already has the profile open */
+const PROFILE_IN_USE_PATTERN = /existing browser session|profile appears to be in use|ProcessSingleton/i;
+/**
+ * Remember where Chrome's logs end before the launch, so only this launch's
+ * output is reported.
+ *
+ * @param userDataDir - Chrome profile directory
+ * @returns Log positions
+ */
+export function markStartupLogs(userDataDir) {
+    return {
+        files: ['chrome-err.log', 'chrome-out.log'].map((name) => {
+            const file = path.join(userDataDir, name);
+            return { file, offset: fs.existsSync(file) ? fs.statSync(file).size : 0 };
+        }),
+    };
+}
+/**
+ * Chrome's output (stderr, then stdout) since {@link markStartupLogs}. The
+ * marked offsets are byte sizes, so the files are cut before decoding.
+ *
+ * @param logs - Log positions
+ * @returns Output lines
+ */
+export function readStartupLines(logs) {
+    return logs.files.flatMap(({ file, offset }) => {
+        if (!fs.existsSync(file))
+            return [];
+        return fs.readFileSync(file).subarray(offset).toString('utf8').split('\n');
+    });
+}
+/**
+ * Chrome's output since {@link markStartupLogs}, last lines first trimmed.
+ *
+ * @param logs - Log positions
+ * @returns Up to {@link OUTPUT_LINES} non-empty lines
+ */
+function readStartupOutput(logs) {
+    return readStartupLines(logs)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .slice(-OUTPUT_LINES);
+}
+/**
+ * Reject when the launched Chrome exits before it is ready.
+ *
+ * @param getProcess - Returns the spawned process once chrome-launcher has it
+ * @param logs - Log positions from before the launch
+ * @param userDataDir - Chrome profile directory (named in the error)
+ * @returns A promise that only rejects, and a function to stop watching
+ */
+export function watchStartupExit(getProcess, logs, userDataDir) {
+    let timer;
+    let stopped = false;
+    const exited = new Promise((_resolve, reject) => {
+        const attach = () => {
+            if (stopped)
+                return;
+            const child = getProcess();
+            if (!child) {
+                timer = setTimeout(attach, PROCESS_POLL_MS);
+                return;
+            }
+            const report = (code) => {
+                if (!stopped)
+                    reject(startupExitError(code, readStartupOutput(logs), userDataDir));
+            };
+            if (child.exitCode !== null || child.signalCode !== null)
+                report(child.exitCode);
+            else
+                child.once('exit', report);
+        };
+        attach();
+    });
+    exited.catch(() => undefined);
+    return {
+        exited,
+        stop: () => {
+            stopped = true;
+            clearTimeout(timer);
+        },
+    };
+}
+/**
+ * The error for a Chrome that exited during startup.
+ *
+ * @param exitCode - Chrome's exit code
+ * @param output - Chrome's last output lines
+ * @param userDataDir - Chrome profile directory
+ * @returns Launch error with a structured issue
+ */
+function startupExitError(exitCode, output, userDataDir) {
+    const profileInUse = output.some((line) => PROFILE_IN_USE_PATTERN.test(line));
+    return new ChromeLaunchError(`Chrome exited during startup (exit code ${exitCode ?? 'none'})`, {
+        issue: {
+            code: 'CHROME_EXITED_DURING_STARTUP',
+            context: { exitCode, output, userDataDir, profileInUse },
+        },
+    });
+}
+//# sourceMappingURL=startupExit.js.map

package/dist/connection/typed-cdp.d.ts

@@ -12,8 +12,8 @@
  */
 import type { CDPConnection } from './cdp.js';
 import type { EventCleanup } from './events.js';
-import type Protocol from 'devtools-protocol/types/protocol';
-import type ProtocolMapping from 'devtools-protocol/types/protocol-mapping';
+import type { ProtocolMapping } from 'devtools-protocol/types/protocol-mapping.js';
+import type { Protocol } from 'devtools-protocol/types/protocol.js';
 /**
  * Extract parameter type from a CDP command.
  *
@@ -62,6 +62,7 @@ export declare class TypedCDPConnection {
      *
      * @param method - CDP method name (autocomplete available for 300+ methods)
      * @param params - Command parameters (type-checked)
+     * @param sessionId - Session of an attached target (iframe, worker); the page when omitted
      * @returns Promise resolving to command response (type-safe)
      *
      * @example
@@ -79,12 +80,13 @@ export declare class TypedCDPConnection {
      * const doc = await typed.send('DOM.getDocument', {});
      * ```
      */
-    send<T extends keyof ProtocolMapping.Commands>(method: T, params: CommandParams<T>): Promise<CommandReturn<T>>;
+    send<T extends keyof ProtocolMapping.Commands>(method: T, params: CommandParams<T>, sessionId?: string): Promise<CommandReturn<T>>;
     /**
      * Register a type-safe event handler.
      *
      * @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 of
+     *   the attached target that sent the event (undefined for the page itself)
      * @returns Handler ID for later removal
      *
      * @example
@@ -105,7 +107,7 @@ export declare class TypedCDPConnection {
      * });
      * ```
      */
-    on<T extends keyof ProtocolMapping.Events>(event: T, handler: (params: EventParams<T>) => void): EventCleanup;
+    on<T extends keyof ProtocolMapping.Events>(event: T, handler: (params: EventParams<T>, sessionId?: string) => void): EventCleanup;
     /**
      * Remove an event handler by ID.
      *
@@ -133,7 +135,7 @@ export declare class TypedCDPConnection {
  *
  * @example
  * ```typescript
- * import { Protocol } from '../connection/typed-cdp.js';
+ * import { Protocol } from './typed-cdp.js';
  *
  * type Cookie = Protocol.Network.Cookie;
  * type Headers = Protocol.Network.Headers;

package/dist/connection/typed-cdp.js

@@ -42,6 +42,7 @@ export class TypedCDPConnection {
      *
      * @param method - CDP method name (autocomplete available for 300+ methods)
      * @param params - Command parameters (type-checked)
+     * @param sessionId - Session of an attached target (iframe, worker); the page when omitted
      * @returns Promise resolving to command response (type-safe)
      *
      * @example
@@ -59,15 +60,16 @@ export class TypedCDPConnection {
      * const doc = await typed.send('DOM.getDocument', {});
      * ```
      */
-    async send(method, params) {
-        const result = await this.cdp.send(method, params);
+    async send(method, params, sessionId) {
+        const result = await this.cdp.send(method, params, sessionId);
         return result;
     }
     /**
      * Register a type-safe event handler.
      *
      * @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 of
+     *   the attached target that sent the event (undefined for the page itself)
      * @returns Handler ID for later removal
      *
      * @example

package/dist/connection/types.d.ts

@@ -23,6 +23,7 @@ export interface CDPMessage {
     error?: {
         code?: number;
         message: string;
+        data?: string;
     };
     /** Session ID for commands sent to specific targets */
     sessionId?: string;
@@ -58,6 +59,8 @@ export interface ConnectionOptions {
     onReconnect?: (() => Promise<void>) | undefined;
     /** Async hook invoked when WebSocket closes unexpectedly */
     onDisconnect?: ((code: number, reason: string) => void | Promise<void>) | undefined;
+    /** Stops connection attempts (e.g. the session was stopped while starting) */
+    signal?: AbortSignal | undefined;
 }
 /**
  * Options for CDPConnection.create() factory method.

package/dist/constants.d.ts

@@ -8,11 +8,6 @@
  * Default Chrome debugging port
  */
 export declare const DEFAULT_CDP_PORT = 9222;
-/**
- * Default Chrome debugging port (string version for CLI argument parsing)
- * Derived from DEFAULT_CDP_PORT to maintain single source of truth
- */
-export declare const DEFAULT_DEBUG_PORT: string;
 /**
  * Default Chrome launcher log level for quiet operation
  */
@@ -51,8 +46,12 @@ export declare const BDG_CHROME_FLAGS: string[];
 export declare const DOCKER_CHROME_FLAGS: string[];
 /**
  * BDG-specific Chrome preferences for automation
- * These preferences are automatically merged with user preferences when launching Chrome
- * User preferences take precedence over these defaults
+ * Written into the launched profile's Default/Preferences (dotted names become nested paths)
+ * before every launch, so persistent profiles get them too. User preferences take precedence.
+ *
+ * The password manager and its leak check are off: after a login their bubble
+ * (e.g. "Change your password") captures all input in headless Chrome, so
+ * later clicks silently never reach the page.
  *
  * Note: Crash/restore popup suppression is handled by Chrome flags (--disable-session-crashed-bubble, --disable-infobars)
  * which are more reliable than preference-based approaches.
@@ -104,16 +103,6 @@ export declare const CHROME_NETWORK_BUFFER_PER_RESOURCE: number;
  * Limits size of POST body data included in requestWillBeSent notification
  */
 export declare const CHROME_POST_DATA_LIMIT: number;
-/**
- * Stale network request timeout (60 seconds)
- * Network requests incomplete after this duration are cleaned up
- */
-export declare const STALE_REQUEST_TIMEOUT = 60000;
-/**
- * Stale request cleanup interval (30 seconds)
- * How often to check for and remove stale network requests
- */
-export declare const STALE_REQUEST_CLEANUP_INTERVAL = 30000;
 /**
  * Default page readiness timeout (2 seconds)
  * Maximum time to wait for page to be ready before proceeding
@@ -121,13 +110,10 @@ export declare const STALE_REQUEST_CLEANUP_INTERVAL = 30000;
  */
 export declare const DEFAULT_PAGE_READINESS_TIMEOUT_MS = 2000;
 /**
- * Maximum JSONL buffer size in bytes (50MB)
- * Prevents OOM attacks from malicious/buggy processes sending data without newlines
- * If buffer exceeds this size, connection is terminated with protocol error
- *
- * Set to 50MB to accommodate large screenshots (base64-encoded full-page captures
- * of content-heavy pages like Amazon can exceed 10MB).
- * Matches CHROME_NETWORK_BUFFER_TOTAL for consistency.
+ * Maximum size of one JSONL message from the daemon (256 MB, below V8's
+ * maximum string length so joining a message cannot fail).
+ * Guards against a process sending data without newlines; large enough for
+ * HAR exports of long sessions with response bodies (`--all`).
  */
 export declare const MAX_JSONL_BUFFER_SIZE: number;
 /**
@@ -141,6 +127,15 @@ export declare const MAX_JSONL_BUFFER_SIZE: number;
  * @see docs/IMPROVEMENTS_ANALYSIS.md - Issue #3: Smart Page Readiness Detection
  */
 export declare function getIPCRequestTimeout(): number;
+/**
+ * Timeout for small requests the daemon answers from memory (status, peek,
+ * details, headers): a daemon that does not answer these within seconds is
+ * not responding, so commands do not wait the full IPC timeout. HAR data is
+ * excluded: a large session's requests and bodies take longer to transfer.
+ *
+ * @returns Timeout in milliseconds (10 s, or the IPC timeout if shorter)
+ */
+export declare function getQuickIPCRequestTimeout(): number;
 /**
  * Description for port option in CLI commands
  */
@@ -150,6 +145,14 @@ export declare const PORT_OPTION_DESCRIPTION = "Chrome debugging port";
  * Used for token-efficient display in preview/peek output.
  */
 export declare const RESOURCE_TYPE_ABBREVIATIONS: Record<string, string>;
+/**
+ * The CDP resource type a user means: its name or its abbreviation from
+ * `network list` (`WS`, `DOC`, `FET`), in any case.
+ *
+ * @param name - Type as typed
+ * @returns CDP resource type, or undefined if unknown
+ */
+export declare function resourceTypeFromName(name: string): string | undefined;
 /**
  * Rules for inferring resource types from MIME patterns.
  * Ordered by precedence (first match wins).

package/dist/constants.js

@@ -11,11 +11,6 @@
  * Default Chrome debugging port
  */
 export const DEFAULT_CDP_PORT = 9222;
-/**
- * Default Chrome debugging port (string version for CLI argument parsing)
- * Derived from DEFAULT_CDP_PORT to maintain single source of truth
- */
-export const DEFAULT_DEBUG_PORT = String(DEFAULT_CDP_PORT);
 /**
  * Default Chrome launcher log level for quiet operation
  */
@@ -66,12 +61,15 @@ export const DOCKER_CHROME_FLAGS = [
     '--disable-gpu', // Disable GPU hardware acceleration
     '--disable-dev-shm-usage', // Overcome limited resource problems in Docker
     '--disable-software-rasterizer', // Don't fall back to software rendering
-    '--single-process', // Run Chrome in single-process mode (safer in containers)
 ];
 /**
  * BDG-specific Chrome preferences for automation
- * These preferences are automatically merged with user preferences when launching Chrome
- * User preferences take precedence over these defaults
+ * Written into the launched profile's Default/Preferences (dotted names become nested paths)
+ * before every launch, so persistent profiles get them too. User preferences take precedence.
+ *
+ * The password manager and its leak check are off: after a login their bubble
+ * (e.g. "Change your password") captures all input in headless Chrome, so
+ * later clicks silently never reach the page.
  *
  * Note: Crash/restore popup suppression is handled by Chrome flags (--disable-session-crashed-bubble, --disable-infobars)
  * which are more reliable than preference-based approaches.
@@ -81,6 +79,9 @@ export const BDG_CHROME_PREFS = {
     'translate.enabled': false, // Disable Google Translate popup
     translate_site_blacklist: ['*'], // Block translate for all sites
     'profile.exit_type': 'Normal', // Trick Chrome into thinking it shut down correctly
+    credentials_enable_service: false, // No "Save password?" bubble
+    'profile.password_manager_enabled': false, // Password manager off
+    'profile.password_manager_leak_detection': false, // No "Change your password" breach dialog
 };
 // ============================================================================
 // DATA COLLECTION LIMITS
@@ -140,16 +141,6 @@ export const CHROME_POST_DATA_LIMIT = 1 * 1024 * 1024; // 1MB
 // ============================================================================
 // TIMEOUTS & INTERVALS
 // ============================================================================
-/**
- * Stale network request timeout (60 seconds)
- * Network requests incomplete after this duration are cleaned up
- */
-export const STALE_REQUEST_TIMEOUT = 60000;
-/**
- * Stale request cleanup interval (30 seconds)
- * How often to check for and remove stale network requests
- */
-export const STALE_REQUEST_CLEANUP_INTERVAL = 30000;
 /**
  * Default page readiness timeout (2 seconds)
  * Maximum time to wait for page to be ready before proceeding
@@ -160,15 +151,12 @@ export const DEFAULT_PAGE_READINESS_TIMEOUT_MS = 2000;
 // IPC CONFIGURATION
 // ============================================================================
 /**
- * Maximum JSONL buffer size in bytes (50MB)
- * Prevents OOM attacks from malicious/buggy processes sending data without newlines
- * If buffer exceeds this size, connection is terminated with protocol error
- *
- * Set to 50MB to accommodate large screenshots (base64-encoded full-page captures
- * of content-heavy pages like Amazon can exceed 10MB).
- * Matches CHROME_NETWORK_BUFFER_TOTAL for consistency.
+ * Maximum size of one JSONL message from the daemon (256 MB, below V8's
+ * maximum string length so joining a message cannot fail).
+ * Guards against a process sending data without newlines; large enough for
+ * HAR exports of long sessions with response bodies (`--all`).
  */
-export const MAX_JSONL_BUFFER_SIZE = 50 * 1024 * 1024; // 50MB
+export const MAX_JSONL_BUFFER_SIZE = 256 * 1024 * 1024;
 /**
  * IPC request timeout in milliseconds (45 seconds in production, 5 seconds in tests)
  * Maximum time to wait for IPC responses from daemon
@@ -184,6 +172,17 @@ export function getIPCRequestTimeout() {
         ? parseInt(process.env['BDG_IPC_TIMEOUT_MS'], 10)
         : 45000;
 }
+/**
+ * Timeout for small requests the daemon answers from memory (status, peek,
+ * details, headers): a daemon that does not answer these within seconds is
+ * not responding, so commands do not wait the full IPC timeout. HAR data is
+ * excluded: a large session's requests and bodies take longer to transfer.
+ *
+ * @returns Timeout in milliseconds (10 s, or the IPC timeout if shorter)
+ */
+export function getQuickIPCRequestTimeout() {
+    return Math.min(10000, getIPCRequestTimeout());
+}
 // ============================================================================
 // CLI OPTION DESCRIPTIONS
 // ============================================================================
@@ -210,12 +209,23 @@ export const RESOURCE_TYPE_ABBREVIATIONS = {
     WebSocket: 'WS',
     Manifest: 'MAN',
     SignedExchange: 'SGX',
-    Ping: 'PNG',
+    Ping: 'PIN',
     CSPViolationReport: 'CSP',
     Preflight: 'FLT',
     FedCM: 'FED',
     Other: 'OTH',
 };
+/**
+ * The CDP resource type a user means: its name or its abbreviation from
+ * `network list` (`WS`, `DOC`, `FET`), in any case.
+ *
+ * @param name - Type as typed
+ * @returns CDP resource type, or undefined if unknown
+ */
+export function resourceTypeFromName(name) {
+    const wanted = name.trim().toLowerCase();
+    return Object.entries(RESOURCE_TYPE_ABBREVIATIONS).find(([type, abbreviation]) => type.toLowerCase() === wanted || abbreviation.toLowerCase() === wanted)?.[0];
+}
 /**
  * Rules for inferring resource types from MIME patterns.
  * Ordered by precedence (first match wins).

package/dist/daemon/SessionController.d.ts

@@ -0,0 +1,125 @@
+/**
+ * Daemon request handling for the single in-process session.
+ *
+ * Maps each client IPC request to a response object. Holds the current
+ * {@link Session} and asks the daemon to shut down when the session ends,
+ * since the daemon's lifetime is the session's lifetime.
+ */
+import { type SessionEndReason } from './session/Session.js';
+import { type ClientRequestUnion, type HandshakeRequest, type HandshakeResponse, type HARDataRequest, type HARDataResponse, type PeekRequest, type PeekResponse, type StartSessionRequest, type StartSessionResponse, type StatusRequest, type StatusResponse, type StopSessionRequest, type StopSessionResponse } from '../ipc/index.js';
+/**
+ * Owns the daemon's session and answers client requests.
+ */
+export declare class SessionController {
+    private readonly daemonStartTime;
+    private readonly socketPath;
+    private readonly onSessionEnded;
+    private session;
+    private launching;
+    private closing;
+    /**
+     * @param daemonStartTime - Daemon start timestamp (ms)
+     * @param socketPath - Daemon socket path, reported in status
+     * @param onSessionEnded - Called once the session has ended or failed to start
+     */
+    constructor(daemonStartTime: number, socketPath: string, onSessionEnded: (reason: SessionEndReason) => void);
+    /**
+     * Whether no session is running or starting.
+     *
+     * @returns True if the daemon hosts nothing
+     */
+    isIdle(): boolean;
+    /**
+     * Reject any further start requests (the daemon is shutting down).
+     */
+    refuseNewSessions(): void;
+    /**
+     * Stop the session if one is running or launching (used on daemon shutdown).
+     *
+     * @returns True if a session was stopped
+     */
+    stopActiveSession(): Promise<boolean>;
+    /**
+     * Error fields for a request that needs the session when there is none:
+     * still starting (85), or none at all.
+     *
+     * @returns Error message, plus exit code and suggestion while starting
+     */
+    private noSessionError;
+    /**
+     * Respond to a handshake.
+     *
+     * @param request - Handshake request
+     * @returns Handshake response
+     */
+    handshake(request: HandshakeRequest): HandshakeResponse;
+    /**
+     * Report daemon status, enriched with live session activity when available.
+     *
+     * @param request - Status request
+     * @returns Status response
+     */
+    status(request: StatusRequest): Promise<StatusResponse>;
+    /**
+     * Return a preview of recent telemetry.
+     *
+     * @param request - Peek request
+     * @returns Peek response
+     */
+    peek(request: PeekRequest): Promise<PeekResponse>;
+    /**
+     * Return all captured network requests for HAR export.
+     *
+     * @param request - HAR data request
+     * @returns HAR data response
+     */
+    harData(request: HARDataRequest): Promise<HARDataResponse>;
+    /**
+     * Execute a session command (dom_*, cdp_call, session_details, ...).
+     *
+     * @param request - Command request
+     * @returns Command response, forwarding exit code and suggestion on failure
+     */
+    command(request: ClientRequestUnion): Promise<unknown>;
+    /**
+     * Start a session, or report the one already running.
+     *
+     * A start whose client disconnects (Ctrl-C) is abandoned: the session is
+     * stopped, whether it is still launching or has just started, since nobody
+     * learns that it exists.
+     *
+     * @param request - Start session request
+     * @param abandoned - Aborted when the requesting client disconnects
+     * @returns Start session response
+     */
+    startSession(request: StartSessionRequest, abandoned?: AbortSignal): Promise<StartSessionResponse>;
+    /**
+     * Create and launch a session, mapping the outcome to response fields.
+     *
+     * @param request - Start session request
+     * @param onCreated - Receives the session before launch, so it can be stopped mid-launch
+     * @returns Status plus data or error fields for the start response
+     */
+    private launchSession;
+    /**
+     * Stop the running session, or abort one that is still launching.
+     *
+     * @param request - Stop session request
+     * @returns Stop session response
+     */
+    stopSession(request: StopSessionRequest): Promise<StopSessionResponse>;
+    /**
+     * React to the session ending (stop, crash, or timeout).
+     *
+     * @param reason - Why the session ended
+     */
+    private handleSessionEnded;
+    /**
+     * Build the error part of a start response when a session already exists.
+     *
+     * @param request - Start session request
+     * @returns Error message, code and existing-session details
+     */
+    private describeExistingSession;
+}
+//# sourceMappingURL=SessionController.d.ts.map