browser-debugger-cli 0.7.2 → 0.9.0

package/dist/connection/launcher.js

@@ -3,21 +3,29 @@ 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 { verifyLaunchedChrome } from './chromeIdentity.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 { writeProfilePreferences } from './launcher/profilePreferences.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,54 +53,58 @@ 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();
-    const userDataDir = options.userDataDir ?? getPersistentUserDataDir(options.baseDir);
+    const userDataDir = options.userDataDir ?? getPersistentUserDataDir(options.baseDir ?? options.sessionDir);
     if (!fs.existsSync(userDataDir)) {
         try {
             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));
-    const chromeOptions = buildChromeOptions(options);
+    logger.debug(`User data directory: ${userDataDir}`);
+    applyProfilePreferences(userDataDir, options, logger);
+    const chromeOptions = buildChromeOptions({ ...options, port });
     const launcher = new chromeLauncher.Launcher(chromeOptions);
+    const logs = markStartupLogs(userDataDir);
+    const startup = watchStartupExit(() => launcher.chromeProcess, logs, 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));
+        await verifyLaunchedChrome({ logs, port, pid: chromeProcessPid });
+        logger.info(`Chrome launched successfully (PID: ${chromeProcessPid}, ${launchDurationMs}ms)`);
         return {
             pid: chromeProcessPid,
-            port: launcher.port ?? port,
+            port,
             userDataDir: launcher.userDataDir,
             kill: async () => {
                 return Promise.resolve().then(() => {
@@ -103,19 +115,27 @@ 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) },
+            },
+        });
     }
 }
 /**
  * Get the default persistent user-data-dir path.
  *
- * Uses the session directory ($BDG_SESSION_DIR) to store Chrome profile data,
+ * Uses the session directory (`~/.bdg`, `$BDG_SESSION_DIR`, or
+ * `<base>/sessions/<name>` for a named session, passed as `sessionDir`) to
+ * store Chrome profile data,
  * ensuring each session has its own isolated Chrome profile. This prevents
  * SingletonLock conflicts when multiple agents run concurrently.
  *
@@ -123,7 +143,7 @@ export async function launchChrome(options = {}) {
  * For shared login state across sessions, use --user-data-dir to specify a
  * shared location explicitly.
  *
- * @param baseDir - Optional base directory (defaults to session dir). Allows injection for testing or custom locations.
+ * @param baseDir - Optional base directory (defaults to `~/.bdg` or `$BDG_SESSION_DIR`). Allows injection for testing or custom locations.
  * @returns Absolute path to session-isolated user-data-dir
  * @throws Error if user data directory cannot be created due to permission issues
  */
@@ -143,51 +163,76 @@ 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;
 }
 /**
- * Load Chrome preferences from options.
+ * Preferences for the launched profile: bdg's defaults (no translate prompt,
+ * no password manager or leak check, whose bubbles capture input) for
+ * profiles bdg manages, with the caller's preferences on top. A profile the
+ * user chose (`--user-data-dir`) gets only preferences the caller passed.
  *
  * File-based preferences take precedence over inline preferences because
  * files allow for complex, reusable configurations that can be version
  * controlled and shared across team members or CI environments.
  *
  * @param options - Launch options containing prefs or prefsFile
- * @returns Chrome preferences object or undefined if no preferences specified
- * @throws ChromeLaunchError if prefs file cannot be read, parsed, or doesn't exist
+ * @returns Merged preferences (empty when there is nothing to apply)
+ * @throws ChromeLaunchError if prefs file cannot be read or parsed, or prefs are not JSON
+ */
+export function resolveChromePrefs(options) {
+    const defaults = options.userDataDir === undefined ? BDG_CHROME_PREFS : {};
+    const prefs = { ...defaults, ...loadChromePrefs(options) };
+    ensureJSONCompatiblePrefs(prefs);
+    return prefs;
+}
+/**
+ * Write the launch preferences into the profile, if there are any.
+ *
+ * @param userDataDir - Chrome user data directory
+ * @param options - Launch options
+ * @param logger - Logger for failures
+ * @throws ChromeLaunchError if prefs file cannot be read or parsed, or prefs are not JSON
  */
