browser-debugger-cli 0.13.0 → 0.15.0

package/dist/commands/dom/formInteraction.js

@@ -58,7 +58,7 @@ export function registerFormInteractionCommands(program) {
         .command('fill')
         .description('Fill a form field with a value (React-compatible, waits for stability)')
         .argument('<selectorOrIndex>', SELECTOR_OR_INDEX_ARGUMENT)
-        .argument('<value>', 'Value to fill (file inputs: paths separated by commas, "" clears)')
+        .argument('<value>', 'Value to fill (file inputs: local file paths, separated by commas, that are uploaded to the page; "" clears)')
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
         .option('--no-blur', 'Do not blur after filling (keeps focus on element)')
         .option('--no-wait', 'Skip waiting for network stability after fill')

package/dist/commands/dom/get.js

@@ -9,12 +9,14 @@ import { DomElementResolver } from './DomElementResolver.js';
 import { getDOMElements, getDomContext, selectMatch, } from './helpers/index.js';
 import { formatSemanticNodeWithContext, resolveNodeWithFallback, } from './semanticUtils.js';
 import { runCommand } from '../shared/CommandRunner.js';
+import { MAX_VALUE_LENGTH } from '../../constants.js';
 import { CommandError } from '../../errors/index.js';
 import { conflictingOptionsError, indexWithIndexOptionError, nodeIdNotFoundError, optionRequiresError, } from '../../errors/messages.js';
 import { resolveA11yNode } from '../../telemetry/a11y.js';
 import { formatDomGet } from '../../ui/formatters/dom.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { filterDefined } from '../../utils/objects.js';
+import { capLength } from '../../utils/strings.js';
 /** What `bdg dom get` reads without a selector */
 export const DOM_GET_DEFAULT_SELECTOR = 'body';
 /**
@@ -58,7 +60,7 @@ async function semanticElement(backendNodeId, full) {
  * Raw view: the element(s) with attributes and outer HTML.
  *
  * @param selectorOrIndex - CSS selector or cached index
- * @param options - Command options (`--all`, `--index`)
+ * @param options - Command options (`--all`, `--index`, `--full`)
  */
 async function handleRawGet(selectorOrIndex, options) {
     await runCommand(async () => {
@@ -70,8 +72,27 @@ async function handleRawGet(selectorOrIndex, options) {
                 all: options.all,
                 nth: matchIndex(options),
             });
-        return { success: true, data: await getDOMElements(getOptions) };
-    }, options, formatDomGet);
+        return { success: true, data: rawGetData(await getDOMElements(getOptions), options) };
+    }, options, (data) => formatDomGet(data, { full: options.full }));
+}
+/**
+ * Raw elements for the output: in JSON each outer HTML is cut to
+ * {@link MAX_VALUE_LENGTH} characters with `truncatedFrom`, unless `--full`
+ * (human output is cut when formatted).
+ *
+ * @param result - Elements read
+ * @param options - `--json`, `--full`
+ * @returns Elements to output
+ */
+function rawGetData(result, options) {
+    if (!options.json || options.full)
+        return result;
+    return {
+        nodes: result.nodes.map((node) => {
+            const { text, truncatedFrom } = capLength(node.outerHTML ?? '', MAX_VALUE_LENGTH);
+            return truncatedFrom === undefined ? node : { ...node, outerHTML: text, truncatedFrom };
+        }),
+    };
 }
 /**
  * Semantic view of the target.
@@ -105,9 +126,6 @@ function getOptionsConflict(selectorOrIndex, options) {
     if (options.nodeId !== undefined && selectorOrIndex !== undefined) {
         return conflictingOptionsError('--node-id', 'a selector or index');
     }
-    if (options.full && (options.raw || options.nodeId !== undefined)) {
-        return conflictingOptionsError('--full', options.raw ? '--raw' : '--node-id');
-    }
     if (options.index !== undefined && options.nth !== undefined) {
         return conflictingOptionsError('--index', '--nth');
     }
@@ -134,7 +152,7 @@ export async function handleDomGet(selectorOrIndex, options) {
     }
     const { nodeId } = options;
     if (nodeId !== undefined) {
-        await runCommand(async () => ({ success: true, data: await getDOMElements({ nodeId }) }), options, formatDomGet);
+        await runCommand(async () => ({ success: true, data: rawGetData(await getDOMElements({ nodeId }), options) }), options, (data) => formatDomGet(data, { full: options.full }));
         return;
     }
     const target = selectorOrIndex ?? DOM_GET_DEFAULT_SELECTOR;

package/dist/commands/dom/helpers/evalResult.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Bounds of a `dom eval --json` result (#478): one eval must not put
+ * megabytes into an agent's context.
+ */
+/**
+ * The `result` of `dom eval --json`, and what was left out of it. A string
+ * `result` with `truncatedFrom` while `type` is `object` is the start of
+ * the value's JSON text, not a string the script returned.
+ */
+export interface BoundedEvalResult {
+    /** The value, its first elements, or the start of its (JSON) text */
+    result: unknown;
+    /** Elements of an array result in the page, set only when it was bounded */
+    count?: number;
+    /** Elements left out of a listed array result */
+    omitted?: number;
+    /**
+     * Length of the string, or of the JSON text of the copied object or array
+     * (which holds at most 1000 entries per list or object), `result` was cut from
+     */
+    truncatedFrom?: number;
+}
+/**
+ * Bound an eval result for JSON output: a string is cut to
+ * {@link MAX_VALUE_LENGTH} characters, an array keeps its first
+ * {@link EVAL_JSON_ARRAY_LIMIT} elements (with `count` and `omitted`), and
+ * an object or array whose JSON is still longer than the cap becomes the
+ * start of its JSON text (with `truncatedFrom`), so the output stays valid
+ * JSON. Small values are returned as they are.
+ *
+ * @param value - Evaluated value, as copied from the page
+ * @param length - Elements of an array result in the page (its copy may hold fewer)
+ * @returns `result`, with what was left out when bounded
+ */
+export declare function boundEvalResult(value: unknown, length?: number): BoundedEvalResult;
+//# sourceMappingURL=evalResult.d.ts.map

