browser-debugger-cli 0.7.2 → 0.9.0

package/dist/daemon/session/plugins.js

@@ -0,0 +1,219 @@
+import { startConsoleCollection } from '../../telemetry/console.js';
+import { startDialogHandling } from '../../telemetry/dialogs.js';
+import { prepareDOMCollection } from '../../telemetry/dom.js';
+import { startNavigationTracking } from '../../telemetry/navigation.js';
+import { startNetworkCollection, startWebSocketCollection } from '../../telemetry/network.js';
+import { getErrorMessage } from '../../utils/errors.js';
+import { filterDefined } from '../../utils/objects.js';
+/** Delay before reading the title after a same-document navigation */
+const TITLE_REFRESH_DELAY_MS = 300;
+/**
+ * Keep the store's target URL and title in sync with the page.
+ *
+ * The target info is captured once at session start; without this, `status`,
+ * `peek` and "session already running" keep reporting the start URL after the
+ * page navigates. Same-document navigations (`history.pushState`, hash
+ * changes in single-page apps) update the URL too, and the title shortly
+ * after (apps set it once the new view renders).
+ *
+ * @param cdp - CDP connection
+ * @param store - Telemetry store whose target info is updated
+ * @param logger - Logger for title refresh failures
+ * @returns Cleanup function
+ */
+function trackCurrentPage(cdp, store, logger) {
+    const update = (fields) => {
+        if (store.targetInfo)
+            store.setTargetInfo({ ...store.targetInfo, ...fields });
+    };
+    const refreshTitle = () => {
+        cdp
+            .send('Runtime.evaluate', { expression: 'document.title', returnByValue: true })
+            .then((response) => {
+            const value = response.result?.value;
+            if (typeof value === 'string')
+                update({ title: value });
+        })
+            .catch((error) => {
+            logger.debug(`Could not refresh page title: ${getErrorMessage(error)}`);
+        });
+    };
+    let mainFrameId;
+    let titleTimer;
+    cdp
+        .send('Page.getFrameTree')
+        .then((tree) => {
+        mainFrameId ??= tree.frameTree?.frame?.id;
+    })
+        .catch((error) => logger.debug(`No frame tree: ${getErrorMessage(error)}`));
+    const cleanups = [
+        cdp.on('Page.frameNavigated', ({ frame }) => {
+            if (frame.parentId !== undefined)
+                return;
+            mainFrameId = frame.id;
+            update({ url: frame.url, title: '' });
+        }),
+        cdp.on('Page.navigatedWithinDocument', (params) => {
+            if (params.frameId !== mainFrameId)
+                return;
+            update({ url: params.url });
+            clearTimeout(titleTimer);
+            titleTimer = setTimeout(refreshTitle, TITLE_REFRESH_DELAY_MS);
+        }),
+        cdp.on('Page.loadEventFired', refreshTitle),
+    ];
+    return () => {
+        clearTimeout(titleTimer);
+        cleanups.forEach((cleanup) => cleanup());
+    };
+}
+/**
+ * Make the page behave as focused even when its tab is in the background.
+ *
+ * Without this, once the page opens another tab (`window.open`, a
+ * `target=_blank` link), every `Input.dispatchMouseEvent` waits about 5 s, and
+ * fills before the first click fire no focus/blur events (the document never
+ * had focus).
+ *
+ * @param cdp - CDP connection
+ * @param logger - Logger for failures (the session works without it)
+ */
+async function emulatePageFocus(cdp, logger) {
+    await cdp
+        .send('Emulation.setFocusEmulationEnabled', { enabled: true })
+        .catch((error) => logger.debug(`No focus emulation: ${getErrorMessage(error)}`));
+}
+/** Reads the client hints Chrome reports, renaming the HeadlessChrome brand */
+const USER_AGENT_METADATA_SCRIPT = `(async () => {
+  const data = navigator.userAgentData;
+  if (!data) return null;
+  const values = await data.getHighEntropyValues(
+    ['architecture', 'bitness', 'model', 'platformVersion', 'fullVersionList', 'wow64']
+  );
+  const rename = (list) => (list || []).map((entry) => ({
+    brand: entry.brand.replace('HeadlessChrome', 'Google Chrome'),
+    version: entry.version,
+  }));
+  return {
+    brands: rename(values.brands),
+    fullVersionList: rename(values.fullVersionList),
+    platform: values.platform,
+    platformVersion: values.platformVersion,
+    architecture: values.architecture,
+    model: values.model,
+    mobile: values.mobile,
+    bitness: values.bitness,
+    wow64: values.wow64,
+  };
+})()`;
+/**
+ * Send the user agent and client hints of regular Chrome from headless
+ * Chrome: sites serve "HeadlessChrome" a different page (or a bot
+ * challenge), so the page would not be the one a user sees.
+ *
+ * @param cdp - CDP connection
+ * @param logger - Logger for failures (the session works without it)
+ */
+async function hideHeadlessUserAgent(cdp, logger) {
+    try {
+        const { userAgent } = (await cdp.send('Browser.getVersion'));
+        if (!userAgent.includes('HeadlessChrome'))
+            return;
+        const metadata = (await cdp.send('Runtime.evaluate', {
+            expression: USER_AGENT_METADATA_SCRIPT,
+            awaitPromise: true,
+            returnByValue: true,
+        }));
+        await cdp.send('Emulation.setUserAgentOverride', {
+            userAgent: userAgent.replace('HeadlessChrome', 'Chrome'),
+            ...(metadata.result?.value ? { userAgentMetadata: metadata.result.value } : {}),
+        });
+    }
+    catch (error) {
+        logger.debug(`User agent left as is: ${getErrorMessage(error)}`);
+    }
+}
+export function createDefaultTelemetryPlugins() {
+    return [
+        {
+            name: 'dialogs',
+            runAlways: true,
+            async start({ cdp, store }) {
+                return startDialogHandling(cdp, (dialog) => store.recordDialog(dialog));
+            },
+        },
+        {
+            name: 'page-identity',
+            runAlways: true,
+            async start({ cdp, logger }) {
+                await emulatePageFocus(cdp, logger);
+                await hideHeadlessUserAgent(cdp, logger);
+                return () => undefined;
+            },
+        },
+        {
+            name: 'navigation',
+            runAlways: true,
+            async start({ cdp, store, logger }) {
+                const { cleanup, getCurrentNavigationId } = await startNavigationTracking(cdp, store.navigationEvents);
+                store.setNavigationResolver(getCurrentNavigationId);
+                const stopTracking = trackCurrentPage(cdp, store, logger);
+                return () => {
+                    stopTracking();
+                    void cleanup();
+                };
+            },
+        },
+        {
+            name: 'network',
+            telemetry: 'network',
+            async start({ cdp, config, store }) {
+                const networkOptions = {
+                    includeAll: config.includeAll ?? false,
+                    fetchAllBodies: config.includeAll ?? false,
+                    getCurrentNavigationId: store.getCurrentNavigationId ?? undefined,
+                    pendingRequests: store.pendingNetworkRequests,
+                    ...filterDefined({
+                        maxBodySize: config.maxBodySize,
+                    }),
+                };
+                return startNetworkCollection(cdp, store.networkRequests, networkOptions);
+            },
+        },
+        {
+            name: 'websocket',
+            telemetry: 'network',
+            start({ cdp, store }) {
+                return Promise.resolve(startWebSocketCollection(cdp, store.websocketConnections));
+            },
+        },
+        {
+            name: 'console',
+            telemetry: 'console',
+            async start({ cdp, config, store }) {
+                return startConsoleCollection(cdp, store.consoleMessages, config.includeAll ?? false, store.getCurrentNavigationId ?? undefined);
+            },
+        },
+        {
+            name: 'dom',
+            telemetry: 'dom',
+            async start({ cdp }) {
+                return await prepareDOMCollection(cdp);
+            },
+        },
+    ];
+}
+export function shouldActivatePlugin(plugin, store) {
+    if (plugin.runAlways) {
+        return true;
+    }
+    if (plugin.telemetry) {
+        return store.activeTelemetry.includes(plugin.telemetry);
+    }
+    return false;
+}
+const pluginRegistry = createDefaultTelemetryPlugins();
+export function getRegisteredTelemetryPlugins() {
+    return [...pluginRegistry];
+}
+//# sourceMappingURL=plugins.js.map

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