+function applyProfilePreferences(userDataDir, options, logger) {
+    const prefs = resolveChromePrefs(options);
+    if (Object.keys(prefs).length > 0)
+        writeProfilePreferences(userDataDir, prefs, logger);
+}
 /**
  * Build chrome-launcher options from bdg launch options.
  *
  * Maps LaunchOptions to chrome-launcher API format using a clean utility approach
- * that filters out undefined values automatically. User preferences override bdg
- * defaults to allow customization while maintaining sensible base configuration.
+ * that filters out undefined values automatically. Preferences are not passed:
+ * chrome-launcher would replace whole nested sections of an existing profile's
+ * Preferences, so `writeProfilePreferences` merges them instead.
  *
  * @param options - bdg launch options to convert
  * @returns chrome-launcher compatible options object
- * @throws ChromeLaunchError if preference loading fails
  */
 function buildChromeOptions(options) {
-    const userPrefs = loadChromePrefs(options);
-    const userDataDir = options.userDataDir ?? getPersistentUserDataDir(options.baseDir);
+    const userDataDir = options.userDataDir ?? getPersistentUserDataDir(options.baseDir ?? options.sessionDir);
     const chromePathOverride = resolveChromeBinary(options);
-    const mergedPrefs = userPrefs ? { ...BDG_CHROME_PREFS, ...userPrefs } : BDG_CHROME_PREFS;
     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,
             chromePath: chromePathOverride,
         }),

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.

package/dist/connection/pageReadiness.js

@@ -2,11 +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 { trackInFlightRequests } from './inFlightRequests.js';
 import { createLogger } from '../ui/logging/index.js';
 import { delay } from '../utils/async.js';
 import { getErrorMessage } from '../utils/errors.js';
@@ -17,15 +17,15 @@ const NETWORK_IDLE_THRESHOLD_MS = 200;
 const DOM_STABLE_THRESHOLD_MS = 300;
 /** Interval for checking deadline expiration in milliseconds */
 const DEADLINE_CHECK_INTERVAL_MS = 100;
-/** Interval for checking network activity in milliseconds */
-const NETWORK_CHECK_INTERVAL_MS = 50;
+/** Interval for checking network and DOM activity in milliseconds */
+const QUIET_CHECK_INTERVAL_MS = 50;
 /**
  * Wait for page to be ready using fixed thresholds
  *
  * 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.
@@ -49,9 +49,8 @@ export async function waitForPageReady(cdp, options = {}) {
     try {
         await waitForLoadEvent(cdp, deadline);
         log.info('Load event fired');
-        const networkIdleMs = await waitForNetworkStable(cdp, deadline);
+        const { networkIdleMs, domIdleMs } = await waitForQuiet(cdp, deadline);
         log.info(`Network stable (${networkIdleMs}ms idle)`);
-        const domIdleMs = await waitForDOMStable(cdp, deadline);
         log.info(`DOM stable (${domIdleMs}ms idle)`);
         log.info('Page ready');
     }
@@ -116,135 +115,79 @@ async function waitForLoadEvent(cdp, deadline) {
     });
 }
 /**
- * Wait for network to stabilize
- *
- * Uses a fixed 200ms idle threshold which works well for most pages:
- * - Fast enough for quick sites (avoids unnecessary waiting)
- * - Patient enough for API-heavy apps (catches late requests)
- * - Simpler and more predictable than adaptive learning
- *
- * Network is considered stable when there are zero active requests
- * for at least 200ms continuously.
- *
- * Why this works:
- * - Catches initial request bursts (CSS, JS, images)
- * - Waits for lazy-loaded resources
- * - Detects API calls triggered by hydration
- * - Framework-agnostic - based on actual network activity
- *
- * @param cdp - CDP connection
- * @param deadline - Timestamp when to timeout
- * @returns Actual idle duration detected
- * @throws Error if deadline exceeded
+ * Page script tracking DOM mutations until {@link REMOVE_MUTATION_OBSERVER_JS}.
+ * Installs only once per document: a page that navigated itself (a redirect
+ * right after load) gets a new observer, its quiet time counted from then.
  */
