browser-debugger-cli 0.11.0 → 0.13.0

package/dist/commands/stop.d.ts

@@ -1,4 +1,15 @@
 import type { Command } from 'commander';
+/**
+ * Wait until the stopped session's daemon has exited: it removes the
+ * session's files on the way out, and a command run right after (`bdg
+ * sessions`, a new start) would otherwise still see the session. The wait is
+ * bounded, as after a failed start.
+ *
+ * @param pid - Daemon PID read before the stop, or null when unknown
+ * @param waitMs - Milliseconds to wait at most
+ * @returns Warning when the daemon still runs after the wait
+ */
+export declare function waitForDaemonExit(pid: number | null, waitMs?: number): Promise<string | undefined>;
 /**
  * Register stop command
  *

package/dist/commands/stop.js

@@ -3,13 +3,33 @@ import { jsonOption } from './shared/commonOptions.js';
 import { stopSession } from '../ipc/client.js';
 import { IPCErrorCode } from '../ipc/index.js';
 import { IPCTimeoutError } from '../ipc/transport/index.js';
+import { readLiveDaemonPid } from '../session/cleanup/staleSession.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 { daemonStillExitingHint, daemonStillExitingSuggestion, sessionStopped, STOP_MESSAGES, stopFailedError, } from '../ui/messages/session.js';
 import { noActiveSessionMessage, sessionCommand, startSessionSuggestion, } from '../ui/messages/sessionCommand.js';
+import { waitUntil } from '../utils/async.js';
 import { getExitCodeForIPCError, isDaemonNotRunningError } from '../utils/errorMapping.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
+import { isProcessAlive } from '../utils/process.js';
+/** How long `bdg stop` waits for the session's daemon to exit */
+const DAEMON_EXIT_WAIT_MS = 3000;
+/**
+ * Wait until the stopped session's daemon has exited: it removes the
+ * session's files on the way out, and a command run right after (`bdg
+ * sessions`, a new start) would otherwise still see the session. The wait is
+ * bounded, as after a failed start.
+ *
+ * @param pid - Daemon PID read before the stop, or null when unknown
+ * @param waitMs - Milliseconds to wait at most
+ * @returns Warning when the daemon still runs after the wait
+ */
+export async function waitForDaemonExit(pid, waitMs = DAEMON_EXIT_WAIT_MS) {
+    if (pid === null || (await waitUntil(() => !isProcessAlive(pid), waitMs)))
+        return undefined;
+    return `${daemonStillExitingHint(pid, waitMs)}; ${daemonStillExitingSuggestion()}`;
+}
 /**
  * Format stop result for human-readable output.
  *
@@ -36,8 +56,10 @@ export function registerStopCommand(program) {
         .action(async (options) => {
         await runCommand(async () => {
             try {
+                const daemonPid = readLiveDaemonPid();
                 const response = await stopSession();
                 if (response.status === 'ok') {
+                    const warning = await waitForDaemonExit(daemonPid);
                     return {
                         success: true,
                         data: {
@@ -48,6 +70,7 @@ export function registerStopCommand(program) {
                             },
                             orphanedDaemonsCount: 0,
                             message: response.message ?? STOP_MESSAGES.SUCCESS,
+                            ...(warning && { warnings: [warning] }),
                         },
                     };
                 }

package/dist/commands/tail.d.ts

@@ -1,6 +1,12 @@
 /**
- * Tail command for continuous session monitoring.
+ * `bdg tail`: deprecated alias of `bdg peek --follow` (#115). It keeps its
+ * options and says to use `peek --follow` instead.
  */
 import type { Command } from 'commander';
+/**
+ * Register the deprecated `tail` command.
+ *
+ * @param program - Root command
+ */
 export declare function registerTailCommand(program: Command): void;
 //# sourceMappingURL=tail.d.ts.map

package/dist/commands/tail.js

@@ -1,43 +1,19 @@
 /**
- * Tail command for continuous session monitoring.
+ * `bdg tail`: deprecated alias of `bdg peek --follow` (#115). It keeps its
+ * options and says to use `peek --follow` instead.
+ */
+import { followPreview } from './peek.js';
+import { jsonOption } from './shared/commonOptions.js';
+import { tailDeprecatedNotice } from '../ui/messages/preview.js';
+/**
+ * Register the deprecated `tail` command.
+ *
+ * @param program - Root command
  */
