browser-debugger-cli 0.7.2 → 0.9.0

package/dist/daemon/session/TelemetryStore.d.ts

@@ -0,0 +1,30 @@
+import type { DialogInfo } from '../../ipc/protocol/domTypes.js';
+import type { NavigationEvent } from '../../telemetry/navigation.js';
+import type { PendingRequest } from '../../telemetry/network.js';
+import type { CDPTarget, ConsoleMessage, NetworkRequest, TelemetryType, WebSocketConnection } from '../../types.js';
+export declare class TelemetryStore {
+    readonly networkRequests: NetworkRequest[];
+    /** Requests still in flight, keyed by CDP requestId */
+    readonly pendingNetworkRequests: Map<string, PendingRequest>;
+    readonly consoleMessages: ConsoleMessage[];
+    readonly navigationEvents: NavigationEvent[];
+    readonly websocketConnections: WebSocketConnection[];
+    /** JavaScript dialogs accepted during the session */
+    readonly dialogs: DialogInfo[];
+    activeTelemetry: TelemetryType[];
+    getCurrentNavigationId: (() => number) | null;
+    sessionStartTime: number;
+    targetInfo: CDPTarget | null;
+    resetSessionStart(): void;
+    setTargetInfo(target: CDPTarget | null): void;
+    setNavigationResolver(navigationId: (() => number) | null): void;
+    /**
+     * Record an accepted dialog, and show it among the console messages when
+     * console telemetry is collected (it is otherwise invisible: bdg accepts it
+     * before anyone could see it).
+     *
+     * @param dialog - Dialog type and text
+     */
+    recordDialog(dialog: DialogInfo): void;
+}
+//# sourceMappingURL=TelemetryStore.d.ts.map

package/dist/daemon/session/TelemetryStore.js

@@ -0,0 +1,44 @@
+import { dialogConsoleText } from '../../ui/messages/commands.js';
+export class TelemetryStore {
+    networkRequests = [];
+    /** Requests still in flight, keyed by CDP requestId */
+    pendingNetworkRequests = new Map();
+    consoleMessages = [];
+    navigationEvents = [];
+    websocketConnections = [];
+    /** JavaScript dialogs accepted during the session */
+    dialogs = [];
+    activeTelemetry = [];
+    getCurrentNavigationId = null;
+    sessionStartTime = Date.now();
+    targetInfo = null;
+    resetSessionStart() {
+        this.sessionStartTime = Date.now();
+    }
+    setTargetInfo(target) {
+        this.targetInfo = target;
+    }
+    setNavigationResolver(navigationId) {
+        this.getCurrentNavigationId = navigationId;
+    }
+    /**
+     * Record an accepted dialog, and show it among the console messages when
+     * console telemetry is collected (it is otherwise invisible: bdg accepts it
+     * before anyone could see it).
+     *
+     * @param dialog - Dialog type and text
+     */
+    recordDialog(dialog) {
+        this.dialogs.push(dialog);
+        if (!this.activeTelemetry.includes('console'))
+            return;
+        this.consoleMessages.push({
+            type: 'info',
+            text: dialogConsoleText(dialog),
+            timestamp: Date.now(),
+            source: 'other',
+            ...(this.getCurrentNavigationId && { navigationId: this.getCurrentNavigationId() }),
+        });
+    }
+}
+//# sourceMappingURL=TelemetryStore.js.map

package/dist/daemon/session/cdpSetup.d.ts