-async function waitForNetworkStable(cdp, deadline) {
-    await cdp.send('Network.enable');
-    let activeRequests = 0;
-    let lastActivity = Date.now();
-    const requestHandler = () => {
-        activeRequests++;
-        lastActivity = Date.now();
-    };
-    const finishHandler = () => {
-        activeRequests--;
-        if (activeRequests === 0) {
-            lastActivity = Date.now();
-        }
-    };
-    const cleanupRequest = cdp.on('Network.requestWillBeSent', requestHandler);
-    const cleanupFinished = cdp.on('Network.loadingFinished', finishHandler);
-    const cleanupFailed = cdp.on('Network.loadingFailed', finishHandler);
-    try {
-        while (Date.now() < deadline) {
-            if (activeRequests === 0) {
-                const idleTime = Date.now() - lastActivity;
-                if (idleTime >= NETWORK_IDLE_THRESHOLD_MS) {
-                    return idleTime; // Success!
-                }
-            }
-            await delay(NETWORK_CHECK_INTERVAL_MS);
-        }
-        throw new Error('Network stability timeout');
-    }
-    finally {
-        cleanupRequest();
-        cleanupFinished();
-        cleanupFailed();
-    }
-}
+const INSTALL_MUTATION_OBSERVER_JS = `
+  if (!window.__bdg_observer) {
+    window.__bdg_lastMutation = Date.now();
+    window.__bdg_observer = new MutationObserver(() => {
+      window.__bdg_lastMutation = Date.now();
+    });
+    window.__bdg_observer.observe(document.body ?? document.documentElement, {
+      childList: true,
+      subtree: true,
+      attributes: true,
+      characterData: true
+    });
+  }
+`;
+const REMOVE_MUTATION_OBSERVER_JS = `
+  window.__bdg_observer?.disconnect();
+  delete window.__bdg_observer;
+  delete window.__bdg_lastMutation;
+`;
 /**
- * Wait for DOM to stabilize
+ * Wait until the network and the DOM are both quiet: no request in flight
+ * for 200 ms and no DOM mutation for 300 ms (hydration, client rendering,
+ * lazy-loaded resources and API calls all show up in one or the other).
  *
- * Uses a MutationObserver to detect when the DOM stops changing.
- * DOM is considered stable when there are no mutations for 300ms continuously.
- *
- * HOW IT WORKS:
- * 1. Inject MutationObserver into page to track all DOM changes
- * 2. Monitor childList, attributes, subtree, and characterData changes
- * 3. Wait for 300ms of continuous no-change activity
- * 4. Clean up observer when complete
- *
- * Why this works:
- * - SSR hydration causes DOM mutations (React, Vue, Svelte)
- * - Client-side rendering creates DOM elements
- * - When mutations stop, framework initialization is complete
- * - 300ms is long enough to catch batched updates, short enough to be responsive
- *
- * Framework-agnostic - detects actual mutations regardless of framework.
+ * Both are watched at once, so a page that is already quiet is ready after
+ * 300 ms, not after 200 ms and then another 300 ms.
  *
  * @param cdp - CDP connection
  * @param deadline - Timestamp when to timeout
- * @returns Actual stable duration detected
+ * @returns How long each has been quiet
  * @throws Error if deadline exceeded
  */
