browser-debugger-cli 0.7.1 → 0.8.0

package/dist/commands/start.js

@@ -1,10 +1,17 @@
+import fs from 'node:fs';
 import os from 'node:os';
-import { startSessionViaDaemon } from '../commands/shared/startHelpers.js';
-import { positiveIntRule } from '../commands/shared/validation.js';
+import { Option } from 'commander';
+import { jsonOption } from './shared/commonOptions.js';
+import { handleValidationError } from './shared/handleValidationError.js';
+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 { startCommandHelpMessage } from '../ui/messages/commands.js';
-import { genericError } from '../ui/messages/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
+import { findSimilar } from '../utils/suggestions.js';
+import { validateChromeWsUrl, validateUrl } from '../utils/url.js';
 /**
  * Check if a display server (X11 or Wayland) is available.
  * Used to determine default headless mode.
@@ -14,6 +21,42 @@ function hasDisplay() {
     const wayland = process.env['WAYLAND_DISPLAY'];
     return (display !== undefined && display !== '') || (wayland !== undefined && wayland !== '');
 }
+/**
+ * Expand a leading `~/` in a path to the user's home directory.
+ * Chrome itself does not expand `~`, so bdg normalizes it for users.
+ */
+export function expandHome(value) {
+    return value.startsWith('~/') ? value.replace(/^~/, os.homedir()) : value;
+}
+/**
+ * Extract `--user-data-dir` from a flags array.
+ *
+ * Supports both `--user-data-dir=<path>` and `--user-data-dir <path>` forms.
+ * When found, returns the path (with `~/` expanded) and the remaining flags
+ * with every matching entry removed, so callers can avoid passing the same
+ * switch to Chrome twice.
+ */
+export function extractUserDataDirFromFlags(flags) {
+    const rest = [];
+    let userDataDir;
+    for (let i = 0; i < flags.length; i++) {
+        const flag = flags[i];
+        if (flag.startsWith('--user-data-dir=')) {
+            userDataDir = flag.slice('--user-data-dir='.length);
+            continue;
+        }
+        if (flag === '--user-data-dir' && i + 1 < flags.length) {
+            userDataDir = flags[i + 1];
+            i++;
+            continue;
+        }
+        rest.push(flag);
+    }
+    return {
+        userDataDir: userDataDir ? expandHome(userDataDir) : undefined,
+        rest,
+    };
+}
 /**
  * Apply shared telemetry options to a command
  *
@@ -25,15 +68,16 @@ function applyCollectorOptions(command) {
     const defaultHeadless = !hasDisplay();
     return command
         .option('-p, --port <number>', PORT_OPTION_DESCRIPTION)
-        .option('-t, --timeout <seconds>', 'Auto-stop after timeout in seconds (unlimited if not specified)')
+        .option('-t, --timeout <seconds>', 'Stop the session this many seconds after the page has loaded (unlimited if not specified)')
         .option('-u, --user-data-dir <path>', 'Chrome user data directory (defaults to session dir)')
-        .option('-a, --all', 'Include all data (disable filtering of tracking/analytics)', false)
+        .option('-a, --all', 'Include all data: no tracking/analytics filtering, and capture every response body (incl. binary)', false)
         .option('-m, --max-body-size <megabytes>', 'Maximum response body size in MB', '5')
-        .option('--compact', 'Use compact JSON format (no indentation) for output files', false)
-        .option('--headless', 'Run in headless mode (auto if no display)', defaultHeadless)
+        .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 WebSocket URL (e.g., ws://localhost:9222/devtools/page/...)')
+        .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('-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")');
 }
 /**
@@ -43,45 +87,108 @@ function applyCollectorOptions(command) {
  * @returns Session options object with parsed and normalized values
  */
 function buildSessionOptions(options) {
-    const maxBodySizeRule = positiveIntRule({ min: 1, max: 100, required: false });
-    const timeoutRule = positiveIntRule({ min: 1, max: 3600, required: false });
-    const maxBodySizeMB = options.maxBodySize
-        ? maxBodySizeRule.validate(options.maxBodySize)
-        : undefined;
-    const timeout = options.timeout ? timeoutRule.validate(options.timeout) : undefined;
-    let userDataDir = options.userDataDir;
-    if (userDataDir?.startsWith('~/')) {
-        userDataDir = userDataDir.replace(/^~/, os.homedir());
-    }
+    const maxBodySizeRule = positiveIntRule({
+        name: '--max-body-size',
+        min: 1,
+        max: 100,
+        required: false,
+    });
+    const timeoutRule = positiveIntRule({ name: '--timeout', min: 1, max: 3600, required: false });
+    const portRule = positiveIntRule({ name: '--port', min: 1024, max: 65535, required: false });
+    const maxBodySizeMB = options.maxBodySize !== undefined ? maxBodySizeRule.validate(options.maxBodySize) : undefined;
+    const timeout = options.timeout !== undefined ? timeoutRule.validate(options.timeout) : undefined;
     // Merge env var flags with CLI flags (CLI flags come after, taking precedence)
     const envFlags = process.env['BDG_CHROME_FLAGS']?.split(' ').filter(Boolean) ?? [];
     const cliFlags = options.chromeFlags?.split(' ').filter(Boolean) ?? [];
-    const combinedFlags = [...envFlags, ...cliFlags];
+    const { userDataDir: flagUserDataDir, rest: combinedFlags } = extractUserDataDirFromFlags([
+        ...envFlags,
+        ...cliFlags,
+    ]);
+    // Precedence: -u / --user-data-dir > --chrome-flags / BDG_CHROME_FLAGS > default
+    const userDataDir = options.userDataDir ? expandHome(options.userDataDir) : flagUserDataDir;
     const chromeFlags = combinedFlags.length > 0 ? combinedFlags : undefined;
     return {
-        port: parseInt(options.port, 10),
+        port: options.port !== undefined ? portRule.validate(options.port) : undefined,
         timeout,
         userDataDir,
         includeAll: options.all ?? false,
         maxBodySize: maxBodySizeMB !== undefined ? maxBodySizeMB * 1024 * 1024 : undefined,
-        compact: options.compact ?? false,
         headless: options.headless ?? !hasDisplay(),
         chromeWsUrl: options.chromeWsUrl,
         quiet: options.quiet ?? false,
+        json: options.json ?? false,
         chromeFlags,
     };
 }
