browser-debugger-cli 0.13.0 → 0.14.0

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/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.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;
     }

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

package/dist/commands/optionBehaviors.js

@@ -65,8 +65,9 @@ const OPTION_BEHAVIORS = {
     },
     'get:--full': {
         default: 'Semantic output shows the element text up to 500 characters (whitespace collapsed; close buttons such as "×" and aria-hidden icons left out)',
-        whenEnabled: 'Shows all of the element text; cannot be combined with --raw or --node-id',
-        tokenImpact: 'A page-sized container can add thousands of tokens; target the element you need',
+        whenEnabled: 'Shows all of the element text; with --raw (or --node-id) prints the whole outer HTML instead of its first 20000 characters, and JSON outerHTML is whole too (else cut to 20000 with truncatedFrom, the original length)',
+        automaticBehavior: 'Without --full, --raw output cuts each element\'s HTML at 20000 characters and ends it with "… N more chars (use --full)"',
+        tokenImpact: 'A page-sized container can add thousands of tokens; dom get body --raw --full on Wikipedia is about 3.4 MB. Target the element you need',
     },
     'get:--all': {
         default: 'Returns first matching element only',
@@ -78,30 +79,42 @@ const OPTION_BEHAVIORS = {
         automaticBehavior: 'Past the last match exits 81; a numeric index argument (a cached query index) past the indexed matches, or from an earlier page, exits 87 (re-run dom query)',
     },
     'query:--limit': {
-        default: 'dom query and dom a11y query list the first 50 matches and say how many more there are; --json returns 1000 (dom query) or all of them (dom a11y query)',
+        default: 'dom query and dom a11y query list the first 50 matches and say how many more there are; --json lists the first 100 with count (all matches) and omitted (the rest)',
         whenEnabled: 'Lists that many matches (0 = all), in human and JSON output; count is always the total, JSON omitted the rest',
         automaticBehavior: 'Matches are cached for index-based access (bdg dom click 55 works even when 50 are listed): all of them for dom a11y query, the first 1000 (or --limit, if higher) for dom query, which describes only those, so a page with 50000 matches answers in under a second; an element the page and frame trees both report is listed once. Indices work with click, fill, hover, pressKey, scroll, submit, layout, get and listeners, also for elements of a cross-origin iframe of the same site (a consent dialog), whose scripts then run in that frame',
-        tokenImpact: 'About one line per match; a page can have hundreds of links',
+        tokenImpact: 'About one line per match (piped JSON about 160 bytes per dom query match, 230 per a11y match); a page can have thousands of links: on Wikipedia "United States" --limit 0 --json is 1.0 MB (dom query a) and 1.3 MB (dom a11y query role:link), the default 16 KB and 23 KB',
+    },
+    'tree:--limit': {
+        default: 'dom a11y tree lists the first 50 meaningful nodes depth-first, in human and JSON output; JSON count is the whole tree = nodes listed + omitted (cut by --limit/--depth) + skipped (never listed)',
+        whenEnabled: 'Lists that many nodes; 0 = all listed nodes (text boxes and empty wrappers are always skipped)',
+        automaticBehavior: 'Ignored nodes, text boxes, blank text, text repeating its parent name and nameless layout wrappers (generic, none, presentation, layout tables) are never listed (JSON skipped counts them); their children move up a level. For the raw tree with every node use bdg cdp Accessibility.getFullAXTree --json. JSON nodes carry depth (0 = root) instead of childIds; nodes outside the root (frame content) follow the root tree',
+        tokenImpact: 'About 140 bytes per piped JSON node (7 KB by default); the whole tree of a long page is megabytes (Wikipedia "United States": 51k nodes, 20k listed, 2.6 MB with --limit 0 --json), so prefer --depth or dom a11y query "role:<role>"',
+    },
+    'tree:--depth': {
+        default: 'dom a11y tree lists every level (up to --limit nodes)',
+        whenEnabled: 'Lists nodes down to that level (0 = root only); deeper nodes are counted in omitted',
+        tokenImpact: 'An outline of a page (landmarks, headings) in a few levels',
     },
     'eval:--frame': {
         default: "Evaluates in the page's main frame",
         whenEnabled: "Evaluates in one iframe's main world (its own globals), including cross-origin (out-of-process) iframes; output gains a frame field (its URL)",
         automaticBehavior: 'The value is matched as: a 0-based index (bdg dom frames order: 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.',
     },
-    'console:-H': {
-        default: 'Shows messages from current page load only (most recent navigation)',
-        whenEnabled: 'Shows messages from ALL page loads during the session',
-        automaticBehavior: 'Page navigations create new "navigation contexts" - default filters to latest context',
+    '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',
+    },
+    '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)',
+        whenEnabled: 'Message texts are printed whole, in human and JSON output',
+        tokenImpact: 'A page that logs a large payload or throws a long error can add megabytes; bdg details console <n> shows one message whole',
     },
     'console:--history': {
         default: 'Shows messages from current page load only (most recent navigation)',
         whenEnabled: 'Shows messages from ALL page loads during the session',
         automaticBehavior: 'Page navigations create new "navigation contexts" - default filters to latest context',
     },