package/dist/commands/dom/helpers/evalResult.js

@@ -0,0 +1,59 @@
+/**
+ * Bounds of a `dom eval --json` result (#478): one eval must not put
+ * megabytes into an agent's context.
+ */
+import { EVAL_JSON_ARRAY_LIMIT, MAX_VALUE_LENGTH } from '../../../constants.js';
+import { capLength } from '../../../utils/strings.js';
+/**
+ * Bound an eval result for JSON output: a string is cut to
+ * {@link MAX_VALUE_LENGTH} characters, an array keeps its first
+ * {@link EVAL_JSON_ARRAY_LIMIT} elements (with `count` and `omitted`), and
+ * an object or array whose JSON is still longer than the cap becomes the
+ * start of its JSON text (with `truncatedFrom`), so the output stays valid
+ * JSON. Small values are returned as they are.
+ *
+ * @param value - Evaluated value, as copied from the page
+ * @param length - Elements of an array result in the page (its copy may hold fewer)
+ * @returns `result`, with what was left out when bounded
+ */
+export function boundEvalResult(value, length) {
+    if (typeof value === 'string') {
+        const { text, truncatedFrom } = capLength(value, MAX_VALUE_LENGTH);
+        return { result: text, ...(truncatedFrom !== undefined && { truncatedFrom }) };
+    }
+    if (Array.isArray(value))
+        return boundArray(value, length ?? value.length);
+    if (value === null || typeof value !== 'object')
+        return { result: value };
+    const json = JSON.stringify(value);
+    return json.length > MAX_VALUE_LENGTH ? jsonStart(json) : { result: value };
+}
+/**
+ * Bound an array result: its first {@link EVAL_JSON_ARRAY_LIMIT} elements,
+ * or the start of its JSON text when even those are over the cap.
+ *
+ * @param value - Array result
+ * @param count - Elements of the array in the page
+ * @returns `result` with `count`, and `omitted` or `truncatedFrom`
+ */
+function boundArray(value, count) {
+    const listed = value.slice(0, EVAL_JSON_ARRAY_LIMIT);
+    const listedJson = JSON.stringify(listed);
+    if (listedJson.length > MAX_VALUE_LENGTH) {
+        const json = listed.length === value.length ? listedJson : JSON.stringify(value);
+        return { ...jsonStart(json), count };
+    }
+    return listed.length < count
+        ? { result: listed, count, omitted: count - listed.length }
+        : { result: value };
+}
+/**
+ * The first {@link MAX_VALUE_LENGTH} characters of a JSON text.
+ *
+ * @param json - JSON text of an object or array over the cap
+ * @returns Its start, and the length of all of it
+ */
+function jsonStart(json) {
+    return { result: capLength(json, MAX_VALUE_LENGTH).text, truncatedFrom: json.length };
+}
+//# sourceMappingURL=evalResult.js.map

