browser-debugger-cli 0.12.0 → 0.14.0

package/dist/ui/formatters/cdp.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Human-readable output of `bdg cdp`: search results, domain and method
+ * lists, method schemas and method results (`--json` prints the data as is).
+ */
+import type { ParameterSchema, ReturnSchema } from '../../cdp/schema.js';
+/** Protocol description and flags shared by domains and methods */
+interface ProtocolEntry {
+    description?: string | undefined;
+    experimental?: boolean | undefined;
+    deprecated?: boolean | undefined;
+}
+/** A method in `bdg cdp --search` results */
+interface CdpSearchMethod extends ProtocolEntry {
+    name: string;
+    domain: string;
+    method: string;
+    parameterCount: number;
+    example?: string | undefined;
+}
+/** `bdg cdp --search <query>` result */
+export interface CdpSearchData {
+    query: string;
+    count: number;
+    methods: CdpSearchMethod[];
+}
+/** A domain in `bdg cdp --list` */
+interface CdpDomainEntry extends ProtocolEntry {
+    name: string;
+    commands: number;
+    events: number;
+    dependencies?: string[] | undefined;
+}
+/** `bdg cdp --list` result */
+export interface CdpDomainListData {
+    count: number;
+    domains: CdpDomainEntry[];
+}
+/** A method in `bdg cdp <Domain> --list` */
+interface CdpDomainMethod extends ProtocolEntry {
+    name: string;
+    fullName: string;
+    parameterCount: number;
+    parameters: Pick<ParameterSchema, 'name' | 'type' | 'required'>[];
+    returns: Pick<ReturnSchema, 'name' | 'type'>[];
+    example?: string | undefined;
+}
+/** `bdg cdp <Domain> --list` result */
+export interface CdpDomainMethodsData {
+    domain: string;
+    description?: string | undefined;
+    count: number;
+    methods: CdpDomainMethod[];
+}
+/** `bdg cdp <Domain> --describe` result */
+export interface CdpDomainDescription extends ProtocolEntry {
+    type: 'domain';
+    domain: string;
+    commands: number;
+    events: number;
+    note?: string | undefined;
+    nextStep: string;
+}
+/** A parameter or return value in `bdg cdp <Domain.method> --describe` */
+interface CdpField {
+    name: string;
+    type: string;
+    description?: string | undefined;
+    items?: string | undefined;
+}
+/** `bdg cdp <Domain.method> --describe` result */
+export interface CdpMethodDescription extends ProtocolEntry {
+    type: 'method';
+    name: string;
+    domain: string;
+    method: string;
+    note?: string | undefined;
+    parameters: (CdpField & {
+        required: boolean;
+        enum?: string[] | undefined;
+        deprecated?: boolean | undefined;
+    })[];
+    returns: (CdpField & {
+        optional: boolean;
+    })[];
+    example?: {
+        command: string;
+        params?: Record<string, unknown> | undefined;
+    } | undefined;
+}
+/** `bdg cdp <Domain.method>` result */
+export interface CdpExecuteData {
+    method: string;
+    result: unknown;
+}
+/**
+ * Format `bdg cdp --search <query>`.
+ *
+ * @param data - Search result
+ * @returns Matching methods with their first description sentence
+ */
+export declare function formatCdpSearch(data: CdpSearchData): string;
+/**
+ * Format `bdg cdp --list`.
+ *
+ * @param data - All domains
+ * @returns One line per domain with its method and event counts
+ */
+export declare function formatCdpDomains(data: CdpDomainListData): string;
+/**
+ * Format `bdg cdp <Domain> --list`.
+ *
+ * @param data - The domain's methods
+ * @returns One line per method with the first sentence of its description
+ */
+export declare function formatCdpDomainMethods(data: CdpDomainMethodsData): string;
+/**
+ * Format `bdg cdp <Domain.method> --describe` or `bdg cdp <Domain> --describe`.
+ *
+ * @param data - Method or domain description
+ * @returns Description, parameters (`?` = optional), returns, note and example
+ */
+export declare function formatCdpDescription(data: CdpMethodDescription | CdpDomainDescription): string;
+/**
+ * Whether a CDP method returned nothing (null, undefined or an empty object).
+ *
+ * @param result - Method result
+ * @returns True for an empty result
+ */
+export declare function isEmptyCdpResult(result: unknown): boolean;
+/**
+ * Format a CDP method's result: the result object as indented JSON.
+ *
+ * @param data - Method and its result
+ * @returns The result, or a line saying the method returned nothing
+ */
+export declare function formatCdpResult(data: CdpExecuteData): string;
+export {};
+//# sourceMappingURL=cdp.d.ts.map

