browser-debugger-cli 0.15.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/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 */
@@ -331,9 +331,9 @@ const OPTION_BEHAVIORS = {
         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 fields of JSON (primitives at any depth under such a name), form-urlencoded (also sniffed when the Content-Type says otherwise) and multipart request bodies. A JSON body too deep to walk becomes "[redacted]" whole. Header, cookie and parameter names, cookie attributes, headersSize and bodySize stay; log.comment and JSON sanitized: true say so',
+        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) are replaced too, and credentials under other names are kept. Unlike Chrome DevTools, which drops these headers and empties cookies, names are kept so the HAR still shows a request was authenticated. Response bodies and WebSocket messages are not redacted. HAR files are written readable by their owner only (0600). network headers and network getCookies always show real values',
+        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)',
@@ -365,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',
@@ -386,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;

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

@@ -15,6 +15,8 @@ import type { TelemetryType } from '../../types.js';
 export type StartOutcome = {
     ok: true;
     data: StartSessionResponseData;
+    /** The daemon this attempt spawned (internal: stopped if the start is interrupted) */
+    spawned?: SpawnedDaemon;
 } | {
     ok: false;
     /** Message for `--json` (no "Error:" prefix) */
@@ -44,6 +46,8 @@ export interface StartDeps {
     launch: () => Promise<SpawnedDaemon | undefined>;
     /** Sends `start_session_request` */
     send: typeof sendStartSessionRequest;
+    /** Sends `stop_session_request` (stops a session whose start was interrupted) */
+    stop: () => Promise<unknown>;
     /** How long a failed start waits for the daemons it spawned to exit */
     exitWaitMs: number;
 }
@@ -53,6 +57,19 @@ export interface StartDeps {
  * Spawns the daemon if needed, sends `start_session_request`, then prints the
  * result as a JSON envelope (`--json`) or human-readable text, and exits.
  *
+ * Ctrl-C (or SIGTERM) cancels the start at any point until the outcome is
+ * printed: the connection is closed, so the daemon abandons the session (a
+ * daemon spawned but not yet asked is told to shut down, a session that has
+ * just started is stopped), and the command exits with 130 (143) once the
+ * daemon it spawned has exited (bounded, like a failed start), so a command
+ * run right after sees no session. A second signal exits at once.
+ *
+ * Race-free: {@link attemptStart} checks the interrupt last, synchronously,
+ * and only microtasks run between that check and the exit in
+ * {@link reportStartOutcome}; a signal handler runs as a macrotask, so a
+ * signal either lands before the check (the start is cancelled) or after the
+ * outcome has been printed.
+ *
  * @param url - Target URL to navigate to
  * @param options - Session configuration options
  * @param telemetry - Array of telemetry types to enable
@@ -63,13 +80,19 @@ export declare function startSessionViaDaemon(url: string, options: SessionStart
  * failure the daemon reported (or a dropped connection), it waits for every
  * daemon the attempts spawned to exit ({@link afterSpawnedDaemonExit}).
  *
+ * An interrupt cancels the start whenever it arrives: a start that succeeded
+ * meanwhile is stopped ({@link cancelStartedSession}), and a failure keeps its
+ * message but exits 130 (143), also when the signal came during the wait.
+ *
  * @param url - Target URL
  * @param options - Session options
  * @param telemetry - Telemetry types
  * @param deps - How to reach the daemon (tests replace it)
- * @returns Start outcome, ready to report
+ * @param interrupt - Aborted (reason: the signal) on Ctrl-C or SIGTERM: the
+ *   start is cancelled and the daemon it spawned waited for like after a failure
+ * @returns Start outcome, ready to report (the interrupt is checked last)
  */
-export declare function attemptStart(url: string, options: SessionStartOptions, telemetry: TelemetryType[], deps?: StartDeps): Promise<StartOutcome>;
+export declare function attemptStart(url: string, options: SessionStartOptions, telemetry: TelemetryType[], deps?: StartDeps, interrupt?: AbortSignal): Promise<StartOutcome>;
 /**
  * Let the daemons a failed start spawned finish exiting before the error is
  * reported: a daemon removes its session files on the way out, and a command
@@ -82,5 +105,5 @@ export declare function attemptStart(url: string, options: SessionStartOptions,
  * @param waitMs - Milliseconds to wait at most for all of them
  * @returns The failure (without internal fields), with a hint when a daemon did not exit in time
  */
-export declare function afterSpawnedDaemonExit(outcome: StartOutcome, spawned: SpawnedDaemon[], waitMs: number): Promise<StartOutcome>;
+export declare function afterSpawnedDaemonExit(outcome: StartOutcome, spawned: Pick<SpawnedDaemon, 'pid' | 'hasExited'>[], waitMs: number): Promise<StartOutcome>;
 //# sourceMappingURL=startHelpers.d.ts.map