-import { jsonOption, showBothSectionsWhenBothRequested } from './shared/commonOptions.js';
-import { noteFollowConnected } from './shared/daemonErrorHandler.js';
-import { fetchPreviewOutput } from './shared/dataFetcher.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';
-import { followingPreviewMessage, stoppedFollowingPreviewMessage } from '../ui/messages/preview.js';
-function parseOptions(options) {
-    const lastRule = positiveIntRule({
-        name: '--last',
-        min: 1,
-        max: MAX_LAST_ITEMS,
-        default: 10,
-        allowZeroForAll: true,
-    });
-    const intervalRule = positiveIntRule({ name: '--interval', min: 100, max: 60000, default: 1000 });
-    return {
-        lastN: lastRule.validate(options.last),
-        interval: intervalRule.validate(options.interval),
-    };
-}
-function createPreviewOptions(options, lastN) {
-    return {
-        json: options.json,
-        network: options.network,
-        console: options.console,
-        last: lastN,
-        verbose: options.verbose,
-        follow: true,
-        viewedAt: new Date(),
-    };
-}
 export function registerTailCommand(program) {
     program
         .command('tail')
-        .description('Continuously monitor session data (like tail -f)')
+        .description('Deprecated: use "bdg peek --follow" (same options)')
         .addOption(jsonOption())
         .option('-v, --verbose', 'Use verbose output with full URLs and formatting', false)
         .option('-n, --network', 'Show only network requests', false)
@@ -45,33 +21,8 @@ export function registerTailCommand(program) {
         .option('--last <count>', 'Show last N items (network requests + console messages), 0 for all', '10')
         .option('--interval <ms>', 'Update interval in milliseconds', '1000')
         .action(async (options) => {
-        showBothSectionsWhenBothRequested(options);
-        let lastN;
-        let interval;
-        try {
-            const parsed = parseOptions(options);
-            lastN = parsed.lastN;
-            interval = parsed.interval;
-        }
-        catch (error) {
-            handleValidationError(error, options.json ?? false);
-        }
-        const showPreview = async () => {
-            const result = await fetchPreviewOutput({ lastN });
-            if (!result.success) {
-                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,
-            stopMessage: stoppedFollowingPreviewMessage,
-            intervalMs: interval,
-        });
+        console.error(tailDeprecatedNotice());
+        await followPreview({ ...options, follow: true });
     });
 }
 //# sourceMappingURL=tail.js.map

package/dist/commands.js

@@ -1,6 +1,7 @@
 import { registerCdpCommand } from './commands/cdp.js';
 import { registerCleanupCommand } from './commands/cleanup.js';
 import { registerConsoleCommand } from './commands/console.js';
+import { registerCssCommands } from './commands/css.js';
 import { registerDetailsCommand } from './commands/details.js';
 import { registerFormInteractionCommands } from './commands/dom/formInteraction.js';
 import { registerDomCommands } from './commands/dom/index.js';
@@ -39,6 +40,7 @@ export const commandRegistry = [
     registerDomCommands,
     registerFormInteractionCommands,
     registerPageCommands,
+    registerCssCommands,
     addCommandGroup('CDP Commands:'),
     registerCdpCommand,
     addCommandGroup('Network Commands:'),

package/dist/connection/cdp.d.ts

@@ -181,6 +181,13 @@ export declare class CDPConnection implements CDPEventSource {
      * @returns Calculated delay in milliseconds (base delay * 2^attempt, capped at maxDelay)
      */
     private calculateBackoffDelay;
+    /**
+     * Fail every command still waiting for an answer, e.g. after the page's
+     * renderer crashed: commands it was running are never answered.
+     *
+     * @param error - Error the waiting commands fail with
+     */
+    rejectPending(error: Error): void;
     /**
      * Clear all pending command promises with the given error.
      *

package/dist/connection/cdp.js

@@ -390,6 +390,15 @@ export class CDPConnection {
     calculateBackoffDelay(attempt, maxDelay) {
         return Math.min(this.config.baseRetryDelay * Math.pow(2, attempt), maxDelay);
     }
+    /**
+     * Fail every command still waiting for an answer, e.g. after the page's
+     * renderer crashed: commands it was running are never answered.
+     *
+     * @param error - Error the waiting commands fail with
+     */
+    rejectPending(error) {
+        this.clearPendingMessages(error);
+    }
     /**
      * Clear all pending command promises with the given error.
      *

package/dist/connection/launcher.js

@@ -3,6 +3,7 @@ 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 { makeDirectory } from '../utils/directories.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { filterDefined } from '../utils/objects.js';
 import { isProcessAlive } from '../utils/process.js';
@@ -62,7 +63,7 @@ export async function launchChrome(options = {}) {
     const userDataDir = options.userDataDir ?? getPersistentUserDataDir(options.baseDir ?? options.sessionDir);
     if (!fs.existsSync(userDataDir)) {
         try {
-            fs.mkdirSync(userDataDir, { recursive: true });
+            makeDirectory(userDataDir);
         }
         catch (error) {
             throw new ChromeLaunchError(`Failed to create user data directory`, {
@@ -160,7 +161,7 @@ function getPersistentUserDataDir(baseDir) {
     const userDataDir = path.join(dir, CHROME_PROFILE_DIR);
     if (!fs.existsSync(userDataDir)) {
         try {
-            fs.mkdirSync(userDataDir, { recursive: true });
+            makeDirectory(userDataDir);
         }
         catch (error) {
             throw new ChromeLaunchError(`Failed to create user data directory`, {

package/dist/daemon/SessionController.js

@@ -241,8 +241,13 @@ export class SessionController {
                         duration: data.duration,
                         target: data.target,
                         data: { network: data.network, console: data.console },
-                        totals: { network: data.totalNetwork, console: data.totalConsole },
+                        totals: {
+                            network: data.totalNetwork,
+                            console: data.totalConsole,
+                            ...(data.droppedConsole && { consoleDropped: data.droppedConsole }),
+                        },
                         currentNavigationId: data.currentNavigationId,
+                        ...(data.pageCrashedAt !== undefined && { pageCrashedAt: data.pageCrashedAt }),
                         partial: true,
                     },
                 },

package/dist/daemon/launcher.d.ts

@@ -24,8 +24,9 @@ export declare function launchDaemon(): Promise<SpawnedDaemon | undefined>;
  * Check that the session directory can hold the daemon's files before
  * spawning it (otherwise the daemon dies and only its log says why).
  *
- * @throws SessionDirError (103) for a file, (81) for a too-long path like a
- *   named session's, (82) when not writable
+ * @throws SessionDirError (103) for a file or a path that cannot hold a
+ *   directory (a pseudo-filesystem like `/proc`), (81) for a too-long path
+ *   like a named session's, (82) when not writable
  */
 export declare function assertUsableSessionDir(): void;
 //# sourceMappingURL=launcher.d.ts.map

package/dist/daemon/launcher.js

@@ -11,13 +11,16 @@ import fs from 'fs';
 import { join } from 'path';
 import { DaemonStartupError, SessionDirError } from './errors.js';
 import { sessionDirIsFileError, sessionDirNotWritableError, socketPathTooLongError, } from '../errors/messages.js';
-import { isDaemonAlive } from '../session/daemonSocket.js';
+import { killSessionChromes, readLiveDaemonPid } from '../session/cleanup/staleSession.js';
+import { isDaemonAlive, isDaemonSocketGone } from '../session/daemonSocket.js';
 import { MAX_DAEMON_SOCKET_PATH_BYTES, ensureSessionDir, getSessionDir, getSessionFilePath, } from '../session/paths.js';
 import { createLogger } from '../ui/logging/index.js';
 import { delay } from '../utils/async.js';
+import { directoryProblem } from '../utils/directories.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { DAEMON_SCRIPT_PATH } from '../utils/packageRoot.js';
+import { isProcessAlive } from '../utils/process.js';
 const log = createLogger('launcher');
 const DAEMON_READY_TIMEOUT_MS = 5000;
 const DAEMON_READY_POLL_MS = 20;
@@ -37,6 +40,7 @@ export async function launchDaemon() {
         throw new DaemonStartupError(`Daemon script not found at ${DAEMON_SCRIPT_PATH}. Did you run 'npm run build'?`, 'DAEMON_SCRIPT_NOT_FOUND');
     }
     assertUsableSessionDir();
+    await stopUnreachableDaemon();
     const logPath = join(getSessionDir(), 'daemon.log');
     rotateLog(logPath);
     const logFd = fs.openSync(logPath, 'a');
@@ -54,12 +58,48 @@ export async function launchDaemon() {
     await waitForDaemonReady(() => exited);
     return { pid: daemon.pid, hasExited: () => exited };
 }
+/** How long a daemon that lost its socket gets to end its session before it is killed */
+const UNREACHABLE_DAEMON_EXIT_MS = 8000;
+/**
+ * Stop a daemon of this session directory that still runs but can no longer
+ * be reached (its socket was removed, or refuses connections; one that is
+ * only slow to answer is left alone), before a new one starts: two daemons
+ * would launch two Chromes and remove each other's files. It is asked to end
+ * its session (closing its Chrome), and killed with what it launched if it
+ * does not exit in time.
+ */
+async function stopUnreachableDaemon() {
+    const pid = readLiveDaemonPid();
+    if (pid === null || !(await isDaemonSocketGone()))
+        return;
+    log.info(`Stopping daemon ${pid}, which can no longer be reached (its socket is gone)`);
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch (error) {
+        log.debug(`Daemon ${pid} not signalled: ${getErrorMessage(error)}`);
+        return;
+    }
+    const deadline = Date.now() + UNREACHABLE_DAEMON_EXIT_MS;
+    while (isProcessAlive(pid) && Date.now() < deadline)
+        await delay(100);
+    if (!isProcessAlive(pid))
+        return;
+    try {
+        process.kill(pid, 'SIGKILL');
+    }
+    catch (error) {
+        log.debug(`Daemon ${pid} not killed: ${getErrorMessage(error)}`);
+    }
+    killSessionChromes();
+}
 /**
  * Check that the session directory can hold the daemon's files before
  * spawning it (otherwise the daemon dies and only its log says why).
  *
- * @throws SessionDirError (103) for a file, (81) for a too-long path like a
- *   named session's, (82) when not writable
+ * @throws SessionDirError (103) for a file or a path that cannot hold a
+ *   directory (a pseudo-filesystem like `/proc`), (81) for a too-long path
+ *   like a named session's, (82) when not writable
  */
 export function assertUsableSessionDir() {
     const dir = getSessionDir();
@@ -72,6 +112,10 @@ export function assertUsableSessionDir() {
     if (Buffer.byteLength(socketPath) > MAX_DAEMON_SOCKET_PATH_BYTES) {
         fail(socketPathTooLongError(socketPath, MAX_DAEMON_SOCKET_PATH_BYTES), EXIT_CODES.INVALID_ARGUMENTS);
     }
+    const problem = directoryProblem(dir);
+    if (problem) {
+        fail(sessionDirNotWritableError(dir, problem.reason), problem.denied ? EXIT_CODES.PERMISSION_DENIED : EXIT_CODES.SESSION_FILE_ERROR);
+    }
     try {
         ensureSessionDir();
         fs.accessSync(dir, fs.constants.W_OK);

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

@@ -80,7 +80,10 @@ export declare class Session {
      */
     launch(): Promise<void>;
     /**
-     * Execute a registered command against this session.
+     * Execute a registered command against this session. After a renderer
+     * crash only {@link RUN_ON_CRASHED_PAGE} commands run (`bdg cdp` only for
+     * {@link CRASH_SAFE_CDP} methods); others fail with exit 107 instead of
+     * waiting for a page that cannot answer.
      *
      * @param name - Command name
      * @param params - Command parameters

package/dist/daemon/session/Session.js

@@ -18,6 +18,7 @@ import { readPageLoadingState } from '../../runtime/page/loadingState.js';
 import { reapOrphanedChrome, removeSessionFiles } from '../../session/cleanup/staleSession.js';
 import { writeSessionMetadata } from '../../session/metadata.js';
 import { getSessionPort } from '../../session/port.js';
+import { pageCrashedCommandError } from '../../telemetry/pageCrash.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { formatChromeNotice } from '../../ui/messages/chrome.js';
 import { delay } from '../../utils/async.js';
@@ -31,6 +32,26 @@ const log = createLogger('session');
 const CRASH_SETTLE_MS = 500;
 /** Ports tried when automatically chosen ports turn out to be taken */
 const PORT_ATTEMPTS = 3;
+/**
+ * Commands that still work after the page's renderer crashed: they read what
+ * the session collected, load the page again (`page reload`/`navigate`) or
+ * send raw CDP. Every other command needs the page and fails at once.
+ */
+const RUN_ON_CRASHED_PAGE = new Set([
+    'session_peek',
+    'session_details',
+    'session_status',
+    'session_har_data',
+    'session_network_headers',
+    'page_navigate',
+    'cdp_call',
+]);
+/**
+ * CDP methods `bdg cdp` may still send after a renderer crash: loading the
+ * page again, and domains the browser process answers. Others wait for the
+ * renderer, which never answers.
+ */
+const CRASH_SAFE_CDP = /^(Page\.(navigate|reload|getNavigationHistory|navigateToHistoryEntry)|Target\.|Browser\.|Inspector\.|Network\.(?!getResponseBody|getRequestPostData)|Storage\.|SystemInfo\.)/;
 /**
  * Whether a launch failed because another process holds the port.
  *
@@ -127,7 +148,10 @@ export class Session {
         }
     }
     /**
-     * Execute a registered command against this session.
+     * Execute a registered command against this session. After a renderer
+     * crash only {@link RUN_ON_CRASHED_PAGE} commands run (`bdg cdp` only for
+     * {@link CRASH_SAFE_CDP} methods); others fail with exit 107 instead of
+     * waiting for a page that cannot answer.
      *
      * @param name - Command name
      * @param params - Command parameters
@@ -137,6 +161,13 @@ export class Session {
         if (!this.cdp || !this.started || this.stopping) {
             return Promise.reject(new Error('No active session'));
         }
+        const crashedAt = this.store.pageCrashedAt;
+        const cdpMethod = name === 'cdp_call' ? params.method : undefined;
+        const needsPage = !RUN_ON_CRASHED_PAGE.has(name) ||
+            (cdpMethod !== undefined && !CRASH_SAFE_CDP.test(cdpMethod));
+        if (crashedAt !== undefined && needsPage) {
+            return Promise.reject(pageCrashedCommandError(crashedAt));
+        }
         return this.registry[name](this.cdp, params);
     }
     /**
@@ -223,7 +254,7 @@ export class Session {
             await this.releaseResources();
             if (!this.started)
                 return;
-            removeSessionFiles();
+            removeSessionFiles(process.pid);
             this.onEnded(reason);
         })();
         return this.stopping;

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

@@ -7,11 +7,18 @@ export declare class TelemetryStore {
     /** Requests still in flight, keyed by CDP requestId */
     readonly pendingNetworkRequests: Map<string, PendingRequest>;
     readonly consoleMessages: ConsoleMessage[];
+    /**
+     * Console messages dropped at the limit, oldest first: the index of
+     * `consoleMessages[i]` in the session is `consoleDropped + i`
+     */
+    consoleDropped: number;
     readonly navigationEvents: NavigationEvent[];
     readonly websocketConnections: WebSocketConnection[];
     /** JavaScript dialogs accepted during the session */
     readonly dialogs: DialogInfo[];
     activeTelemetry: TelemetryType[];
+    /** When the page's renderer crashed (epoch ms); undefined while the page is alive */
+    pageCrashedAt: number | undefined;
     getCurrentNavigationId: (() => number) | null;
     sessionStartTime: number;
     targetInfo: CDPTarget | null;
@@ -21,7 +28,7 @@ export declare class TelemetryStore {
     /**
      * 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).
+     * before anyone could see it), dropping the oldest message at the limit.
      *
      * @param dialog - Dialog type and text
      */

package/dist/daemon/session/TelemetryStore.js

@@ -1,14 +1,22 @@
+import { MAX_CONSOLE_MESSAGES } from '../../constants.js';
 import { dialogConsoleText } from '../../ui/messages/commands.js';
 export class TelemetryStore {
     networkRequests = [];
     /** Requests still in flight, keyed by CDP requestId */
     pendingNetworkRequests = new Map();
     consoleMessages = [];
+    /**
+     * Console messages dropped at the limit, oldest first: the index of
+     * `consoleMessages[i]` in the session is `consoleDropped + i`
+     */
+    consoleDropped = 0;
     navigationEvents = [];
     websocketConnections = [];
     /** JavaScript dialogs accepted during the session */
     dialogs = [];
     activeTelemetry = [];
+    /** When the page's renderer crashed (epoch ms); undefined while the page is alive */
+    pageCrashedAt;
     getCurrentNavigationId = null;
     sessionStartTime = Date.now();
     targetInfo = null;
@@ -24,7 +32,7 @@ export class TelemetryStore {
     /**
      * 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).
+     * before anyone could see it), dropping the oldest message at the limit.
      *
      * @param dialog - Dialog type and text
      */
@@ -32,6 +40,10 @@ export class TelemetryStore {
         this.dialogs.push(dialog);
         if (!this.activeTelemetry.includes('console'))
             return;
+        if (this.consoleMessages.length >= MAX_CONSOLE_MESSAGES) {
+            this.consoleMessages.shift();
+            this.consoleDropped++;
+        }
         this.consoleMessages.push({
             type: 'info',
             text: dialogConsoleText(dialog),