browser-debugger-cli 0.14.0 → 0.16.0

package/dist/ui/formatters/sessions.js

@@ -1,10 +1,11 @@
 import { OutputFormatter } from '../formatting.js';
-import { endedSessionText } from '../messages/session.js';
+import { endedSessionText, untrustedSessionText } from '../messages/session.js';
 /** Label of the default session in the list */
 const DEFAULT_SESSION_LABEL = '(default)';
 /**
- * Format the sessions as a table, followed by why ended sessions ended and
- * the cleanup commands of crashed and stale sessions.
+ * Format the sessions as a table, followed by why ended sessions ended, why
+ * untrusted sessions' directories are not safe to use, and the cleanup
+ * commands of crashed and stale sessions.
  *
  * @param data - Sessions
  * @returns Human-readable list
@@ -38,6 +39,12 @@ export function formatSessionList(data) {
     if (ended.length > 0) {
         fmt.blank().section('Ended without bdg stop:', ended);
     }
+    const untrusted = data.sessions.flatMap(({ name, untrusted: why }) => why ? [untrustedSessionText(name ?? DEFAULT_SESSION_LABEL, why)] : []);
+    if (untrusted.length > 0) {
+        fmt
+            .blank()
+            .section('Directory not safe to use (not asked; bdg status --session <name> says how to fix it):', untrusted);
+    }
     const cleanups = data.sessions.flatMap((session) => (session.cleanup ? [session.cleanup] : []));
     if (cleanups.length > 0) {
         fmt.hints('Crashed or stale sessions; clean up with:', cleanups);

package/dist/ui/formatters/status.js

@@ -1,7 +1,7 @@
 import { describeRunningChrome } from '../../session/chrome.js';
 import { calculateDuration, formatTimeAgo } from '../../session/statusData.js';
 import { OutputFormatter } from '../formatting.js';
-import { colorSchemeLabel, sessionActiveLine } from '../messages/commands.js';
+import { colorSchemeLabel, downloadsSummary, sessionActiveLine } from '../messages/commands.js';
 import { networkEvictedNote } from '../messages/networkMessages.js';
 import { lastSessionEndText } from '../messages/session.js';
 import { noActiveSessionMessage, sessionCommand } from '../messages/sessionCommand.js';
@@ -62,6 +62,11 @@ export function formatSessionStatus(metadata, pid, activity, pageState, verbose
         if (activity.lastConsoleMessageAt) {
             fmt.keyValue('  Last Message', formatTimeAgo(activity.lastConsoleMessageAt), 18);
         }
+        const downloadRows = [
+            ...(activity.downloads?.length ? [downloadsSummary(activity.downloads)] : []),
+            ...(activity.downloadsWarning ? [`⚠ ${activity.downloadsWarning}`] : []),
+        ];
+        downloadRows.forEach((row, index) => index === 0 ? fmt.keyValue('Downloads', row, 18) : fmt.text(`${' '.repeat(18)}${row}`));
     }
     fmt.blank().text('Collectors').separator('━', 50);
     const activeTelemetry = metadata.activeTelemetry ?? ['network', 'console', 'dom'];

package/dist/ui/formatting.d.ts

@@ -83,4 +83,11 @@ export declare function truncateUrl(url: string, maxLength?: number): string;
 export declare function cutMiddle(text: string, maxLength: number): string;
 export declare function pluralize(count: number, singular: string, plural?: string): string;
 export declare function formatDuration(ms: number): string;
+/**
+ * Format a byte count for humans.
+ *
+ * @param bytes - Byte count
+ * @returns e.g. "512 B", "12.3 KB"
+ */
+export declare function formatBytes(bytes: number): string;
 //# sourceMappingURL=formatting.d.ts.map

package/dist/ui/formatting.js

@@ -216,4 +216,17 @@ export function formatDuration(ms) {
     }
     return `${ms}ms`;
 }