package/dist/ui/formatters/cdp.js

@@ -0,0 +1,131 @@
+/**
+ * Human-readable output of `bdg cdp`: search results, domain and method
+ * lists, method schemas and method results (`--json` prints the data as is).
+ */
+import { joinLines, pluralize } from '../formatting.js';
+/**
+ * First sentence (or line) of a protocol description.
+ *
+ * @param description - Description, possibly multi-line
+ * @returns Its first sentence, or an empty string
+ */
+function firstSentence(description) {
+    const [line = ''] = (description ?? '').split('\n');
+    const end = line.indexOf('. ');
+    return end === -1 ? line : line.slice(0, end + 1);
+}
+/**
+ * `(experimental, deprecated)` tags, or nothing.
+ *
+ * @param flags - Protocol flags
+ * @returns Tag text with a leading space, or an empty string
+ */
+function tags(flags) {
+    const names = [flags.experimental && 'experimental', flags.deprecated && 'deprecated'].filter(Boolean);
+    return names.length > 0 ? ` (${names.join(', ')})` : '';
+}
+/**
+ * Rows of a name column padded to one width, then the rest.
+ *
+ * @param rows - Name and text of each row
+ * @returns Indented lines
+ */
+function columns(rows) {
+    const width = Math.max(0, ...rows.map(([name]) => name.length));
+    return rows.map(([name, text]) => `  ${name.padEnd(width)}  ${text.trim()}`.trimEnd());
+}
+/**
+ * A type as written in the schema, e.g. "array<Cookie>".
+ *
+ * @param field - Parameter or return value
+ * @returns Type text
+ */
+function typeText(field) {
+    return field.items ? `${field.type}<${field.items}>` : field.type;
+}
+/**
+ * Format `bdg cdp --search <query>`.
+ *
+ * @param data - Search result
+ * @returns Matching methods with their first description sentence
+ */
+export function formatCdpSearch(data) {
+    if (data.count === 0) {
+        return joinLines(`No CDP method matches "${data.query}"`, 'List the domains: bdg cdp --list');
+    }
+    return joinLines(`${pluralize(data.count, 'method')} ${data.count === 1 ? 'matches' : 'match'} "${data.query}":`, ...columns(data.methods.map((m) => [m.name, `${firstSentence(m.description)}${tags(m)}`])), 'Parameters and an example: bdg cdp <Domain.method> --describe');
+}
+/**
+ * Format `bdg cdp --list`.
+ *
+ * @param data - All domains
+ * @returns One line per domain with its method and event counts
+ */
+export function formatCdpDomains(data) {
+    return joinLines(`${pluralize(data.count, 'CDP domain')}:`, ...columns(data.domains.map((d) => [
+        d.name,
+        `${pluralize(d.commands, 'method')}, ${pluralize(d.events, 'event')}${tags(d)}`,
+    ])), 'Methods of a domain: bdg cdp <Domain> --list');
+}
+/**
+ * Format `bdg cdp <Domain> --list`.
+ *
+ * @param data - The domain's methods
+ * @returns One line per method with the first sentence of its description
+ */
+export function formatCdpDomainMethods(data) {
+    return joinLines(`${data.domain}: ${pluralize(data.count, 'method')}`, firstSentence(data.description) || undefined, ...columns(data.methods.map((m) => [m.name, `${firstSentence(m.description)}${tags(m)}`])), `Parameters and an example: bdg cdp ${data.domain}.<method> --describe`);
+}
+/**
+ * Lines of a parameter or return value list.
+ *
+ * @param title - Section title
+ * @param fields - Parameters or return values
+ * @returns Title and one line per field, or nothing for an empty list
+ */
+function fieldSection(title, fields) {
+    if (fields.length === 0)
+        return [];
+    return [
+        `${title}:`,
+        ...columns(fields.map((f) => [
+            `${f.name}${f.optional ? '?' : ''}: ${typeText(f)}`,
+            (f.description ?? '').replace(/\s*\n\s*/g, ' '),
+        ])),
+    ];
+}
+/**
+ * Format `bdg cdp <Domain.method> --describe` or `bdg cdp <Domain> --describe`.
+ *
+ * @param data - Method or domain description
+ * @returns Description, parameters (`?` = optional), returns, note and example
+ */
+export function formatCdpDescription(data) {
+    if (data.type === 'domain') {
+        return joinLines(`${data.domain}: ${pluralize(data.commands, 'method')}, ${pluralize(data.events, 'event')}${tags(data)}`, data.description, data.note, data.nextStep);
+    }
+    return joinLines(`${data.name}${tags(data)}`, data.description, ...fieldSection('Parameters', data.parameters.map((p) => ({ ...p, optional: !p.required }))), ...fieldSection('Returns', data.returns), data.note && `Note: ${data.note}`, data.example && `Example: ${data.example.command}`);
+}
+/**
+ * Whether a CDP method returned nothing (null, undefined or an empty object).
+ *
+ * @param result - Method result
+ * @returns True for an empty result
+ */
+export function isEmptyCdpResult(result) {
+    return (result === null ||
+        result === undefined ||
+        (typeof result === 'object' && Object.keys(result).length === 0));
+}
+/**
+ * Format a CDP method's result: the result object as indented JSON.
+ *
+ * @param data - Method and its result
+ * @returns The result, or a line saying the method returned nothing
+ */
+export function formatCdpResult(data) {
+    return isEmptyCdpResult(data.result)
+        ? `${data.method}: done (no result data)`
+        : JSON.stringify(data.result, null, 2);
+}
+//# sourceMappingURL=cdp.js.map