package/dist/commands/dom/index.js

@@ -31,6 +31,9 @@ import { handleDomScreenshot } from './screenshot.js';
 import { registerWaitCommand } from './wait.js';
 import { SELECTOR_OR_INDEX_ARGUMENT, SELECTOR_SCOPE_HELP, } from '../shared/commonOptions.js';
 import { integerOption, screenshotFormatOption } from '../shared/validation.js';
+import { MAX_VALUE_LENGTH, QUERY_JSON_LIST_LIMIT } from '../../constants.js';
+/** Help of `--full` on `dom eval` and the `eval` shortcut */
+const EVAL_FULL_HELP = `Print the whole value (default: the first ${MAX_VALUE_LENGTH} characters; a string result in JSON too)`;
 /**
  * Register DOM telemetry commands on the root Commander program.
  */
@@ -50,7 +53,7 @@ export function registerDomCommands(program) {
         .command('query')
         .description('Find elements by CSS selector')
         .argument('<selector>', 'CSS selector (e.g., ".error", "#app", "button")')
-        .option('--limit <n>', `Matches to list (default: ${QUERY_LIST_LIMIT}, ${QUERY_CACHE_LIMIT} with --json; 0 = all); the first ${QUERY_CACHE_LIMIT} (or more with a higher limit) are indexed`, integerOption(0))
+        .option('--limit <n>', `Matches to list (default: ${QUERY_LIST_LIMIT}, ${QUERY_JSON_LIST_LIMIT} with --json; 0 = all); the first ${QUERY_CACHE_LIMIT} (or more with a higher limit) are indexed`, integerOption(0))
         .option('-j, --json', 'Output as JSON')
         .addHelpText('after', SELECTOR_SCOPE_HELP)
         .action(async (selector, options) => {
@@ -61,6 +64,7 @@ export function registerDomCommands(program) {
         .description('Evaluate JavaScript expression in the page context')
         .argument('<script>', 'JavaScript to execute (e.g., "document.title", "window.location.href")')
         .option('--frame <frame>', 'Evaluate in an iframe, cross-origin ones included: index (from dom frames; 87 when stale), name/id attribute, or part of the name, id or URL')
+        .option('--full', EVAL_FULL_HELP)
         .option('-j, --json', 'Output as JSON')
         .action(async (script, options) => {
         await handleDomEval(script, options);
@@ -70,6 +74,7 @@ export function registerDomCommands(program) {
         .description('Shortcut for: bdg dom eval')
         .argument('<script>', 'JavaScript to execute')
         .option('--frame <frame>', 'Evaluate in an iframe (see dom frames)')
+        .option('--full', EVAL_FULL_HELP)
         .option('-j, --json', 'Output as JSON')
         .action(async (script, options) => {
         await handleDomEval(script, options);
@@ -86,7 +91,7 @@ export function registerDomCommands(program) {
         .description('Get semantic accessibility structure (default) or raw HTML (--raw)')
         .argument('[selectorOrIndex]', `${SELECTOR_OR_INDEX_ARGUMENT} (e.g. ".error", "#app", 0); default: ${DOM_GET_DEFAULT_SELECTOR}`)
         .option('--raw', 'Output raw HTML with all filtering options')
-        .option('--full', 'Show all of the element text (default: the first 500 characters)')
+        .option('--full', `Show all of the element text (default: the first 500 characters); with --raw, all of the HTML (default: the first ${MAX_VALUE_LENGTH} characters)`)
         .option('--all', 'Get all matches (only with --raw)')
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
         .addOption(new Option('--nth <n>', 'Alias of --index').argParser(integerOption(0)).hideHelp())

package/dist/commands/dom/query.d.ts

@@ -10,7 +10,8 @@ export declare const QUERY_LIST_LIMIT = 50;
  *
  * Runs the selector, caches the described matches so later commands can
  * reference elements by index, and lists the first `--limit` of them (50,
- * or {@link QUERY_CACHE_LIMIT} with `--json`; 0 = all) with the total count.
+ * or {@link QUERY_JSON_LIST_LIMIT} with `--json`; 0 = all) with the total
+ * count. The first {@link QUERY_CACHE_LIMIT} are indexed whatever is listed.
  * No match exits 83, like `dom get` and `dom a11y`, and clears the cache so
  * indices of an earlier query are not used by mistake.
  */

package/dist/commands/dom/query.js

@@ -2,8 +2,9 @@
  * `bdg dom query` — find elements by CSS selector and populate the query cache.
  */
 import { noMatchesError, pageDocumentId, queryDOMElements } from './helpers/index.js';
-import { QUERY_CACHE_LIMIT, VIEWPORT_HINT_LIMIT } from './helpers/query.js';
+import { VIEWPORT_HINT_LIMIT } from './helpers/query.js';
 import { runCommand } from '../shared/CommandRunner.js';
+import { QUERY_JSON_LIST_LIMIT } from '../../constants.js';
 import { QueryCacheManager } from '../../session/QueryCacheManager.js';
 import { formatDomQuery } from '../../ui/formatters/dom.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
@@ -14,12 +15,13 @@ export const QUERY_LIST_LIMIT = 50;
  *
  * Runs the selector, caches the described matches so later commands can
  * reference elements by index, and lists the first `--limit` of them (50,
- * or {@link QUERY_CACHE_LIMIT} with `--json`; 0 = all) with the total count.
+ * or {@link QUERY_JSON_LIST_LIMIT} with `--json`; 0 = all) with the total
+ * count. The first {@link QUERY_CACHE_LIMIT} are indexed whatever is listed.
  * No match exits 83, like `dom get` and `dom a11y`, and clears the cache so
  * indices of an earlier query are not used by mistake.
  */
 export async function handleDomQuery(selector, options) {
-    const limit = options.limit ?? (options.json ? QUERY_CACHE_LIMIT : QUERY_LIST_LIMIT);
+    const limit = options.limit ?? (options.json ? QUERY_JSON_LIST_LIMIT : QUERY_LIST_LIMIT);
     await runCommand(async () => {
         const document = await pageDocumentId();
         const result = await queryDOMElements(selector, limit);

package/dist/commands/dom/screenshot.js

@@ -189,6 +189,7 @@ async function handleSequenceCapture(outputDir, options) {
 /**
  * End a capture sequence on an error (e.g. the element disappeared): print
  * it (one JSON line with `--json`, like the frames) and exit with its code.
+ * It stays compact on a terminal too, since it ends the NDJSON frame stream.
  *
  * @param error - Capture error
  * @param captured - Frames captured before it

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

@@ -36,7 +36,7 @@ function convertOption(option, commandName) {
     if (option.argChoices) {
         metadata.choices = option.argChoices;
     }
-    const behavior = getOptionBehavior(commandName, option.flags);
+    const behavior = getOptionBehavior(commandName, option);
     if (behavior) {
         metadata.behavior = behavior;
     }
@@ -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/network/list.js

@@ -112,13 +112,51 @@ function buildFormatOptions(options, result, lastLimit) {
         totalCount: result.totalCount,
         filteredCount: result.filteredCount,
         ...(result.pageStart && { pageStart: result.pageStart }),
+        evictions: {
+            requestsDropped: result.dropped ?? 0,
+            bodiesEvicted: result.bodiesEvicted ?? 0,
+        },
+    };
+}
+/**
+ * Watch the session's dropped/evicted counts across follow polls, so the
+ * stream notes them once per kind instead of on every poll.
+ *
+ * @returns Function giving the counts when requests or bodies were let go
+ *   for the first time since the stream started, otherwise undefined
+ */
+function newEvictionKinds() {
+    let requestsNoted = false;
+    let bodiesNoted = false;
+    return (counts) => {
+        const newRequests = !requestsNoted && counts.requestsDropped > 0;
+        const newBodies = !bodiesNoted && counts.bodiesEvicted > 0;
+        requestsNoted ||= newRequests;
+        bodiesNoted ||= newBodies;
+        return newRequests || newBodies ? counts : undefined;
+    };
+}
+/**
+ * JSON fields of the dropped/evicted counts (the non-zero ones).
+ *
+ * @param counts - Counts to report, if any
+ * @returns `dropped` and `bodiesEvicted` when non-zero
+ */
+function evictionFields(counts) {
+    if (!counts)
+        return {};
+    return {
+        ...(counts.requestsDropped > 0 && { dropped: counts.requestsDropped }),
+        ...(counts.bodiesEvicted > 0 && { bodiesEvicted: counts.bodiesEvicted }),
     };
 }
 /**
  * Stream network requests: the last `lastN` finished ones at start, then
  * each request once, when it has finished loading or failed (a request whose
  * headers arrived but whose body is still loading waits), like `tail -f`,
- * with a warning (JSON `pageCrashedAt`) once when the page crashes.
+ * with a warning (JSON `pageCrashedAt`) once when the page crashes, and a
+ * note (JSON `dropped`, `bodiesEvicted`) the first time the session drops
+ * requests or evicts bodies at its limits.
  *
  * @param options - Command options
  * @param resourceTypes - Validated resource types
@@ -127,6 +165,7 @@ function buildFormatOptions(options, result, lastLimit) {
 async function runFollowMode(options, resourceTypes, lastN) {
     const shown = new Set();
     const newCrash = newPageCrashes();
+    const newEviction = newEvictionKinds();
     let started = false;
     const showNetwork = async () => {
         const result = await fetchNetworkRequests(filtersNeedHeaders(options));
@@ -136,6 +175,7 @@ async function runFollowMode(options, resourceTypes, lastN) {
         noteFollowConnected();
         const { requests } = result.data;
         const crashedAt = newCrash(result.data.pageCrashedAt);
+        const evictions = newEviction(result.data.evictions);
         const finished = filterRequests(requests, options, resourceTypes).filter((request) => request.duration !== undefined && !shown.has(request.requestId));
         const present = new Set(requests.map((request) => request.requestId));
         for (const id of shown)
@@ -144,12 +184,13 @@ async function runFollowMode(options, resourceTypes, lastN) {
         finished.forEach((request) => shown.add(request.requestId));
         const fresh = started || lastN === 0 ? finished : finished.slice(-lastN);
         if (options.json) {
-            if (!started || fresh.length > 0 || crashedAt !== undefined) {
+            if (!started || fresh.length > 0 || crashedAt !== undefined || evictions) {
                 const data = {
                     requests: fresh,
                     totalCount: requests.length,
                     filteredCount: fresh.length,
                     ...(crashedAt !== undefined && { pageCrashedAt: crashedAt }),
+                    ...evictionFields(evictions),
                 };
                 console.log(JSON.stringify(buildSuccessResponse(data)));
             }
@@ -160,6 +201,7 @@ async function runFollowMode(options, resourceTypes, lastN) {
                 header: !started,
                 verbose: options.verbose ?? false,
                 ...(pageStart && { pageStart }),
+                ...(evictions && { evictions }),
             });
             if (text)
                 console.log(text);
@@ -227,7 +269,7 @@ export function registerListCommand(networkCmd) {
                 }
                 return createErrorResult(result.error, result.exitCode, result.suggestion);
             }
-            const { requests, pageCrashedAt } = result.data;
+            const { requests, pageCrashedAt, evictions } = result.data;
             const filtered = filterRequests(requests, options, resourceTypes);
             const pageStart = pageStartOf(requests);
             return {
@@ -238,6 +280,7 @@ export function registerListCommand(networkCmd) {
                     filteredCount: filtered.length,
                     ...(pageStart && { pageStart }),
                     ...(pageCrashedAt !== undefined && { pageCrashedAt }),
+                    ...evictionFields(evictions),
                 },
             };
         }, options, (data) => withPageCrashedNote(formatNetworkList(data.requests, buildFormatOptions(options, data, lastN)), data.pageCrashedAt));

package/dist/commands/optionBehaviors.d.ts

@@ -6,13 +6,36 @@
  *
  * @see docs/principles/SELF_DOCUMENTING_SYSTEMS.md
  */
+import type { Option } from 'commander';
 import type { OptionBehavior } from './helpJson.js';
+/**
+ * Registry key format: last command name, colon, long flag (the short flag
+ * when there is no long one), e.g. "screenshot:--no-resize", "bdg:--headless"
+ */
+type BehaviorKey = string;
+/**
+ * Build behavior registry key from command and option: the command's own
+ * name (`bdg` for the root) and the option's long flag, or its short flag
+ * when it has no long one.
+ *
+ * @param commandName - Command name (e.g., "screenshot")
+ * @param option - Commander option
+ * @returns Registry key
+ */
+export declare function behaviorKey(commandName: string, option: Option): BehaviorKey;
+/**
+ * Every key in the behavior registry.
+ *
+ * @returns Registry keys
+ */
+export declare function listBehaviorKeys(): BehaviorKey[];
 /**
  * Look up behavioral metadata for an option.
  *
  * @param commandName - Name of the command containing the option
- * @param flags - Option flags string from Commander
+ * @param option - Commander option
  * @returns Behavioral metadata if registered, undefined otherwise
  */
-export declare function getOptionBehavior(commandName: string, flags: string): OptionBehavior | undefined;
+export declare function getOptionBehavior(commandName: string, option: Option): OptionBehavior | undefined;
+export {};
 //# sourceMappingURL=optionBehaviors.d.ts.map