browser-debugger-cli 0.7.1 → 0.8.0

package/dist/commands/optionBehaviors.js

@@ -6,7 +6,7 @@
  *
  * @see docs/principles/SELF_DOCUMENTING_SYSTEMS.md
  */
-import { MAX_EDGE_PX, PIXELS_PER_TOKEN, TALL_PAGE_THRESHOLD, } from '../commands/dom/screenshotResize.js';
+import { MAX_EDGE_PX, PIXELS_PER_TOKEN, TALL_PAGE_THRESHOLD, } from './dom/screenshotResize.js';
 /**
  * Behavioral metadata registry.
  *
@@ -29,8 +29,9 @@ const OPTION_BEHAVIORS = {
         automaticBehavior: 'When used with tall pages, prevents the automatic viewport fallback message since scroll is an explicit user choice',
     },
     'screenshot:--format': {
-        default: 'PNG format (lossless, larger file size)',
-        whenEnabled: 'JPEG format available for smaller files with quality trade-off',
+        default: 'Taken from the file extension: .jpg/.jpeg is JPEG, anything else PNG',
+        whenEnabled: 'png or jpeg (jpg, any case); JPEG gives smaller files with a quality trade-off',
+        automaticBehavior: 'A --format that contradicts the extension, or an extension Chrome cannot write (.gif, .webp, ...), is refused with exit 81',
     },
     'screenshot:--quality': {
         default: 'JPEG quality 90 (good balance of quality and size)',
@@ -47,7 +48,12 @@ const OPTION_BEHAVIORS = {
     },
     'get:--nth': {
         default: 'Returns first matching element',
-        whenEnabled: 'Returns the nth matching element (1-based index, only works with --raw)',
+        whenEnabled: 'Returns the nth matching element (0-based index, only works with --raw)',
+    },
+    'eval:--frame': {
+        default: "Evaluates in the page's main frame",
+        whenEnabled: "Evaluates in one iframe's main world (its own globals), including cross-origin (out-of-process) iframes; output gains a frame field (its URL)",
+        automaticBehavior: 'The value is matched as: a 0-based index (bdg dom frames order, main page not counted), else an exact name/id attribute, else a case-insensitive part of the URL. Several matches fail with 81 listing them; none fails with 83 listing all frames. Frames are looked up on every call (a reloaded iframe is found again).',
     },
     'console:-H': {
         default: 'Shows messages from current page load only (most recent navigation)',
@@ -84,7 +90,25 @@ const OPTION_BEHAVIORS = {
     'click:--no-wait': {
         default: 'Waits for network stability after click (200ms idle)',
         whenDisabled: 'Returns immediately without waiting for network',
-        automaticBehavior: 'Network wait helps ensure AJAX requests triggered by click complete',
+        automaticBehavior: 'Network wait helps ensure AJAX requests triggered by click complete. The click itself uses real mouse events in the visible part of the element (method "mouse"); if the element is covered or has no size it falls back to DOM events (method "dom", with a warning)',
+    },
+    'click:--double': {
+        default: 'Single click',
+        whenEnabled: 'Double-click: two presses with clickCount 1 and 2, so the page gets click, click and dblclick',
+    },
+    'click:--right': {
+        default: 'Left click',
+        whenEnabled: 'Right-click: the page gets contextmenu (custom context menus open); cannot be combined with --double',
+    },
+    'hover:--no-wait': {
+        default: 'Waits for network stability after moving the mouse (menus may load content)',
+        whenDisabled: 'Returns immediately without waiting for network',
+        automaticBehavior: 'The mouse stays over the element afterwards, so hover menus stay open until the next mouse action',
+    },
+    'navigate:--no-wait': {
+        default: 'Waits until the new page has loaded and the network and DOM are idle (up to 15 s)',
+        whenDisabled: 'Returns as soon as the navigation has started',
+        automaticBehavior: 'Also applies to page reload/back/forward; indices from earlier queries become stale (87)',
     },
     'pressKey:--no-wait': {
         default: 'Waits for network stability after key press (200ms idle)',
@@ -105,6 +129,12 @@ const OPTION_BEHAVIORS = {
         default: 'Default network idle timeout',
         whenEnabled: 'Custom network idle timeout in ms (use for slow APIs)',
     },
+    'listeners:--type': {
+        default: 'Lists listeners of every event type on the element, its ancestors (through open shadow roots), its document and window',
+        whenEnabled: 'Lists only these event types (comma-separated, case-sensitive like addEventListener)',
+        automaticBehavior: 'Listeners are grouped by type, nearest first; JSON line/column numbers are 0-based (human output shows them 1-based like DevTools). The Debugger domain is not enabled',
+        tokenImpact: 'Pages with many window/document listeners produce long lists; --type keeps the output short',
+    },
     'scroll:--down': {
         whenEnabled: 'Scrolls page down by specified pixel amount',
     },
@@ -157,23 +187,25 @@ const OPTION_BEHAVIORS = {
         default: 'Compact output (truncated URLs, no resource types)',
         whenEnabled: 'Verbose output with full URLs and resource types',
     },
+    'start:--all': {
+        default: 'Tracking/analytics requests and console noise are filtered; bodies of binary responses (images, fonts) are not captured',
+        whenEnabled: 'Everything is captured, including binary response bodies (base64, flagged by responseBodyBase64, within --max-body-size)',
+        tokenImpact: 'details network --json and HAR exports can grow considerably on media-heavy pages',
+    },
     'peek:--verbose': {
         default: 'Compact output (truncated URLs, no resource types)',
         whenEnabled: 'Verbose output with full URLs and resource types',
     },
-    'peek:--dom': {
-        automaticBehavior: 'DOM data only available after session stops. During live session shows "(none)".',
-    },
-    'cleanup:--force': {
-        default: 'Only cleans up if session process is dead',
-        whenEnabled: 'Forces cleanup even if session appears active (use when stuck)',
+    'cleanup:-f': {
+        default: 'Refuses to run while a session is active; removes files left by a crashed session',
+        whenEnabled: 'Kills the running daemon and its Chrome first (use when a session is stuck)',
     },
     'cleanup:--aggressive': {
-        whenEnabled: 'Kills ALL Chrome processes on system (uses chrome-launcher killAll). Use with caution!',
+        whenEnabled: 'Alias for --force, kept for compatibility',
     },
     'stop:--kill-chrome': {
-        default: 'Stops session but leaves Chrome running for potential reconnection',
-        whenEnabled: 'Stops session AND terminates the Chrome browser process',
+        default: 'Chrome launched by bdg is always closed on stop; an attached Chrome (--chrome-ws-url) is left running',
+        whenEnabled: 'No additional effect; kept for compatibility',
     },
     'status:-v': {
         default: 'Basic session status (daemon running, session active, URL)',
@@ -207,15 +239,4 @@ export function getOptionBehavior(commandName, flags) {
     const key = buildKey(commandName, flags);
     return OPTION_BEHAVIORS[key];
 }
-/**
- * Check if an option has registered behavioral metadata.
- *
- * @param commandName - Name of the command containing the option
- * @param flags - Option flags string from Commander
- * @returns True if behavior metadata exists
- */
-export function hasOptionBehavior(commandName, flags) {
-    const key = buildKey(commandName, flags);
-    return key in OPTION_BEHAVIORS;
-}
 //# sourceMappingURL=optionBehaviors.js.map