package/dist/ui/formatters/console/chronological.js

@@ -2,11 +2,11 @@
  * Chronological list view (--list mode): all messages with timestamps,
  * level prefixes, and navigation reload markers.
  */
+import { MAX_CONSOLE_TEXT_LENGTH } from '../../../constants.js';
+import { capForDisplay } from '../longValues.js';
 import { OutputFormatter } from '../../formatting.js';
-import { consoleIndexGapNote } from '../../messages/consoleMessages.js';
-import { truncateByLength } from '../../../utils/strings.js';
+import { consoleDroppedNote, consoleIndexGapNote } from '../../messages/consoleMessages.js';
 import { formatSourceLocation, formatTimestamp } from './shared.js';
-const MAX_LIST_TEXT_LENGTH = 200;
 /**
  * Format console output as chronological list (--list mode).
  *
@@ -22,6 +22,8 @@ export function formatConsoleChronological(messages, options) {
         : `Console Messages (last ${displayMessages.length} of ${messages.length})${headerSuffix}`;
     fmt.text(header);
     fmt.separator('━', 50);
+    if (options.dropped)
+        fmt.text(consoleDroppedNote(options.dropped));
     if (displayMessages.length === 0) {
         fmt.text('No console messages');
         return fmt.build();
@@ -44,8 +46,8 @@ export function formatConsoleChronological(messages, options) {
             }
             lastNavigationId = msg.navigationId;
         }
-        const truncatedText = truncateByLength(msg.text, MAX_LIST_TEXT_LENGTH);
-        fmt.text(`${index}  ${level} ${time}  ${truncatedText}`);
+        const text = capForDisplay(msg.text, MAX_CONSOLE_TEXT_LENGTH, options.full);
+        fmt.text(`${index}  ${level} ${time}  ${text}`);
         const source = formatSourceLocation(msg.stackTrace);
         if (source) {
             fmt.text(`${sourceIndent}→ ${source}`);

package/dist/ui/formatters/console/follow.d.ts

@@ -5,14 +5,17 @@
 import type { ConsoleMessage } from '../../../types.js';
 /**
  * Lines of the console stream: the new messages since the last poll, with
- * the stream header the first time and a separator after a navigation.
+ * a rule the first time (the stream banner is on stderr) and a separator
+ * after a navigation. Texts are cut like `console --list` cuts them.
  *
  * @param messages - New messages
- * @param options - `header` the first time; `navigationId` when the page changed
+ * @param options - `header` the first time; `navigationId` when the page
+ *   changed; `full` to print the texts whole
  * @returns Text to print (empty when there is nothing new)
  */
 export declare function formatConsoleFollowLines(messages: ConsoleMessage[], options?: {
     header?: boolean;
     navigationId?: number;
+    full?: boolean | undefined;
 }): string;
 //# sourceMappingURL=follow.d.ts.map