@@ -0,0 +1,47 @@
+/**
+ * CDP Setup and Navigation
+ *
+ * Handles CDP connection and page navigation for a session.
+ */
+import { CDPConnection } from '../../connection/cdp.js';
+import type { TelemetryStore } from './TelemetryStore.js';
+import type { SessionConfig } from './types.js';
+import type { LaunchedChrome } from '../../types.js';
+import type { Logger } from '../../ui/logging/index.js';
+/**
+ * Connect to the session's target over CDP.
+ *
+ * @param telemetryStore - Store holding the resolved target
+ * @param log - Logger
+ * @param onDisconnect - Called if an established connection is later lost
+ * @param options - `external`: an already running Chrome, so a failed connect is
+ *   not retried for long (a launched Chrome may still be starting); `signal`:
+ *   stops retrying when the session is stopped while starting
+ * @returns Open CDP connection
+ * @throws CDPConnectionError if no target is known or connecting fails
+ */
+export declare function connectCDP(telemetryStore: TelemetryStore, log: Logger, onDisconnect: () => void, options?: {
+    external?: boolean;
+    signal?: AbortSignal;
+}): Promise<CDPConnection>;
+/**
+ * Network errors that mean the start URL could not be reached at all.
+ *
+ * Other `Page.navigate` errors still leave a page worth inspecting: HTTP error
+ * pages with an empty body (`ERR_HTTP_RESPONSE_CODE_FAILURE`), downloads and
+ * 204 responses (`ERR_ABORTED`), certificate interstitials (`ERR_CERT_*`).
+ */
+export declare const UNREACHABLE_ERRORS: RegExp;
+/**
+ * Navigate to the configured URL, wait for the page, and refresh target info.
+ *
+ * @param cdp - Open CDP connection
+ * @param config - Session configuration
+ * @param telemetryStore - Store whose target info is refreshed
+ * @param chrome - Launched Chrome, or null when attached to an external browser
+ * @param log - Logger
+ * @returns Loader id of the navigation (the main document's request id)
+ * @throws CommandError (80) when the URL cannot be reached at all
+ */
+export declare function navigateToTarget(cdp: CDPConnection, config: SessionConfig, telemetryStore: TelemetryStore, chrome: LaunchedChrome | null, log: Logger): Promise<string | undefined>;
+//# sourceMappingURL=cdpSetup.d.ts.map

package/dist/daemon/session/cdpSetup.js

@@ -0,0 +1,94 @@
+/**
+ * CDP Setup and Navigation
+ *
+ * Handles CDP connection and page navigation for a session.
+ */
+import { CDPConnection } from '../../connection/cdp.js';
+import { CDPConnectionError } from '../../connection/errors.js';
+import { waitForPageReady } from '../../connection/pageReadiness.js';
+import { DEFAULT_PAGE_READINESS_TIMEOUT_MS } from '../../constants.js';
+import { sessionEndingConnectionLoss } from '../messages.js';
+import { CommandError } from '../../errors/index.js';
+import { navigationFailedError } from '../../errors/messages.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { fetchCDPTargets } from '../../utils/http.js';
+import { normalizeUrl } from '../../utils/url.js';
+/** Connection attempts for a Chrome bdg launched (it may still be starting) */
+const LAUNCHED_CONNECT_ATTEMPTS = 10;
+/** Connection attempts for an external Chrome (already running) */
+const EXTERNAL_CONNECT_ATTEMPTS = 2;
+/**
+ * Connect to the session's target over CDP.
+ *
+ * @param telemetryStore - Store holding the resolved target
+ * @param log - Logger
+ * @param onDisconnect - Called if an established connection is later lost
+ * @param options - `external`: an already running Chrome, so a failed connect is
+ *   not retried for long (a launched Chrome may still be starting); `signal`:
+ *   stops retrying when the session is stopped while starting
+ * @returns Open CDP connection
+ * @throws CDPConnectionError if no target is known or connecting fails
+ */
+export async function connectCDP(telemetryStore, log, onDisconnect, options = {}) {
+    if (!telemetryStore.targetInfo) {
+        throw new CDPConnectionError('Failed to obtain target information');
+    }
+    const cdp = new CDPConnection(log);
+    await cdp.connect(telemetryStore.targetInfo.webSocketDebuggerUrl, {
+        autoReconnect: false,
+        maxRetries: options.external ? EXTERNAL_CONNECT_ATTEMPTS : LAUNCHED_CONNECT_ATTEMPTS,
+        signal: options.signal,
+        onDisconnect: (code, reason) => {
+            log.info(`Chrome connection lost (code: ${code}, reason: ${reason})`);
+            log.debug(sessionEndingConnectionLoss());
+            onDisconnect();
+        },
+    });
+    log.info('CDP connection established');
+    return cdp;
+}
+/**
+ * Network errors that mean the start URL could not be reached at all.
+ *
+ * Other `Page.navigate` errors still leave a page worth inspecting: HTTP error
+ * pages with an empty body (`ERR_HTTP_RESPONSE_CODE_FAILURE`), downloads and
+ * 204 responses (`ERR_ABORTED`), certificate interstitials (`ERR_CERT_*`).
+ */
+export const UNREACHABLE_ERRORS = /ERR_NAME_NOT_RESOLVED|ERR_NAME_RESOLUTION_FAILED|ERR_CONNECTION_(REFUSED|RESET|CLOSED|FAILED|TIMED_OUT)|ERR_ADDRESS_UNREACHABLE|ERR_INTERNET_DISCONNECTED|ERR_TIMED_OUT|ERR_EMPTY_RESPONSE|ERR_FILE_NOT_FOUND|ERR_UNSAFE_PORT|ERR_INVALID_URL/;
+/**
+ * Navigate to the configured URL, wait for the page, and refresh target info.
+ *
+ * @param cdp - Open CDP connection
+ * @param config - Session configuration
+ * @param telemetryStore - Store whose target info is refreshed
+ * @param chrome - Launched Chrome, or null when attached to an external browser
+ * @param log - Logger
+ * @returns Loader id of the navigation (the main document's request id)
+ * @throws CommandError (80) when the URL cannot be reached at all
+ */
+export async function navigateToTarget(cdp, config, telemetryStore, chrome, log) {
+    const normalizedUrl = normalizeUrl(config.url);
+    log.info(`Navigating to ${normalizedUrl}...`);
+    const navigation = (await cdp.send('Page.navigate', { url: normalizedUrl }));
+    if (navigation.errorText && UNREACHABLE_ERRORS.test(navigation.errorText)) {
+        const err = navigationFailedError(normalizedUrl, navigation.errorText);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_URL);
+    }
+    if (navigation.errorText)
+        log.info(`Navigation reported ${navigation.errorText}`);
+    await waitForPageReady(cdp, {
+        maxWaitMs: DEFAULT_PAGE_READINESS_TIMEOUT_MS,
+    });
+    log.info(`Page ready`);
+    if (chrome && telemetryStore.targetInfo) {
+        const currentTargetId = telemetryStore.targetInfo.id;
+        const updatedTargets = await fetchCDPTargets(config.port, log);
+        const updatedTarget = updatedTargets.find((t) => t.id === currentTargetId);
+        if (updatedTarget) {
+            telemetryStore.setTargetInfo(updatedTarget);
+            log.info(`Target updated: ${updatedTarget.title} (${updatedTarget.url})`);
+        }
+    }
+    return navigation.loaderId;
+}
+//# sourceMappingURL=cdpSetup.js.map

