browser-debugger-cli 0.7.2 → 0.9.0

package/dist/commands/console.d.ts

@@ -2,9 +2,45 @@
  * Console command for inspecting and filtering console messages.
  */
 import { type Command } from 'commander';
+import type { ConsoleCommandOptions } from './shared/optionTypes.js';
 import type { ConsoleMessage } from '../types.js';
-import { type ConsoleLevel } from '../ui/formatters/console.js';
-export declare function filterByCurrentNavigation(messages: ConsoleMessage[]): ConsoleMessage[];
+import { type ConsoleLevel, type ConsoleSkipped } from '../ui/formatters/console.js';
+/**
+ * Whether to list the messages instead of summarising them: with `--list`,
+ * and when `--last` asks for a number of them.
+ *
+ * @param options - Command options
+ * @returns True to list
+ */
+export declare function listsMessages(options: Pick<ConsoleCommandOptions, 'list' | 'last'>): boolean;
+/**
+ * Keep the messages of the page currently loaded.
+ *
+ * @param messages - All captured messages
+ * @param currentNavigationId - Navigation id of the current page; when unknown,
+ *   the newest navigation id among the messages is used
+ * @returns Messages of the current page (empty if it logged nothing)
+ */
+export declare function filterByCurrentNavigation(messages: ConsoleMessage[], currentNavigationId?: number): ConsoleMessage[];
 export declare function filterByLevel(messages: ConsoleMessage[], level: ConsoleLevel): ConsoleMessage[];
+/**
+ * Messages the filters left out between the first and the last listed
+ * message (their session indices skip them), by why: logged by another page
+ * load, or of another level.
+ *
+ * @param all - All messages of the session
+ * @param listed - Messages listed
+ * @returns Counts per reason
+ */
+export declare function skippedMessages(all: ConsoleMessage[], listed: ConsoleMessage[]): ConsoleSkipped;
+/**
+ * Identity of each message across polls (its index can shift when an earlier
+ * message is inserted late). Identical messages logged in the same
+ * millisecond are told apart by their order.
+ *
+ * @param messages - Messages in order
+ * @returns One key per message
+ */
+export declare function messageKeys(messages: ConsoleMessage[]): string[];
 export declare function registerConsoleCommand(program: Command): void;
 //# sourceMappingURL=console.d.ts.map

package/dist/commands/console.js

@@ -2,92 +2,144 @@
  * Console command for inspecting and filtering console messages.
  */
 import { Option } from 'commander';
-import { runCommand } from '../commands/shared/CommandRunner.js';
-import { jsonOption } from '../commands/shared/commonOptions.js';
-import { handleDaemonConnectionError } from '../commands/shared/daemonErrorHandler.js';
-import { fetchConsoleMessages, createErrorResult } from '../commands/shared/dataFetcher.js';
-import { setupFollowMode } from '../commands/shared/followMode.js';
-import { positiveIntRule } from '../commands/shared/validation.js';
-import { OutputBuilder } from '../ui/OutputBuilder.js';
-import { CommandError } from '../ui/errors/index.js';
-import { formatConsole, formatConsoleFollow, LEVEL_MAP, } from '../ui/formatters/console.js';
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
+import { noteFollowConnected } from './shared/daemonErrorHandler.js';
+import { fetchConsoleMessages, createErrorResult } from './shared/dataFetcher.js';
+import { followFetchFailure, setupFollowMode, } from './shared/followMode.js';
+import { handleValidationError } from './shared/handleValidationError.js';
+import { consoleLevelOption, positiveIntRule } from './shared/validation.js';
+import { buildSuccessResponse } from '../ui/OutputBuilder.js';
+import { buildConsoleJsonOutput, formatConsole, formatConsoleFollowLines, LEVEL_MAP, lastMessages, } from '../ui/formatters/console.js';
 import { followingConsoleMessage, stoppedFollowingConsoleMessage, } from '../ui/messages/consoleMessages.js';
-import { EXIT_CODES } from '../utils/exitCodes.js';
 const MIN_LAST = 0;
 const MAX_LAST = 10000;
 const DEFAULT_LAST = 100;