@@ -0,0 +1,34 @@
+/**
+ * Target-intent check for `start_session` while a session is already running.
+ *
+ * Decides whether a new start request targets the same Chrome as the running
+ * session (launched vs attached via --chrome-ws-url, and which endpoint).
+ */
+import type { StartSessionRequest } from '../../ipc/index.js';
+import type { SessionMetadata } from '../../session/metadata.js';
+/**
+ * Describes a mismatch between the caller's requested target and the
+ * currently-active session's target.
+ */
+export interface TargetMismatch {
+    current: string | undefined;
+    requested: string | undefined;
+}
+/**
+ * Detect whether a new start-session request names a different Chrome target
+ * than the currently-active session.
+ *
+ * Modes:
+ * - **Launched**: no `--chrome-ws-url` (request) / `chromePid > 0` (active).
+ * - **Attached**: `--chrome-ws-url` present (request) / `chromePid` 0 or
+ *   missing (active).
+ *
+ * Rules:
+ * - Both launched → no mismatch (idempotent re-attach to bdg's Chrome).
+ * - Mode differs → mismatch (attaching to a different browser is not
+ *   compatible with the live one).
+ * - Both attached → compare `host:port` (path/page-id may differ
+ *   harmlessly). Different endpoints → mismatch.
+ */
+export declare function detectTargetMismatch(request: Pick<StartSessionRequest, 'chromeWsUrl'>, metadata: SessionMetadata | null): TargetMismatch | null;
+//# sourceMappingURL=targetMismatch.d.ts.map