package/dist/daemon/session/chromeConnection.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Chrome Connection Setup
+ *
+ * Handles Chrome launch or connection to existing Chrome instance.
+ * Finds the appropriate CDP target for the session.
+ */
+import type { TelemetryStore } from './TelemetryStore.js';
+import type { SessionConfig } from './types.js';
+import type { ChromeNoticeCode, NoticeSink } from '../../errors/notices.js';
+import type { LaunchedChrome } from '../../types.js';
+import type { Logger } from '../../ui/logging/index.js';
+/**
+ * Setup Chrome connection - either launch new instance or connect to existing.
+ *
+ * @returns Launched Chrome instance (null if connecting to external Chrome)
+ */
+export declare function setupChromeConnection(config: SessionConfig, telemetryStore: TelemetryStore, log: Logger, notify: NoticeSink<ChromeNoticeCode>): Promise<LaunchedChrome | null>;
+/**
+ * Debugging port of an external Chrome, taken from its WebSocket URL.
+ *
+ * @param wsUrl - `--chrome-ws-url` value
+ * @returns Port in the URL, or the protocol default
+ */
+export declare function externalChromePort(wsUrl: string): number;
+/**
+ * Chrome flags of a launched Chrome: with `--viewport`, a window of that size
+ * first (so tabs the page opens get it too), then the user's own flags, which
+ * win over it.
+ *
+ * @param config - Session configuration
+ * @returns Flags, or undefined without any
+ */
+export declare function windowSizeFlags(config: SessionConfig): string[] | undefined;
+/**
+ * Find the page target of a Chrome that bdg launched.
+ *
+ * Kept separate from the launch so the session owns Chrome before this can
+ * fail, and tears it down if it does. A Chrome that has not opened its first
+ * tab yet gets a blank one.
+ *
+ * @param config - Session configuration
+ * @param telemetryStore - Store receiving the target info
+ * @param log - Logger
+ * @throws ChromeLaunchError if Chrome exposes no page target
+ */
+export declare function findPageTarget(config: SessionConfig, telemetryStore: TelemetryStore, log: Logger): Promise<void>;
+//# sourceMappingURL=chromeConnection.d.ts.map