-const FOLLOW_LIMIT = 20;
-const VALID_LEVELS = ['error', 'warning', 'info', 'debug'];
-const consoleLastOption = new Option('--last <n>', `Show last N console messages (0 = all, default: ${DEFAULT_LAST})`).default(String(DEFAULT_LAST));
+const consoleLastOption = new Option('--last <n>', `List the last N console messages (0 = all; default: ${DEFAULT_LAST} with --list or --follow)`);
 /**
- * Handle validation errors with proper JSON/human formatting.
+ * Whether to list the messages instead of summarising them: with `--list`,
+ * and when `--last` asks for a number of them.
  *
- * @param error - Error from validation
- * @param json - Whether to output JSON format
+ * @param options - Command options
+ * @returns True to list
  */
-function handleValidationError(error, json) {
-    if (error instanceof CommandError) {
-        if (json) {
-            const errorOptions = {
-                exitCode: error.exitCode,
-            };
-            if (error.metadata.suggestion) {
-                errorOptions.suggestion = error.metadata.suggestion;
-            }
-            console.log(JSON.stringify(OutputBuilder.buildJsonError(error.message, errorOptions)));
-        }
-        else {
-            console.error(error.message);
-            if (error.metadata.suggestion)
-                console.error(error.metadata.suggestion);
-        }
-        process.exit(error.exitCode);
-    }
-    console.error(error instanceof Error ? error.message : String(error));
-    process.exit(EXIT_CODES.INVALID_ARGUMENTS);
+export function listsMessages(options) {
+    return options.list === true || options.last !== undefined;
 }
-export function filterByCurrentNavigation(messages) {
+/**
+ * Keep the messages of the page currently loaded.
+ *
+ * @param messages - All captured messages
+ * @param currentNavigationId - Navigation id of the current page; when unknown,
+ *   the newest navigation id among the messages is used
+ * @returns Messages of the current page (empty if it logged nothing)
+ */
+export function filterByCurrentNavigation(messages, currentNavigationId) {
     if (messages.length === 0)
         return messages;
-    const maxNavId = Math.max(...messages.map((m) => m.navigationId ?? 0));
-    return messages.filter((m) => m.navigationId === maxNavId);
+    const navId = currentNavigationId ?? Math.max(...messages.map((m) => m.navigationId ?? 0));
+    return messages.filter((m) => (m.navigationId ?? 0) === navId);
 }
 export function filterByLevel(messages, level) {
     return messages.filter((m) => LEVEL_MAP[m.type] === level);
 }
-function applyFilters(messages, options) {
-    let filtered = options.history ? messages : filterByCurrentNavigation(messages);
+function applyFilters(messages, options, currentNavigationId) {
+    let filtered = options.history
+        ? messages
+        : filterByCurrentNavigation(messages, currentNavigationId);
     if (options.level)
         filtered = filterByLevel(filtered, options.level);
     return filtered;
 }
-function buildFormatOptions(options, lastN) {
+/**
+ * Messages the filters left out between the first and the last listed
+ * message (their session indices skip them), by why: logged by another page
+ * load, or of another level.
+ *
+ * @param all - All messages of the session
+ * @param listed - Messages listed
+ * @returns Counts per reason
+ */
+export function skippedMessages(all, listed) {
+    const shown = new Set(listed.map((message) => message.index));
+    const indices = listed.map((message) => message.index).filter((index) => index !== undefined);
+    const skipped = { otherPages: 0, otherLevels: 0 };
+    if (indices.length < 2)
+        return skipped;
+    const [first, last] = [Math.min(...indices), Math.max(...indices)];
+    const pages = new Set(listed.map((message) => message.navigationId));
+    for (const { index, navigationId } of all) {
+        if (index === undefined || index < first || index > last || shown.has(index))
+            continue;
+        if (pages.has(navigationId))
+            skipped.otherLevels++;
+        else
+            skipped.otherPages++;
+    }
+    return skipped;
+}
+/**
+ * Formatting options from the command options.
+ *
+ * @param options - Command options
+ * @param lastN - `--last` value
+ * @param skipped - Messages the filters left out between the listed ones
+ * @returns Formatting options
+ */
+function buildFormatOptions(options, lastN, skipped) {
     return {
         json: options.json,
-        list: options.list,
+        list: listsMessages(options),
         follow: options.follow,
         last: lastN,
         history: options.history,
         level: options.level,
+        skipped,
     };
 }
-async function runFollowMode(options) {
+/**
+ * Stream console messages: the last `lastN` at start, then each new message
+ * once (like `tail -f`), with a separator when the page navigates.
+ *
+ * @param options - Command options
+ * @param lastN - Messages to show at start (0 = all)
+ */
+async function runFollowMode(options, lastN) {
+    const shown = new Set();
+    let navigationId;
+    let started = false;
     const showConsole = async () => {
         const result = await fetchConsoleMessages();
         if (!result.success) {
-            const errorResult = handleDaemonConnectionError(result.error, {
-                json: options.json,
-                follow: true,
-                retryIntervalMs: 1000,
-                exitCode: result.exitCode,
+            return followFetchFailure(result, { json: options.json, retryIntervalMs: 1000 });
+        }
+        noteFollowConnected();
+        const { messages, currentNavigationId } = result.data;
+        const matching = applyFilters(messages, options, currentNavigationId);
+        const keys = messageKeys(matching);
+        const fresh = matching.filter((_message, i) => !shown.has(keys[i]));
+        const backlog = started || lastN === 0 ? fresh : fresh.slice(-lastN);
+        shown.clear();
+        keys.forEach((key) => shown.add(key));
+        const navigated = started && navigationId !== currentNavigationId;
+        navigationId = currentNavigationId;
+        if (options.json) {
+            if (!started || backlog.length > 0) {
+                const data = buildConsoleJsonOutput(backlog, { list: true, last: 0 });
+                console.log(JSON.stringify(buildSuccessResponse(data), null, 2));
+            }
+        }
+        else {
+            const text = formatConsoleFollowLines(backlog, {
+                header: !started,
+                ...(navigated &&
+                    currentNavigationId !== undefined && { navigationId: currentNavigationId }),
             });
-            if (errorResult.shouldExit)
-                process.exit(errorResult.exitCode);
-            return;
+            if (text)
+                console.log(text);
         }
-        const filtered = applyFilters(result.data, options);
-        console.clear();
-        console.log(formatConsoleFollow(filtered.slice(-FOLLOW_LIMIT)));
+        started = true;
+        return undefined;
     };
     await setupFollowMode(showConsole, {
         startMessage: followingConsoleMessage,
@@ -95,6 +147,23 @@ async function runFollowMode(options) {
         intervalMs: 1000,
     });
 }
+/**
+ * Identity of each message across polls (its index can shift when an earlier
+ * message is inserted late). Identical messages logged in the same
+ * millisecond are told apart by their order.
+ *
+ * @param messages - Messages in order
+ * @returns One key per message
+ */
+export function messageKeys(messages) {
+    const seen = new Map();
+    return messages.map((message) => {
+        const base = `${message.timestamp}|${message.type}|${message.navigationId ?? ''}|${message.text}`;
+        const occurrence = (seen.get(base) ?? 0) + 1;
+        seen.set(base, occurrence);
+        return `${base}#${occurrence}`;
+    });
+}
 export function registerConsoleCommand(program) {
     program
         .command('console')
@@ -102,29 +171,45 @@ export function registerConsoleCommand(program) {
         .addOption(new Option('-l, --list', 'List all messages chronologically').default(false))
         .addOption(new Option('-f, --follow', 'Stream console messages in real-time').default(false))
         .addOption(new Option('-H, --history', 'Show messages from all page loads (default: current only)').default(false))
-        .addOption(new Option('--level <level>', 'Filter by message level (error, warning, info, debug)').choices(VALID_LEVELS))
+        .addOption(new Option('--level <level>', 'Filter by message level: error, warning, info (includes log), debug; any case').argParser(consoleLevelOption))
         .addOption(consoleLastOption)
         .addOption(jsonOption())
         .action(async (options) => {
         let lastN;
         try {
-            lastN = positiveIntRule({ min: MIN_LAST, max: MAX_LAST, default: DEFAULT_LAST }).validate(options.last);
+            lastN = positiveIntRule({
+                name: '--last',
+                min: MIN_LAST,
+                max: MAX_LAST,
+                default: DEFAULT_LAST,
+            }).validate(options.last);
         }
         catch (error) {
             handleValidationError(error, options.json ?? false);
         }
         if (options.follow) {
-            await runFollowMode(options);
+            await runFollowMode(options, lastN);
             return;
         }
         await runCommand(async () => {
             const result = await fetchConsoleMessages();
             if (!result.success) {
-                return createErrorResult(result.error, result.exitCode);
+                return createErrorResult(result.error, result.exitCode, result.suggestion);
+            }
+            const { messages, currentNavigationId } = result.data;
+            const filtered = applyFilters(messages, options, currentNavigationId);
+            if (options.json) {
+                return {
+                    success: true,
+                    data: buildConsoleJsonOutput(filtered, buildFormatOptions(options, lastN)),
+                };
             }
-            const filtered = applyFilters(result.data, options);
-            return { success: true, data: { messages: result.data, filtered } };
-        }, options, (data) => formatConsole(data.filtered, buildFormatOptions(options, lastN)));
+            return { success: true, data: { messages, filtered } };
+        }, options, (data) => {
+            const { messages, filtered } = data;
+            const skipped = skippedMessages(messages, lastMessages(filtered, lastN));
+            return formatConsole(filtered, buildFormatOptions(options, lastN, skipped));
+        });
     });
 }
 //# sourceMappingURL=console.js.map

package/dist/commands/details.js

@@ -1,8 +1,9 @@
-import { runCommand } from '../commands/shared/CommandRunner.js';
-import { jsonOption } from '../commands/shared/commonOptions.js';
+import { runCommand } from './shared/CommandRunner.js';
+import { jsonOption } from './shared/commonOptions.js';
 import { getDetails } from '../ipc/client.js';
 import { validateIPCResponse } from '../ipc/index.js';
 import { formatNetworkDetails, formatConsoleDetails } from '../ui/formatters/details.js';
+import { sessionCommand } from '../ui/messages/sessionCommand.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 import { validateDetailsItem } from '../utils/typeGuards.js';
 /**
@@ -46,6 +47,16 @@ export function registerDetailsCommand(program) {
                     },
                 };
             }
+            if (!opts.id.trim()) {
+                return {
+                    success: false,
+                    error: `The ${opts.type === 'network' ? 'request id' : 'message index'} is empty`,
+                    exitCode: EXIT_CODES.INVALID_ARGUMENTS,
+                    errorContext: {
+                        suggestion: 'Usage: bdg details network <requestId> or bdg details console <index>',
+                    },
+                };
+            }
             const response = await getDetails(opts.type, opts.id);
             validateIPCResponse(response);
             if (!response.data?.item) {
@@ -55,8 +66,8 @@ export function registerDetailsCommand(program) {
                     exitCode: EXIT_CODES.RESOURCE_NOT_FOUND,
                     errorContext: {
                         suggestion: opts.type === 'network'
-                            ? 'Use bdg peek --network to see available request IDs'
-                            : 'Use bdg peek --console to see available console message indices',
+                            ? `Use ${sessionCommand('bdg network list')} to see available request IDs`
+                            : `Use ${sessionCommand('bdg peek --console')} to see available console message indices`,
                     },
                 };
             }

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

@@ -1,41 +1,41 @@
 /**
  * DOM element resolver for index and selector-based access.
  *
- * Provides centralized resolution of DOM elements from:
- * - Numeric indices (referencing cached query results)
- * - CSS selectors (used directly)
- *
- * Handles cache validation, staleness detection, and automatic refresh.
- * When cache is stale due to navigation, automatically re-runs the original
- * query to provide seamless "just works" experience.
+ * A numeric argument is an index into the last `bdg dom query` / `bdg dom form`
+ * result and resolves to that exact element (its backend node id). Whether the
+ * element still exists is checked where it is used: if the page navigated or
+ * the element was removed, commands fail with exit 87 instead of acting on a
+ * different element that happens to match the selector now.
  *
  * @example
  * ```typescript
  * const resolver = DomElementResolver.getInstance();
  *
- * // Resolve index from cached query
- * const target = await resolver.resolve('0');
- * // { success: true, selector: '.cached-selector', index: 1 }
+ * const target = await resolver.resolve('0', undefined, 'click');
+ * // { success: true, selector: '.cached-selector', backendNodeId: 42 }
  *
- * // Resolve CSS selector directly
- * const target = await resolver.resolve('button.submit');
+ * const target = await resolver.resolve('button.submit', undefined, 'click');
  * // { success: true, selector: 'button.submit' }
- *
- * // Get nodeId for cached index (throws if invalid)
- * const nodeId = await resolver.getNodeIdForIndex(0);
  * ```
  */
 import { QueryCacheManager } from '../../session/QueryCacheManager.js';
+import type { IndexSource } from '../../types.js';
 /**
  * Successful result of resolving a selector or index argument.
  */
 export interface ElementTargetSuccess {
     /** Resolution succeeded */
     success: true;
-    /** CSS selector to use */
+    /** CSS selector (for an index: the selector shown to the user) */
     selector: string;
-    /** 0-based index for selector (if resolved from cached query) */
+    /** 0-based index among the selector's matches (selector arguments only) */
     index?: number | undefined;
+    /** Exact element from the query cache (index arguments only) */
+    backendNodeId?: number | undefined;
+    /** The list the index refers to (index arguments only) */
+    source?: IndexSource | undefined;
+    /** What the cached element was when listed, e.g. `h3 "Welcome"` (index arguments only) */
+    preview?: string | undefined;
 }
 /**
  * Failed result of resolving a selector or index argument.
@@ -52,14 +52,10 @@ export interface ElementTargetFailure {
 }
 /**
  * Result of resolving a selector or index argument to an element target.
- * Discriminated union that guarantees selector exists when success is true.
  */
 export type ElementTargetResult = ElementTargetSuccess | ElementTargetFailure;
 /**
  * Singleton resolver for DOM element access patterns.
- *
- * Centralizes element resolution with cache validation, automatic refresh,
- * and consistent error handling.
  */
 export declare class DomElementResolver {
     private static instance;
@@ -70,16 +66,6 @@ export declare class DomElementResolver {
      * @param cacheManager - Query cache manager (defaults to singleton)
      */
     constructor(cacheManager?: QueryCacheManager);
-    /**
-     * Refresh stale cache by re-running the original query.
-     *
-     * Called automatically when cache validation fails due to navigation.
-     * Re-queries using the stored selector and updates the cache with fresh results.
-     *
-     * @param selector - Original CSS selector from stale cache
-     * @returns Fresh query result
-     */
-    private refreshCache;
     /**
      * Get the singleton instance.
      *
@@ -93,56 +79,24 @@ export declare class DomElementResolver {
     /**
      * Resolve a selectorOrIndex argument to an element target.
      *
-     * Handles the common pattern of accepting either:
-     * - A CSS selector string (used directly)
-     * - A numeric index (resolved from cached query results)
-     *
-     * Automatically refreshes stale cache by re-running the original query.
-     * This provides a "just works" experience where navigation doesn't break
-     * index-based access.
-     *
      * @param selectorOrIndex - CSS selector or numeric index from query results
-     * @param explicitIndex - Optional explicit --index flag value (0-based)
-     * @returns Resolution result with selector and optional index
-     *
-     * @example
-     * ```typescript
-     * const target = await resolver.resolve('button');
-     * // { success: true, selector: 'button' }
-     *
-     * const target = await resolver.resolve('0');
-     * // { success: true, selector: '.cached-selector', index: 1 }
-     * ```
+     * @param explicitIndex - Optional explicit --index flag value (0-based, selectors only)
+     * @param command - `bdg dom` subcommand being run, e.g. "click" (for suggestions)
+     * @returns Resolution result
      */
-    resolve(selectorOrIndex: string, explicitIndex?: number): Promise<ElementTargetResult>;
+    resolve(selectorOrIndex: string, explicitIndex: number | undefined, command: string): Promise<ElementTargetResult>;
     /**
-     * Get nodeId for a cached index.
-     *
-     * Automatically refreshes stale cache by re-running the original query.
-     * Throws CommandError only if refresh fails or index is out of range after refresh.
+     * Get the backend node id for a cached index, checking the element still exists.
      *
      * @param index - Zero-based index from query results
-     * @returns Node with nodeId from cache
-     * @throws CommandError if cache missing, index out of range after refresh, or node not found
-     *
-     * @example
-     * ```typescript
-     * const node = await resolver.getNodeIdForIndex(0);
-     * console.log(node.nodeId); // CDP node ID
-     * ```
+     * @returns Cached node; `nodeId` is its backend node id
+     * @throws CommandError if there is no usable cache, the index is out of range,
+     *   or the element is no longer in the page (87)
      */
     getNodeIdForIndex(index: number): Promise<{
         nodeId: number;
+        source: IndexSource;
     }>;
-    /**
-     * Get the count of cached elements.
-     *
-     * Automatically refreshes stale cache by re-running the original query.
-     *
-     * @returns Number of cached elements
-     * @throws CommandError if cache is missing or refresh fails
-     */
-    getElementCount(): Promise<number>;
     /**
      * Check if the argument is a numeric index.
      *
@@ -150,5 +104,13 @@ export declare class DomElementResolver {
      * @returns True if the string is a numeric index
      */
     isNumericIndex(selectorOrIndex: string): boolean;
+    /**
+     * Find a cached node by index.
+     *
+     * @param index - Zero-based index
+     * @returns Cached node and the query's selector
+     * @throws CommandError (83) without a session, (81) without a usable cache, (87) for an index outside the cached results
+     */
+    private lookup;
 }
 //# sourceMappingURL=DomElementResolver.d.ts.map