browser-debugger-cli 0.8.0 → 0.9.0

package/dist/commands/start.js

@@ -7,11 +7,12 @@ import { startSessionViaDaemon } from './shared/startHelpers.js';
 import { positiveIntRule } from './shared/validation.js';
 import { PORT_OPTION_DESCRIPTION } from '../constants.js';
 import { CommandError } from '../errors/index.js';
-import { chromeWsUrlConflictError, invalidChromeFlagError, invalidUserDataDirError, missingStartUrlError, unknownCommandError, } from '../errors/messages.js';
+import { chromeWsUrlConflictError, externalChromeUnreachableError, invalidChromeFlagError, notDevToolsEndpointError, invalidColorSchemeError, invalidUserDataDirError, invalidViewportError, missingStartUrlError, unknownCommandError, } from '../errors/messages.js';
 import { startCommandHelpMessage } from '../ui/messages/commands.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
+import { probeDevToolsEndpoint } from '../utils/http.js';
 import { findSimilar } from '../utils/suggestions.js';
-import { validateChromeWsUrl, validateUrl } from '../utils/url.js';
+import { devToolsHttpEndpoint, validateChromeWsUrl, validateUrl } from '../utils/url.js';
 /**
  * Check if a display server (X11 or Wayland) is available.
  * Used to determine default headless mode.
@@ -63,7 +64,7 @@ export function extractUserDataDirFromFlags(flags) {
  * @param command - Commander.js Command instance to apply options to
  * @returns The modified Command instance with all telemetry options applied
  */