package/dist/commands/page.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `bdg page navigate|reload|back|forward` — move the session's page.
+ */
+import type { Command } from 'commander';
+/**
+ * Register the `page` command group.
+ *
+ * @param program - Root command
+ */
+export declare function registerPageCommands(program: Command): void;
+//# sourceMappingURL=page.d.ts.map

package/dist/commands/page.js

@@ -0,0 +1,112 @@
+/**
+ * `bdg page navigate|reload|back|forward` — move the session's page.
+ */
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
+import { javascriptNavigationError } from '../errors/messages.js';
+import { pageNavigate } from '../ipc/client.js';
+import { OutputFormatter } from '../ui/formatting.js';
+import { PAGE_ACTION_DESCRIPTIONS, PAGE_ACTION_DONE } from '../ui/messages/commands.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
+import { validateUrl } from '../utils/url.js';
+/**
+ * Human-readable result.
+ *
+ * @param result - Page after the action
+ * @returns Text
+ */
+function formatPageResult(result) {
+    const fmt = new OutputFormatter()
+        .text(`✓ ${PAGE_ACTION_DONE[result.action]}`)
+        .keyValueList([
+        ['URL', result.url],
+        ['Title', result.title],
+        ...(result.status !== undefined
+            ? [['Status', String(result.status)]]
+            : []),
+    ], 8);
+    if (result.warning)
+        fmt.text(`⚠ ${result.warning}`);
+    return fmt.build();
+}
+/**
+ * Whether a URL is a `javascript:` URL, which runs a script instead of
+ * loading a page (bdg points to `dom eval`; other schemes load normally).
+ *
+ * @param url - URL given
+ * @returns True for the javascript scheme
+ */
+function isScriptUrl(url) {
+    const [scheme = ''] = url.trim().split(':', 1);
+    return url.includes(':') && scheme.toLowerCase() === 'javascript';
+}
+/**
+ * Run a page action through the daemon.
+ *
+ * @param action - What to do
+ * @param options - Command options
+ * @param url - URL for navigate
+ */
+async function runPageAction(action, options, url) {
+    await runCommand(async () => {
+        if (url !== undefined && isScriptUrl(url)) {
+            const err = javascriptNavigationError();
+            return {
+                success: false,
+                error: err.message,
+                exitCode: EXIT_CODES.INVALID_URL,
+                errorContext: { suggestion: err.suggestion },
+            };
+        }
+        if (url !== undefined) {
+            const check = validateUrl(url);
+            if (!check.valid) {
+                return {
+                    success: false,
+                    error: check.error,
+                    exitCode: EXIT_CODES.INVALID_URL,
+                    ...(check.suggestion && { errorContext: { suggestion: check.suggestion } }),
+                };
+            }
+        }
+        const response = await pageNavigate({
+            action,
+            ...(url !== undefined && { url }),
+            wait: options.wait !== false,
+        });
+        if (response.status === 'error' || !response.data) {
+            return {
+                success: false,
+                error: response.error ?? `Failed to ${action}`,
+                exitCode: response.exitCode ?? EXIT_CODES.SOFTWARE_ERROR,
+                ...(response.suggestion && { errorContext: { suggestion: response.suggestion } }),
+            };
+        }
+        return { success: true, data: response.data };
+    }, options, formatPageResult);
+}
+/**
+ * Register the `page` command group.
+ *
+ * @param program - Root command
+ */
+export function registerPageCommands(program) {
+    const page = program
+        .command('page')
+        .description('Navigate the session page: navigate <url>, reload, back, forward');
+    const withCommon = (command) => command
+        .option('--no-wait', 'Return without waiting for the page to load')
+        .addOption(jsonOption());
+    withCommon(page
+        .command('navigate')
+        .description('Load a URL in the session page')
+        .argument('<url>', 'URL to load')).action(async (url, options) => {
+        await runPageAction('navigate', options, url);
+    });
+    for (const action of ['reload', 'back', 'forward']) {
+        withCommon(page.command(action).description(PAGE_ACTION_DESCRIPTIONS[action])).action(async (options) => {
+            await runPageAction(action, options);
+        });
+    }
+}
+//# sourceMappingURL=page.js.map