+/**
+ * Format a byte count for humans.
+ *
+ * @param bytes - Byte count
+ * @returns e.g. "512 B", "12.3 KB"
+ */
+export function formatBytes(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    return bytes < 1024 * 1024
+        ? `${(bytes / 1024).toFixed(1)} KB`
+        : `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
 //# sourceMappingURL=formatting.js.map

package/dist/ui/logging/logger.d.ts

@@ -29,7 +29,7 @@ export type LogLevel = 'info' | 'debug';
  * Log contexts for different components.
  * Used to prefix log messages with component name.
  */
-export type LogContext = 'bdg' | 'launcher' | 'daemon' | 'client' | 'cleanup' | 'session' | 'chrome' | 'cdp' | 'ipc' | 'http' | 'dialogs' | 'navigation' | 'page-crash' | 'console' | 'dom' | 'network' | 'diagnostics' | 'readiness' | 'atomic-file' | 'object-expander' | 'fetcher' | 'targets';
+export type LogContext = 'bdg' | 'launcher' | 'daemon' | 'client' | 'cleanup' | 'session' | 'chrome' | 'cdp' | 'ipc' | 'http' | 'dialogs' | 'downloads' | 'navigation' | 'page-crash' | 'console' | 'dom' | 'network' | 'diagnostics' | 'readiness' | 'atomic-file' | 'object-expander' | 'fetcher' | 'targets';
 /**
  * Logger instance with support for different log levels.
  */

package/dist/ui/messages/chrome.d.ts

@@ -20,8 +20,14 @@ export declare function formatChromeNotice(notice: NoticeDetails<ChromeNoticeCod
  * Called at the UI boundary when a ChromeLaunchError with `issue` details
  * reaches a CLI or daemon log sink. Core modules produce the IssueDetails;
  * this function is the only place wording is assembled.
+ *
+ * @param issue - Structured issue
+ * @param diagnostics - Source of Chrome installation diagnostics (tests stub it)
+ * @returns User-facing message
  */
-export declare function formatChromeIssue(issue: IssueDetails): string;
+export declare function formatChromeIssue(issue: IssueDetails, diagnostics?: () => ChromeDiagnostics): string;
+/** Chrome's launch ended because the session was stopped meanwhile */
+export declare const CHROME_LAUNCH_ABORTED_MESSAGE = "Chrome launch aborted: the session was stopped";
 /**
  * Chrome exited before its debugging port opened.
  *
@@ -33,15 +39,19 @@ export declare function formatChromeIssue(issue: IssueDetails): string;
  */
 export declare function chromeExitedDuringStartupError(exitCode: number | null, output: string[], userDataDir: string, profileInUse: boolean): string;
 /**
- * Retrieve Chrome diagnostics and format for error messages.
- *
- * @returns Array of formatted diagnostic strings
+ * Options of {@link formatDiagnosticsForError}.
  */
-export declare function getFormattedDiagnostics(): string[];
+export interface DiagnosticsFormatOptions {
+    /** OS the CHROME_PATH example is for (default: this one) */
+    platform?: NodeJS.Platform;
+    /** Suggest CHROME_PATH when no Chrome is found (off when CHROME_PATH is the problem) */
+    suggestChromePath?: boolean;
+}
 /**
  * Format Chrome diagnostics for error reporting when Chrome launch fails.
  *
  * @param diagnostics - Chrome diagnostics information
+ * @param options - Platform of the example and whether to suggest CHROME_PATH
  * @returns Formatted error message lines with troubleshooting steps
  *
  * @example
@@ -51,7 +61,7 @@ export declare function getFormattedDiagnostics(): string[];
  * console.error(errorLines.join('\n'));
  * ```
  */
-export declare function formatDiagnosticsForError(diagnostics: ChromeDiagnostics): string[];
+export declare function formatDiagnosticsForError(diagnostics: ChromeDiagnostics, { platform, suggestChromePath }?: DiagnosticsFormatOptions): string[];
 /**
  * Generate invalid port error message.
  *
@@ -180,6 +190,17 @@ export declare function portTakenByReason(answeredBy: 'browser' | 'process' | 'n
  * @returns Reason for the CHROME_LAUNCH_FAILED issue
  */
 export declare function chromeNotAnsweringReason(port: number, waitedMs: number): string;
+/**
+ * Chrome is running but did not open its debugging port within
+ * chrome-launcher's readiness budget (a slow start, not a crash or a port
+ * conflict: nothing answered on the port, which was free before the launch).
+ *
+ * @param pid - Chrome's PID
+ * @param port - Debugging port
+ * @param waitedMs - The readiness budget
+ * @returns Error message
+ */
+export declare function chromePortNotOpenedMessage(pid: number, port: number, waitedMs: number): string;
 /**
  * Warning when bdg's Chrome preferences (password manager and leak check
  * off, etc.) could not be written into the profile.

package/dist/ui/messages/chrome.js

@@ -32,8 +32,12 @@ export function formatChromeNotice(notice) {
  * Called at the UI boundary when a ChromeLaunchError with `issue` details
  * reaches a CLI or daemon log sink. Core modules produce the IssueDetails;
  * this function is the only place wording is assembled.
+ *
+ * @param issue - Structured issue
+ * @param diagnostics - Source of Chrome installation diagnostics (tests stub it)
+ * @returns User-facing message
  */
-export function formatChromeIssue(issue) {
+export function formatChromeIssue(issue, diagnostics = getChromeDiagnostics) {
     const ctx = issue.context ?? {};
     switch (issue.code) {
         case 'PORT_IN_USE':
@@ -52,16 +56,20 @@ export function formatChromeIssue(issue) {
                 : reason
                     ? chromeLaunchFailedError(reason)
                     : `Chrome failed to launch`;
-            const diagnostics = getFormattedDiagnostics();
-            return joinLines(header, '', 'Possible causes:', `  - Port ${port} conflict (check: lsof -ti:${port})`, `  - Chrome binary not found`, `  - Insufficient permissions`, `  - Chrome crashed on startup`, '', ...diagnostics, '', 'Try:', `  - ${sessionCommand('bdg cleanup')}`, `  - See what uses the port: lsof -i :${port}`, `  - Use different port: ${sessionCommand(`bdg <url> --port ${port + 1}`)}`, `  - In a container where Chrome's sandbox fails: BDG_NO_SANDBOX=1 ${sessionCommand('bdg <url>')}`);
+            const found = diagnostics();
+            const diagnosticLines = formatDiagnosticsForError(found);
+            if (noChromeFound(found))
+                return joinLines(header, '', ...diagnosticLines);
+            return joinLines(header, '', 'Possible causes:', `  - Port ${port} conflict (check: lsof -ti:${port})`, `  - Chrome binary not found`, `  - Insufficient permissions`, `  - Chrome crashed on startup`, '', ...diagnosticLines, '', 'Try:', `  - ${sessionCommand('bdg cleanup')}`, `  - See what uses the port: lsof -i :${port}`, `  - Use different port: ${sessionCommand(`bdg <url> --port ${port + 1}`)}`, `  - In a container where Chrome's sandbox fails: BDG_NO_SANDBOX=1 ${sessionCommand('bdg <url>')}`);
         }
+        case 'CHROME_PORT_NOT_OPENED':
+            return joinLines(chromePortNotOpenedMessage(ctx['pid'], ctx['port'], ctx['waitedMs']), chromePortNotOpenedSuggestion());
         case 'CHROME_EXITED_DURING_STARTUP':
             return chromeExitedDuringStartupError(ctx['exitCode'], ctx['output'] ?? [], ctx['userDataDir'], ctx['profileInUse'] === true);
         case 'NO_PAGE_TARGET_FOUND':
             return noPageTargetFoundError(ctx['port'], ctx['availableTargets']);
         case 'CHROME_BINARY_NOT_FOUND': {
-            const diagnostics = getFormattedDiagnostics();
-            return joinLines(chromeBinaryOverrideNotFound(ctx['chromePath'], ctx['source']), '', ...diagnostics);
+            return joinLines(chromeBinaryOverrideNotFound(ctx['chromePath'], ctx['source']), '', ...formatDiagnosticsForError(diagnostics(), { suggestChromePath: false }));
         }
         case 'CHROME_BINARY_IS_DIRECTORY':
             return chromeBinaryOverrideIsDirectory(ctx['chromePath'], ctx['source']);
@@ -80,6 +88,8 @@ export function formatChromeIssue(issue) {
             return `Chrome preferences must be JSON-serializable: ${ctx['reason'] ?? 'unknown error'}`;
     }
 }
+/** Chrome's launch ended because the session was stopped meanwhile */
+export const CHROME_LAUNCH_ABORTED_MESSAGE = 'Chrome launch aborted: the session was stopped';
 /**
  * Chrome exited before its debugging port opened.
  *
@@ -96,17 +106,49 @@ export function chromeExitedDuringStartupError(exitCode, output, userDataDir, pr
     return joinLines(`Chrome exited during startup (exit code ${exitCode ?? 'none'})`, ...(output.length > 0 ? ['Chrome said:', ...output.map((line) => `  ${line}`)] : []), 'Check --chrome-flags and BDG_CHROME_FLAGS (an unknown flag or value can stop Chrome)');
 }
 /**
- * Retrieve Chrome diagnostics and format for error messages.
+ * Whether no Chrome was found at all: no installation and no default binary
+ * (chrome-launcher's default honors a valid CHROME_PATH).
+ *
+ * @param diagnostics - Chrome diagnostics
+ * @returns True when there is nothing to launch
+ */
+function noChromeFound(diagnostics) {
+    return diagnostics.installationCount === 0 && !diagnostics.defaultPath;
+}
+/**
+ * A Chromium-based browser binary that chrome-launcher does not find on its
+ * own, as an example value for CHROME_PATH.
+ *
+ * @param platform - OS the path is for
+ * @returns Microsoft Edge's binary on macOS or Linux; none on other systems
+ */
+function exampleChromePath(platform) {
+    if (platform === 'darwin')
+        return '/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge';
+    if (platform === 'linux')
+        return '/usr/bin/microsoft-edge';
+    return undefined;
+}
+/**
+ * How to point bdg at another Chromium-based browser through CHROME_PATH.
  *
- * @returns Array of formatted diagnostic strings
+ * @param platform - OS the example is for
+ * @returns Message lines, with an example command where one is known
  */
-export function getFormattedDiagnostics() {
-    return formatDiagnosticsForError(getChromeDiagnostics());
+function chromePathSuggestion(platform) {
+    const example = exampleChromePath(platform);
+    if (!example)
+        return ['Set CHROME_PATH to a Chromium-based browser (Edge, Brave, Chromium)\n'];
+    return [
+        'Set CHROME_PATH to a Chromium-based browser (Edge, Brave, Chromium), e.g.:',
+        `   CHROME_PATH="${example}" ${sessionCommand('bdg <url>')}\n`,
+    ];
 }
 /**
  * Format Chrome diagnostics for error reporting when Chrome launch fails.
  *
  * @param diagnostics - Chrome diagnostics information
+ * @param options - Platform of the example and whether to suggest CHROME_PATH
  * @returns Formatted error message lines with troubleshooting steps
  *
  * @example
@@ -116,11 +158,13 @@ export function getFormattedDiagnostics() {
  * console.error(errorLines.join('\n'));
  * ```
  */
-export function formatDiagnosticsForError(diagnostics) {
+export function formatDiagnosticsForError(diagnostics, { platform = process.platform, suggestChromePath = true } = {}) {
     const lines = [];
-    if (diagnostics.installationCount === 0) {
+    if (noChromeFound(diagnostics)) {
         lines.push('Error: No Chrome installations detected\n');
-        lines.push('Install Chrome from:');
+        if (suggestChromePath)
+            lines.push(...chromePathSuggestion(platform));
+        lines.push(suggestChromePath ? 'Or install Chrome from:' : 'Install Chrome from:');
         lines.push('   https://www.google.com/chrome/\n');
     }
     else {
@@ -305,6 +349,28 @@ export function portTakenByReason(answeredBy, chromeHost) {
 export function chromeNotAnsweringReason(port, waitedMs) {
     return `Chrome announced port ${port} but did not answer on 127.0.0.1 within ${(waitedMs / 1000).toFixed(1)}s (slow start)`;
 }
+/**
+ * Chrome is running but did not open its debugging port within
+ * chrome-launcher's readiness budget (a slow start, not a crash or a port
+ * conflict: nothing answered on the port, which was free before the launch).
+ *
+ * @param pid - Chrome's PID
+ * @param port - Debugging port
+ * @param waitedMs - The readiness budget
+ * @returns Error message
+ */
+export function chromePortNotOpenedMessage(pid, port, waitedMs) {
+    return `Chrome started (pid ${pid}) but did not open its debugging port ${port} within ${Number((waitedMs / 1000).toFixed(1))} s`;
+}
+/**
+ * What to do when Chrome started but did not open its debugging port in time.
+ *
+ * @returns Suggestion
+ */
+function chromePortNotOpenedSuggestion() {
+    return (`Retry: ${sessionCommand('bdg <url>')} (a first start on a cold machine can be slow). ` +
+        `If it keeps failing: ${sessionCommand('bdg cleanup')} && ${sessionCommand('bdg <url>')}`);
+}
 /**
  * Warning when bdg's Chrome preferences (password manager and leak check
  * off, etc.) could not be written into the profile.

package/dist/ui/messages/commands.d.ts

@@ -5,7 +5,7 @@
  * cleaning up stale files, and validating command arguments.
  */
 import type { DomFrame, PageLoadingState, PendingRequestInfo } from '../../ipc/protocol/commands.js';
-import type { ElementLayout, FillValueMismatch, LayoutSize, NewMessage, PageLayout, PageNavigation, PendingChanges, ShownElement } from '../../ipc/protocol/domTypes.js';
+import type { DownloadInfo, ElementLayout, FillValueMismatch, LayoutSize, NewMessage, PageLayout, PageNavigation, PendingChanges, ShownElement } from '../../ipc/protocol/domTypes.js';
 import type { InspectVisibility } from '../../ipc/protocol/inspectTypes.js';
 import type { DelegationNote } from '../../runtime/dom/listenerSummary.js';
 import type { WaitCondition, WaitSnapshot } from '../../runtime/dom/waitCondition.js';
@@ -40,6 +40,34 @@ export declare function skillBackupMessage(path: string): string;
 export declare function domClickFallbackWarning(reason: string | null | undefined): string;
 /** Reason of a `bdg dom form` blocker for a required field left empty */
 export declare const REQUIRED_FIELD_EMPTY_REASON = "Required field is empty";
+/**
+ * Warning for a `bdg cdp` method the bundled protocol lacks, sent anyway.
+ *
+ * @param method - Method sent
+ * @param protocolVersion - Bundled devtools-protocol version
+ * @returns Warning text
+ */
+export declare function cdpUnlistedMethodWarning(method: string, protocolVersion: string): string;
+/**
+ * `bdg cdp --describe` line for a redirect to a method the protocol lacks
+ * (e.g. Page.deleteCookie names Network.deleteCookie).
+ *
+ * @param method - Redirect target
+ * @returns Line text
+ */
+export declare function cdpUnresolvedRedirectLine(method: string): string;
+/**
+ * `bdg cdp --describe` title of a redirect to a method the protocol has.
+ *
+ * @param method - Redirect target
+ * @returns Title text
+ */
+export declare function cdpRedirectTitle(method: string): string;
+/**
+ * Lines of `bdg cdp --help` saying how names are matched (each short
+ * enough not to be wrapped).
+ */
+export declare const CDP_EXECUTION_HELP: string;
 /**
  * Part of the `bdg dom form` summary naming the required fields left empty.
  *
@@ -101,6 +129,38 @@ export declare function shownElementText(element: ShownElement): string;
  *   "URL changed to https://example.com/#/active (same document)"
  */
 export declare function pageNavigationText(navigation: PageNavigation): string;
+/**
+ * A download an action started, as its output line reads.
+ *
+ * @param download - Download
+ * @returns e.g. `Download: report.txt → /Users/me/.bdg/downloads/report.txt (completed, 15 B)`,
+ *   `Download: big.zip → … (inProgress, 9.8 KB so far)` (no size before the first
+ *   bytes), `Download: report.txt (canceled)`
+ */
+export declare function downloadText(download: DownloadInfo): string;
+/**
+ * The session's downloads in one line: how many, and the last one.
+ *
+ * @param downloads - Downloads, oldest first (at least one)
+ * @returns e.g. `2 (last: report.txt → /Users/me/.bdg/downloads/report.txt, completed)`
+ */
+export declare function downloadsSummary(downloads: DownloadInfo[]): string;
+/**
+ * Warning while Chrome did not take bdg's download behavior, so downloads
+ * are not saved in the session directory.
+ *
+ * @param detail - Chrome's error
+ * @returns Warning shown by `bdg status`
+ */
+export declare function downloadsNotRedirectedWarning(detail: string): string;
+/**
+ * Why downloads are refused when the session's downloads directory could not
+ * be created.
+ *
+ * @param detail - What went wrong, e.g. `/home/me/.bdg/downloads is a file`
+ * @returns Reason recorded on each refused download
+ */
+export declare function downloadsDirUnavailableReason(detail: string): string;
 /**
  * Last `New text:` row when an action made more messages appear than are listed.
  *
@@ -748,9 +808,17 @@ export declare function sessionFilesCleanedMessage(): string;
  */
 export declare function sessionOutputRemovedMessage(): string;
 /**
- * Generate session directory clean message.
+ * Cleanup left the session's downloaded files in place.
  *
- * @returns Formatted success message
+ * @param dir - Downloads directory
+ * @param files - Files in it
+ * @returns e.g. `Downloads kept: 2 files in /Users/me/.bdg/downloads (delete them yourself when done)`
+ */
+export declare function downloadsKeptMessage(dir: string, files: number): string;
+/**
+ * Cleanup finished and left nothing behind.
+ *
+ * @returns Message
  */
 export declare function sessionDirectoryCleanMessage(): string;
 /**

package/dist/ui/messages/commands.js

@@ -5,7 +5,7 @@
  * cleaning up stale files, and validating command arguments.
  */
 import { buildAgentDiscoveryHelp, buildCommonTaskExamples, buildUrlExamples, buildSessionManagementReminder, } from '../formatters/helpFormatters.js';
-import { formatDuration, joinLines, pluralize, truncateUrl } from '../formatting.js';
+import { formatBytes, formatDuration, joinLines, pluralize, truncateUrl } from '../formatting.js';
 import { sessionCommand } from './sessionCommand.js';
 import { truncateByLength } from '../../utils/strings.js';
 /**
@@ -60,6 +60,41 @@ function fieldLabelList(labels) {
         .join(', ');
     return labels.length > 5 ? `${shown} and ${labels.length - 5} more` : shown;
 }
+/**
+ * Warning for a `bdg cdp` method the bundled protocol lacks, sent anyway.
+ *
+ * @param method - Method sent
+ * @param protocolVersion - Bundled devtools-protocol version
+ * @returns Warning text
+ */
+export function cdpUnlistedMethodWarning(method, protocolVersion) {
+    return `${method} is not in the bundled protocol (devtools-protocol ${protocolVersion}); sending it to Chrome as is`;
+}
+/**
+ * `bdg cdp --describe` line for a redirect to a method the protocol lacks
+ * (e.g. Page.deleteCookie names Network.deleteCookie).
+ *
+ * @param method - Redirect target
+ * @returns Line text
+ */
+export function cdpUnresolvedRedirectLine(method) {
+    return `Redirect target ${method} is not in the protocol (unresolved redirect)`;
+}
+/**
+ * `bdg cdp --describe` title of a redirect to a method the protocol has.
+ *
+ * @param method - Redirect target
+ * @returns Title text
+ */
+export function cdpRedirectTitle(method) {
+    return `Implemented by ${method} (redirect)`;
+}
+/**
+ * Lines of `bdg cdp --help` saying how names are matched (each short
+ * enough not to be wrapped).
+ */
+export const CDP_EXECUTION_HELP = '  Execution: bundled methods are case-insensitive (network.getcookies works)\n' +
+    '  Other methods are sent as typed (case-sensitive)';
 /**
  * Part of the `bdg dom form` summary naming the required fields left empty.
  *
@@ -145,6 +180,56 @@ export function pageNavigationText(navigation) {
     const status = navigation.status === undefined ? '' : ` (${navigation.status})`;
     return `navigated to ${navigation.url}${status}`;
 }
+/**
+ * A download an action started, as its output line reads.
+ *
+ * @param download - Download
+ * @returns e.g. `Download: report.txt → /Users/me/.bdg/downloads/report.txt (completed, 15 B)`,
+ *   `Download: big.zip → … (inProgress, 9.8 KB so far)` (no size before the first
+ *   bytes), `Download: report.txt (canceled)`
+ */
+export function downloadText(download) {
+    const where = download.path === undefined ? '' : ` → ${download.path}`;
+    const running = download.state === 'inProgress';
+    const bytes = download.bytes === undefined || (running && download.bytes === 0)
+        ? ''
+        : `, ${formatBytes(download.bytes)}${running ? ' so far' : ''}`;
+    const reason = download.reason === undefined ? '' : `: ${download.reason}`;
+    return `Download: ${download.suggestedFilename}${where} (${download.state}${bytes}${reason})`;
+}
+/**
+ * The session's downloads in one line: how many, and the last one.
+ *
+ * @param downloads - Downloads, oldest first (at least one)
+ * @returns e.g. `2 (last: report.txt → /Users/me/.bdg/downloads/report.txt, completed)`
+ */
+export function downloadsSummary(downloads) {
+    const last = downloads[downloads.length - 1];
+    if (!last)
+        return '0';
+    const where = last.path === undefined ? '' : ` → ${last.path}`;
+    return `${downloads.length} (last: ${last.suggestedFilename}${where}, ${last.state})`;
+}
+/**
+ * Warning while Chrome did not take bdg's download behavior, so downloads
+ * are not saved in the session directory.
+ *
+ * @param detail - Chrome's error
+ * @returns Warning shown by `bdg status`
+ */
+export function downloadsNotRedirectedWarning(detail) {
+    return `downloads are not redirected to the session directory (Chrome refused the download behavior: ${detail}); Chrome saves them in its default folder, usually ~/Downloads`;
+}
+/**
+ * Why downloads are refused when the session's downloads directory could not
+ * be created.
+ *
+ * @param detail - What went wrong, e.g. `/home/me/.bdg/downloads is a file`
+ * @returns Reason recorded on each refused download
+ */
+export function downloadsDirUnavailableReason(detail) {
+    return `bdg's downloads directory could not be created (${detail}), so downloads are refused`;
+}
 /**
  * Last `New text:` row when an action made more messages appear than are listed.
  *
@@ -1161,9 +1246,19 @@ export function sessionOutputRemovedMessage() {
     return 'Session output file removed';
 }
 /**
- * Generate session directory clean message.
+ * Cleanup left the session's downloaded files in place.
  *
- * @returns Formatted success message
+ * @param dir - Downloads directory
+ * @param files - Files in it
+ * @returns e.g. `Downloads kept: 2 files in /Users/me/.bdg/downloads (delete them yourself when done)`
+ */
+export function downloadsKeptMessage(dir, files) {
+    return `Downloads kept: ${pluralize(files, 'file')} in ${dir} (delete them yourself when done)`;
+}
+/**
+ * Cleanup finished and left nothing behind.
+ *
+ * @returns Message
  */
 export function sessionDirectoryCleanMessage() {
     return 'Session directory is now clean';

package/dist/ui/messages/networkMessages.d.ts

@@ -4,23 +4,42 @@
  * User-facing messages for the network list command output and formatting.
  */
 /**
- * Why a stored response body was replaced by a placeholder (shown by
- * `bdg details network <id>` as `bodyNotCaptured`).
+ * Why a stored request or response body was replaced by a placeholder
+ * (shown by `bdg details network <id>` as `requestBodyNotCaptured` or
+ * `bodyNotCaptured`).
  *
  * @param budgetBytes - Total body budget of the session
- * @returns e.g. `evicted: total body budget (bdg keeps the newest 100 MB of response bodies)`
+ * @returns e.g. `evicted: total body budget (bdg keeps the newest 100 MB of request and response bodies)`
  */
 export declare function bodyEvictedReason(budgetBytes: number): string;
+/**
+ * Why a response body is missing when Chrome no longer had it
+ * (`Network.getResponseBody` failed with "No resource with given identifier
+ * found" or "No data found for resource with given identifier"), shown by
+ * `bdg details network <id>` as `bodyNotCaptured` and in the HAR as the
+ * content comment.
+ *
+ * @returns Reason text
+ */
+export declare function bodyGoneReason(): string;
+/**
+ * Why a response body is missing when `Network.getResponseBody` failed for
+ * another reason (a CDP timeout, the connection closing mid-fetch).
+ *
+ * @param errorMessage - The error Chrome or the connection gave
+ * @returns e.g. `Chrome did not return the body: CDP command timeout`
+ */
+export declare function bodyFetchFailedReason(errorMessage: string): string;
 /** What a session's network capture let go at its limits */
 export interface NetworkEvictionCounts {
     /** Oldest finished requests dropped at the request cap */
     requestsDropped: number;
-    /** Oldest response bodies evicted at the body budget */
+    /** Oldest request and response bodies evicted at the body budget */
     bodiesEvicted: number;
 }
 /**
  * Note that the session dropped its oldest requests or evicted its oldest
- * response bodies at its limits.
+ * request and response bodies at its limits.
  *
  * @param counts - Requests dropped and bodies evicted
  * @returns e.g. `⚠ 2000 older network requests were dropped: bdg keeps the newest 10000`;
@@ -53,4 +72,30 @@ export declare function headerRepeatedNote(count: number): string;
  * @returns Note text
  */
 export declare function localProxyNote(): string;
+/**
+ * HAR log comment of a sanitized export.
+ *
+ * @returns Comment naming what was redacted and the flag that keeps it
+ */
+export declare function harSanitizedComment(): string;
+/**
+ * Result of a HAR export to a file.
+ */
+export interface HarExportSummary {
+    /** Absolute path written */
+    file: string;
+    /** Requests exported */
+    entries: number;
+    /** Whether --filter left requests out */
+    filtered: boolean;
+    /** Whether credentials were redacted */
+    sanitized: boolean;
+}
+/**
+ * Success message of `bdg network har`.
+ *
+ * @param result - Export result
+ * @returns e.g. `✓ Exported 4 requests to /tmp/out.har` and a line on sanitization
+ */
+export declare function harExportedMessage(result: HarExportSummary): string;
 //# sourceMappingURL=networkMessages.d.ts.map