+/** Telemetry collected by every session. */
+const SESSION_TELEMETRY = ['dom', 'network', 'console'];
+/** Flags users type as commands (`bdg version`). */
+const FLAG_WORDS = { version: '--version', help: '--help' };
+/**
+ * Reject a bare word that is most likely a mistyped command.
+ *
+ * Without a dot, colon or slash an argument cannot be a public URL; treating
+ * it as one would start Chrome on `http://<word>/`. A dotless host still
+ * works as a full URL (`bdg http://intranet/`).
+ *
+ * @param arg - The URL argument
+ * @param commandNames - Registered top-level command names
+ * @throws CommandError (81) for a bare word other than `localhost`
+ */
+function assertNotCommandTypo(arg, commandNames) {
+    if (!/^[a-z][a-z0-9_-]*$/i.test(arg) || arg.toLowerCase() === 'localhost')
+        return;
+    const flag = FLAG_WORDS[arg.toLowerCase()];
+    const err = unknownCommandError(arg, flag ? [flag] : findSimilar(arg, commandNames));
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
+/**
+ * Reject a subcommand typed without its group (`bdg query x` for
+ * `bdg dom query x`) before Commander reads it as a start URL with extra
+ * arguments.
+ *
+ * @param program - Root command with all commands registered
+ * @param argv - Process arguments
+ * @throws CommandError (81) naming the full command
+ */
+export function assertNotGroupSubcommand(program, argv) {
+    const [first] = argv.slice(2).filter((arg) => !arg.startsWith('-'));
+    if (first === undefined || program.commands.some((command) => command.name() === first))
+        return;
+    const group = program.commands.find((command) => command.commands.some((sub) => sub.name() === first));
+    if (!group)
+        return;
+    const err = unknownCommandError(first, [`${group.name()} ${first}`]);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
 /**
- * Common action handler for telemetry commands
+ * Validate the URL and all start options before anything is spawned.
  *
- * @param url - Target URL to collect telemetry from
+ * @param url - Target URL
  * @param options - Parsed command-line options from Commander
- * @returns Promise that resolves when session completes or is stopped
+ * @param commandNames - Registered top-level command names (for typo detection)
+ * @returns The URL and normalized session options
+ * @throws CommandError on any invalid input
  */
-async function collectorAction(url, options) {
-    const sessionOptions = buildSessionOptions(options);
-    const telemetry = ['dom', 'network', 'console'];
-    await startSessionViaDaemon(url, sessionOptions, telemetry);
+function validateStartInput(url, options, commandNames) {
+    if (url === undefined) {
+        const err = missingStartUrlError();
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    assertNotCommandTypo(url, commandNames);
+    assertValidUrl(url);
+    if (options.chromeWsUrl !== undefined) {
+        assertValidChromeWsUrl(options.chromeWsUrl);
+        assertNoLaunchOptions(options);
+    }
+    if (options.userDataDir !== undefined)
+        assertUserDataDir(options.userDataDir);
+    if (options.chromeWsUrl === undefined)
+        assertChromeFlags([
+            ...(process.env['BDG_CHROME_FLAGS']?.split(' ') ?? []),
+            ...(options.chromeFlags?.split(' ') ?? []),
+        ]);
+    return { url, sessionOptions: buildSessionOptions(options) };
 }
 /**
  * Register the start command
@@ -91,20 +198,101 @@ async function collectorAction(url, options) {
  */
 export function registerStartCommands(program) {
     applyCollectorOptions(program.argument('[url]', 'Target URL (example.com or localhost:3000)')).action(async (url, options) => {
-        if (!url) {
+        if (url === undefined && !hasUserOptions(program)) {
             console.error(startCommandHelpMessage());
             process.exit(0);
         }
-        const { validateUrl } = await import('../utils/url.js');
-        const validation = validateUrl(url);
-        if (!validation.valid) {
-            console.error(genericError(validation.error ?? 'Invalid URL'));
-            if (validation.suggestion) {
-                console.error(`Suggestion: ${validation.suggestion}`);
-            }
-            process.exit(EXIT_CODES.INVALID_URL);
+        let validated;
+        try {
+            validated = validateStartInput(url, options, program.commands.map((command) => command.name()));
         }
-        await collectorAction(url, options);
+        catch (error) {
+            handleValidationError(error, options.json ?? false);
+        }
+        await startSessionViaDaemon(validated.url, validated.sessionOptions, SESSION_TELEMETRY);
     });
 }
+/**
+ * Whether any start option was given on the command line (`bdg --port 9333`
+ * without a URL is an error, a bare `bdg` shows help).
+ *
+ * @param program - Root command
+ * @returns True if an option came from the command line
+ */
+function hasUserOptions(program) {
+    return program.options.some((option) => program.getOptionValueSource(option.attributeName()) === 'cli');
+}
+/**
+ * Reject a `-u` value that is an option (`-u --json` swallowed the next flag)
+ * or an existing file.
+ *
+ * @param value - Value of `--user-data-dir`
+ * @throws CommandError (81) when it cannot be a profile directory
+ */
+function assertUserDataDir(value) {
+    const resolved = expandHome(value);
+    let reason;
+    if (!value.trim())
+        reason = 'the path is empty';
+    else if (value.startsWith('-'))
+        reason = 'it looks like an option; -u needs a directory path';
+    else if (fs.existsSync(resolved) && !fs.statSync(resolved).isDirectory())
+        reason = 'it is a file';
+    if (reason === undefined)
+        return;
+    const err = invalidUserDataDirError(value, reason);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
+/**
+ * Reject options that only apply to a Chrome bdg launches.
+ *
+ * @param options - Parsed options (with `--chrome-ws-url`)
+ * @throws CommandError (81) for `--port` or `-u`
+ */
+function assertNoLaunchOptions(options) {
+    const conflicts = [
+        ...(options.port !== undefined ? ['--port'] : []),
+        ...(options.userDataDir !== undefined ? ['--user-data-dir'] : []),
+    ];
+    if (conflicts.length === 0)
+        return;
+    const err = chromeWsUrlConflictError(conflicts);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
+/** bdg's own options, which a `--chrome-flags` value must not be */
+const BDG_OPTION_WORDS = new Set([
+    '--json',
+    '-j',
+    '--port',
+    '-p',
+    '--no-headless',
+    '-q',
+    '--quiet',
+]);
+/**
+ * Reject Chrome flags bdg sets itself, and a `--chrome-flags` value that is
+ * one of bdg's options (`--chrome-flags --json` swallowed `--json`).
+ *
+ * @param flags - Flags from BDG_CHROME_FLAGS and --chrome-flags
+ * @throws CommandError (81) for a conflicting or swallowed flag
+ */
+function assertChromeFlags(flags) {
+    const flag = flags.find((value) => /^--remote-debugging-(port|pipe)\b/.test(value) || BDG_OPTION_WORDS.has(value));
+    if (flag === undefined)
+        return;
+    const err = invalidChromeFlagError(flag);
+    throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+}
+function assertValidUrl(url) {
+    const result = validateUrl(url);
+    if (result.valid)
+        return;
+    throw new CommandError(result.error, result.suggestion ? { suggestion: result.suggestion } : {}, EXIT_CODES.INVALID_URL);
+}
+function assertValidChromeWsUrl(url) {
+    const result = validateChromeWsUrl(url);
+    if (result.valid)
+        return;
+    throw new CommandError(result.error, result.suggestion ? { suggestion: result.suggestion } : {}, EXIT_CODES.INVALID_URL);
+}
 //# sourceMappingURL=start.js.map

package/dist/commands/status.js

@@ -1,11 +1,35 @@
-import { runCommand } from '../commands/shared/CommandRunner.js';
+import { runCommand } from './shared/CommandRunner.js';
+import { isDaemonConnectionError } from '../errors/index.js';
+import { invalidResponseError, sessionNotRespondingError } from '../errors/messages.js';
 import { getStatus } from '../ipc/client.js';
-import { cleanupStaleDaemonPid } from '../session/cleanup.js';
-import { isDaemonConnectionError } from '../ui/errors/index.js';
+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 { formatSessionStatus, formatStatusAsJson, formatNoSessionMessage, } from '../ui/formatters/status.js';
-import { invalidResponseError, daemonNotRunningError } from '../ui/messages/errors.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
+/**
+ * Status without a running session: a start in progress, or a Chrome left
+ * running by an earlier session.
+ *
+ * @param starting - Start in progress, as reported by the daemon
+ * @param ending - Whether the daemon is shutting the session down
+ * @returns Status data (inactive)
+ */
+function inactiveStatus(starting, ending) {
+    if (starting)
+        return { active: false, starting };
+    if (ending)
+        return { active: false, ending: true };
+    const orphanedChromePid = findOrphanedChrome();
+    const lastSession = readLastSessionEnd();
+    return {
+        active: false,
+        ...(orphanedChromePid !== null && { orphanedChromePid }),
+        ...(lastSession && { lastSession }),
+    };
+}
 /**
  * Register status command
  *
@@ -17,7 +41,7 @@ export function registerStatusCommand(program) {
         .command('status')
         .description('Show active session status and collection statistics')
         .option('-j, --json', 'Output as JSON', false)
-        .option('-v, --verbose', 'Show detailed Chrome diagnostics', false)
+        .option('-v, --verbose', "Also show the session's Chrome executable, mode and profile", false)
         .action(async (options) => {
         let latestMetadata;
         let latestSessionPid;
@@ -52,7 +76,7 @@ export function registerStatusCommand(program) {
                 if (!data.sessionPid || !data.sessionMetadata) {
                     latestMetadata = undefined;
                     latestSessionPid = undefined;
-                    const jsonOutput = formatStatusAsJson(null, null);
+                    const jsonOutput = inactiveStatus(data.starting, data.ending);
                     if (data.activity) {
                         jsonOutput.activity = data.activity;
                     }
@@ -69,10 +93,16 @@ export function registerStatusCommand(program) {
                     targetId: data.sessionMetadata.targetId,
                     webSocketDebuggerUrl: data.sessionMetadata.webSocketDebuggerUrl,
                     activeTelemetry: data.sessionMetadata.activeTelemetry,
+                    autoStopAt: data.sessionMetadata.autoStopAt,
                 };
                 latestMetadata = metadata;
                 latestSessionPid = data.sessionPid;
                 const jsonOutput = formatStatusAsJson(metadata, data.sessionPid);
+                const chrome = options.verbose && metadata.chromePid
+                    ? describeRunningChrome(metadata.chromePid)
+                    : null;
+                if (chrome)
+                    jsonOutput.chrome = chrome;
                 if (data.activity) {
                     jsonOutput.activity = data.activity;
                 }
@@ -83,14 +113,21 @@ export function registerStatusCommand(program) {
             }
             catch (error) {
                 const errorMessage = getErrorMessage(error);
-                if (isDaemonConnectionError(error)) {
-                    const cleaned = cleanupStaleDaemonPid();
+                if (error instanceof IPCTimeoutError) {
+                    const err = sessionNotRespondingError(error.timeoutMs / 1000);
                     return {
                         success: false,
-                        error: daemonNotRunningError({ staleCleanedUp: cleaned }),
-                        exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
+                        error: err.message,
+                        exitCode: EXIT_CODES.CDP_TIMEOUT,
+                        errorContext: { suggestion: err.suggestion },
                     };
                 }
+                if (isDaemonConnectionError(error)) {
+                    await removeStaleDaemonFiles();
+                    latestMetadata = undefined;
+                    latestSessionPid = undefined;
+                    return { success: true, data: inactiveStatus() };
+                }
                 return {
                     success: false,
                     error: `Error checking status: ${errorMessage}`,
@@ -102,7 +139,7 @@ export function registerStatusCommand(program) {
             }
         }, options, (data) => {
             if (!data.active) {
-                return formatNoSessionMessage();
+                return formatNoSessionMessage(data);
             }
             if (!latestMetadata || latestSessionPid === undefined) {
                 return formatNoSessionMessage();

package/dist/commands/stop.js

@@ -1,28 +1,25 @@
-import { runCommand } from '../commands/shared/CommandRunner.js';
-import { jsonOption } from '../commands/shared/commonOptions.js';
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
 import { stopSession } from '../ipc/client.js';
 import { IPCErrorCode } from '../ipc/index.js';
-import { performSessionCleanup } from '../session/cleanup.js';
-import { getSessionFilePath } from '../session/paths.js';
+import { IPCTimeoutError } from '../ipc/transport/index.js';
 import { joinLines } from '../ui/formatting.js';
-import { createLogger } from '../ui/logging/index.js';
-import { chromeKilledMessage, orphanedDaemonsCleanedMessage, warningMessage, } from '../ui/messages/commands.js';
+import { chromeClosedMessage, orphanedDaemonsCleanedMessage, warningMessage, } from '../ui/messages/commands.js';
 import { sessionStopped, STOP_MESSAGES, stopFailedError } from '../ui/messages/session.js';
 import { getExitCodeForIPCError, isDaemonNotRunningError } from '../utils/errorMapping.js';
 import { getErrorMessage } from '../utils/errors.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
-const log = createLogger('cleanup');
 /**
  * Format stop result for human-readable output.
  *
  * @param data - Stop result data
  */
 function formatStop(data) {
-    const outputLine = data.stopped.bdg ? sessionStopped(getSessionFilePath('OUTPUT')) : undefined;
+    const outputLine = data.stopped.bdg ? sessionStopped() : undefined;
     const daemonsLine = data.stopped.daemons && data.orphanedDaemonsCount
         ? orphanedDaemonsCleanedMessage(data.orphanedDaemonsCount)
         : undefined;
-    return joinLines(outputLine, data.stopped.chrome && chromeKilledMessage(), daemonsLine, ...(data.warnings ?? []).map((warning) => warningMessage(warning)));
+    return joinLines(outputLine, data.stopped.chrome && chromeClosedMessage(), daemonsLine, ...(data.warnings ?? []).map((warning) => warningMessage(warning)));
 }
 /**
  * Register stop command
@@ -32,33 +29,24 @@ function formatStop(data) {
 export function registerStopCommand(program) {
     program
         .command('stop')
-        .description('Stop daemon and write collected telemetry to ~/.bdg/session.json')
-        .option('--kill-chrome', 'Also kill Chrome browser process', false)
+        .description('Stop daemon and close browser session')
+        .option('--kill-chrome', 'Kept for compatibility: Chrome launched by bdg is always closed on stop', false)
         .addOption(jsonOption())
-        .addHelpText('after', '\nOutput Location:\n  Default: ~/.bdg/session.json\n  Tip: Copy to custom location with: cp ~/.bdg/session.json /path/to/output.json')
         .action(async (options) => {
-        await runCommand(async (opts) => {
+        await runCommand(async () => {
             try {
                 const response = await stopSession();
                 if (response.status === 'ok') {
-                    const cleanupResult = await performSessionCleanup({
-                        killChrome: opts.killChrome,
-                        chromePid: response.chromePid,
-                    });
-                    if (cleanupResult.cleaned.chrome && !opts.json) {
-                        log.info(chromeKilledMessage(response.chromePid));
-                    }
                     return {
                         success: true,
                         data: {
                             stopped: {
                                 bdg: true,
-                                chrome: cleanupResult.cleaned.chrome,
-                                daemons: cleanupResult.cleaned.daemons,
+                                chrome: Boolean(response.chromePid),
+                                daemons: false,
                             },
-                            orphanedDaemonsCount: cleanupResult.orphanedDaemonsCount,
+                            orphanedDaemonsCount: 0,
                             message: response.message ?? STOP_MESSAGES.SUCCESS,
-                            ...(cleanupResult.warnings.length > 0 && { warnings: cleanupResult.warnings }),
                         },
                     };
                 }
@@ -69,7 +57,7 @@ export function registerStopCommand(program) {
                             error: response.message ?? STOP_MESSAGES.NO_SESSION,
                             exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                             errorContext: {
-                                suggestion: 'Start a session first with: bdg <url>',
+                                suggestion: 'Start a session with: bdg <url>',
                             },
                         };
                     }
@@ -85,6 +73,8 @@ export function registerStopCommand(program) {
                 }
             }
             catch (error) {
+                if (error instanceof IPCTimeoutError)
+                    throw error;
                 const errorMessage = getErrorMessage(error);
                 if (isDaemonNotRunningError(errorMessage)) {
                     return {
@@ -92,7 +82,7 @@ export function registerStopCommand(program) {
                         error: STOP_MESSAGES.DAEMON_NOT_RUNNING,
                         exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                         errorContext: {
-                            suggestion: 'Start a session first with: bdg <url>',
+                            suggestion: 'Start a session with: bdg <url>',
                         },
                     };
                 }

package/dist/commands/tail.js

@@ -1,45 +1,28 @@
 /**
  * Tail command for continuous session monitoring.
  */
-import { jsonOption } from '../commands/shared/commonOptions.js';
-import { handleDaemonConnectionError } from '../commands/shared/daemonErrorHandler.js';
-import { fetchPreviewOutput } from '../commands/shared/dataFetcher.js';
-import { setupFollowMode } from '../commands/shared/followMode.js';
-import { positiveIntRule } from '../commands/shared/validation.js';
-import { OutputBuilder } from '../ui/OutputBuilder.js';
-import { CommandError } from '../ui/errors/index.js';
+import { jsonOption, showBothSectionsWhenBothRequested } from './shared/commonOptions.js';
+import { handleDaemonConnectionError, noteFollowConnected, } from './shared/daemonErrorHandler.js';
+import { fetchPreviewOutput } from './shared/dataFetcher.js';
+import { 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';
-import { EXIT_CODES } from '../utils/exitCodes.js';
 function parseOptions(options) {
-    const lastRule = positiveIntRule({ min: 1, max: 1000, default: 10 });
-    const intervalRule = positiveIntRule({ min: 100, max: 60000, default: 1000 });
+    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 handleValidationError(error, json) {
-    if (error instanceof CommandError) {
-        if (json) {
-            const errorOptions = {
-                exitCode: error.exitCode,
-            };
-            if (error.metadata.suggestion) {
-                errorOptions.suggestion = error.metadata.suggestion;
-            }
-            console.log(JSON.stringify(OutputBuilder.buildJsonError(error.message, errorOptions)));
-        }
-        else {
-            console.error(error.message);
-            if (error.metadata.suggestion)
-                console.error(error.metadata.suggestion);
-        }
-        process.exit(error.exitCode);
-    }
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
-}
 function createPreviewOptions(options, lastN) {
     return {
         json: options.json,
@@ -59,9 +42,10 @@ export function registerTailCommand(program) {
         .option('-v, --verbose', 'Use verbose output with full URLs and formatting', false)
         .option('-n, --network', 'Show only network requests', false)
         .option('-c, --console', 'Show only console messages', false)
-        .option('--last <count>', 'Show last N items (network requests + console messages)', '10')
+        .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 {
@@ -73,7 +57,7 @@ export function registerTailCommand(program) {
             handleValidationError(error, options.json ?? false);
         }
         const showPreview = async () => {
-            const result = await fetchPreviewOutput();
+            const result = await fetchPreviewOutput({ lastN });
             if (!result.success) {
                 const errorResult = handleDaemonConnectionError(result.error, {
                     json: options.json,
@@ -85,14 +69,15 @@ export function registerTailCommand(program) {
                     process.exit(errorResult.exitCode);
                 return;
             }
-            console.clear();
+            noteFollowConnected();
+            if (!options.json)
+                console.clear();
             console.log(formatPreview(result.data, createPreviewOptions(options, lastN)));
         };
         await setupFollowMode(showPreview, {
             startMessage: followingPreviewMessage,
             stopMessage: stoppedFollowingPreviewMessage,
             intervalMs: interval,
-            handleEpipe: true,
         });
     });
 }

package/dist/commands.js

@@ -5,6 +5,7 @@ import { registerDetailsCommand } from './commands/details.js';
 import { registerFormInteractionCommands } from './commands/dom/formInteraction.js';
 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 { registerStartCommands } from './commands/start.js';
 import { registerStatusCommand } from './commands/status.js';
@@ -34,6 +35,7 @@ export const commandRegistry = [
     registerDetailsCommand,
     registerDomCommands,
     registerFormInteractionCommands,
+    registerPageCommands,
     addCommandGroup('CDP Commands:'),
     registerCdpCommand,
     addCommandGroup('Network Commands:'),