package/dist/commands/peek.js

@@ -1,59 +1,67 @@
 /**
  * Peek command for previewing collected session data.
  */
-import { runCommand } from '../commands/shared/CommandRunner.js';
-import { jsonOption } from '../commands/shared/commonOptions.js';
-import { handleDaemonConnectionError } from '../commands/shared/daemonErrorHandler.js';
-import { fetchPreviewOutput, createErrorResult, } from '../commands/shared/dataFetcher.js';
-import { setupFollowMode } from '../commands/shared/followMode.js';
-import { positiveIntRule, resourceTypeRule } from '../commands/shared/validation.js';
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption, showBothSectionsWhenBothRequested } from './shared/commonOptions.js';
+import { handleDaemonConnectionError, noteFollowConnected, } from './shared/daemonErrorHandler.js';
+import { fetchPreviewOutput, createErrorResult, } from './shared/dataFetcher.js';
+import { setupFollowMode } from './shared/followMode.js';
+import { handleValidationError } from './shared/handleValidationError.js';
+import { MAX_LAST_ITEMS, positiveIntRule, resourceTypeRule } from './shared/validation.js';
 import { filterByResourceType } from '../telemetry/filters.js';
-import { OutputBuilder } from '../ui/OutputBuilder.js';
-import { CommandError } from '../ui/errors/index.js';
-import { formatPreview } from '../ui/formatters/preview.js';
+import { buildPreviewJsonData, 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 lastN = positiveIntRule({ min: 1, max: 1000, default: 10 }).validate(options.last);
+    const lastN = positiveIntRule({
+        name: '--last',
+        min: 1,
+        max: MAX_LAST_ITEMS,
+        default: 10,
+        allowZeroForAll: true,
+    }).validate(options.last);
     const resourceTypes = resourceTypeRule().validate(options.type);
     return { lastN, resourceTypes };
 }