package/dist/ui/formatters/console/follow.js

@@ -2,20 +2,23 @@
  * Follow-mode (live streaming) view. Compact format optimised for
  * repeated polling output.
  */
+import { MAX_CONSOLE_TEXT_LENGTH } from '../../../constants.js';
+import { capForDisplay } from '../longValues.js';
 import { OutputFormatter } from '../../formatting.js';
 import { formatSourceLocation, formatTimestamp } from './shared.js';
 /**
  * Lines of the console stream: the new messages since the last poll, with
- * the stream header the first time and a separator after a navigation.
+ * a rule the first time (the stream banner is on stderr) and a separator
+ * after a navigation. Texts are cut like `console --list` cuts them.
  *
  * @param messages - New messages
- * @param options - `header` the first time; `navigationId` when the page changed
+ * @param options - `header` the first time; `navigationId` when the page
+ *   changed; `full` to print the texts whole
  * @returns Text to print (empty when there is nothing new)
  */
 export function formatConsoleFollowLines(messages, options = {}) {
     const fmt = new OutputFormatter();
     if (options.header) {
-        fmt.text('Streaming console... (Ctrl+C to stop)');
         fmt.separator('━', 40);
         if (messages.length === 0)
             fmt.text('Waiting for messages...');
@@ -26,7 +29,7 @@ export function formatConsoleFollowLines(messages, options = {}) {
     for (const msg of messages) {
         const time = formatTimestamp(msg.timestamp);
         const level = msg.type.padEnd(7);
-        fmt.text(`${time} ${level} ${msg.text}`);
+        fmt.text(`${time} ${level} ${capForDisplay(msg.text, MAX_CONSOLE_TEXT_LENGTH, options.full)}`);
         const source = formatSourceLocation(msg.stackTrace);
         if (source)
             fmt.text(`                → ${source}`);

package/dist/ui/formatters/console/json.d.ts

@@ -6,16 +6,13 @@
 import type { ConsoleMessage } from '../../../types.js';
 import { type ConsoleFormatOptions, type ConsoleJsonOutput } from './shared.js';
 /**
- * Build the rich JSON output shape (summary + deduped errors/warnings, plus
- * the full message list when --list is requested).
+ * Build the rich JSON output shape (summary + the newest deduped
+ * errors/warnings, plus the message list when --list is requested). Texts
+ * longer than 10000 characters are cut with
+ * `truncatedFrom`, unless `--full`.
  *
  * Returns a plain object so callers (e.g. runCommand's JSON envelope) can
  * embed it without re-parsing a stringified payload.
  */
 export declare function buildConsoleJsonOutput(messages: ConsoleMessage[], options: ConsoleFormatOptions): ConsoleJsonOutput;
-/**
- * Format console output as a JSON string. Thin wrapper around
- * buildConsoleJsonOutput for callers that want a serialized payload.
- */
-export declare function formatConsoleJson(messages: ConsoleMessage[], options: ConsoleFormatOptions): string;
 //# sourceMappingURL=json.d.ts.map

package/dist/ui/formatters/console/json.js

@@ -4,7 +4,7 @@
  * --list is set.
  */
 import { lastMessages } from './chronological.js';
-import { analyzeMessages, } from './shared.js';
+import { analyzeMessages, capMessageText, newestGroups, } from './shared.js';
 function toJsonError(dedup, includeStackTrace) {
     const source = dedup.message.stackTrace?.[0];
     return {
@@ -25,28 +25,30 @@ function toJsonError(dedup, includeStackTrace) {
     };
 }
 /**
- * Build the rich JSON output shape (summary + deduped errors/warnings, plus
- * the full message list when --list is requested).
+ * Build the rich JSON output shape (summary + the newest deduped
+ * errors/warnings, plus the message list when --list is requested). Texts
+ * longer than 10000 characters are cut with
+ * `truncatedFrom`, unless `--full`.
  *
  * Returns a plain object so callers (e.g. runCommand's JSON envelope) can
  * embed it without re-parsing a stringified payload.
  */
 export function buildConsoleJsonOutput(messages, options) {
     const { grouped, summary } = analyzeMessages(messages);
+    const errors = newestGroups(grouped.errors, options.groupLimit);
+    const warnings = newestGroups(grouped.warnings, options.groupLimit);
     const output = {
         summary,
-        errors: grouped.errors.map((d) => toJsonError(d, true)),
-        warnings: grouped.warnings.map((d) => toJsonError(d, false)),
+        errors: errors.shown.map((d) => capMessageText(toJsonError(d, true), options.full)),
+        warnings: warnings.shown.map((d) => capMessageText(toJsonError(d, false), options.full)),
+        ...(errors.more > 0 && { moreErrors: errors.more }),
+        ...(warnings.more > 0 && { moreWarnings: warnings.more }),
+        ...(options.dropped && { dropped: options.dropped }),
+        ...(options.pageCrashedAt !== undefined && { pageCrashedAt: options.pageCrashedAt }),
     };
-    if (options.list)
-        output.messages = lastMessages(messages, options.last);
+    if (options.list) {
+        output.messages = lastMessages(messages, options.last).map((message) => capMessageText(message, options.full));
+    }
     return output;
 }
-/**
- * Format console output as a JSON string. Thin wrapper around
- * buildConsoleJsonOutput for callers that want a serialized payload.
- */
-export function formatConsoleJson(messages, options) {
-    return JSON.stringify(buildConsoleJsonOutput(messages, options), null, 2);
-}
 //# sourceMappingURL=json.js.map

package/dist/ui/formatters/console/shared.d.ts

@@ -43,8 +43,6 @@ export interface ConsoleSummary {
  * Options for console formatting.
  */
 export interface ConsoleFormatOptions {
-    /** Output as JSON */
-    json?: boolean | undefined;
     /** List all messages chronologically (--list flag) */
     list?: boolean | undefined;
     /** Follow mode (live streaming) */
@@ -57,7 +55,29 @@ export interface ConsoleFormatOptions {
     level?: ConsoleLevel | undefined;
     /** Messages between the first and last listed index that the filters left out */
     skipped?: ConsoleSkipped | undefined;
+    /** Distinct errors and warnings listed, the newest (0 = all; default {@link DEFAULT_GROUP_LIMIT}) */
+    groupLimit?: number | undefined;
+    /** Oldest messages the session dropped at its limit */
+    dropped?: number | undefined;
+    /** When the page crashed (epoch ms), while it is not loaded again */
+    pageCrashedAt?: number | undefined;
+    /** Print message texts whole (`--full`) */
+    full?: boolean | undefined;
 }
+/** Distinct errors and warnings the summary lists without `--last` */
+export declare const DEFAULT_GROUP_LIMIT = 50;
+/**
+ * The newest distinct messages of a level, and how many earlier ones are not
+ * listed.
+ *
+ * @param groups - Distinct messages, in order of first appearance
+ * @param limit - How many to keep (0 = all; undefined: {@link DEFAULT_GROUP_LIMIT})
+ * @returns Groups to list and the count left out
+ */
+export declare function newestGroups(groups: DeduplicatedMessage[], limit: number | undefined): {
+    shown: DeduplicatedMessage[];
+    more: number;
+};
 /**
  * Messages the page and level filters left out between the first and last
  * listed index (session indices then skip numbers).
@@ -75,6 +95,8 @@ export interface JsonErrorEntry {
     count: number;
     level: string;
     text: string;
+    /** Original length of `text` when it was cut (`--full` keeps it whole) */
+    truncatedFrom?: number;
     /** Position in the session's message list (what `details console <n>` takes) */
     index?: number;
     /** Where it came from; no line/column for a resource URL (e.g. a failed load) */
@@ -90,8 +112,18 @@ export interface JsonErrorEntry {
  */
 export interface ConsoleJsonOutput {
     summary: ConsoleSummary;
+    /** The newest distinct errors (see `moreErrors`) */
     errors: JsonErrorEntry[];
+    /** The newest distinct warnings (see `moreWarnings`) */
     warnings: Omit<JsonErrorEntry, 'stackTrace'>[];
+    /** Earlier distinct errors not in `errors` (`--last 0` lists all) */
+    moreErrors?: number;
+    /** Earlier distinct warnings not in `warnings` */
+    moreWarnings?: number;
+    /** Oldest messages the session dropped at its limit (10000 are kept) */
+    dropped?: number;
+    /** When the page crashed (epoch ms), while it is not loaded again */
+    pageCrashedAt?: number;
     messages?: ConsoleMessage[];
 }
 /**
@@ -145,4 +177,17 @@ export declare function formatSectionHeader(label: string, unique: number, total
  * @returns Location text
  */
 export declare function formatFramePosition(frame: StackFrame): string;
+/**
+ * A console message (or error entry) for JSON output: its text cut to
+ * {@link MAX_CONSOLE_JSON_TEXT_LENGTH} characters with `truncatedFrom`, or
+ * whole with `--full`.
+ *
+ * @param message - Message with a text
+ * @param full - `--full`: keep the text whole
+ * @returns The message, with the text cut when too long
+ */
+export declare function capMessageText<T extends {
+    text: string;
+    truncatedFrom?: number;
+}>(message: T, full: boolean | undefined): T;
 //# sourceMappingURL=shared.d.ts.map

package/dist/ui/formatters/console/shared.js

@@ -1,6 +1,24 @@
 /**
  * Shared types, constants, and helpers used by every console formatter.
  */
+import { MAX_CONSOLE_JSON_TEXT_LENGTH } from '../../../constants.js';
+import { capLength } from '../../../utils/strings.js';
+/** Distinct errors and warnings the summary lists without `--last` */
+export const DEFAULT_GROUP_LIMIT = 50;
+/**
+ * The newest distinct messages of a level, and how many earlier ones are not
+ * listed.
+ *
+ * @param groups - Distinct messages, in order of first appearance
+ * @param limit - How many to keep (0 = all; undefined: {@link DEFAULT_GROUP_LIMIT})
+ * @returns Groups to list and the count left out
+ */
+export function newestGroups(groups, limit) {
+    const keep = limit ?? DEFAULT_GROUP_LIMIT;
+    if (keep === 0 || groups.length <= keep)
+        return { shown: groups, more: 0 };
+    return { shown: groups.slice(-keep), more: groups.length - keep };
+}
 /**
  * Mapping from console message types to level categories.
  * Exported for use by console command filtering.
@@ -155,4 +173,19 @@ export function formatFramePosition(frame) {
         ? frame.url
         : `${frame.url}:${frame.lineNumber + 1}:${frame.columnNumber + 1}`;
 }
+/**
+ * A console message (or error entry) for JSON output: its text cut to
+ * {@link MAX_CONSOLE_JSON_TEXT_LENGTH} characters with `truncatedFrom`, or
+ * whole with `--full`.
+ *
+ * @param message - Message with a text
+ * @param full - `--full`: keep the text whole
+ * @returns The message, with the text cut when too long
+ */
+export function capMessageText(message, full) {
+    if (full)
+        return message;
+    const { text, truncatedFrom } = capLength(message.text, MAX_CONSOLE_JSON_TEXT_LENGTH);
+    return truncatedFrom === undefined ? message : { ...message, text, truncatedFrom };
+}
 //# sourceMappingURL=shared.js.map

package/dist/ui/formatters/console/summarize.d.ts

@@ -3,8 +3,15 @@
  * and shows info/debug/other as count-only footer entries.
  */
 import type { ConsoleMessage } from '../../../types.js';
+import { type ConsoleFormatOptions } from './shared.js';
 /**
- * Format console output as smart summary (default mode).
+ * Format console output as smart summary (default mode): the newest distinct
+ * errors and warnings, counts of the rest, and a note when the session
+ * dropped its oldest messages.
+ *
+ * @param messages - Messages to summarise
+ * @param options - Distinct messages listed, messages dropped and `--full`
+ * @returns Summary
  */
-export declare function formatConsoleSummary(messages: ConsoleMessage[]): string;
+export declare function formatConsoleSummary(messages: ConsoleMessage[], options?: Pick<ConsoleFormatOptions, 'groupLimit' | 'dropped' | 'full'>): string;
 //# sourceMappingURL=summarize.d.ts.map