browser-debugger-cli 0.7.1 → 0.8.0

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

package/dist/connection/launcher/flagsBuilder.js

@@ -9,20 +9,53 @@
  */
 import * as fs from 'fs';
 import * as chromeLauncher from 'chrome-launcher';
-import { BDG_CHROME_FLAGS, DEFAULT_CDP_PORT, HEADLESS_FLAG, DOCKER_CHROME_FLAGS, } from '../../constants.js';
-const REMOTE_DEBUGGING_FLAG = (port) => `--remote-debugging-port=${port}`;
+import { BDG_CHROME_FLAGS, HEADLESS_FLAG, DOCKER_CHROME_FLAGS } from '../../constants.js';
+/**
+ * Marker flag identifying a Chrome launched by bdg for a given session directory.
+ *
+ * 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.
+ *
+ * @param sessionDir - bdg session directory
+ * @returns Marker flag
+ */
+export function chromeSessionMarkerFlag(sessionDir) {
+    return `--bdg-session-dir=${sessionDir}`;
+}
+/** Environment variable that forces `--no-sandbox` (e.g. in restricted containers). */
+const NO_SANDBOX_ENV = 'BDG_NO_SANDBOX';
+/**
+ * Whether Chrome must run with `--no-sandbox`.
+ *
+ * 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 True if `--no-sandbox` should be added
+ */
+export function needsNoSandbox() {
+    if (process.env[NO_SANDBOX_ENV] === '1')
+        return true;
+    if (process.platform === 'linux' && process.getuid?.() === 0)
+        return true;
+    return fs.existsSync('/.dockerenv');
+}
 /**
  * Check if running inside a Docker container.
  *
- * Detects Docker environment by checking for:
- * 1. /.dockerenv file (standard Docker indicator)
- * 2. "docker" or "containerd" in /proc/self/cgroup
+ * Detects a container by checking for:
+ * 1. /.dockerenv (Docker) or /run/.containerenv (Podman)
+ * 2. "docker" or "containerd" in /proc/self/cgroup (cgroup v1 hosts)
  *
  * @returns True if running in Docker, false otherwise
  */
 export function isDocker() {
     try {
-        if (fs.existsSync('/.dockerenv')) {
+        if (fs.existsSync('/.dockerenv') || fs.existsSync('/run/.containerenv')) {
             return true;
         }
         if (fs.existsSync('/proc/self/cgroup')) {
@@ -35,35 +68,6 @@ export function isDocker() {
         return false;
     }
 }
-/**
- * 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.
- *
- * Supports space-separated flags, with proper handling of flags containing
- * equals signs (e.g., --window-size=1920,1080).
- *
- * @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
- * ```
- */
-export function getEnvChromeFlags() {
-    const envFlags = process.env['BDG_CHROME_FLAGS'];
-    if (!envFlags) {
-        return [];
-    }
-    return envFlags.split(' ').filter(Boolean);
-}
 /**
  * Build Chrome flags array from launch options.
  *
@@ -97,16 +101,37 @@ export function getEnvChromeFlags() {
  * // Includes --disable-gpu, --no-sandbox if in Docker
  * ```
  */
+/**
+ * chrome-launcher's default flags (plus its Linux sandbox flag). bdg passes
+ * them itself and tells chrome-launcher to skip its own copy, so each flag
+ * appears once; chrome-launcher adds `--remote-debugging-port`.
+ *
+ * @returns Default flags
+ */
+function defaultFlags() {
+    const flags = chromeLauncher.Launcher.defaultFlags();
+    return process.platform === 'linux' ? [...flags, '--disable-setuid-sandbox'] : flags;
+}
 export function buildChromeFlags(options) {
-    const port = options.port ?? DEFAULT_CDP_PORT;
-    const baseFlags = options.ignoreDefaultFlags ? [] : chromeLauncher.Launcher.defaultFlags();
-    const bdgFlags = [REMOTE_DEBUGGING_FLAG(port), ...BDG_CHROME_FLAGS];
+    const baseFlags = options.ignoreDefaultFlags ? [] : defaultFlags();
+    const bdgFlags = [
+        ...(options.sessionDir ? [chromeSessionMarkerFlag(options.sessionDir)] : []),
+        ...BDG_CHROME_FLAGS,
+    ];
     const dockerFlags = isDocker() ? DOCKER_CHROME_FLAGS : [];
+    const sandboxFlags = needsNoSandbox() ? ['--no-sandbox'] : [];
     // Custom flags from CLI option (env var BDG_CHROME_FLAGS is parsed by CLI and passed here)
     const customFlags = options.chromeFlags ?? [];
     if (options.headless) {
-        return [HEADLESS_FLAG, ...baseFlags, ...bdgFlags, ...dockerFlags, ...customFlags];
+        return [
+            HEADLESS_FLAG,
+            ...baseFlags,
+            ...bdgFlags,
+            ...dockerFlags,
+            ...sandboxFlags,
+            ...customFlags,
+        ];
     }
-    return [...baseFlags, ...bdgFlags, ...dockerFlags, ...customFlags];
+    return [...baseFlags, ...bdgFlags, ...dockerFlags, ...sandboxFlags, ...customFlags];
 }
 //# sourceMappingURL=flagsBuilder.js.map

package/dist/connection/launcher/preferencesLoader.js

@@ -5,8 +5,7 @@
  * and validates that they are JSON-serializable for chrome-launcher compatibility.
  */
 import * as fs from 'fs';
-import { ChromeLaunchError } from '../../connection/errors.js';
-import { prefsFileNotFoundError, invalidPrefsFormatError, prefsLoadError, } from '../../ui/messages/chrome.js';
+import { ChromeLaunchError } from '../errors.js';
 import { getErrorMessage } from '../../utils/errors.js';
 /**
  * Load Chrome preferences from file or inline options.
@@ -37,14 +36,22 @@ import { getErrorMessage } from '../../utils/errors.js';
  */
 export function loadChromePrefs(options) {
     if (options.prefsFile) {
-        if (!fs.existsSync(options.prefsFile)) {
-            throw new ChromeLaunchError(prefsFileNotFoundError(options.prefsFile), new Error('File does not exist'));
+        const file = options.prefsFile;
+        if (!fs.existsSync(file)) {
+            throw new ChromeLaunchError(`Chrome preferences file not found: ${file}`, {
+                issue: { code: 'PREFS_FILE_NOT_FOUND', context: { file } },
+            });
         }
         try {
-            const prefsContent = fs.readFileSync(options.prefsFile, 'utf8');
+            const prefsContent = fs.readFileSync(file, 'utf8');
             const parsed = JSON.parse(prefsContent);
             if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
-                throw new ChromeLaunchError(invalidPrefsFormatError(options.prefsFile, typeof parsed), new Error('Invalid JSON structure'));
+                throw new ChromeLaunchError(`Invalid Chrome preferences format in ${file}: expected object, got ${typeof parsed}`, {
+                    issue: {
+                        code: 'PREFS_INVALID_FORMAT',
+                        context: { file, actualType: Array.isArray(parsed) ? 'array' : typeof parsed },
+                    },
+                });
             }
             return parsed;
         }
@@ -52,7 +59,13 @@ export function loadChromePrefs(options) {
             if (error instanceof ChromeLaunchError) {
                 throw error;
             }
-            throw new ChromeLaunchError(prefsLoadError(options.prefsFile, getErrorMessage(error)), error instanceof Error ? error : undefined);
+            throw new ChromeLaunchError(`Failed to load Chrome preferences from ${file}`, {
+                ...(error instanceof Error && { cause: error }),
+                issue: {
+                    code: 'PREFS_LOAD_FAILED',
+                    context: { file, reason: getErrorMessage(error) },
+                },
+            });
         }
     }
     return options.prefs;
@@ -83,7 +96,13 @@ export function ensureJSONCompatiblePrefs(prefs) {
         JSON.stringify(prefs);
     }
     catch (error) {
-        throw new ChromeLaunchError(`Chrome preferences must be JSON-serializable: ${getErrorMessage(error)}`, error instanceof Error ? error : undefined);
+        throw new ChromeLaunchError('Chrome preferences must be JSON-serializable', {
+            ...(error instanceof Error && { cause: error }),
+            issue: {
+                code: 'PREFS_NOT_JSON_SERIALIZABLE',
+                context: { reason: getErrorMessage(error) },
+            },
+        });
     }
     return prefs;
 }

package/dist/connection/launcher.d.ts

@@ -23,6 +23,8 @@ export interface LaunchOptions extends Pick<ChromeLaunchOptions, 'logLevel' | 'c
     prefsFile?: string | undefined;
     /** Override Chrome binary detection with an explicit path */
     chromePath?: string;
+    /** bdg session directory, recorded as a marker flag on the Chrome command line */
+    sessionDir?: string | undefined;
 }
 /**
  * Launch Chrome with remote debugging enabled using chrome-launcher.

package/dist/connection/launcher.js

@@ -3,21 +3,27 @@ import * as os from 'os';
 import * as path from 'path';
 import * as chromeLauncher from 'chrome-launcher';
 import { BDG_CHROME_PREFS, DEFAULT_CDP_PORT, CHROME_PROFILE_DIR, DEFAULT_CHROME_LOG_LEVEL, DEFAULT_CHROME_HANDLE_SIGINT, } from '../constants.js';
-import { chromeLaunchSuccessMessage, chromeUserDataDirMessage, invalidPortError, userDataDirError, chromeLaunchFailedError, } from '../ui/messages/chrome.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { filterDefined } from '../utils/objects.js';
 import { isProcessAlive } from '../utils/process.js';
-import { getFormattedDiagnostics } from './diagnostics.js';
 import { ChromeLaunchError } from './errors.js';
 import { resolveChromeBinary } from './launcher/binaryResolver.js';
 import { buildChromeFlags } from './launcher/flagsBuilder.js';
 import { loadChromePrefs, ensureJSONCompatiblePrefs } from './launcher/preferencesLoader.js';
 import { reservePort } from './portReservation.js';
+import { markStartupLogs, watchStartupExit } from './startupExit.js';
 /**
  * Default logger instance for launcher (uses console).
  *
  * Can be overridden in tests or when launcher is used as a library.
  */
+/**
+ * How often to check whether Chrome's debugging port answers (chrome-launcher
+ * defaults to 500 ms; Chrome is usually listening within 100–300 ms)
+ */
+const CHROME_READY_POLL_MS = 50;
+/** Checks before giving up: 25 s in all, as with chrome-launcher's defaults */
+const CHROME_READY_POLL_ATTEMPTS = 500;
 const defaultLogger = {
     info: (msg) => console.error(msg),
     debug: () => { }, // No-op by default
@@ -45,7 +51,9 @@ export async function launchChrome(options = {}) {
     const logger = options.logger ?? defaultLogger;
     const port = options.port ?? DEFAULT_CDP_PORT;
     if (port < 1 || port > 65535) {
-        throw new ChromeLaunchError(invalidPortError(port));
+        throw new ChromeLaunchError(`Invalid port number: ${port}`, {
+            issue: { code: 'INVALID_PORT', context: { port } },
+        });
     }
     const reservation = await reservePort(port);
     reservation.release();
@@ -55,41 +63,40 @@ export async function launchChrome(options = {}) {
             fs.mkdirSync(userDataDir, { recursive: true });
         }
         catch (error) {
-            throw new ChromeLaunchError(userDataDirError(userDataDir, getErrorMessage(error)), error);
+            throw new ChromeLaunchError(`Failed to create user data directory`, {
+                cause: error,
+                issue: {
+                    code: 'USER_DATA_DIR_CREATE_FAILED',
+                    context: { userDataDir, reason: getErrorMessage(error) },
+                },
+            });
         }
     }
     logger.info(`Launching Chrome on port ${port}...`);
-    logger.debug(chromeUserDataDirMessage(userDataDir));
+    logger.debug(`User data directory: ${userDataDir}`);
     const chromeOptions = buildChromeOptions(options);
     const launcher = new chromeLauncher.Launcher(chromeOptions);
+    const startup = watchStartupExit(() => launcher.chromeProcess, markStartupLogs(userDataDir), userDataDir);
     try {
         const launchStart = Date.now();
-        await launcher.launch();
         logger.info('Waiting for Chrome to be ready...');
-        await launcher.waitUntilReady();
+        await Promise.race([launcher.launch(), startup.exited]);
+        startup.stop();
         const launchDurationMs = Date.now() - launchStart;
         logger.info(`✓ Chrome ready (${launchDurationMs}ms)`);
         const chromeProcessPid = launcher.pid ?? 0;
         if (!chromeProcessPid || chromeProcessPid <= 0 || !isProcessAlive(chromeProcessPid)) {
             launcher.kill();
             launcher.destroyTmp();
-            const diagnosticLines = getFormattedDiagnostics();
-            const errorType = !chromeProcessPid || chromeProcessPid <= 0
-                ? 'failed to launch'
-                : 'died immediately after launch';
-            throw new ChromeLaunchError(`Chrome ${errorType} (PID: ${chromeProcessPid})\n\n` +
-                `Possible causes:\n` +
-                `  - Port ${port} conflict (check: lsof -ti:${port})\n` +
-                `  - Chrome binary not found\n` +
-                `  - Insufficient permissions\n` +
-                `  - Chrome crashed on startup\n\n` +
-                `${diagnosticLines.join('\n')}\n\n` +
-                `Try:\n` +
-                `  - bdg cleanup\n` +
-                `  - Kill conflicting process: kill $(lsof -ti:${port})\n` +
-                `  - Use different port: bdg <url> --port ${port + 1}`);
+            const didNotStart = !chromeProcessPid || chromeProcessPid <= 0;
+            throw new ChromeLaunchError(`Chrome ${didNotStart ? 'failed to launch' : 'died immediately after launch'} (PID: ${chromeProcessPid})`, {
+                issue: {
+                    code: didNotStart ? 'CHROME_LAUNCH_FAILED' : 'CHROME_DIED_AFTER_LAUNCH',
+                    context: { port, pid: chromeProcessPid },
+                },
+            });
         }
-        logger.info(chromeLaunchSuccessMessage(chromeProcessPid, launchDurationMs));
+        logger.info(`Chrome launched successfully (PID: ${chromeProcessPid}, ${launchDurationMs}ms)`);
         return {
             pid: chromeProcessPid,
             port: launcher.port ?? port,
@@ -103,13 +110,19 @@ export async function launchChrome(options = {}) {
         };
     }
     catch (error) {
+        startup.stop();
         launcher.kill();
         launcher.destroyTmp();
         if (error instanceof ChromeLaunchError) {
             throw error;
         }
-        const diagnosticLines = getFormattedDiagnostics();
-        throw new ChromeLaunchError(`${chromeLaunchFailedError(getErrorMessage(error))}\n\n${diagnosticLines.join('\n')}`, error instanceof Error ? error : undefined);
+        throw new ChromeLaunchError(`Failed to launch Chrome: ${getErrorMessage(error)}`, {
+            ...(error instanceof Error && { cause: error }),
+            issue: {
+                code: 'CHROME_LAUNCH_FAILED',
+                context: { port, reason: getErrorMessage(error) },
+            },
+        });
     }
 }
 /**
@@ -143,7 +156,13 @@ function getPersistentUserDataDir(baseDir) {
             fs.mkdirSync(userDataDir, { recursive: true });
         }
         catch (error) {
-            throw new Error(userDataDirError(userDataDir, getErrorMessage(error)));
+            throw new ChromeLaunchError(`Failed to create user data directory`, {
+                cause: error,
+                issue: {
+                    code: 'USER_DATA_DIR_CREATE_FAILED',
+                    context: { userDataDir, reason: getErrorMessage(error) },
+                },
+            });
         }
     }
     return userDataDir;
@@ -178,14 +197,14 @@ function buildChromeOptions(options) {
     return {
         logLevel: options.logLevel ?? DEFAULT_CHROME_LOG_LEVEL,
         handleSIGINT: options.handleSIGINT ?? DEFAULT_CHROME_HANDLE_SIGINT,
-        ignoreDefaultFlags: options.ignoreDefaultFlags ?? false,
+        ignoreDefaultFlags: true,
         chromeFlags: buildChromeFlags(options),
         userDataDir,
         ...filterDefined({
             port: options.port,
             startingUrl: options.url,
-            connectionPollInterval: options.connectionPollInterval,
-            maxConnectionRetries: options.maxConnectionRetries,
+            connectionPollInterval: options.connectionPollInterval ?? CHROME_READY_POLL_MS,
+            maxConnectionRetries: options.maxConnectionRetries ?? CHROME_READY_POLL_ATTEMPTS,
             portStrictMode: options.portStrictMode,
             prefs: ensureJSONCompatiblePrefs(mergedPrefs),
             envVars: options.envVars,

package/dist/connection/pageReadiness.d.ts

@@ -2,12 +2,11 @@
  * Smart page readiness detection using fixed thresholds
  *
  * This module provides page load detection that works for most page types
- * without configuration. It uses a three-phase approach:
+ * without configuration. It uses a two-phase approach:
  * 1. Load event (baseline readiness)
- * 2. Network stability (200ms idle threshold)
- * 3. DOM stability (300ms idle threshold)
+ * 2. Network (200ms idle) and DOM (300ms without mutations) quiet at once
  */
-import type { CDPConnection } from '../connection/cdp.js';
+import type { CDPConnection } from './cdp.js';
 /**
  * Options for page readiness detection
  */
@@ -23,8 +22,8 @@ export interface PageReadinessOptions {
  *
  * Strategy (always applied):
  * 1. Wait for load event (baseline readiness)
- * 2. Wait for network to stabilize (200ms idle threshold)
- * 3. Wait for DOM to stabilize (300ms idle threshold)
+ * 2. Wait for the network (200ms idle) and the DOM (300ms without
+ *    mutations) to be quiet at the same time
  *
  * Uses fixed thresholds that work well for most pages.
  * No framework detection, no configuration needed.