-async function waitForDOMStable(cdp, deadline) {
-    await cdp.send('Runtime.evaluate', {
-        expression: `
-      window.__bdg_mutations = 0;
-      window.__bdg_lastMutation = Date.now();
-
-      const observer = new MutationObserver(() => {
-        window.__bdg_mutations++;
-        window.__bdg_lastMutation = Date.now();
-      });
-
-      observer.observe(document.body, {
-        childList: true,
-        subtree: true,
-        attributes: true,
-        characterData: true
-      });
-
-      window.__bdg_observer = observer;
-    `,
-    });
+async function waitForQuiet(cdp, deadline) {
+    await cdp.send('Network.enable');
+    const requests = trackInFlightRequests(cdp);
     try {
+        await cdp.send('Runtime.evaluate', { expression: INSTALL_MUTATION_OBSERVER_JS });
         while (Date.now() < deadline) {
-            const checkResult = (await cdp.send('Runtime.evaluate', {
-                expression: 'Date.now() - window.__bdg_lastMutation',
-                returnByValue: true,
-            }));
-            const timeSinceLastMutation = checkResult.result.value ?? 0;
-            if (timeSinceLastMutation >= DOM_STABLE_THRESHOLD_MS) {
-                return timeSinceLastMutation; // Success!
+            const networkIdleMs = requests.count === 0 ? Date.now() - requests.lastActivity : 0;
+            if (networkIdleMs >= NETWORK_IDLE_THRESHOLD_MS) {
+                const domIdleMs = await msSinceLastMutation(cdp);
+                if (domIdleMs >= DOM_STABLE_THRESHOLD_MS)
+                    return { networkIdleMs, domIdleMs };
             }
-            await delay(DEADLINE_CHECK_INTERVAL_MS);
+            await delay(QUIET_CHECK_INTERVAL_MS);
         }
-        throw new Error('DOM stability timeout');
+        throw new Error('Page stability timeout');
     }
     finally {
+        requests.dispose();
         await cdp
-            .send('Runtime.evaluate', {
-            expression: `
-        window.__bdg_observer?.disconnect();
-        delete window.__bdg_observer;
-        delete window.__bdg_mutations;
-        delete window.__bdg_lastMutation;
-      `,
-        })
+            .send('Runtime.evaluate', { expression: REMOVE_MUTATION_OBSERVER_JS })
             .catch((error) => {
             log.debug(`Failed to clean up DOM observer: ${getErrorMessage(error)}`);
         });
     }
 }
+/**
+ * Time since the page's DOM last changed.
+ *
+ * @param cdp - CDP connection
+ * @returns Milliseconds since the last mutation (0 when unknown)
+ */
+async function msSinceLastMutation(cdp) {
+    const check = (await cdp.send('Runtime.evaluate', {
+        expression: `${INSTALL_MUTATION_OBSERVER_JS}; Date.now() - window.__bdg_lastMutation`,
+        returnByValue: true,
+    }));
+    const value = check.result.value;
+    return typeof value === 'number' && Number.isFinite(value) ? value : 0;
+}
 //# sourceMappingURL=pageReadiness.js.map

package/dist/connection/portReservation.d.ts

@@ -11,6 +11,26 @@ export interface PortReservation {
     /** Release the port reservation */
     release: () => void;
 }
+/**
+ * Whether something already accepts connections on host:port.
+ *
+ * @param port - Port to check
+ * @param host - Address to connect to
+ * @returns True if a connection was accepted
+ */
+export declare function acceptsConnections(port: number, host: string): Promise<boolean>;
+/**
+ * Whether something already accepts connections on the port, on 127.0.0.1 or
+ * ::1. A listener on all interfaces (`0.0.0.0`/`::`) does not stop bdg from
+ * binding 127.0.0.1 on macOS, but Chrome would then fail to listen; a Chrome
+ * on [::1] (one that found 127.0.0.1 taken) does not stop it either, but a
+ * second Chrome would be reached through the first one's port. Both are found
+ * by connecting.
+ *
+ * @param port - Port to check
+ * @returns True if a connection was accepted on either address
+ */
+export declare function isPortAnswering(port: number): Promise<boolean>;
 /**
  * Atomically reserve a port to prevent race conditions during Chrome launch.
  *

package/dist/connection/portReservation.js

@@ -5,8 +5,56 @@
  * Chrome launch when multiple processes might try to bind to the same port.
  */
 import * as net from 'net';
-import { portInUseError } from '../ui/messages/chrome.js';
 import { ChromeLaunchError } from './errors.js';
+/** How long a connection attempt may take when checking a port */
+const CONNECT_CHECK_MS = 500;
+/** Loopback addresses Chrome may listen on (it falls back to IPv6 when IPv4 is taken) */
+const LOOPBACK_HOSTS = ['127.0.0.1', '::1'];
+/**
+ * Whether something already accepts connections on host:port.
+ *
+ * @param port - Port to check
+ * @param host - Address to connect to
+ * @returns True if a connection was accepted
+ */
+export function acceptsConnections(port, host) {
+    return new Promise((resolve) => {
+        const socket = net.connect({ port, host });
+        const finish = (answering) => {
+            socket.destroy();
+            resolve(answering);
+        };
+        socket.setTimeout(CONNECT_CHECK_MS, () => finish(false));
+        socket.once('connect', () => finish(true));
+        socket.once('error', () => finish(false));
+    });
+}
+/**
+ * Whether something already accepts connections on the port, on 127.0.0.1 or
+ * ::1. A listener on all interfaces (`0.0.0.0`/`::`) does not stop bdg from
+ * binding 127.0.0.1 on macOS, but Chrome would then fail to listen; a Chrome
+ * on [::1] (one that found 127.0.0.1 taken) does not stop it either, but a
+ * second Chrome would be reached through the first one's port. Both are found
+ * by connecting.
+ *
+ * @param port - Port to check
+ * @returns True if a connection was accepted on either address
+ */
+export async function isPortAnswering(port) {
+    const answers = await Promise.all(LOOPBACK_HOSTS.map((host) => acceptsConnections(port, host)));
+    return answers.some(Boolean);
+}
+/**
+ * The error for a port another process uses.
+ *
+ * @param port - Port
+ * @returns Launch error with the PORT_IN_USE issue
+ */
+function portInUseError(port) {
+    return new ChromeLaunchError(`Port ${port} is already in use`, {
+        issue: { code: 'PORT_IN_USE', context: { port } },
+    });
+}
 /**
  * Atomically reserve a port to prevent race conditions during Chrome launch.
  *
@@ -33,11 +81,13 @@ import { ChromeLaunchError } from './errors.js';
  * ```
  */
 export async function reservePort(port) {
+    if (await isPortAnswering(port))
+        throw portInUseError(port);
     return new Promise((resolve, reject) => {
         const server = net.createServer();
         server.once('error', (err) => {
             if (err.code === 'EADDRINUSE') {
-                reject(new ChromeLaunchError(portInUseError(port)));
+                reject(portInUseError(port));
             }
             else {
                 reject(err);

package/dist/connection/startupExit.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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 type { ChildProcess } from 'child_process';
+/** Chrome's log files in the profile directory, and their size before the launch */
+export interface StartupLogs {
+    files: Array<{
+        file: string;
+        offset: number;
+    }>;
+}
+/**
+ * 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 declare function markStartupLogs(userDataDir: string): StartupLogs;
+/**
+ * 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 declare function readStartupLines(logs: StartupLogs): string[];
+/**
+ * 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 declare function watchStartupExit(getProcess: () => ChildProcess | undefined, logs: StartupLogs, userDataDir: string): {
+    exited: Promise<never>;
+    stop: () => void;
+};
+//# sourceMappingURL=startupExit.d.ts.map