-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);
+/**
+ * Data section selected by `--network` / `--console`, if any.
+ *
+ * @param options - Peek options
+ * @returns Section to fetch, or undefined for both
+ */
+function peekSection(options) {
+    if (options.network)
+        return 'network';
+    return options.console ? 'console' : undefined;
 }
-async function fetchAndFilterPreview(lastN, resourceTypes) {
-    const result = await fetchPreviewOutput(lastN);
+/**
+ * Fetch the preview, filtering network requests by resource type first.
+ *
+ * With a type filter all requests are fetched and filtered before the
+ * `--last` window is applied, so older matches are not hidden by newer
+ * requests of other types.
+ *
+ * @param lastN - Items to show (0 = all)
+ * @param resourceTypes - Resource types to keep (empty = all)
+ * @param only - Fetch only network or only console data
+ * @returns Preview with filtered network data and the unfiltered request count
+ */
+async function fetchAndFilterPreview(lastN, resourceTypes, only) {
+    const result = await fetchPreviewOutput({
+        lastN: resourceTypes.length > 0 ? 0 : lastN,
+        ...(only && { only }),
+    });
     if (!result.success)
         return result;
     const output = result.data;
-    const unfilteredNetworkCount = output.data.network?.length ?? 0;
-    if (resourceTypes.length === 0) {
+    const unfilteredNetworkCount = output.totals?.network ?? output.data.network?.length ?? 0;
+    if (resourceTypes.length === 0 || !output.data.network) {
         return { success: true, data: { output, unfilteredNetworkCount } };
     }
-    const filteredNetwork = output.data.network
-        ? filterByResourceType(output.data.network, resourceTypes)
-        : undefined;
+    const network = filterByResourceType(output.data.network, resourceTypes);
     const filteredOutput = {
         ...output,
-        data: { ...output.data, ...(filteredNetwork && { network: filteredNetwork }) },
+        data: { ...output.data, network },
+        ...(output.totals && { totals: { ...output.totals, network: network.length } }),
     };
     return { success: true, data: { output: filteredOutput, unfilteredNetworkCount } };
 }
@@ -69,7 +77,7 @@ function createPreviewOptions(base, resourceTypes, unfilteredCount) {
 }
 async function runFollowMode(options, lastN, resourceTypes, baseOptions) {
     const showPreview = async () => {
-        const result = await fetchAndFilterPreview(lastN, resourceTypes);
+        const result = await fetchAndFilterPreview(lastN, resourceTypes, peekSection(options));
         if (!result.success) {
             const errorResult = handleDaemonConnectionError(result.error, {
                 json: options.json,
@@ -81,7 +89,9 @@ async function runFollowMode(options, lastN, resourceTypes, baseOptions) {
                 process.exit(errorResult.exitCode);
             return;
         }
-        console.clear();
+        noteFollowConnected();
+        if (!options.json)
+            console.clear();
         const previewOptions = createPreviewOptions(baseOptions, resourceTypes, result.data.unfilteredNetworkCount);
         console.log(formatPreview(result.data.output, previewOptions));
     };
@@ -99,11 +109,11 @@ export function registerPeekCommand(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('-d, --dom', 'Show DOM/A11y tree data', false)
         .option('-f, --follow', 'Watch for updates (like tail -f)', false)
-        .option('--last <count>', 'Show last N items (default: 10)', '10')
+        .option('--last <count>', 'Show last N items, 0 for all', '10')
         .option('--type <types>', 'Filter network requests by resource type (comma-separated: Document,XHR,Fetch,etc.)')
         .action(async (options) => {
+        showBothSectionsWhenBothRequested(options);
         if (options.network && !options.json) {
             console.error('Note: "bdg peek --network" is deprecated. Use "bdg network list" for enhanced filtering.');
         }
@@ -121,7 +131,6 @@ export function registerPeekCommand(program) {
             json: options.json,
             network: options.network,
             console: options.console,
-            dom: options.dom,
             last: lastN,
             verbose: options.verbose,
             follow: options.follow,
@@ -131,12 +140,17 @@ export function registerPeekCommand(program) {
             return;
         }
         await runCommand(async () => {
-            const result = await fetchAndFilterPreview(lastN, resourceTypes);
+            const result = await fetchAndFilterPreview(lastN, resourceTypes, peekSection(options));
             if (!result.success) {
-                return createErrorResult(result.error, result.exitCode);
+                return createErrorResult(result.error, result.exitCode, result.suggestion);
             }
-            return { success: true, data: result.data.output };
-        }, options, (output) => {
+            const { output } = result.data;
+            return {
+                success: true,
+                data: options.json ? buildPreviewJsonData(output, baseOptions) : output,
+            };
+        }, options, (data) => {
+            const output = data;
             const previewOptions = createPreviewOptions(baseOptions, resourceTypes, output.data.network?.length ?? 0);
             return formatPreview(output, previewOptions);
         });

package/dist/commands/shared/CommandRunner.d.ts

@@ -1,5 +1,13 @@
-import { type BaseOptions } from '../../commands/shared/optionTypes.js';
+import { type BaseOptions } from './optionTypes.js';
+import { CommandError } from '../../errors/index.js';
+import { IPCTimeoutError } from '../../ipc/transport/IPCError.js';
 export type { BaseOptions };
+/**
+ * The error every command gives when there is no session to talk to.
+ *
+ * @returns Command error (exit 83) with how to start one
+ */
+export declare function noActiveSessionError(): CommandError;
 /**
  * Execute an async function and output JSON result with proper error handling.
  *
@@ -49,6 +57,15 @@ export type CommandHandler<TOptions extends BaseOptions, TResult = unknown> = (o
  * @returns Formatted string to be output to console
  */
 export type CommandFormatter<TResult = unknown> = (data: TResult) => string;
+/**
+ * An IPC timeout as a user-facing error (exit 102): a quick request (status,
+ * peek, the handshake before page work) means the session is not responding;
+ * a long one means the command itself did not finish.
+ *
+ * @param error - IPC timeout
+ * @returns Command error with a way out
+ */
+export declare function timeoutError(error: IPCTimeoutError): CommandError;
 /**
  * Run a command with consistent error handling, output formatting, and exit codes.
  * Eliminates boilerplate try-catch and JSON output logic from command handlers.

package/dist/commands/shared/CommandRunner.js

@@ -1,8 +1,20 @@
-import { OutputBuilder } from '../../ui/OutputBuilder.js';
-import { CommandError, isDaemonConnectionError } from '../../ui/errors/index.js';
-import { daemonNotRunningError, unknownError, genericError } from '../../ui/messages/errors.js';
-import { getErrorMessage } from '../../utils/errors.js';
+import { getQuickIPCRequestTimeout } from '../../constants.js';
+import { CommandError, isDaemonConnectionError } from '../../errors/index.js';
+import { daemonNotRunningError, unknownError, genericError, commandTimedOutError, sessionNotRespondingError, sessionEndedDuringCommandError, } from '../../errors/messages.js';
+import { IPCEarlyCloseError, IPCTimeoutError } from '../../ipc/transport/IPCError.js';
+import { OutputBuilder, buildSuccessResponse } from '../../ui/OutputBuilder.js';
+import { escapeControlChars } from '../../ui/formatting.js';
+import { STOP_MESSAGES } from '../../ui/messages/session.js';
+import { getErrorExitCode, getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
+/**
+ * The error every command gives when there is no session to talk to.
+ *
+ * @returns Command error (exit 83) with how to start one
+ */
+export function noActiveSessionError() {
+    return new CommandError(STOP_MESSAGES.DAEMON_NOT_RUNNING, { suggestion: 'Start a session with: bdg <url>' }, EXIT_CODES.RESOURCE_NOT_FOUND);
+}
 /**
  * Execute an async function and output JSON result with proper error handling.
  *
@@ -24,15 +36,50 @@ import { EXIT_CODES } from '../../utils/exitCodes.js';
 export async function runJsonCommand(fn) {
     try {
         const data = await fn();
-        console.log(JSON.stringify(data, null, 2));
+        console.log(JSON.stringify(buildSuccessResponse(data), null, 2));
         process.exit(EXIT_CODES.SUCCESS);
     }
-    catch (error) {
-        const exitCode = error instanceof CommandError ? error.exitCode : EXIT_CODES.UNHANDLED_EXCEPTION;
-        console.log(JSON.stringify(OutputBuilder.buildJsonError(getErrorMessage(error)), null, 2));
+    catch (caught) {
+        const error = isDaemonConnectionError(caught)
+            ? noActiveSessionError()
+            : caught instanceof IPCTimeoutError
+                ? timeoutError(caught)
+                : caught;
+        const exitCode = getErrorExitCode(error, EXIT_CODES.UNHANDLED_EXCEPTION);
+        const suggestion = error instanceof CommandError && typeof error.metadata['suggestion'] === 'string'
+            ? error.metadata['suggestion']
+            : undefined;
+        console.log(JSON.stringify(OutputBuilder.buildJsonError(getErrorMessage(error), {
+            exitCode,
+            ...(suggestion && { suggestion }),
+        }), null, 2));
         process.exit(exitCode);
     }
 }
+/**
+ * An IPC timeout as a user-facing error (exit 102): a quick request (status,
+ * peek, the handshake before page work) means the session is not responding;
+ * a long one means the command itself did not finish.
+ *
+ * @param error - IPC timeout
+ * @returns Command error with a way out
+ */
+export function timeoutError(error) {
+    const seconds = error.timeoutMs / 1000;
+    const err = error.timeoutMs <= getQuickIPCRequestTimeout()
+        ? sessionNotRespondingError(seconds)
+        : commandTimedOutError(seconds);
+    return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.CDP_TIMEOUT);
+}
+/**
+ * The daemon closed the connection before answering: the session ended.
+ *
+ * @returns Command error (83)
+ */
+function sessionEndedError() {
+    const err = sessionEndedDuringCommandError();
+    return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+}
 /**
  * Run a command with consistent error handling, output formatting, and exit codes.
  * Eliminates boilerplate try-catch and JSON output logic from command handlers.
@@ -63,49 +110,57 @@ export async function runCommand(handler, options, formatter) {
     try {
         const result = await handler(options);
         if (!result.success) {
+            const exitCode = result.exitCode ?? EXIT_CODES.UNHANDLED_EXCEPTION;
             if (options.json) {
-                const errorData = {
-                    ...(result.exitCode !== undefined && { exitCode: result.exitCode }),
+                console.log(JSON.stringify(OutputBuilder.buildJsonError(result.error ?? 'Unknown error', {
                     ...result.errorContext,
-                };
-                console.log(JSON.stringify(OutputBuilder.buildJsonError(result.error ?? 'Unknown error', errorData), null, 2));
+                    exitCode,
+                }), null, 2));
             }
             else {
                 console.error(result.error ? genericError(result.error) : unknownError());
                 if (result.errorContext && typeof result.errorContext === 'object') {
                     for (const value of Object.values(result.errorContext)) {
                         if (value !== undefined && value !== null) {
-                            console.error(typeof value === 'string' ? value : JSON.stringify(value));
+                            console.error(escapeControlChars(typeof value === 'string' ? value : JSON.stringify(value)));
                         }
                     }
                 }
             }
-            process.exit(result.exitCode ?? EXIT_CODES.UNHANDLED_EXCEPTION);
+            process.exit(exitCode);
         }
-        if (result.hint) {
-            console.error(result.hint);
+        if (result.hint && !options.quiet) {
+            console.error(escapeControlChars(result.hint));
         }
         if (options.json) {
-            console.log(JSON.stringify(result.data, null, 2));
+            console.log(JSON.stringify(buildSuccessResponse(result.data), null, 2));
         }
         else if (formatter) {
             const formattedOutput = formatter(result.data);
-            console.log(formattedOutput);
+            console.log(escapeControlChars(formattedOutput));
         }
         else {
-            console.log(JSON.stringify(result.data, null, 2));
+            console.log(JSON.stringify(buildSuccessResponse(result.data), null, 2));
         }
         process.exit(EXIT_CODES.SUCCESS);
     }
-    catch (error) {
+    catch (caught) {
+        const error = caught instanceof IPCTimeoutError
+            ? timeoutError(caught)
+            : caught instanceof IPCEarlyCloseError
+                ? sessionEndedError()
+                : caught;
         if (error instanceof CommandError) {
             if (options.json) {
-                console.log(JSON.stringify(OutputBuilder.buildJsonError(error.message, error.metadata), null, 2));
+                console.log(JSON.stringify(OutputBuilder.buildJsonError(error.message, {
+                    ...error.metadata,
+                    exitCode: error.exitCode,
+                }), null, 2));
             }
             else {
                 console.error(genericError(error.message));
                 for (const value of Object.values(error.metadata)) {
-                    console.error(value);
+                    console.error(escapeControlChars(String(value)));
                 }
             }
             process.exit(error.exitCode);
@@ -113,8 +168,9 @@ export async function runCommand(handler, options, formatter) {
         const errorMessage = getErrorMessage(error);
         if (isDaemonConnectionError(error)) {
             if (options.json) {
-                console.log(JSON.stringify(OutputBuilder.buildJsonError('Daemon not running', {
-                    suggestion: 'Start it with: bdg <url>',
+                console.log(JSON.stringify(OutputBuilder.buildJsonError(STOP_MESSAGES.DAEMON_NOT_RUNNING, {
+                    suggestion: 'Start a session with: bdg <url>',
+                    exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                 }), null, 2));
             }
             else {
@@ -122,13 +178,14 @@ export async function runCommand(handler, options, formatter) {
             }
             process.exit(EXIT_CODES.RESOURCE_NOT_FOUND);
         }
+        const exitCode = getErrorExitCode(error, EXIT_CODES.UNHANDLED_EXCEPTION);
         if (options.json) {
-            console.log(JSON.stringify(OutputBuilder.buildJsonError(errorMessage), null, 2));
+            console.log(JSON.stringify(OutputBuilder.buildJsonError(errorMessage, { exitCode }), null, 2));
         }
         else {
             console.error(genericError(errorMessage));
         }
-        process.exit(EXIT_CODES.UNHANDLED_EXCEPTION);
+        process.exit(exitCode);
     }
 }
 //# sourceMappingURL=CommandRunner.js.map

package/dist/commands/shared/commonOptions.d.ts

@@ -20,4 +20,14 @@ import { Option } from 'commander';
  * ```
  */
 export declare function jsonOption(): Option;
+/**
+ * `--network` together with `--console` asks for both sections, which is what
+ * neither flag shows; clear both so the output is not empty.
+ *
+ * @param options - Parsed `peek`/`tail` options (changed in place)
+ */
+export declare function showBothSectionsWhenBothRequested(options: {
+    network?: boolean;
+    console?: boolean;
+}): void;
 //# sourceMappingURL=commonOptions.d.ts.map