-    'console:-l': {
-        default: 'Smart summary with errors deduplicated and warnings grouped: the newest 50 distinct errors and warnings, with a note for the earlier ones. The session keeps the newest 10000 messages; dropped ones are counted (dropped in JSON)',
-        whenEnabled: 'Lists all messages chronologically without deduplication',
-    },
     'console:--list': {
         default: 'Smart summary with errors deduplicated and warnings grouped: the newest 50 distinct errors and warnings, with a note for the earlier ones. The session keeps the newest 10000 messages; dropped ones are counted (dropped in JSON)',
         whenEnabled: 'Lists all messages chronologically without deduplication',
@@ -253,6 +266,7 @@ const OPTION_BEHAVIORS = {
     },
     'inspect:--no-hints': {
         default: "Hints at the element's own author declarations that have no effect (flex/grid properties without flex or grid, item properties without a flex or grid parent, offsets on static elements, sizes on inline ones, var() of an unset custom property, form controls in the browser's font), within a 1 s budget; hints none when nothing was found",
+        automaticBehavior: "After a hint read times out, later inspects on the same page skip the hints without waiting (hints skipped: this page's stylesheets are slow to read) until a read is fast again, a stylesheet changes or it navigates; --rules and --why still wait up to 5 s. Matched rules that took over 300 ms are reused for up to 5 s, until a command that may change the page or a stylesheet or DOM change",
         whenEnabled: 'Skips the hints and does not read the matched rules',
     },
     'scroll:--down': {
@@ -293,56 +307,52 @@ const OPTION_BEHAVIORS = {
         whenEnabled: 'Quick scan: field names, types, and required status only',
         tokenImpact: 'Reduces output ~50% for initial discovery',
     },
+    'peek:--full': {
+        default: 'Console message texts are cut: human output at 200 characters (compact output also at 2 lines) followed by "… N more chars (use --full)"; JSON text at 10000 characters with truncatedFrom (the original length)',
+        whenEnabled: 'Console message texts are printed whole, in human and JSON output',
+        tokenImpact: 'A page that logs a large payload can add megabytes per peek',
+    },
     'peek:--type': {
         whenEnabled: 'Filters network requests by CDP resource type. Case-insensitive, comma-separated. Valid: Document, Stylesheet, Image, Media, Font, Script, XHR, Fetch, WebSocket, etc.',
     },
-    'peek:-f': {
-        default: 'Shows snapshot of current data',
-        whenEnabled: 'Continuous monitoring (like tail -f): refreshes every second, or every --interval ms (100-60000). Replaces the deprecated bdg tail',
-        automaticBehavior: FOLLOW_BEHAVIOR,
-    },
     'peek:--follow': {
         default: 'Shows snapshot of current data',
         whenEnabled: 'Continuous monitoring (like tail -f): refreshes every second, or every --interval ms (100-60000). Replaces the deprecated bdg tail',
         automaticBehavior: FOLLOW_BEHAVIOR,
     },
-    'console:-f': {
+    'console:--follow': {
         default: 'Prints the messages logged so far and exits',
         whenEnabled: 'Streams new messages as they come (the last --last at start)',
         automaticBehavior: FOLLOW_BEHAVIOR,
     },
-    'list:-f': {
+    'list:--follow': {
         default: 'Lists the requests captured so far and exits',
         whenEnabled: 'Streams requests as they finish',
         automaticBehavior: FOLLOW_BEHAVIOR,
     },
-    'peek:-v': {
+    'peek:--verbose': {
         default: 'Compact output (truncated URLs, no resource types)',
         whenEnabled: 'Verbose output with full URLs and resource types',
     },
-    'start:--headless': {
+    'bdg:--headless': {
         default: 'A window when there is a display: on macOS unless over SSH (SSH_CONNECTION, SSH_TTY) or CI is set; on Linux when DISPLAY or WAYLAND_DISPLAY is set. Servers, containers and CI run headless',
         whenEnabled: 'Chrome runs without a window (pass it when running unattended on a Mac)',
     },
-    'start:--no-headless': {
+    'bdg:--no-headless': {
         default: 'A window when there is a display: on macOS unless over SSH (SSH_CONNECTION, SSH_TTY) or CI is set; on Linux when DISPLAY or WAYLAND_DISPLAY is set',
         whenEnabled: 'Chrome shows its window even without a detected display (it fails without one)',
     },
-    'start:--all': {
+    'bdg:--all': {
         default: 'Tracking/analytics requests and console noise are filtered; bodies of binary responses (images, fonts) are not captured',
         whenEnabled: 'Everything is captured, including binary response bodies (base64, flagged by responseBodyBase64, within --max-body-size)',
         tokenImpact: 'details network --json and HAR exports can grow considerably on media-heavy pages',
     },
-    'peek:--verbose': {
-        default: 'Compact output (truncated URLs, no resource types)',
-        whenEnabled: 'Verbose output with full URLs and resource types',
-    },
     'bdg:--session': {
         default: 'The default session in ~/.bdg (or $BDG_SESSION_DIR); BDG_SESSION=<name> selects a named session like the flag',
         whenEnabled: 'Uses the named session in ~/.bdg/sessions/<name>/ (or $BDG_SESSION_DIR/sessions/<name>/) with its own daemon, Chrome, profile and port; every command (status, stop, cleanup, ...) acts on that session only',
         automaticBehavior: 'Accepted before or after any subcommand; --session wins over BDG_SESSION. Names are case-insensitive (lower-cased: ALPHA is alpha). Without --port a named session takes the first free port above 9222 not claimed by another running session, and keeps it in port.txt. Names: 1-40 letters, digits, "-" or "_", starting with a letter or digit (exit 81 otherwise, also when the socket path would be too long). Hints and suggestions in its output carry --session <name>',
     },
-    'cleanup:-f': {
+    'cleanup:--force': {
         default: 'Refuses to run while a session is active; removes files left by a crashed session',
         whenEnabled: 'Kills the running daemon and its Chrome first (use when a session is stuck)',
     },
@@ -377,36 +387,39 @@ const OPTION_BEHAVIORS = {
         default: 'Chrome launched by bdg is always closed on stop; an attached Chrome (--chrome-ws-url) is left running',
         whenEnabled: 'No additional effect; kept for compatibility',
     },
-    'status:-v': {
-        default: 'Basic session status (daemon running, session active, URL)',
-        whenEnabled: 'Includes Chrome diagnostics and CDP connection details',
-    },
     'status:--verbose': {
         default: 'Basic session status (daemon running, session active, URL)',
         whenEnabled: 'Includes Chrome diagnostics and CDP connection details',
     },
 };
 /**
- * Build behavior registry key from command and flag.
+ * 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 flags - Option flags string (e.g., "--no-resize")
+ * @param option - Commander option
  * @returns Registry key
  */
-function buildKey(commandName, flags) {
-    const firstFlag = flags.split(',')[0] ?? flags;
-    const flagName = firstFlag.trim().split(' ')[0] ?? firstFlag.trim();
-    return `${commandName}:${flagName}`;
+export function behaviorKey(commandName, option) {
+    return `${commandName}:${option.long ?? option.short ?? option.flags}`;
+}
+/**
+ * Every key in the behavior registry.
+ *
+ * @returns Registry keys
+ */
+export function listBehaviorKeys() {
+    return Object.keys(OPTION_BEHAVIORS);
 }
 /**
  * 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 function getOptionBehavior(commandName, flags) {
-    const key = buildKey(commandName, flags);
-    return OPTION_BEHAVIORS[key];
+export function getOptionBehavior(commandName, option) {
+    return OPTION_BEHAVIORS[behaviorKey(commandName, option)];
 }
 //# sourceMappingURL=optionBehaviors.js.map

package/dist/commands/peek.js

@@ -8,6 +8,7 @@ import { fetchPreviewOutput, createErrorResult, } from './shared/dataFetcher.js'
 import { followFetchFailure, setupFollowMode, } from './shared/followMode.js';
 import { handleValidationError } from './shared/handleValidationError.js';
 import { MAX_LAST_ITEMS, positiveIntRule, resourceTypeRule } from './shared/validation.js';
+import { MAX_CONSOLE_JSON_TEXT_LENGTH, MAX_CONSOLE_TEXT_LENGTH } from '../constants.js';
 import { CommandError } from '../errors/index.js';
 import { intervalWithoutFollowError } from '../errors/messages.js';
 import { filterByResourceType } from '../telemetry/filters.js';
@@ -137,6 +138,7 @@ function previewDisplayOptions(options, lastN) {
         last: lastN,
         verbose: options.verbose,
         follow: options.follow,
+        full: options.full,
     };
 }
 /**
@@ -162,6 +164,7 @@ export function registerPeekCommand(program) {
         .option('--interval <ms>', 'Refresh interval of --follow in ms, 100-60000 (default: 1000)')
         .option('--last <count>', 'Show last N items, 0 for all', '10')
         .option('--type <types>', 'Filter network requests by resource type (comma-separated: Document,XHR,Fetch,etc.)')
+        .option('--full', `Print console message texts whole (default: the first ${MAX_CONSOLE_TEXT_LENGTH} characters, ${MAX_CONSOLE_JSON_TEXT_LENGTH} in JSON)`, false)
         .action(async (options) => {
         showBothSectionsWhenBothRequested(options);
         if (options.network && !options.json) {

package/dist/commands/shared/CommandRunner.js

@@ -2,7 +2,7 @@ import { getQuickIPCRequestTimeout } from '../../constants.js';
 import { CommandError, isDaemonConnectionError } from '../../errors/index.js';
 import { daemonNotRunningError, unknownError, genericError, commandTimedOutError, sessionNotRespondingError, sessionEndedDuringCommandError, } from '../../errors/messages.js';
 import { IPCEarlyCloseError, IPCTimeoutError } from '../../ipc/transport/IPCError.js';
-import { OutputBuilder, buildSuccessResponse } from '../../ui/OutputBuilder.js';
+import { OutputBuilder, buildSuccessResponse, stringifyEnvelope } from '../../ui/OutputBuilder.js';
 import { escapeControlChars } from '../../ui/formatting.js';
 import { noActiveSessionMessage, startSessionSuggestion } from '../../ui/messages/sessionCommand.js';
 import { getErrorExitCode, getErrorMessage } from '../../utils/errors.js';
@@ -36,7 +36,7 @@ export function noActiveSessionError() {
 export async function runJsonCommand(fn) {
     try {
         const data = await fn();
-        console.log(JSON.stringify(buildSuccessResponse(data), null, 2));
+        console.log(stringifyEnvelope(buildSuccessResponse(data)));
         process.exit(EXIT_CODES.SUCCESS);
     }
     catch (caught) {
@@ -49,10 +49,10 @@ export async function runJsonCommand(fn) {
         const suggestion = error instanceof CommandError && typeof error.metadata['suggestion'] === 'string'
             ? error.metadata['suggestion']
             : undefined;
-        console.log(JSON.stringify(OutputBuilder.buildJsonError(getErrorMessage(error), {
+        console.log(stringifyEnvelope(OutputBuilder.buildJsonError(getErrorMessage(error), {
             exitCode,
             ...(suggestion && { suggestion }),
-        }), null, 2));
+        })));
         process.exit(exitCode);
     }
 }
@@ -112,10 +112,10 @@ export async function runCommand(handler, options, formatter) {
         if (!result.success) {
             const exitCode = result.exitCode ?? EXIT_CODES.UNHANDLED_EXCEPTION;
             if (options.json) {
-                console.log(JSON.stringify(OutputBuilder.buildJsonError(result.error ?? 'Unknown error', {
+                console.log(stringifyEnvelope(OutputBuilder.buildJsonError(result.error ?? 'Unknown error', {
                     ...result.errorContext,
                     exitCode,
-                }), null, 2));
+                })));
             }
             else {
                 console.error(result.error ? genericError(result.error) : unknownError());
@@ -133,14 +133,14 @@ export async function runCommand(handler, options, formatter) {
             console.error(escapeControlChars(result.hint));
         }
         if (options.json) {
-            console.log(JSON.stringify(buildSuccessResponse(result.data), null, 2));
+            console.log(stringifyEnvelope(buildSuccessResponse(result.data)));
         }
         else if (formatter) {
             const formattedOutput = formatter(result.data);
             console.log(escapeControlChars(formattedOutput));
         }
         else {
-            console.log(JSON.stringify(buildSuccessResponse(result.data), null, 2));
+            console.log(stringifyEnvelope(buildSuccessResponse(result.data)));
         }
         process.exit(EXIT_CODES.SUCCESS);
     }
@@ -152,10 +152,10 @@ export async function runCommand(handler, options, formatter) {
                 : caught;
         if (error instanceof CommandError) {
             if (options.json) {
-                console.log(JSON.stringify(OutputBuilder.buildJsonError(error.message, {
+                console.log(stringifyEnvelope(OutputBuilder.buildJsonError(error.message, {
                     ...error.metadata,
                     exitCode: error.exitCode,
-                }), null, 2));
+                })));
             }
             else {
                 console.error(genericError(error.message));
@@ -168,10 +168,10 @@ export async function runCommand(handler, options, formatter) {
         const errorMessage = getErrorMessage(error);
         if (isDaemonConnectionError(error)) {
             if (options.json) {
-                console.log(JSON.stringify(OutputBuilder.buildJsonError(noActiveSessionMessage(), {
+                console.log(stringifyEnvelope(OutputBuilder.buildJsonError(noActiveSessionMessage(), {
                     suggestion: startSessionSuggestion(),
                     exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
-                }), null, 2));
+                })));
             }
             else {
                 console.error(daemonNotRunningError());
@@ -180,7 +180,7 @@ export async function runCommand(handler, options, formatter) {
         }
         const exitCode = getErrorExitCode(error, EXIT_CODES.UNHANDLED_EXCEPTION);
         if (options.json) {
-            console.log(JSON.stringify(OutputBuilder.buildJsonError(errorMessage, { exitCode }), null, 2));
+            console.log(stringifyEnvelope(OutputBuilder.buildJsonError(errorMessage, { exitCode })));
         }
         else {
             console.error(genericError(errorMessage));