package/dist/daemon/session/chromeConnection.js

@@ -0,0 +1,215 @@
+/**
+ * Chrome Connection Setup
+ *
+ * Handles Chrome launch or connection to existing Chrome instance.
+ * Finds the appropriate CDP target for the session.
+ */
+import { ChromeLaunchError } from '../../connection/errors.js';
+import { launchChrome } from '../../connection/launcher.js';
+import { HTTP_LOCALHOST } from '../../constants.js';
+import { ConfigError } from '../errors.js';
+import { CommandError } from '../../errors/index.js';
+import { chromeInUseBySessionError, externalBrowserIdMismatchError, externalChromeUnreachableError, externalPageNotFoundError, notDevToolsEndpointError, } from '../../errors/messages.js';
+import { writeChromePid } from '../../session/chrome.js';
+import { findConflictingOwner } from '../../session/chromeOwners.js';
+import { getSessionDir } from '../../session/paths.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { createPageTarget, fetchCDPTargets, probeDevToolsEndpoint } from '../../utils/http.js';
+import { filterDefined } from '../../utils/objects.js';
+/**
+ * Setup Chrome connection - either launch new instance or connect to existing.
+ *
+ * @returns Launched Chrome instance (null if connecting to external Chrome)
+ */
+export async function setupChromeConnection(config, telemetryStore, log, notify) {
+    if (config.chromeWsUrl) {
+        return setupExternalChrome(config, telemetryStore, log, notify);
+    }
+    else {
+        return setupLaunchedChrome(config, log);
+    }
+}
+/** Path of browser-level DevTools WebSocket URLs (`/devtools/browser/<uuid>`) */
+const BROWSER_WS_PATH = '/devtools/browser/';
+/**
+ * Debugging port of an external Chrome, taken from its WebSocket URL.
+ *
+ * @param wsUrl - `--chrome-ws-url` value
+ * @returns Port in the URL, or the protocol default
+ */
+export function externalChromePort(wsUrl) {
+    const url = new URL(wsUrl);
+    return Number(url.port) || (url.protocol === 'wss:' ? 443 : 80);
+}
+/**
+ * Connect to existing external Chrome instance.
+ */
+async function setupExternalChrome(config, telemetryStore, log, notify) {
+    const wsUrl = config.chromeWsUrl;
+    if (!wsUrl) {
+        throw new ConfigError('chromeWsUrl is required for external Chrome connection', 'MISSING_WS_URL');
+    }
+    notify({ code: 'EXTERNAL_CHROME_CONNECTING' });
+    notify({ code: 'EXTERNAL_CHROME_WS_URL', context: { wsUrl } });
+    telemetryStore.setTargetInfo(await resolveExternalTarget(wsUrl, config, log));
+    notify({ code: 'EXTERNAL_CHROME_NO_PID' });
+    return null;
+}
+/**
+ * Find the page to attach to in an external Chrome.
+ *
+ * A page URL is used as given. A browser-level URL cannot run page commands,
+ * so the first open page is used (a blank one is opened if there is none),
+ * reached through the same scheme, host and port (HTTPS for a `wss:` URL).
+ *
+ * @param wsUrl - `--chrome-ws-url` value
+ * @param config - Session configuration (port is the URL's port)
+ * @param log - Logger
+ * @returns Page target
+ * @throws CommandError if no page can be found or opened
+ */
+async function resolveExternalTarget(wsUrl, config, log) {
+    const { hostname, pathname, protocol, port } = new URL(wsUrl);
+    const http = { host: hostname, secure: protocol === 'wss:' };
+    const endpoint = `${http.secure ? 'https' : 'http'}://${hostname}:${config.port}`;
+    const probe = await probeDevToolsEndpoint(config.port, log, http);
+    if (probe.kind !== 'devtools') {
+        const err = probe.kind === 'not-devtools'
+            ? notDevToolsEndpointError(endpoint)
+            : externalChromeUnreachableError(endpoint, http.secure);
+        fail(err, EXIT_CODES.CDP_CONNECTION_FAILURE);
+    }
+    const browserWsUrl = probe.wsUrl;
+    const targets = await fetchCDPTargets(config.port, log, http);
+    const targetId = pathname.split('/').pop() ?? '';
+    if (!pathname.startsWith(BROWSER_WS_PATH)) {
+        const known = targets.find((t) => t.id === targetId);
+        if (!known)
+            fail(externalPageNotFoundError(targetId, endpoint), EXIT_CODES.RESOURCE_NOT_FOUND);
+        await assertNotOwned(targets, known.id, endpoint);
+        return { ...known, webSocketDebuggerUrl: wsUrl };
+    }
+    if (new URL(browserWsUrl).pathname !== pathname) {
+        const actual = withEndpoint(browserWsUrl, protocol, hostname, port);
+        fail(externalBrowserIdMismatchError(endpoint, actual), EXIT_CODES.RESOURCE_NOT_FOUND);
+    }
+    const firstPage = targets.find((t) => t.type === 'page');
+    await assertNotOwned(targets, firstPage?.id ?? '', endpoint);
+    const page = firstPage ?? (await createPageTarget(hostname, config.port, log, http));
+    if (!page)
+        fail(externalChromeUnreachableError(endpoint, http.secure), EXIT_CODES.CDP_CONNECTION_FAILURE);
+    log.info(`Attaching to page ${page.url} of the external Chrome`);
+    return {
+        ...page,
+        webSocketDebuggerUrl: withEndpoint(page.webSocketDebuggerUrl, protocol, hostname, port),
+    };
+}
+/**
+ * Refuse to attach when another running bdg session launched this Chrome or
+ * drives the tab this session would use: taking it over would mix both
+ * sessions' telemetry and let one end the other.
+ *
+ * @param targets - Every target of the Chrome
+ * @param targetId - Tab this session would drive ('' for a tab still to be opened)
+ * @param endpoint - e.g. http://127.0.0.1:9222
+ * @throws CommandError (90) naming the other session
+ */
+async function assertNotOwned(targets, targetId, endpoint) {
+    const owner = await findConflictingOwner(targets.map((t) => t.id), targetId);
+    if (owner)
+        fail(chromeInUseBySessionError(endpoint, owner), EXIT_CODES.RESOURCE_CONFLICT);
+}
+/**
+ * A DevTools WebSocket URL from Chrome, reached the way the user's URL is
+ * (Chrome reports its own host, e.g. 127.0.0.1, even behind a proxy).
+ *
+ * @param url - URL reported by Chrome
+ * @param protocol - Protocol of the user's URL
+ * @param hostname - Host of the user's URL
+ * @param port - Port of the user's URL
+ * @returns The URL with the user's protocol, host and port
+ */
+function withEndpoint(url, protocol, hostname, port) {
+    const result = new URL(url);
+    result.protocol = protocol;
+    result.hostname = hostname;
+    result.port = port;
+    return result.toString();
+}
+/**
+ * Throw a user-facing error.
+ *
+ * @param err - Message and suggestion
+ * @param exitCode - Exit code
+ * @throws CommandError always
+ */
+function fail(err, exitCode) {
+    throw new CommandError(err.message, { suggestion: err.suggestion }, exitCode);
+}
+/**
+ * Chrome flags of a launched Chrome: with `--viewport`, a window of that size
+ * first (so tabs the page opens get it too), then the user's own flags, which
+ * win over it.
+ *
+ * @param config - Session configuration
+ * @returns Flags, or undefined without any
+ */
+export function windowSizeFlags(config) {
+    if (!config.viewport)
+        return config.chromeFlags;
+    const { width, height } = config.viewport;
+    return [`--window-size=${width},${height}`, ...(config.chromeFlags ?? [])];
+}
+/**
+ * Launch a new Chrome instance and record its PID for crash cleanup.
+ */
+async function setupLaunchedChrome(config, log) {
+    const chrome = await launchChrome({
+        port: config.port,
+        logger: log,
+        sessionDir: getSessionDir(),
+        ...filterDefined({
+            userDataDir: config.userDataDir,
+            headless: config.headless,
+            chromeFlags: windowSizeFlags(config),
+        }),
+    });
+    log.info(`Chrome launched (PID ${chrome.pid})`);
+    writeChromePid(chrome.pid);
+    log.debug(`Chrome PID ${chrome.pid} cached for emergency cleanup`);
+    return chrome;
+}
+/**
+ * Find the page target of a Chrome that bdg launched.
+ *
+ * Kept separate from the launch so the session owns Chrome before this can
+ * fail, and tears it down if it does. A Chrome that has not opened its first
+ * tab yet gets a blank one.
+ *
+ * @param config - Session configuration
+ * @param telemetryStore - Store receiving the target info
+ * @param log - Logger
+ * @throws ChromeLaunchError if Chrome exposes no page target
+ */
+export async function findPageTarget(config, telemetryStore, log) {
+    log.info(`Connecting to Chrome via CDP...`);
+    const targets = await fetchCDPTargets(config.port, log);
+    const foundTarget = targets.find((t) => t.type === 'page') ??
+        (await createPageTarget(HTTP_LOCALHOST, config.port, log));
+    if (!foundTarget) {
+        const availableTargets = targets.length
+            ? targets
+                .map((t, i) => `  ${i + 1}. ${t.title || '(no title)'}\n     URL: ${t.url}\n     Type: ${t.type}`)
+                .join('\n')
+            : null;
+        throw new ChromeLaunchError('No page target found after Chrome launch', {
+            issue: {
+                code: 'NO_PAGE_TARGET_FOUND',
+                context: { port: config.port, availableTargets },
+            },
+        });
+    }
+    telemetryStore.setTargetInfo(foundTarget);
+    log.info(`Found target: ${foundTarget.title} (${foundTarget.url})`);
+}
+//# sourceMappingURL=chromeConnection.js.map