-function applyCollectorOptions(command) {
+export function applyCollectorOptions(command) {
     // Default to headless if no display available
     const defaultHeadless = !hasDisplay();
     return command
@@ -75,10 +76,48 @@ function applyCollectorOptions(command) {
         .addOption(new Option('--compact', 'No effect; kept for compatibility').hideHelp())
         .option('--headless', 'Run Chrome without a window (default unless DISPLAY or WAYLAND_DISPLAY is set)', defaultHeadless)
         .option('--no-headless', 'Show browser window')
-        .option('--chrome-ws-url <url>', 'Connect to existing Chrome via its DevTools WebSocket URL: browser (ws://host:port/devtools/browser/<id>, uses the first tab) or page (.../devtools/page/<id>)')
+        .option('--chrome-ws-url <url>', 'Connect to an existing Chrome: its DevTools port (9222, host:port, http://host:port), or a WebSocket URL: browser (ws://host:port/devtools/browser/<id>, uses the first tab) or page (.../devtools/page/<id>)')
         .option('-q, --quiet', 'Quiet mode - minimal output for AI agents', false)
         .addOption(jsonOption())
-        .option('--chrome-flags <flags>', 'Custom Chrome flags (space-separated, e.g., --chrome-flags="--ignore-certificate-errors --disable-web-security")');
+        .option('--chrome-flags <flags>', 'Custom Chrome flags (space-separated, e.g., --chrome-flags="--ignore-certificate-errors --disable-web-security")')
+        .option('--viewport <WxH>', 'Viewport size in CSS px for the whole session, e.g. 1280x800 (default: 1920x1080 window)')
+        .option('--color-scheme <scheme>', 'Emulate prefers-color-scheme for the session: light or dark (default: the system setting)');
+}
+/** Largest viewport side accepted by `--viewport` (CSS px) */
+const MAX_VIEWPORT_SIDE = 10000;
+/** Values of `--color-scheme` */
+const COLOR_SCHEMES = ['light', 'dark'];
+/**
+ * Parse a `--viewport` value: width and height in CSS px joined by `x`
+ * (`1280x800`; `X`, `×` and `,` work too).
+ *
+ * @param value - Option value
+ * @returns Viewport size
+ * @throws CommandError (81) for anything else, or a side outside 1-10000
+ */
+export function parseViewport(value) {
+    const match = /^\s*(\d+)\s*[xX×,]\s*(\d+)\s*$/.exec(value);
+    const width = Number(match?.[1]);
+    const height = Number(match?.[2]);
+    const valid = (side) => side >= 1 && side <= MAX_VIEWPORT_SIDE;
+    if (match && valid(width) && valid(height))
+        return { width, height };
+    const err = invalidViewportError(value, MAX_VIEWPORT_SIDE);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
+/**
+ * Parse a `--color-scheme` value (case-insensitive).
+ *
+ * @param value - Option value
+ * @returns The scheme
+ * @throws CommandError (81) for another value, suggesting the closest one
+ */
+export function parseColorScheme(value) {
+    const scheme = COLOR_SCHEMES.find((candidate) => candidate === value.trim().toLowerCase());
+    if (scheme)
+        return scheme;
+    const err = invalidColorSchemeError(value, findSimilar(value, [...COLOR_SCHEMES]), COLOR_SCHEMES);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
 /**
  * Transform CLI options into session options
@@ -118,6 +157,8 @@ function buildSessionOptions(options) {
         quiet: options.quiet ?? false,
         json: options.json ?? false,
         chromeFlags,
+        viewport: options.viewport !== undefined ? parseViewport(options.viewport) : undefined,
+        colorScheme: options.colorScheme !== undefined ? parseColorScheme(options.colorScheme) : undefined,
     };
 }
 /** Telemetry collected by every session. */
@@ -166,20 +207,21 @@ export function assertNotGroupSubcommand(program, argv) {
  *
  * @param url - Target URL
  * @param options - Parsed command-line options from Commander
- * @param commandNames - Registered top-level command names (for typo detection)
+ * @param program - Root command (registered command names for typo detection,
+ *   and which options came from the command line)
  * @returns The URL and normalized session options
  * @throws CommandError on any invalid input
  */
-function validateStartInput(url, options, commandNames) {
+function validateStartInput(url, options, program) {
     if (url === undefined) {
         const err = missingStartUrlError();
         throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
     }
-    assertNotCommandTypo(url, commandNames);
+    assertNotCommandTypo(url, program.commands.map((command) => command.name()));
     assertValidUrl(url);
     if (options.chromeWsUrl !== undefined) {
         assertValidChromeWsUrl(options.chromeWsUrl);
-        assertNoLaunchOptions(options);
+        assertNoLaunchOptions(options, program);
     }
     if (options.userDataDir !== undefined)
         assertUserDataDir(options.userDataDir);
@@ -204,7 +246,8 @@ export function registerStartCommands(program) {
         }
         let validated;
         try {
-            validated = validateStartInput(url, options, program.commands.map((command) => command.name()));
+            validated = validateStartInput(url, options, program);
+            validated.sessionOptions.chromeWsUrl = await resolveChromeWsUrl(validated.sessionOptions.chromeWsUrl);
         }
         catch (error) {
             handleValidationError(error, options.json ?? false);
@@ -212,6 +255,49 @@ export function registerStartCommands(program) {
         await startSessionViaDaemon(validated.url, validated.sessionOptions, SESSION_TELEMETRY);
     });
 }
+/**
+ * Turn a `--chrome-ws-url` that names the HTTP DevTools endpoint (a port,
+ * `host:port`, or `http://host:port`) into the browser's WebSocket URL from
+ * its `/json/version`, so users need not look it up themselves.
+ *
+ * @param value - Option value (WebSocket URLs are returned unchanged)
+ * @returns WebSocket URL, or undefined without the option
+ * @throws CommandError (101) when the endpoint does not answer or is not DevTools
+ */
+async function resolveChromeWsUrl(value) {
+    const endpoint = value === undefined ? null : devToolsHttpEndpoint(value);
+    if (endpoint === null)
+        return value;
+    const { hostname, port, protocol } = new URL(endpoint);
+    const secure = protocol === 'https:';
+    const defaultPort = secure ? 443 : 80;
+    const probe = await probeDevToolsEndpoint(Number(port) || defaultPort, undefined, {
+        host: hostname,
+        secure,
+    });
+    if (probe.kind === 'devtools')
+        return atEndpoint(probe.wsUrl, endpoint);
+    const err = probe.kind === 'not-devtools'
+        ? notDevToolsEndpointError(endpoint)
+        : externalChromeUnreachableError(endpoint, false);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.CDP_CONNECTION_FAILURE);
+}
+/**
+ * Point a WebSocket URL Chrome reported at the endpoint the user gave: Chrome
+ * reports its own host and port, which differ behind a proxy or forwarded
+ * port, and only ws:// (an https endpoint is a TLS proxy, so wss://).
+ *
+ * @param wsUrl - URL from `/json/version`
+ * @param endpoint - Endpoint origin the user gave
+ * @returns The URL with the endpoint's host, port and matching scheme
+ */
+function atEndpoint(wsUrl, endpoint) {
+    const resolved = new URL(wsUrl);
+    const target = new URL(endpoint);
+    resolved.protocol = target.protocol === 'https:' ? 'wss:' : 'ws:';
+    resolved.host = target.host;
+    return resolved.toString();
+}
 /**
  * Whether any start option was given on the command line (`bdg --port 9333`
  * without a URL is an error, a bare `bdg` shows help).
@@ -244,16 +330,30 @@ function assertUserDataDir(value) {
     throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
 }
 /**
- * Reject options that only apply to a Chrome bdg launches.
+ * Options given that only apply to a Chrome bdg launches. `--headless` has a
+ * default, so it counts only when given on the command line.
  *
- * @param options - Parsed options (with `--chrome-ws-url`)
- * @throws CommandError (81) for `--port` or `-u`
+ * @param options - Parsed options
+ * @param program - Command the options were parsed by
+ * @returns The conflicting flags, e.g. ["--port", "--headless"]
  */
-function assertNoLaunchOptions(options) {
-    const conflicts = [
+export function launchOptionConflicts(options, program) {
+    const headlessGiven = program.getOptionValueSource('headless') === 'cli';
+    return [
         ...(options.port !== undefined ? ['--port'] : []),
         ...(options.userDataDir !== undefined ? ['--user-data-dir'] : []),
+        ...(headlessGiven ? [options.headless ? '--headless' : '--no-headless'] : []),
     ];
+}
+/**
+ * Reject options that only apply to a Chrome bdg launches.
+ *
+ * @param options - Parsed options (with `--chrome-ws-url`)
+ * @param program - Command the options were parsed by
+ * @throws CommandError (81) for `--port`, `-u` or `--[no-]headless`
+ */
+function assertNoLaunchOptions(options, program) {
+    const conflicts = launchOptionConflicts(options, program);
     if (conflicts.length === 0)
         return;
     const err = chromeWsUrlConflictError(conflicts);

package/dist/commands/status.js

@@ -6,7 +6,9 @@ import { IPCTimeoutError } from '../ipc/transport/IPCError.js';
 import { describeRunningChrome } from '../session/chrome.js';
 import { findOrphanedChrome, removeStaleDaemonFiles } from '../session/cleanup/staleSession.js';
 import { readLastSessionEnd } from '../session/lastSession.js';
+import { getSessionName } from '../session/paths.js';
 import { formatSessionStatus, formatStatusAsJson, formatNoSessionMessage, } from '../ui/formatters/status.js';
+import { sessionCommand } from '../ui/messages/sessionCommand.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 /**
@@ -30,6 +32,24 @@ function inactiveStatus(starting, ending) {
         ...(lastSession && { lastSession }),
     };
 }
+/**
+ * Add the selected session's name (named sessions only).
+ *
+ * @param data - Status data
+ * @returns Status data with `session` for a named session
+ */
+function withSessionName(data) {
+    const session = getSessionName();
+    return session === null ? data : { session, ...data };
+}
+/**
+ * Force-clean the selected session and start it again.
+ *
+ * @returns Command line
+ */
+function resetCommand() {
+    return `${sessionCommand('bdg cleanup --force')} && ${sessionCommand('bdg <url>')}`;
+}
 /**
  * Register status command
  *
@@ -56,7 +76,7 @@ export function registerStatusCommand(program) {
                         error: `Daemon error: ${response.error ?? 'Unknown error'}`,
                         exitCode: EXIT_CODES.SOFTWARE_ERROR,
                         errorContext: {
-                            suggestion: 'Try: bdg cleanup --force && bdg <url>',
+                            suggestion: `Try: ${resetCommand()}`,
                         },
                     };
                 }
@@ -67,7 +87,7 @@ export function registerStatusCommand(program) {
                         error: invalidResponseError('missing data'),
                         exitCode: EXIT_CODES.SOFTWARE_ERROR,
                         errorContext: {
-                            suggestion: 'This is unexpected. Try: bdg cleanup --force && bdg <url>',
+                            suggestion: `This is unexpected. Try: ${resetCommand()}`,
                         },
                     };
                 }
@@ -83,7 +103,7 @@ export function registerStatusCommand(program) {
                     if (data.pageState) {
                         jsonOutput.pageState = data.pageState;
                     }
-                    return { success: true, data: jsonOutput };
+                    return { success: true, data: withSessionName(jsonOutput) };
                 }
                 const metadata = {
                     bdgPid: data.sessionMetadata.bdgPid,
@@ -94,6 +114,8 @@ export function registerStatusCommand(program) {
                     webSocketDebuggerUrl: data.sessionMetadata.webSocketDebuggerUrl,
                     activeTelemetry: data.sessionMetadata.activeTelemetry,
                     autoStopAt: data.sessionMetadata.autoStopAt,
+                    viewport: data.sessionMetadata.viewport,
+                    colorScheme: data.sessionMetadata.colorScheme,
                 };
                 latestMetadata = metadata;
                 latestSessionPid = data.sessionPid;
@@ -109,7 +131,7 @@ export function registerStatusCommand(program) {
                 if (data.pageState) {
                     jsonOutput.pageState = data.pageState;
                 }
-                return { success: true, data: jsonOutput };
+                return { success: true, data: withSessionName(jsonOutput) };
             }
             catch (error) {
                 const errorMessage = getErrorMessage(error);
@@ -126,14 +148,14 @@ export function registerStatusCommand(program) {
                     await removeStaleDaemonFiles();
                     latestMetadata = undefined;
                     latestSessionPid = undefined;
-                    return { success: true, data: inactiveStatus() };
+                    return { success: true, data: withSessionName(inactiveStatus()) };
                 }
                 return {
                     success: false,
                     error: `Error checking status: ${errorMessage}`,
                     exitCode: EXIT_CODES.SOFTWARE_ERROR,
                     errorContext: {
-                        suggestion: 'Try: bdg cleanup --force to reset session state',
+                        suggestion: `Try: ${sessionCommand('bdg cleanup --force')} to reset session state`,
                     },
                 };
             }
@@ -144,7 +166,7 @@ export function registerStatusCommand(program) {
             if (!latestMetadata || latestSessionPid === undefined) {
                 return formatNoSessionMessage();
             }
-            return formatSessionStatus(latestMetadata, latestSessionPid, latestActivity, latestPageState, options.verbose ?? false);
+            return formatSessionStatus(latestMetadata, latestSessionPid, latestActivity, latestPageState, options.verbose ?? false, data.session);
         });
     });
 }

package/dist/commands/stop.js

@@ -6,6 +6,7 @@ import { IPCTimeoutError } from '../ipc/transport/index.js';
 import { joinLines } from '../ui/formatting.js';
 import { chromeClosedMessage, orphanedDaemonsCleanedMessage, warningMessage, } from '../ui/messages/commands.js';
 import { sessionStopped, STOP_MESSAGES, stopFailedError } from '../ui/messages/session.js';
+import { noActiveSessionMessage, sessionCommand, startSessionSuggestion, } from '../ui/messages/sessionCommand.js';
 import { getExitCodeForIPCError, isDaemonNotRunningError } from '../utils/errorMapping.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
@@ -54,10 +55,10 @@ export function registerStopCommand(program) {
                     if (response.errorCode === IPCErrorCode.NO_SESSION) {
                         return {
                             success: false,
-                            error: response.message ?? STOP_MESSAGES.NO_SESSION,
+                            error: response.message ?? noActiveSessionMessage(),
                             exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                             errorContext: {
-                                suggestion: 'Start a session with: bdg <url>',
+                                suggestion: startSessionSuggestion(),
                             },
                         };
                     }
@@ -67,7 +68,7 @@ export function registerStopCommand(program) {
                         error: response.message ?? STOP_MESSAGES.FAILED,
                         exitCode,
                         errorContext: {
-                            suggestion: 'Check session status with: bdg status',
+                            suggestion: `Check session status with: ${sessionCommand('bdg status')}`,
                         },
                     };
                 }
@@ -79,10 +80,10 @@ export function registerStopCommand(program) {
                 if (isDaemonNotRunningError(errorMessage)) {
                     return {
                         success: false,
-                        error: STOP_MESSAGES.DAEMON_NOT_RUNNING,
+                        error: noActiveSessionMessage(),
                         exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                         errorContext: {
-                            suggestion: 'Start a session with: bdg <url>',
+                            suggestion: startSessionSuggestion(),
                         },
                     };
                 }
@@ -91,7 +92,7 @@ export function registerStopCommand(program) {
                     error: stopFailedError(errorMessage),
                     exitCode: EXIT_CODES.SOFTWARE_ERROR,
                     errorContext: {
-                        suggestion: 'Try: bdg cleanup --force to reset session state',
+                        suggestion: `Try: ${sessionCommand('bdg cleanup --force')} to reset session state`,
                     },
                 };
             }

package/dist/commands/tail.js

@@ -2,9 +2,9 @@
  * Tail command for continuous session monitoring.
  */
 import { jsonOption, showBothSectionsWhenBothRequested } from './shared/commonOptions.js';
-import { handleDaemonConnectionError, noteFollowConnected, } from './shared/daemonErrorHandler.js';
+import { noteFollowConnected } from './shared/daemonErrorHandler.js';
 import { fetchPreviewOutput } from './shared/dataFetcher.js';
-import { setupFollowMode } from './shared/followMode.js';
+import { followFetchFailure, setupFollowMode, } from './shared/followMode.js';
 import { handleValidationError } from './shared/handleValidationError.js';
 import { MAX_LAST_ITEMS, positiveIntRule } from './shared/validation.js';
 import { formatPreview } from '../ui/formatters/preview.js';
@@ -59,20 +59,13 @@ export function registerTailCommand(program) {
         const showPreview = async () => {
             const result = await fetchPreviewOutput({ lastN });
             if (!result.success) {
-                const errorResult = handleDaemonConnectionError(result.error, {
-                    json: options.json,
-                    follow: true,
-                    retryIntervalMs: interval,
-                    exitCode: result.exitCode,
-                });
-                if (errorResult.shouldExit)
-                    process.exit(errorResult.exitCode);
-                return;
+                return followFetchFailure(result, { json: options.json, retryIntervalMs: interval });
             }
             noteFollowConnected();
             if (!options.json)
                 console.clear();
             console.log(formatPreview(result.data, createPreviewOptions(options, lastN)));
+            return undefined;
         };
         await setupFollowMode(showPreview, {
             startMessage: followingPreviewMessage,

package/dist/commands/types.d.ts

@@ -34,6 +34,8 @@ export interface CleanupResult {
         chrome: boolean;
         daemons: boolean;
     };
+    /** Directory deleted by `--purge` */
+    purged?: string;
     message: string;
     warnings?: string[];
 }

package/dist/commands.js

@@ -7,6 +7,7 @@ import { registerDomCommands } from './commands/dom/index.js';
 import { registerNetworkCommands } from './commands/network/index.js';
 import { registerPageCommands } from './commands/page.js';
 import { registerPeekCommand } from './commands/peek.js';
+import { registerSessionsCommand } from './commands/sessions.js';
 import { registerStartCommands } from './commands/start.js';
 import { registerStatusCommand } from './commands/status.js';
 import { registerStopCommand } from './commands/stop.js';
@@ -27,6 +28,7 @@ export const commandRegistry = [
     registerStartCommands,
     addCommandGroup('Session Management:'),
     registerStatusCommand,
+    registerSessionsCommand,
     registerStopCommand,
     registerCleanupCommand,
     addCommandGroup('Data Inspection:'),

package/dist/connection/chromeIdentity.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 { type StartupLogs } from './startupExit.js';
+/**
+ * The debugging endpoint a Chrome announced for itself.
+ */
+export interface DevToolsEndpoint {
+    /** Address the debugging server listens on (`127.0.0.1`, `[::1]`) */
+    host: string;
+    /** Port the debugging server listens on */
+    port: number;
+    /** Browser WebSocket path, `/devtools/browser/<id>` */
+    browserPath: string;
+}
+/**
+ * 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 declare function parseDevToolsListening(lines: readonly string[]): DevToolsEndpoint | 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 declare function waitForDevToolsEndpoint(logs: StartupLogs, isRunning: () => boolean, timeoutMs?: number): Promise<DevToolsEndpoint | null>;
+/**
+ * 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 declare function verifyLaunchedChrome(options: {
+    logs: StartupLogs;
+    port: number;
+    pid: number;
+    timeoutMs?: number;
+}): Promise<void>;
+//# sourceMappingURL=chromeIdentity.d.ts.map

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