package/dist/daemon/session/targetMismatch.js

@@ -0,0 +1,83 @@
+/**
+ * Target-intent check for `start_session` while a session is already running.
+ *
+ * Decides whether a new start request targets the same Chrome as the running
+ * session (launched vs attached via --chrome-ws-url, and which endpoint).
+ */
+import { LAUNCHED_CHROME_DESCRIPTION } from '../../errors/messages.js';
+/**
+ * Extract a normalized `host:port` string from a ws URL. Returns null when the
+ * URL is malformed or has no hostname.
+ *
+ * Used to compare attach-mode endpoints since the user-supplied
+ * `--chrome-ws-url` is typically browser-level (`/devtools/browser/<uuid>`)
+ * while the stored `webSocketDebuggerUrl` is the selected page-level target
+ * (`/devtools/page/<id>`). Host+port identifies the Chrome instance; the path
+ * does not.
+ */
+function extractWsEndpoint(ws) {
+    try {
+        const u = new URL(ws);
+        if (!u.hostname)
+            return null;
+        const port = u.port || (u.protocol === 'wss:' ? '443' : '80');
+        return `${u.hostname}:${port}`;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Decide whether a session represents attached-mode Chrome.
+ *
+ * bdg-launched Chrome always records its PID as a positive integer. Attached
+ * sessions (`--chrome-ws-url`) store `chromePid: 0` because the session does
+ * not own the external Chrome process. A missing `chromePid` is treated as
+ * attached for safety — we would rather compare ws endpoints than assume a
+ * mode we can't prove.
+ */
+function isAttachedMode(metadata) {
+    const pid = metadata?.chromePid;
+    return !pid || pid <= 0;
+}
+/**
+ * Detect whether a new start-session request names a different Chrome target
+ * than the currently-active session.
+ *
+ * Modes:
+ * - **Launched**: no `--chrome-ws-url` (request) / `chromePid > 0` (active).
+ * - **Attached**: `--chrome-ws-url` present (request) / `chromePid` 0 or
+ *   missing (active).
+ *
+ * Rules:
+ * - Both launched → no mismatch (idempotent re-attach to bdg's Chrome).
+ * - Mode differs → mismatch (attaching to a different browser is not
+ *   compatible with the live one).
+ * - Both attached → compare `host:port` (path/page-id may differ
+ *   harmlessly). Different endpoints → mismatch.
+ */
+export function detectTargetMismatch(request, metadata) {
+    const requestedWs = request.chromeWsUrl;
+    const currentWs = metadata?.webSocketDebuggerUrl;
+    const requestedIsAttach = Boolean(requestedWs);
+    const currentIsAttach = isAttachedMode(metadata);
+    if (!requestedIsAttach && !currentIsAttach) {
+        return null;
+    }
+    if (requestedIsAttach && !currentIsAttach) {
+        return { current: LAUNCHED_CHROME_DESCRIPTION, requested: requestedWs };
+    }
+    if (!requestedIsAttach && currentIsAttach) {
+        return { current: currentWs, requested: LAUNCHED_CHROME_DESCRIPTION };
+    }
+    if (!requestedWs || !currentWs) {
+        return { current: currentWs, requested: requestedWs };
+    }
+    const requestedEndpoint = extractWsEndpoint(requestedWs);
+    const currentEndpoint = extractWsEndpoint(currentWs);
+    if (requestedEndpoint && currentEndpoint && requestedEndpoint === currentEndpoint) {
+        return null;
+    }
+    return { current: currentWs, requested: requestedWs };
+}
+//# sourceMappingURL=targetMismatch.js.map

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

@@ -0,0 +1,27 @@
+/**
+ * Session teardown: stop collectors, close CDP, terminate launched Chrome.
+ */
+import type { CDPConnection } from '../../connection/cdp.js';
+import type { ChromeNoticeCode, NoticeSink } from '../../errors/notices.js';
+import type { CleanupFunction, LaunchedChrome } from '../../types.js';
+import type { Logger } from '../../ui/logging/index.js';
+/**
+ * Resources to release during teardown. Any of them may be missing if the
+ * session failed part-way through startup.
+ */
+export interface TeardownContext {
+    chrome: LaunchedChrome | null;
+    cdp: CDPConnection | null;
+    cleanupFunctions: CleanupFunction[];
+    /** Attached to a user's Chrome (--chrome-ws-url) rather than one bdg launched */
+    external: boolean;
+    log: Logger;
+    notify: NoticeSink<ChromeNoticeCode>;
+}
+/**
+ * Release all session resources. Never throws.
+ *
+ * @param context - Resources to release
+ */
+export declare function teardownSession(context: TeardownContext): Promise<void>;
+//# sourceMappingURL=teardown.d.ts.map

package/dist/daemon/session/teardown.js

@@ -0,0 +1,128 @@
+/**
+ * Session teardown: stop collectors, close CDP, terminate launched Chrome.
+ */
+import { clearChromePid } from '../../session/chrome.js';
+import { delay } from '../../utils/async.js';
+import { getErrorMessage } from '../../utils/errors.js';
+import { isProcessAlive, killChromeProcess } from '../../utils/process.js';
+/** How often to check whether Chrome has exited (it usually takes 100–300 ms) */
+const CHROME_EXIT_POLL_MS = 50;
+const CHROME_EXIT_POLL_ATTEMPTS = 100;
+/** Up to 5 s for Chrome to shut down cleanly after SIGTERM. */
+const GRACEFUL_EXIT_POLL_ATTEMPTS = 100;
+/** How long to wait for Browser.close to answer (Chrome may exit without answering) */
+const BROWSER_CLOSE_REPLY_MS = 500;
+/**
+ * Release all session resources. Never throws.
+ *
+ * @param context - Resources to release
+ */
+export async function teardownSession(context) {
+    const { chrome, cdp, cleanupFunctions, external, log, notify } = context;
+    for (const cleanup of cleanupFunctions) {
+        try {
+            await cleanup();
+        }
+        catch (error) {
+            log.debug(`Collector cleanup error: ${getErrorMessage(error)}`);
+        }
+    }
+    if (chrome && cdp) {
+        await requestBrowserClose(cdp, chrome.pid, log);
+    }
+    if (cdp) {
+        try {
+            cdp.close();
+        }
+        catch (error) {
+            log.info(`Error closing CDP: ${getErrorMessage(error)}`);
+        }
+    }
+    if (chrome) {
+        await terminateChrome(chrome, log);
+    }
+    else if (cdp && external) {
+        notify({ code: 'EXTERNAL_CHROME_SKIP_TERMINATION' });
+    }
+}
+/**
+ * Ask Chrome to close itself through CDP and wait for it to exit.
+ *
+ * `Browser.close` runs Chrome's normal shutdown, which writes cookies and
+ * storage to the profile; signals (even SIGTERM) can end the process before
+ * recent changes are persisted.
+ *
+ * @param cdp - Open CDP connection
+ * @param pid - Chrome's main process id
+ * @param log - Logger
+ */
+async function requestBrowserClose(cdp, pid, log) {
+    try {
+        await Promise.race([cdp.send('Browser.close'), delay(BROWSER_CLOSE_REPLY_MS)]);
+    }
+    catch (error) {
+        log.debug(`Browser.close failed: ${getErrorMessage(error)}`);
+    }
+    await waitForExit(pid, GRACEFUL_EXIT_POLL_ATTEMPTS);
+}
+/**
+ * Wait until a process exits.
+ *
+ * @param pid - Process id
+ * @param attempts - Polls of {@link CHROME_EXIT_POLL_MS}
+ */
+async function waitForExit(pid, attempts) {
+    for (let attempt = 0; attempt < attempts && isProcessAlive(pid); attempt++) {
+        await delay(CHROME_EXIT_POLL_MS);
+    }
+}
+/**
+ * Terminate a launched Chrome that is still running (normally it already
+ * exited after `Browser.close`, e.g. when CDP was lost).
+ *
+ * SIGTERM goes to Chrome's main process only (not its process group), so it
+ * can still shut its children down in order; signalling the whole group
+ * (which chrome-launcher's kill does, with SIGKILL) loses cookies and storage
+ * written since the last periodic flush.
+ * chrome-launcher's kill still runs afterwards to remove its temporary
+ * profile, escalating to SIGKILL on the group if Chrome is still alive.
+ *
+ * Clears chrome.pid once Chrome is confirmed dead; otherwise the file is kept
+ * so a later `bdg cleanup` or session start can reap it.
+ *
+ * @param chrome - Launched Chrome instance
+ * @param log - Logger
+ */
+async function terminateChrome(chrome, log) {
+    const pid = chrome.pid;
+    try {
+        process.kill(pid, 'SIGTERM');
+        await waitForExit(pid, GRACEFUL_EXIT_POLL_ATTEMPTS);
+    }
+    catch (error) {
+        log.debug(`SIGTERM to Chrome failed: ${getErrorMessage(error)}`);
+    }
+    try {
+        await chrome.kill();
+    }
+    catch (error) {
+        log.info(`Error killing Chrome: ${getErrorMessage(error)}`);
+    }
+    await waitForExit(pid, CHROME_EXIT_POLL_ATTEMPTS);
+    if (isProcessAlive(pid)) {
+        log.info(`Chrome (PID ${pid}) did not exit gracefully, force killing`);
+        try {
+            killChromeProcess(pid, 'SIGKILL');
+            await waitForExit(pid, CHROME_EXIT_POLL_ATTEMPTS);
+        }
+        catch (error) {
+            log.info(`Failed to force kill Chrome: ${getErrorMessage(error)}`);
+        }
+    }
+    if (isProcessAlive(pid)) {
+        log.info(`Chrome (PID ${pid}) survived SIGKILL`);
+        return;
+    }
+    clearChromePid();
+}
+//# sourceMappingURL=teardown.js.map

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

@@ -0,0 +1,67 @@
+/**
+ * Network requests an interaction triggered, read from the session's network
+ * telemetry (no CDP listeners of its own).
+ */
+import type { TelemetryStore } from './TelemetryStore.js';
+import type { TriggeredRequest } from '../../ipc/protocol/domTypes.js';
+import type { NetworkRequest } from '../../types.js';
+/**
+ * Requests listed in a result (a click that loads a page triggers its whole
+ * load); notable ones ({@link isNotableRequest}) are kept before assets
+ */
+export declare const MAX_TRIGGERED_REQUESTS = 50;
+/** Requests started since the watch began: the first ones, and how many more there were */
+export interface CollectedRequests {
+    triggeredRequests: TriggeredRequest[];
+    triggeredRequestsOmitted?: number;
+}
+/** Lists the requests started since the watch began */
+export type TriggeredRequestsCollector = () => CollectedRequests | undefined;
+/**
+ * Start attributing requests to an interaction.
+ *
+ * Requests are attributed by time: every request (and WebSocket connection)
+ * bdg saw start between this call and the collector's call belongs to the
+ * interaction, including one a page timer or poller happened to start
+ * meanwhile. Collecting adds no wait: requests
+ * still running then are reported as pending.
+ *
+ * @param store - Session store holding the network telemetry
+ * @returns Collector (at most {@link MAX_TRIGGERED_REQUESTS} requests, plus how
+ *   many more there were); it returns undefined when network telemetry is off
+ */
+export declare function watchTriggeredRequests(store: TelemetryStore): TriggeredRequestsCollector;
+/**
+ * At most `limit` requests, notable ones first (pages, API calls, sockets,
+ * failures), then assets, still in start order.
+ *
+ * @param requests - Requests in start order
+ * @param limit - How many to keep
+ * @returns Kept requests, in start order
+ */
+export declare function keepNotableFirst(requests: TriggeredRequest[], limit: number): TriggeredRequest[];
+/**
+ * Count a submission's network requests as its request list does (the
+ * submit watcher counts every request id CDP reported until the wait ended:
+ * `data:` URLs and preflights included, a redirect chain once), so
+ * `networkRequests`, the listed requests and JSON agree. Without network
+ * telemetry the watcher's count stays.
+ *
+ * @param result - Submit result with the requests it triggered
+ * @returns The result, `networkRequests` matching `triggeredRequests`
+ */
+export declare function withTriggeredRequestCount<T extends {
+    networkRequests?: number | undefined;
+    triggeredRequests?: TriggeredRequest[] | undefined;
+    triggeredRequestsOmitted?: number | undefined;
+}>(result: T): T;
+/**
+ * Summarize a captured request.
+ *
+ * @param request - Captured request
+ * @param inFlight - Whether it was still in flight (a request with a response
+ *   is then still loading its body: a stream, a slow download)
+ * @returns Triggered request entry
+ */
+export declare function toTriggeredRequest(request: NetworkRequest, inFlight?: boolean): TriggeredRequest;
+//# sourceMappingURL=triggeredRequests.d.ts.map