browser-debugger-cli 0.14.0 → 0.16.0

package/dist/commands/dom/screenshot.js

@@ -3,8 +3,9 @@
  */
 import { extname } from 'path';
 import { DomElementResolver } from './DomElementResolver.js';
-import { capturePageScreenshot, captureElementScreenshot, resolveSelector, selectMatch, } from './helpers/index.js';
+import { captureScreenshot, resolveSelector, screenshotInterrupted, selectMatch, } from './helpers/index.js';
 import { runCommand } from '../shared/CommandRunner.js';
+import { abortOnInterrupt, unlessInterrupted } from '../shared/interrupt.js';
 import { assertFilePath, outputPathError } from '../shared/outputFile.js';
 import { positiveIntRule } from '../shared/validation.js';
 import { CommandError } from '../../errors/index.js';
@@ -47,34 +48,43 @@ export function resolveImageFormat(outputPath, requested) {
     }
     return requested ?? fromExtension ?? 'png';
 }
-function buildPageScreenshotOptions(options) {
-    return filterDefined({
-        format: options.format,
-        quality: options.quality,
-        fullPage: options.fullPage,
-        noResize: options.resize === false,
-        scroll: options.scroll,
-    });
-}
-function buildElementScreenshotOptions(options) {
-    return filterDefined({
-        format: options.format,
-        quality: options.quality,
-        noResize: options.resize === false,
-        padding: options.padding,
-    });
+/**
+ * What to capture, from the command's options: the element `backendNodeId`
+ * names (with its `--padding`), else the page (`--full-page`, `--scroll`).
+ *
+ * @param options - Command options
+ * @param backendNodeId - Element to capture, if any
+ * @returns Daemon request
+ */
+function buildScreenshotRequest(options, backendNodeId) {
+    const shared = {
+        format: options.format ?? 'png',
+        ...filterDefined({ quality: options.quality }),
+        ...(options.resize === false && { noResize: true }),
+    };
+    if (backendNodeId !== undefined) {
+        return { ...shared, backendNodeId, ...filterDefined({ padding: options.padding }) };
+    }
+    return { ...shared, ...filterDefined({ fullPage: options.fullPage, scroll: options.scroll }) };
 }
 function hasElementTarget(options) {
     return options.selector !== undefined || options.index !== undefined;
 }
+/**
+ * The element to capture: the selector's match (`--index` picks one), or the
+ * cached query result at `--index`.
+ *
+ * @param options - Command options
+ * @returns Its backend node id
+ * @throws CommandError (81) when neither is given
+ */
 async function resolveElementNodeId(options) {
     if (options.selector !== undefined && options.index !== undefined) {
-        return { backendNodeId: await selectMatch(options.selector, options.index) };
+        return selectMatch(options.selector, options.index);
     }
     if (options.index !== undefined) {
-        const resolver = DomElementResolver.getInstance();
-        const node = await resolver.getNodeIdForIndex(options.index);
-        return { backendNodeId: node.nodeId };
+        const node = await DomElementResolver.getInstance().getNodeIdForIndex(options.index);
+        return node.nodeId;
     }
     if (options.selector !== undefined) {
         return resolveSelector(options.selector);
@@ -120,32 +130,42 @@ function ensureDirectory(dirPath, fs) {
 function formatFrameFilename(frameNumber, format) {
     return `${String(frameNumber).padStart(3, '0')}.${format}`;
 }
+/**
+ * Capture the page. Ctrl-C (or SIGTERM) cancels the capture and exits 130
+ * (143), with the error envelope under `--json`.
+ *
+ * @param outputPath - File to write
+ * @param options - Command options
+ */
 async function handlePageScreenshot(outputPath, options) {
+    const interrupt = abortOnInterrupt();
     await runCommand(async () => {
-        const screenshotOptions = buildPageScreenshotOptions(options);
-        const result = await capturePageScreenshot(outputPath, screenshotOptions);
+        const request = buildScreenshotRequest(options);
+        const result = await captureScreenshot(outputPath, request, interrupt);
         return { success: true, data: result };
     }, options, formatDomScreenshot);
 }
+/**
+ * Capture one element; interrupted like {@link handlePageScreenshot}, also
+ * while the element is looked up.
+ *
+ * @param outputPath - File to write
+ * @param options - Command options
+ */
 async function handleElementScreenshot(outputPath, options) {
+    const interrupt = abortOnInterrupt();
     await runCommand(async () => {
-        const nodeRef = await resolveElementNodeId(options);
-        const screenshotOptions = buildElementScreenshotOptions(options);
-        const result = await captureElementScreenshot(outputPath, nodeRef, screenshotOptions);
-        const elementResult = addElementInfo(result, options);
+        const lookup = resolveElementNodeId(options);
+        const backendNodeId = await unlessInterrupted(lookup, interrupt, screenshotInterrupted);
+        const request = buildScreenshotRequest(options, backendNodeId);
+        const shot = await captureScreenshot(outputPath, request, interrupt);
+        const elementResult = addElementInfo(shot, options);
         return { success: true, data: elementResult };
     }, options, formatDomScreenshot);
 }
 async function captureSequenceFrame(outputPath, options) {
-    if (hasElementTarget(options)) {
-        const nodeRef = await resolveElementNodeId(options);
-        const elementOptions = buildElementScreenshotOptions(options);
-        await captureElementScreenshot(outputPath, nodeRef, elementOptions);
-    }
-    else {
-        const pageOptions = buildPageScreenshotOptions(options);
-        await capturePageScreenshot(outputPath, pageOptions);
-    }
+    const backendNodeId = hasElementTarget(options) ? await resolveElementNodeId(options) : undefined;
+    await captureScreenshot(outputPath, buildScreenshotRequest(options, backendNodeId));
 }
 async function handleSequenceCapture(outputDir, options) {
     const fs = await import('fs');

package/dist/commands/helpJson.d.ts

@@ -93,7 +93,7 @@ export interface CompactCommand {
     name: string;
     /** Command aliases (only when it has some) */
     aliases?: readonly string[];
-    /** First line of the description */
+    /** Summary if set, else the first line of the description */
     description: string;
     /** Arguments as in usage, e.g. "<selector> [index]" (only when it takes some) */
     arguments?: string;

package/dist/commands/helpJson.js

@@ -114,8 +114,8 @@ function argumentTerm(argument) {
     return argument.required ? `<${name}>` : `[${name}]`;
 }
 /**
- * Recursively converts a Commander Command to its compact summary: first
- * description line, arguments, and visible options with their descriptions.
+ * Recursively converts a Commander Command to its compact summary: summary
+ * (or first description line), arguments, and visible options with their descriptions.
  * Empty fields are left out.
  *
  * @param command - Commander command instance
@@ -128,7 +128,7 @@ function convertCompactCommand(command) {
     return {
         name: command.name(),
         ...(aliases.length > 0 && { aliases }),
-        description: command.description().split('\n')[0] ?? '',
+        description: command.summary() || (command.description().split('\n')[0] ?? ''),
         ...(args && { arguments: args }),
         ...(options.length > 0 && {
             options: Object.fromEntries(options.map((option) => [option.flags, option.description])),

package/dist/commands/helpTopic.js

@@ -3,11 +3,14 @@
  */
 import { commandPath } from './helpJson.js';
 import { CommandError } from '../errors/index.js';
-import { missingSubcommandMessage, unknownHelpTopicError, usageHelpSuggestion, } from '../errors/messages.js';
+import { didYouMeanSuggestion, missingSubcommandMessage, unknownHelpTopicError, usageHelpSuggestion, } from '../errors/messages.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { findSimilar } from '../utils/suggestions.js';
-/** Commander's typo hint on its own line, e.g. "(Did you mean query?)" */
-const COMMANDER_HINT = /\n?\(Did you mean (.+)\?\)\s*$/;
+/**
+ * Commander's typo hint on its own line: "(Did you mean query?)" or, for
+ * several equally close candidates, "(Did you mean one of form, frames?)"
+ */
+const COMMANDER_HINT = /\n?\(Did you mean (?:one of )?(.+)\?\)\s*$/;
 /**
  * The command path of `bdg help <path...>`: the words before the first option.
  *
@@ -54,7 +57,10 @@ export function splitCommanderHint(text) {
     const hint = COMMANDER_HINT.exec(message);
     if (!hint)
         return { message };
-    return { message: message.slice(0, hint.index).trim(), suggestion: `Did you mean: ${hint[1]}?` };
+    return {
+        message: message.slice(0, hint.index).trim(),
+        suggestion: didYouMeanSuggestion((hint[1] ?? '').split(', ')),
+    };
 }
 /** The option named in Commander's "unknown option '--x'" message, without an `=value` */
 const UNKNOWN_OPTION = /unknown option '([^'=]+)/;

package/dist/commands/network/har.js

@@ -15,6 +15,7 @@ import { getSessionFilePath } from '../../session/paths.js';
 import { applyFilters, parseFilterString } from '../../telemetry/filterDsl.js';
 import { buildHAR } from '../../telemetry/har/builder.js';
 import { createLogger } from '../../ui/logging/index.js';
+import { harExportedMessage } from '../../ui/messages/networkMessages.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { VERSION } from '../../utils/version.js';
 import { getNetworkRequests, validateFilterOption } from './shared.js';
@@ -67,15 +68,20 @@ async function getChromeVersion() {
 function formatHARExport(data) {
     if ('log' in data)
         return JSON.stringify(data, null, 2);
-    const filterNote = data.filtered ? ' (filtered)' : '';
-    return `✓ Exported ${data.entries} requests${filterNote} to ${data.file}`;
+    return harExportedMessage(data);
 }
+/** HAR files may hold credentials (--include-sensitive): readable by their owner only */
+const HAR_FILE_MODE = 0o600;
 /** Output path meaning "write the HAR to stdout" */
 const STDOUT_PATH = '-';
 /**
  * Option for filter DSL.
  */
 const filterDslOption = new Option('--filter <dsl>', 'Filter requests using DevTools DSL (e.g., "status-code:>=400")');
+/**
+ * Option to keep credentials in the export.
+ */
+const includeSensitiveOption = new Option('--include-sensitive', 'Keep credentials (auth/cookie/API key headers, cookie values, URL tokens, password and token body fields); redacted by default');
 /**
  * Register HAR export command.
  *
@@ -88,6 +94,7 @@ export function registerHarCommand(networkCmd) {
         .description('Export network data as HAR 1.2 format')
         .addOption(jsonOption())
         .addOption(filterDslOption)
+        .addOption(includeSensitiveOption)
         .action(async (outputFile, options) => {
         await runCommand(async () => {
             let requests = await getNetworkRequests();
@@ -103,21 +110,18 @@ export function registerHarCommand(networkCmd) {
             if (outputPath !== STDOUT_PATH)
                 assertFilePath(outputPath, '.har');
             const chromeVersion = await getChromeVersion();
-            const har = buildHAR(requests, {
-                version: VERSION,
-                ...(chromeVersion && { chromeVersion }),
-            });
+            const includeSensitive = options.includeSensitive === true;
+            const har = buildHAR(requests, { version: VERSION, ...(chromeVersion && { chromeVersion }) }, { includeSensitive });
             if (outputPath === STDOUT_PATH)
                 return { success: true, data: har };
-            const file = await writeOutputFile(outputPath, JSON.stringify(har, null, 2), '.har');
-            return {
-                success: true,
-                data: {
-                    file,
-                    entries: har.log.entries.length,
-                    filtered,
-                },
+            const file = await writeOutputFile(outputPath, JSON.stringify(har, null, 2), '.har', HAR_FILE_MODE);
+            const data = {
+                file,
+                entries: har.log.entries.length,
+                filtered,
+                sanitized: !includeSensitive,
             };
+            return { success: true, data };
         }, options, formatHARExport);
     });
 }

package/dist/commands/optionBehaviors.js

@@ -6,13 +6,13 @@
  *
  * @see docs/principles/SELF_DOCUMENTING_SYSTEMS.md
  */
-import { MAX_EDGE_PX, PIXELS_PER_TOKEN, TALL_PAGE_THRESHOLD, } from './dom/screenshotResize.js';
+import { MAX_EDGE_PX, PIXELS_PER_TOKEN, TALL_PAGE_THRESHOLD, } from '../runtime/page/screenshotResize.js';
 /** What DOM actions report about the network requests they triggered */
 const TRIGGERED_REQUESTS_BEHAVIOR = 'Requests (and WebSocket connections) that start after the action begins are returned as triggeredRequests (method, url, status, durationMs; pending when still running at return, loading when the response arrived but its body is still streaming; with resourceType; human output lists documents, XHR/fetch and WebSockets first (up to 10) and counts static assets on one line; absent when network telemetry is off). Attribution is by time: requests a page timer or poller starts meanwhile are listed too, whether or not the action caused them';
 /** What every DOM action reports about the page besides its requests */
-const ACTION_EFFECTS_BEHAVIOR = 'The result also says what changed on the page: a navigation (Page: navigated to <url> (status), or URL changed to <url> (same document); JSON navigation { url, sameDocument, status }), and messages that appeared or changed in alert/status/aria-live elements or flash/error/toast-like classes (New text: "…" (element); JSON messages [{ text, element }], at most 3, with "(+N more)" and moreMessages for the rest; after a navigation every message on the new page counts; texts of only digits and time units, such as clocks and counters, are left out, but other text that changes on its own, such as a rotating banner, can show up). Both are absent when nothing changed. Cost: one page script sent before the action without waiting for it and one read after it, a few ms; when the page does not answer (a pending navigation) bdg waits at most 200 ms for the snapshot and 250 ms per read, and the navigation is still reported from CDP events';
+const ACTION_EFFECTS_BEHAVIOR = 'The result also says what changed on the page: a navigation (Page: navigated to <url> (status), or URL changed to <url> (same document); JSON navigation { url, sameDocument, status }), and messages that appeared or changed in alert/status/aria-live elements or flash/error/toast-like classes (New text: "…" (element); JSON messages [{ text, element }], at most 3, with "(+N more)" and moreMessages for the rest; after a navigation every message on the new page counts; texts of only digits and time units, such as clocks and counters, are left out, but other text that changes on its own, such as a rotating banner, can show up). Both are absent when nothing changed. Downloads that began meanwhile are listed (Download: <name> → <path> (<state>, <size>); JSON downloads [{ url, suggestedFilename, path, state: inProgress|completed|canceled, bytes }]); a Chrome bdg launched saves them into <session dir>/downloads (never ~/Downloads), named as suggested with (1), (2)… when taken, and one still running when the action returns is inProgress and appears at its path once complete; downloads of tabs the page opens (target=_blank, window.open) count too; when that directory cannot be created they are refused (canceled, with reason) instead of going to ~/Downloads, and if Chrome refuses the download behavior bdg status warns that downloads are not redirected; ones that begin after the action returned are listed by bdg status and bdg peek (Downloads: N (last: …)); files stay after stop and cleanup; with --chrome-ws-url (the exception: not a browser bdg owns) downloads go to the download folder of that Chrome (usually ~/Downloads), only downloads of the session page are tracked (not those of tabs or popups it opens), and bdg sets behavior default with events, which replaces one another CDP client set and which Chrome drops when the session connection closes. Cost: one page script sent before the action without waiting for it and one read after it, a few ms; when the page does not answer (a pending navigation) bdg waits at most 200 ms for the snapshot and 250 ms per read, and the navigation is still reported from CDP events';
 /** What click and pressKey report when the page was still changing as they returned */
-const STILL_CHANGING_BEHAVIOR = 'When the page was still changing as the action returned, the status line says (page still changing), a note below it says what was pending and suggests bdg dom wait <selector>, and JSON has settled: false with pending { requests (document, fetch/XHR and script requests still running), navigation (a new page still loading), loading (a loading indicator that appeared, e.g. "div#loading"), domChanging (DOM changes kept coming in bursts over a second look 250 ms later; a single render, ticking text and style animations do not count), busy (the page did not answer within 250 ms: a long script) }; absent when the page looked settled (exit code stays 0). A result a timer renders later, with no DOM change, request or loading indicator before it, is not detected. Cost: nothing extra, except 250 ms plus one read when the DOM looked busy. Not checked with --no-wait';
+const STILL_CHANGING_BEHAVIOR = 'When the page was still changing as the action returned, the status line says (page still changing), a note below it says what was pending and suggests bdg dom wait <selector>, and JSON has settled: false with pending { requests (document, fetch/XHR and script requests still running), navigation (a new page still loading), loading (a loading indicator that appeared, e.g. "div#loading"), domChanging (DOM changes came in bursts and, at a second look 250 ms later, again, with no quiet gap over 150 ms; time the page could not run its tasks, a long task or timers a starved renderer runs late, is not quiet, and a single burst more than 150 ms old with at most 75 ms of quiet time since also gets the second look (only that 250 ms; domChanging still needs a fresh change at it); a single render, ticking text and style animations do not count, and changes more than about 150 ms apart while the page could run look settled), busy (the page did not answer within 250 ms and ran a long task since the action began, or did not answer a check within 250 ms more: a long script; a page that answered late without a long task, a starved renderer, gets its answer waited for instead; a renderer descheduled in the middle of a task can still record a long task and is then busy; the check runs at most once per action, adding at most 250 ms, so an endless script is reported busy about 500 ms after the action) }; absent when the page looked settled (exit code stays 0). A result a timer renders later, with no DOM change, request or loading indicator before it, is not detected. Cost: nothing extra, except 250 ms plus one read when the DOM looked busy. Not checked with --no-wait';
 /** What hover and pressKey report about elements they showed */
 const SHOWN_BEHAVIOR = 'Elements the action showed are listed (Shown: <element> "<text>"; JSON shown [{ text, element }], at most 3, outermost first): elements with visible text added inside the target\'s form, search box, dialog or combobox (else its grandparent, or its parent when that is the body), and popups and messages added anywhere (tooltip, menu, listbox, dialog, alert, status roles, popover, aria-live, message-like classes); widgets elsewhere on the page and re-rendered elements whose text was there before do not count';
 /** What `--no-wait` does to a DOM action's triggered requests */
@@ -101,9 +101,9 @@ const OPTION_BEHAVIORS = {
         automaticBehavior: 'The value is matched as: a 0-based index (bdg dom frames order: document order of the <iframe> elements, nested ones depth-first, main page not counted), else an exact name/id attribute, else a case-insensitive part of the name, id or 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). An index that names another frame than in the last bdg dom frames listing (iframes added, removed or moved, or the page navigated) fails with 87 STALE_CACHE: re-run bdg dom frames or pick the frame by name.',
     },
     'eval:--full': {
-        default: 'Human output prints the first 20000 characters of the value followed by "… N more chars (use --full)"; in JSON a string result is cut to 20000 characters with truncatedFrom (the original length). Objects and arrays in JSON are not cut',
-        whenEnabled: 'Prints the whole value, byte for byte',
-        tokenImpact: 'dom eval document.documentElement.outerHTML on Wikipedia is about 3.6 MB with --full; select what you need in the expression instead',
+        default: 'Human output prints the first 20000 characters of the value followed by "… N more chars (use --full)". In JSON a string result is cut to 20000 characters with truncatedFrom (the original length); an array result lists its first 100 elements with count (all of them) and omitted; an object or array whose JSON is still over 20000 characters becomes the first 20000 characters of its JSON text (a string; arrays keep count) with truncatedFrom (the length of the JSON text of the copy, which holds at most 1000 entries per list or object): a string result with truncatedFrom while type is object is such a JSON-text start',
+        whenEnabled: 'Prints the whole value, byte for byte; objects and arrays are copied with every entry (without --full at most 1000 per list or object)',
+        tokenImpact: 'dom eval document.documentElement.outerHTML on Wikipedia is about 3.6 MB with --full; on a page with 20000 elements, [...document.querySelectorAll("*")].map(e => e.outerHTML) --json is 3 MB with --full and 23 KB without; select what you need in the expression instead',
     },
     'console:--full': {
         default: 'Message texts are cut: human output (summary, --list, --follow) at 200 characters followed by "… N more chars (use --full)"; JSON text at 10000 characters with truncatedFrom (the original length)',
@@ -330,6 +330,11 @@ const OPTION_BEHAVIORS = {
         whenEnabled: 'Streams requests as they finish',
         automaticBehavior: FOLLOW_BEHAVIOR,
     },
+    'har:--include-sensitive': {
+        default: 'The HAR is sanitized: values become "[redacted]" for Authorization, Proxy-Authorization, Authentication, Cookie and Set-Cookie headers, X-*key/token/secret/auth headers and headers with an api-key/apikey/token/secret/jwt/subscription-key/session(-id) segment (www-authenticate is kept); every cookie value; query and fragment parameters named like credentials (plus code, sig, key) in the request URL, queryString, redirectURL and Location/Referer headers ("%5Bredacted%5D" in URLs); and password/token/secret/key/session/signature/bearer/cookie/csrf/refresh/auth/sid/pin/ssn/card-number fields of JSON (primitives at any depth under such a name), form-urlencoded (also sniffed when the Content-Type says otherwise, user[password] names too) and multipart request and response bodies (an access_token/refresh_token/id_token login response too) and of WebSocket messages, also in truncated JSON, JSON encoded in string values (3 levels), socket.io and SockJS packets, server-sent events, NDJSON, base64 bodies with no, a generic, JSON, form or event-stream type and binary WebSocket messages that are UTF-8 text; any whole JWT (eyJ…) in a JSON string, form or URL value, multipart part or text body (only the JWT is replaced). camelCase names count as words (userPin). JSON is edited in place, not re-serialized: everything but the replaced values (64-bit numbers, formatting, duplicate keys, a BOM or )]}\' prefix) stays byte for byte. Header, cookie and parameter names, cookie attributes, headersSize, bodySize and content.size stay; log.comment and JSON sanitized: true say so',
+        whenEnabled: 'Writes every captured value (JSON sanitized: false); human output warns that the file holds credentials',
+        automaticBehavior: 'Matching is by name, so it over-redacts: harmless values under credential-looking names (tokenCount: 5, sessionLength, refreshInterval, cookieConsent) are replaced too, and credentials under other names are kept. Only JSON syntax is understood: single-quoted strings, unquoted keys, JSONP, STOMP passcode: header lines and bare values with spaces ({"token":abc def}, a non-JWT token after Bearer in text) are not (fully) redacted. A body the sanitizer fails on is replaced whole by [redacted]. Unlike Chrome DevTools, which drops these headers and empties cookies, names are kept so the HAR still shows a request was authenticated. Kept as captured: other binary (base64) bodies, binary WebSocket messages that are not UTF-8, and text that is not JSON or a form (apart from JWTs); a WebSocket message cut at 100 KB has _truncatedFrom. HAR files are written readable by their owner only (0600). network headers and network getCookies always show real values',
+    },
     'peek:--verbose': {
         default: 'Compact output (truncated URLs, no resource types)',
         whenEnabled: 'Verbose output with full URLs and resource types',
@@ -360,8 +365,8 @@ const OPTION_BEHAVIORS = {
         whenEnabled: 'Alias for --force, kept for compatibility',
     },
     'cleanup:--purge': {
-        default: "A named session's directory (Chrome profile, ~60 MB; logs; port.txt) is kept for its next start",
-        whenEnabled: 'After cleaning up, deletes the directory of the session named by --session (exit 81 without --session); a running session is refused unless --force is given, and the directory is kept (exit 90) if the daemon still answers, cleanup reported a problem, or its Chrome has not exited',
+        default: "A named session's directory (Chrome profile, ~60 MB; logs; port.txt; downloads/) is kept for its next start",
+        whenEnabled: 'After cleaning up, deletes the directory of the session named by --session, downloaded files included (exit 81 without --session); a running session is refused unless --force is given, and the directory is kept (exit 90) if the daemon still answers, cleanup reported a problem, or its Chrome has not exited',
     },
     'bdg:--viewport': {
         default: 'A launched Chrome opens a 1920x1080 window (the viewport is smaller by the scrollbar, and in a visible window by the browser UI); an attached Chrome keeps its window',
@@ -381,12 +386,22 @@ const OPTION_BEHAVIORS = {
     'bdg:--chrome-ws-url': {
         default: 'bdg launches its own Chrome (closed on stop)',
         whenEnabled: 'Attaches to a running Chrome instead; it keeps running after stop. --port, -u and --[no-]headless cannot be combined with it (exit 81)',
-        automaticBehavior: 'A port (9222), host:port or http://host:port is turned into the browser WebSocket URL via /json/version; a browser URL uses the first open tab. Refused with exit 90 when another running bdg session launched that Chrome or drives that tab (sessions of this BDG_SESSION_DIR, and of others that claimed a port)',
+        automaticBehavior: 'A port (9222), host:port or http://host:port is turned into the browser WebSocket URL via /json/version; a browser URL uses the first open tab. Refused with exit 90 when another running bdg session launched that Chrome or drives that tab (sessions of this BDG_SESSION_DIR, and of others that claimed a port). Downloads are not redirected: they go to the download folder of that Chrome (usually ~/Downloads), and only downloads of the session page are reported (not those of tabs or popups it opens)',
     },
     'stop:--kill-chrome': {
         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',
     },
+    'cdp:--send-anyway': {
+        default: 'A Domain.method 1 edit from a bundled method or domain (2 for names over 5 letters, case ignored) is taken for a typo: exit 81 with Did you mean',
+        whenEnabled: 'Sends such a name to Chrome as typed (for a method newer than the bundled protocol, e.g. next to a bundled sibling like getWindowBounds/setWindowBounds), with the not-in-bundled-protocol warning',
+        automaticBehavior: 'Blocked methods (Page.captureScreenshot, Page.close, Browser.close), type names and names that are not Domain.method are still refused; a well-formed name far from every bundled one is sent without the flag',
+    },
+    'cdp:--describe': {
+        default: 'Without --describe, a Domain.method is called (one missing from the bundled protocol is sent as typed, with a warning: only bundled methods are matched case-insensitively)',
+        whenEnabled: 'Describes a domain, a method (parameters with ? for optional, returns, example) or a protocol type (Domain.Type: enum values or object properties)',
+        automaticBehavior: 'Parameters referring to an enum type list its values inline (JSON enum, ref, refType); a redirected method (DOM.highlightNode) also shows the method implementing it and its parameters, which Chrome checks (JSON redirect, resolved: true); a redirect to a method the protocol lacks (Page.deleteCookie → Network.deleteCookie) is shown as unresolved (resolved: false). Example values work as typed: width 1280, height 800, x/y 100, deviceScaleFactor/scale 1, timeout 5000, url https://example.com, other numbers 1 (never 0, which often means off)',
+    },
     'status:--verbose': {
         default: 'Basic session status (daemon running, session active, URL)',
         whenEnabled: 'Includes Chrome diagnostics and CDP connection details',

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

@@ -44,6 +44,11 @@ export interface CommandResult<T = unknown> {
     errorContext?: Record<string, unknown>;
     /** Optional hint message to display on stderr (for successful commands with guidance) */
     hint?: string;
+    /**
+     * Warning about how the command ran (success or failure): top-level
+     * `warning` in the JSON envelope, `Warning: …` on stderr otherwise
+     */
+    warning?: string;
 }
 /**
  * Handler function type.

package/dist/commands/shared/CommandRunner.js

@@ -80,6 +80,15 @@ function sessionEndedError() {
     const err = sessionEndedDuringCommandError();
     return new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
 }
+/**
+ * Print a command's warning on stderr (text output; `--json` has it in the envelope).
+ *
+ * @param warning - Warning, if any
+ */
+function printWarning(warning) {
+    if (warning)
+        console.error(escapeControlChars(`Warning: ${warning}`));
+}
 /**
  * Run a command with consistent error handling, output formatting, and exit codes.
  * Eliminates boilerplate try-catch and JSON output logic from command handlers.
@@ -114,6 +123,7 @@ export async function runCommand(handler, options, formatter) {
             if (options.json) {
                 console.log(stringifyEnvelope(OutputBuilder.buildJsonError(result.error ?? 'Unknown error', {
                     ...result.errorContext,
+                    ...(result.warning && { warning: result.warning }),
                     exitCode,
                 })));
             }
@@ -126,14 +136,17 @@ export async function runCommand(handler, options, formatter) {
                         }
                     }
                 }
+                printWarning(result.warning);
             }
             process.exit(exitCode);
         }
+        if (!options.json)
+            printWarning(result.warning);
         if (result.hint && !options.quiet) {
             console.error(escapeControlChars(result.hint));
         }
         if (options.json) {
-            console.log(stringifyEnvelope(buildSuccessResponse(result.data)));
+            console.log(stringifyEnvelope(buildSuccessResponse(result.data, result.warning)));
         }
         else if (formatter) {
             const formattedOutput = formatter(result.data);
@@ -158,10 +171,12 @@ export async function runCommand(handler, options, formatter) {
                 })));
             }
             else {
+                const { warning, ...metadata } = error.metadata;
                 console.error(genericError(error.message));
-                for (const value of Object.values(error.metadata)) {
-                    console.error(escapeControlChars(String(value)));
+                for (const value of Object.values(metadata)) {
+                    console.error(escapeControlChars(typeof value === 'string' ? value : JSON.stringify(value)));
                 }
+                printWarning(warning);
             }
             process.exit(error.exitCode);
         }

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

@@ -0,0 +1,40 @@
+/**
+ * Ctrl-C and SIGTERM for a command that cancels its daemon request instead
+ * of dying mid-request, so it can still report (the `--json` envelope) and
+ * exit with the shell's code.
+ */
+/** Signals that interrupt a command */
+export type InterruptSignal = 'SIGINT' | 'SIGTERM';
+/**
+ * The exit code of an interrupted command, as shells expect.
+ *
+ * @param signal - The signal
+ * @returns 130 for SIGINT, 143 for SIGTERM
+ */
+export declare function interruptExitCode(signal: InterruptSignal): number;
+/**
+ * The signal that aborted an interrupt, from its reason.
+ *
+ * @param interrupt - Aborted interrupt (reason: the signal name)
+ * @returns The signal, SIGINT unless it was SIGTERM
+ */
+export declare function interruptSignal(interrupt: AbortSignal): InterruptSignal;
+/**
+ * Abort on Ctrl-C or SIGTERM (reason: the signal name). A second signal
+ * exits at once.
+ *
+ * @returns Aborted on the first signal
+ */
+export declare function abortOnInterrupt(): AbortSignal;
+/**
+ * Wait for work unless interrupted first: the first signal ends the wait at
+ * once with the interrupted error (the work is left to the exiting process).
+ *
+ * @param work - Work to wait for
+ * @param interrupt - Aborted on Ctrl-C or SIGTERM (reason: the signal)
+ * @param interruptedError - The error for an interrupt by a signal
+ * @returns The work's value
+ * @throws The interrupted error once interrupted, else the work's error
+ */
+export declare function unlessInterrupted<T>(work: Promise<T>, interrupt: AbortSignal, interruptedError: (signal: InterruptSignal) => Error): Promise<T>;
+//# sourceMappingURL=interrupt.d.ts.map

package/dist/commands/shared/interrupt.js

@@ -0,0 +1,73 @@
+/**
+ * Ctrl-C and SIGTERM for a command that cancels its daemon request instead
+ * of dying mid-request, so it can still report (the `--json` envelope) and
+ * exit with the shell's code.
+ */
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+/**
+ * The exit code of an interrupted command, as shells expect.
+ *
+ * @param signal - The signal
+ * @returns 130 for SIGINT, 143 for SIGTERM
+ */
+export function interruptExitCode(signal) {
+    return signal === 'SIGINT' ? EXIT_CODES.INTERRUPTED : EXIT_CODES.TERMINATED;
+}
+/**
+ * The signal that aborted an interrupt, from its reason.
+ *
+ * @param interrupt - Aborted interrupt (reason: the signal name)
+ * @returns The signal, SIGINT unless it was SIGTERM
+ */
+export function interruptSignal(interrupt) {
+    return interrupt.reason === 'SIGTERM' ? 'SIGTERM' : 'SIGINT';
+}
+/**
+ * Abort on Ctrl-C or SIGTERM (reason: the signal name). A second signal
+ * exits at once.
+ *
+ * @returns Aborted on the first signal
+ */
+export function abortOnInterrupt() {
+    const interrupt = new AbortController();
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        process.on(signal, () => {
+            if (interrupt.signal.aborted)
+                process.exit(interruptExitCode(signal));
+            interrupt.abort(signal);
+        });
+    }
+    return interrupt.signal;
+}
+/**
+ * Wait for work unless interrupted first: the first signal ends the wait at
+ * once with the interrupted error (the work is left to the exiting process).
+ *
+ * @param work - Work to wait for
+ * @param interrupt - Aborted on Ctrl-C or SIGTERM (reason: the signal)
+ * @param interruptedError - The error for an interrupt by a signal
+ * @returns The work's value
+ * @throws The interrupted error once interrupted, else the work's error
+ */
+export async function unlessInterrupted(work, interrupt, interruptedError) {
+    const fail = () => interruptedError(interruptSignal(interrupt));
+    if (interrupt.aborted)
+        throw fail();
+    let onAbort = () => undefined;
+    const interrupted = new Promise((_, reject) => {
+        onAbort = () => reject(fail());
+        interrupt.addEventListener('abort', onAbort, { once: true });
+    });
+    try {
+        return await Promise.race([work, interrupted]);
+    }
+    catch (error) {
+        if (interrupt.aborted)
+            throw fail();
+        throw error;
+    }
+    finally {
+        interrupt.removeEventListener('abort', onAbort);
+    }
+}
+//# sourceMappingURL=interrupt.js.map

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

@@ -129,6 +129,8 @@ export interface CdpMethodOptions {
     describe?: boolean;
     /** Search for methods */
     search?: string;
+    /** Send a method that looks like a typo of a bundled one as typed */
+    sendAnyway?: boolean;
 }
 /** Options for stop command */
 export type StopCommandOptions = BaseOptions & ChromeOptions;
@@ -300,6 +302,7 @@ export type NetworkCookiesCommandOptions = BaseOptions & {
 /** Options for network HAR command */
 export type NetworkHarCommandOptions = BaseOptions & {
     outputFile?: string;
+    includeSensitive?: boolean;
 };
 /** Options for network headers command */
 export type NetworkHeadersCommandOptions = BaseOptions & {

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

@@ -26,8 +26,9 @@ export declare function assertFilePath(filePath: string, extension?: string): vo
  * @param filePath - Path the user gave
  * @param data - File contents
  * @param extension - Extension of the file kind, for examples in errors
+ * @param mode - File permissions of a text file (default: 0666 less the umask)
  * @returns Absolute path written
  * @throws CommandError naming the path when it cannot be written
  */
-export declare function writeOutputFile(filePath: string, data: string | Buffer, extension?: string): Promise<string>;
+export declare function writeOutputFile(filePath: string, data: string | Buffer, extension?: string, mode?: number): Promise<string>;
 //# sourceMappingURL=outputFile.d.ts.map

package/dist/commands/shared/outputFile.js

@@ -62,18 +62,21 @@ export function assertFilePath(filePath, extension) {
  * @param filePath - Path the user gave
  * @param data - File contents
  * @param extension - Extension of the file kind, for examples in errors
+ * @param mode - File permissions of a text file (default: 0666 less the umask)
  * @returns Absolute path written
  * @throws CommandError naming the path when it cannot be written
  */
-export async function writeOutputFile(filePath, data, extension) {
+export async function writeOutputFile(filePath, data, extension, mode) {
     assertFilePath(filePath, extension);
     const absolutePath = path.resolve(filePath);
     try {
         makeDirectory(path.dirname(absolutePath));
-        if (typeof data === 'string')
-            await AtomicFileWriter.writeAsync(absolutePath, data);
-        else
+        if (typeof data === 'string') {
+            await AtomicFileWriter.writeAsync(absolutePath, data, mode === undefined ? {} : { mode });
+        }
+        else {
             await AtomicFileWriter.writeBufferAsync(absolutePath, data);
+        }
     }
     catch (error) {
         throw outputPathError(filePath, error, extension);