package/dist/daemon/{worker → session}/collectors.d.ts

@@ -1,8 +1,8 @@
 import type { TelemetryStore } from './TelemetryStore.js';
 import type { TelemetryPlugin } from './plugins.js';
-import type { WorkerConfig } from './types.js';
+import type { SessionConfig } from './types.js';
 import type { CDPConnection } from '../../connection/cdp.js';
-import type { CleanupFunction } from '../../types';
+import type { CleanupFunction } from '../../types.js';
 import type { Logger } from '../../ui/logging/index.js';
-export declare function startTelemetryCollectors(cdp: CDPConnection, config: WorkerConfig, store: TelemetryStore, logger: Logger, plugins?: TelemetryPlugin[]): Promise<CleanupFunction[]>;
+export declare function startTelemetryCollectors(cdp: CDPConnection, config: SessionConfig, store: TelemetryStore, logger: Logger, plugins?: TelemetryPlugin[]): Promise<CleanupFunction[]>;
 //# sourceMappingURL=collectors.d.ts.map

package/dist/daemon/{worker → session}/collectors.js

@@ -1,4 +1,4 @@
-import { workerActivatingCollector, workerCollectorsActivated } from '../../ui/messages/debug.js';
+import { sessionActivatingCollector, sessionCollectorsActivated } from '../messages.js';
 import { getRegisteredTelemetryPlugins, shouldActivatePlugin } from './plugins.js';
 const DEFAULT_TELEMETRY = ['network', 'console', 'dom'];
 export async function startTelemetryCollectors(cdp, config, store, logger, plugins) {
@@ -9,11 +9,11 @@ export async function startTelemetryCollectors(cdp, config, store, logger, plugi
         if (!shouldActivatePlugin(plugin, store)) {
             continue;
         }
-        logger.debug(workerActivatingCollector(plugin.name));
+        logger.debug(sessionActivatingCollector(plugin.name));
         const cleanup = await plugin.start({ cdp, config, store, logger });
         cleanupFunctions.push(cleanup);
     }
-    logger.debug(workerCollectorsActivated(store.activeTelemetry));
+    logger.debug(sessionCollectorsActivated(store.activeTelemetry));
     return cleanupFunctions;
 }
 //# sourceMappingURL=collectors.js.map