browser-debugger-cli 0.7.1 → 0.8.0

package/dist/ui/formatters/requestStatus.js

@@ -0,0 +1,55 @@
+/**
+ * Shared status labels for network requests.
+ *
+ * A request is pending until it completes or fails. Status 0 means it failed
+ * without any response (DNS, refused, aborted, blocked); a request that got a
+ * response keeps its HTTP status even if loading failed afterwards.
+ */
+/**
+ * Classify a request.
+ *
+ * @param request - Captured request
+ * @returns Its lifecycle state
+ */
+export function getRequestState(request) {
+    if (request.status === undefined)
+        return 'pending';
+    return request.status === 0 ? 'failed' : 'complete';
+}
+/**
+ * Why a request failed, leaving out Chrome stopping an unneeded body after a
+ * complete response (204/304 report `net::ERR_ABORTED` that way).
+ *
+ * @param request - Captured request
+ * @returns Reason, or undefined when there is none worth showing
+ */
+export function failureReason(request) {
+    if (!request.errorText)
+        return undefined;
+    return getRequestState(request) === 'complete' && request.errorText === BODY_ABORTED
+        ? undefined
+        : request.errorText;
+}
+/**
+ * Human-readable status: the HTTP status (with the failure reason if loading
+ * failed after the response), `FAILED (<reason>)`, or `pending`.
+ *
+ * @param request - Captured request
+ * @returns Status label
+ */
+export function formatRequestStatus(request) {
+    const state = getRequestState(request);
+    if (state === 'pending')
+        return 'pending';
+    if (state === 'failed')
+        return `FAILED (${request.errorText ?? 'no response'})`;
+    return request.errorText && request.errorText !== BODY_ABORTED
+        ? `${request.status} (${request.errorText})`
+        : String(request.status);
+}
+/**
+ * Error Chrome reports when it stops reading a response body nobody needs
+ * (the response itself arrived; not a failure of the request).
+ */
+const BODY_ABORTED = 'net::ERR_ABORTED';
+//# sourceMappingURL=requestStatus.js.map

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

@@ -2,7 +2,7 @@
  * Semantic output formatter for accessibility trees.
  *
  * Converts accessibility tree to token-optimized Markdown-style format.
- * Used by dom get, peek --dom, and session.json output.
+ * Used by dom get.
  */
 import type { A11yTree } from '../../types.js';
 /**

package/dist/ui/formatters/semantic.js

@@ -2,7 +2,7 @@
  * Semantic output formatter for accessibility trees.
  *
  * Converts accessibility tree to token-optimized Markdown-style format.
- * Used by dom get, peek --dom, and session.json output.
+ * Used by dom get.
  */
 /**
  * Format accessibility tree as semantic output.

package/dist/ui/formatters/sessionFormatters.js

@@ -4,7 +4,8 @@
  * Provides well-structured, TSDoc'd helpers for building each section
  * of the landing page, organized by priority (high-level commands first).
  */
-import { section } from '../../ui/formatting.js';
+import { getProtocolCounts } from '../../cdp/schema.js';
+import { section } from '../formatting.js';
 /**
  * Builds the common tasks section showing task-to-command mappings.
  *
@@ -37,16 +38,17 @@ export function buildDomainCommandsSection() {
         '  bdg dom query <selector>          Query elements (returns JSON)',
         '  bdg dom get <selector|index>      Get element details',
         '  bdg dom eval <javascript>         Execute JavaScript in page context',
-        '  bdg dom screenshot [path]         Capture full page screenshot',
+        '  bdg dom screenshot <path>         Capture full page screenshot',
         '  bdg dom fill <selector> <value>   Fill form input',
         '  bdg dom click <selector>          Click element',
         '  bdg dom pressKey <selector> <key> Press key (Enter, Tab, Escape, etc.)',
-        '  bdg dom a11y [selector]           Accessibility tree',
+        '  bdg dom a11y [search]             Accessibility search (tree, query, describe)',
+        '  bdg dom listeners <selector>      Event listeners (incl. delegated)',
         '',
         'Network:',
         '  bdg network har [path]            Export HTTP Archive (HAR)',
         '  bdg network getCookies            List all cookies',
-        '  bdg network headers <id>          HTTP headers for request',
+        '  bdg network headers [id]          HTTP headers (default: main document)',
         '',
         'Console:',
         '  bdg console [options]             Query console logs',
@@ -79,7 +81,7 @@ export function buildSessionManagementSection() {
     return section('Session Management:', [
         'bdg status        Check session state',
         'bdg status --verbose     Include Chrome diagnostics',
-        'bdg stop          End session & save output',
+        'bdg stop          End session',
         'bdg cleanup       Clean stale sessions',
     ]);
 }
@@ -93,9 +95,10 @@ export function buildSessionManagementSection() {
  * @returns Formatted CDP section
  */
 export function buildCdpSection() {
-    return section('Advanced: Raw CDP Access (53 domains, 300+ methods):', [
+    const counts = getProtocolCounts();
+    return section(`Advanced: Raw CDP Access (${counts.domains} domains, ${counts.methods} methods):`, [
         'bdg cdp --list                      List all domains',
-        'bdg cdp Network --list              List Network methods (39 methods)',
+        `bdg cdp Network --list              List Network methods (${counts.methodsIn('Network')} methods)`,
         'bdg cdp --search cookie             Search methods by keyword',
         'bdg cdp Runtime.evaluate --params \'{"expression":"document.title"}\'',
         '',
@@ -112,7 +115,7 @@ export function buildCdpSection() {
 export function buildDiscoverySection() {
     return section('Discovery (for AI agents):', [
         'bdg --help --json          Machine-readable schema (commands, options, exit codes)',
-        '.claude/skills/bdg/        Claude skill with 15+ recipes & patterns',
+        'bdg cdp --search <term>    Find CDP methods by keyword',
     ]);
 }
 //# sourceMappingURL=sessionFormatters.js.map

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

@@ -1,11 +1,14 @@
 import type { SessionActivity, PageState } from '../../ipc/index.js';
+import { type RunningChromeInfo } from '../../session/chrome.js';
+import type { LastSessionEnd } from '../../session/lastSession.js';
 import type { SessionMetadata } from '../../session/metadata.js';
 export interface StatusData {
-    version: string;
     active: boolean;
     bdgPid?: number;
     chromePid?: number | undefined;
     chromeAlive?: boolean;
+    /** Attached to a Chrome bdg did not launch (`--chrome-ws-url`); it has no known PID */
+    externalChrome?: boolean;
     startTime?: number;
     duration?: number;
     durationFormatted?: string;
@@ -13,19 +16,34 @@ export interface StatusData {
     targetId?: string | undefined;
     webSocketDebuggerUrl?: string | undefined;
     telemetry?: string[];
+    /** When `--timeout` stops the session (ISO time) */
+    autoStopAt?: string;
     stale?: boolean;
     stalePid?: number;
     warning?: string;
     activity?: SessionActivity;
     pageState?: PageState;
+    /** Set while `bdg <url>` is starting a session */
+    starting?: {
+        url: string;
+        since: number;
+    };
+    /** The session's Chrome (`--verbose`) */
+    chrome?: RunningChromeInfo;
+    /** The session is shutting down */
+    ending?: boolean;
+    /** How the last session ended, when not by `bdg stop` */
+    lastSession?: LastSessionEnd;
+    /** Chrome of an earlier session that is still running (no session owns it) */
+    orphanedChromePid?: number;
 }
 /**
  * Format session status for human-readable output
  * @param metadata - Session metadata
  * @param pid - BDG process ID
- * @param activity - Live activity metrics from worker
- * @param pageState - Current page state from worker
- * @param verbose - Show detailed Chrome diagnostics
+ * @param activity - Live activity metrics from the session
+ * @param pageState - Current page state from the session
+ * @param verbose - Also show the session's Chrome executable, mode and profile
  */
 export declare function formatSessionStatus(metadata: SessionMetadata, pid: number, activity?: SessionActivity, pageState?: PageState, verbose?: boolean): string;
 /**
@@ -35,5 +53,5 @@ export declare function formatStatusAsJson(metadata: SessionMetadata | null, pid
 /**
  * Format "no session" message
  */
-export declare function formatNoSessionMessage(): string;
+export declare function formatNoSessionMessage(data?: StatusData): string;
 //# sourceMappingURL=status.d.ts.map

package/dist/ui/formatters/status.js

@@ -1,16 +1,15 @@
-import { getChromeDiagnostics } from '../../connection/diagnostics.js';
+import { describeRunningChrome } from '../../session/chrome.js';
 import { calculateDuration, formatTimeAgo } from '../../session/statusData.js';
-import { OutputFormatter } from '../../ui/formatting.js';
-import { formatDiagnosticsForStatus } from '../../ui/messages/chrome.js';
+import { OutputFormatter } from '../formatting.js';
+import { lastSessionEndText } from '../messages/session.js';
 import { isProcessAlive } from '../../utils/process.js';
-import { VERSION } from '../../utils/version.js';
 /**
  * Format session status for human-readable output
  * @param metadata - Session metadata
  * @param pid - BDG process ID
- * @param activity - Live activity metrics from worker
- * @param pageState - Current page state from worker
- * @param verbose - Show detailed Chrome diagnostics
+ * @param activity - Live activity metrics from the session
+ * @param pageState - Current page state from the session
+ * @param verbose - Also show the session's Chrome executable, mode and profile
  */
 export function formatSessionStatus(metadata, pid, activity, pageState, verbose = false) {
     const duration = calculateDuration(metadata.startTime);
@@ -20,12 +19,18 @@ export function formatSessionStatus(metadata, pid, activity, pageState, verbose
     fmt.keyValueList([
         ['Status', 'ACTIVE'],
         ['Duration', duration.formatted],
+        ...(metadata.autoStopAt
+            ? [['Auto-stop', new Date(metadata.autoStopAt).toLocaleTimeString()]]
+            : []),
     ], 18);
     fmt.blank().text('Process Information').separator('━', 50);
     fmt.keyValue('Daemon PID', pid.toString(), 18);
     if (metadata.chromePid) {
         fmt.keyValue('Chrome PID', `${metadata.chromePid} ${chromeAlive ? '(running)' : '(not running)'}`, 18);
     }
+    else {
+        fmt.keyValue('Chrome', 'external (not launched by bdg)', 18);
+    }
     fmt.keyValue('Port', metadata.port.toString(), 18);
     if (pageState) {
         fmt.blank().text('Target Information').separator('━', 50);
@@ -52,18 +57,21 @@ export function formatSessionStatus(metadata, pid, activity, pageState, verbose
         ['Console', activeTelemetry.includes('console') ? 'Active' : 'Inactive'],
         ['DOM', activeTelemetry.includes('dom') ? 'Active' : 'Inactive'],
     ], 18);
-    if (verbose) {
-        fmt.blank().text('Chrome Diagnostics').separator('━', 50);
-        const diagnostics = getChromeDiagnostics();
-        const diagnosticLines = formatDiagnosticsForStatus(diagnostics);
-        diagnosticLines.forEach((line) => fmt.text(line));
+    const chrome = verbose && metadata.chromePid ? describeRunningChrome(metadata.chromePid) : null;
+    if (chrome) {
+        fmt.blank().text('Chrome').separator('━', 50);
+        fmt.keyValueList([
+            ['Executable', chrome.executable],
+            ['Mode', chrome.headless ? 'headless' : 'with window'],
+            ...(chrome.userDataDir ? [['Profile', chrome.userDataDir]] : []),
+        ], 18);
     }
     fmt
         .blank()
         .section('Commands:', [
-        'Stop session:    bdg stop',
         'Peek data:       bdg peek',
-        'Query browser:   bdg query <script>',
+        'Run JavaScript:  bdg dom eval <script>',
+        'End session:     bdg stop',
     ]);
     return fmt.build();
 }
@@ -72,15 +80,14 @@ export function formatSessionStatus(metadata, pid, activity, pageState, verbose
  */
 export function formatStatusAsJson(metadata, pid) {
     if (!pid) {
-        return { version: VERSION, active: false };
+        return { active: false };
     }
     const isAlive = isProcessAlive(pid);
     if (!isAlive) {
-        return { version: VERSION, active: false, stale: true, stalePid: pid };
+        return { active: false, stale: true, stalePid: pid };
     }
     if (!metadata) {
         return {
-            version: VERSION,
             active: true,
             bdgPid: pid,
             warning: 'Metadata not found (session may be from older version)',
@@ -89,15 +96,15 @@ export function formatStatusAsJson(metadata, pid) {
     const duration = calculateDuration(metadata.startTime);
     const chromeAlive = metadata.chromePid ? isProcessAlive(metadata.chromePid) : false;
     return {
-        version: VERSION,
         active: true,
         bdgPid: pid,
         chromePid: metadata.chromePid,
-        chromeAlive,
+        ...(metadata.chromePid ? { chromeAlive } : { externalChrome: true }),
         startTime: metadata.startTime,
         duration: duration.durationMs,
         durationFormatted: duration.formatted,
         port: metadata.port,
+        ...(metadata.autoStopAt && { autoStopAt: new Date(metadata.autoStopAt).toISOString() }),
         targetId: metadata.targetId,
         webSocketDebuggerUrl: metadata.webSocketDebuggerUrl,
         telemetry: metadata.activeTelemetry ?? ['network', 'console', 'dom'],
@@ -106,14 +113,31 @@ export function formatStatusAsJson(metadata, pid) {
 /**
  * Format "no session" message
  */
-export function formatNoSessionMessage() {
+export function formatNoSessionMessage(data = { active: false }) {
     const fmt = new OutputFormatter();
+    if (data.starting) {
+        const seconds = Math.round((Date.now() - data.starting.since) / 1000);
+        return fmt
+            .text(`Session starting: ${data.starting.url} (${seconds}s so far)`)
+            .blank()
+            .text('Commands work once "bdg <url>" returns.')
+            .build();
+    }
+    if (data.ending) {
+        return fmt.text('The session is ending (its Chrome is being closed)').build();
+    }
+    fmt.text('No active session found');
+    if (data.lastSession)
+        fmt.text(lastSessionEndText(data.lastSession));
+    if (data.orphanedChromePid) {
+        fmt.text(`Chrome of an earlier session is still running (PID ${data.orphanedChromePid})`);
+    }
     return fmt
-        .text('No active session found')
-        .blank()
-        .section('Suggestions:', [
+        .hints('Suggestions:', [
         'Start a new session:     bdg <url>',
-        'List Chrome tabs:        bdg tabs',
+        data.orphanedChromePid
+            ? 'Close that Chrome:       bdg cleanup'
+            : 'Clean up after a crash:  bdg cleanup',
     ])
         .build();
 }

package/dist/ui/formatting.d.ts

@@ -5,6 +5,16 @@
  * Includes: sections, lists, key-value pairs, text utilities, time formatting,
  * and the OutputFormatter class for building complex formatted output.
  */
+/**
+ * Leave tips and next-step hints out of human output (`-q`).
+ */
+export declare function hideHints(): void;
+/**
+ * Whether tips and hints are left out (`-q`).
+ *
+ * @returns True in quiet mode
+ */
+export declare function areHintsHidden(): boolean;
 /**
  * Fluent builder for constructing formatted console output.
  *
@@ -17,12 +27,37 @@ export declare class OutputFormatter {
     blank(): this;
     list(items: string[], indent?: number): this;
     section(title: string, items: string[], indent?: number): this;
+    /**
+     * A block of tips or next steps after a blank line; left out with `-q`.
+     *
+     * @param title - Block title, e.g. "Next steps:"
+     * @param items - Lines of the block
+     * @param indent - Indentation of the lines
+     */
+    hints(title: string, items: string[], indent?: number): this;
+    /**
+     * A one-line tip; left out with `-q`.
+     *
+     * @param content - Tip text
+     */
+    tip(content: string): this;
     separator(char?: string, width?: number): this;
     keyValue(key: string, value: string, keyWidth?: number): this;
     keyValueList(pairs: Array<[string, string]>, keyWidth?: number): this;
     indent(content: string, spaces?: number): this;
     build(): string;
 }
+/**
+ * Make page-provided text safe to print to a terminal.
+ *
+ * Console messages, titles and URLs come from the page; escape sequences in
+ * them could otherwise retitle, clear or recolor the user's terminal. Control
+ * characters are shown as `\uXXXX`; newlines and tabs are kept.
+ *
+ * @param text - Text to print
+ * @returns Text with control characters escaped
+ */
+export declare function escapeControlChars(text: string): string;
 export declare function joinLines(...lines: Array<string | null | undefined | false>): string;
 export declare function section(title: string, content: string[], indent?: number): string;
 export declare function truncateText(text: string, maxLines?: number): string;

package/dist/ui/formatting.js

@@ -6,6 +6,21 @@
  * and the OutputFormatter class for building complex formatted output.
  */
 import { safeParseUrl } from '../utils/url.js';
+let hintsHidden = false;
+/**
+ * Leave tips and next-step hints out of human output (`-q`).
+ */
+export function hideHints() {
+    hintsHidden = true;
+}
+/**
+ * Whether tips and hints are left out (`-q`).
+ *
+ * @returns True in quiet mode
+ */
+export function areHintsHidden() {
+    return hintsHidden;
+}
 /**
  * Fluent builder for constructing formatted console output.
  *
@@ -31,6 +46,26 @@ export class OutputFormatter {
         this.lines.push(title);
         return this.list(items, indent);
     }
+    /**
+     * A block of tips or next steps after a blank line; left out with `-q`.
+     *
+     * @param title - Block title, e.g. "Next steps:"
+     * @param items - Lines of the block
+     * @param indent - Indentation of the lines
+     */
+    hints(title, items, indent = 2) {
+        if (hintsHidden)
+            return this;
+        return this.blank().section(title, items, indent);
+    }
+    /**
+     * A one-line tip; left out with `-q`.
+     *
+     * @param content - Tip text
+     */
+    tip(content) {
+        return hintsHidden ? this : this.text(content);
+    }
     separator(char = '━', width = 50) {
         this.lines.push(char.repeat(width));
         return this;
@@ -51,8 +86,40 @@ export class OutputFormatter {
         return this;
     }
     build() {
-        return this.lines.join('\n');
+        return escapeControlChars(this.lines.join('\n'));
+    }
+}
+/**
+ * Whether a character code is a control character other than tab/newline
+ * (C0, DEL, C1), or a bidirectional override/isolate that can make output
+ * read differently than it is (e.g. U+202E right-to-left override).
+ *
+ * @param code - UTF-16 code unit
+ * @returns True for characters that must not reach the terminal raw
+ */
+function isControlChar(code) {
+    return ((code < 0x20 && code !== 0x09 && code !== 0x0a) ||
+        (code >= 0x7f && code <= 0x9f) ||
+        (code >= 0x202a && code <= 0x202e) ||
+        (code >= 0x2066 && code <= 0x2069));
+}
+/**
+ * Make page-provided text safe to print to a terminal.
+ *
+ * Console messages, titles and URLs come from the page; escape sequences in
+ * them could otherwise retitle, clear or recolor the user's terminal. Control
+ * characters are shown as `\uXXXX`; newlines and tabs are kept.
+ *
+ * @param text - Text to print
+ * @returns Text with control characters escaped
+ */
+export function escapeControlChars(text) {
+    let result = '';
+    for (const char of text.replace(/\r\n/g, '\n')) {
+        const code = char.charCodeAt(0);
+        result += isControlChar(code) ? `\\u${code.toString(16).padStart(4, '0')}` : char;
     }
+    return result;
 }
 export function joinLines(...lines) {
     return lines
@@ -73,30 +140,62 @@ export function truncateText(text, maxLines = 3) {
 }
 export function truncateUrl(url, maxLength = 60) {
     const parsed = safeParseUrl(url);
-    if (!parsed) {
-        return url.length > maxLength ? url.substring(0, maxLength - 3) + '...' : url;
+    if (!parsed || !WEB_PROTOCOLS.has(parsed.protocol)) {
+        return truncateEnd(url, maxLength);
     }
-    const domain = parsed.hostname.replace(/^www\./, '');
+    const host = parsed.host;
     const path = parsed.pathname.substring(1);
-    let result = domain + (path ? `/${path}` : '');
-    if (result.length > maxLength) {
-        const pathParts = path.split('/');
-        if (pathParts.length > 2) {
-            const first = pathParts[0];
-            const last = pathParts[pathParts.length - 1];
-            if (first && last) {
-                result = `${domain}/${first}/.../${last}`;
-                if (result.length > maxLength) {
-                    const truncatedLast = last.substring(0, 8);
-                    result = `${domain}/${first}/.../${truncatedLast}`;
-                }
-            }
-        }
-        else {
-            result = result.substring(0, maxLength - 3) + '...';
-        }
-    }
-    return result;
+    const full = `${host}${path ? `/${path}` : ''}`;
+    if (`${full}${parsed.search}`.length <= maxLength)
+        return `${full}${parsed.search}`;
+    if (!parsed.search)
+        return shortenPath(host, path, maxLength);
+    const room = maxLength - full.length;
+    if (room >= MIN_QUERY_SHOWN)
+        return `${full}${cutQuery(parsed.search, room)}`;
+    const query = cutQuery(parsed.search, MIN_QUERY_SHOWN);
+    return `${shortenPath(host, path, maxLength - query.length)}${query}`;
+}
+/**
+ * A query string cut to a length, marked with "…" when cut.
+ *
+ * @param search - Query string including "?"
+ * @param length - Maximum length
+ * @returns The query, or its start followed by "…"
+ */
+function cutQuery(search, length) {
+    return search.length <= length ? search : `${search.substring(0, length - 1)}…`;
+}
+/** Characters of a long query string kept, so similar requests stay distinguishable */
+const MIN_QUERY_SHOWN = 12;
+/** Protocols whose URLs are shown as host/path (others, like data: or blob:, verbatim) */
+const WEB_PROTOCOLS = new Set(['http:', 'https:', 'ws:', 'wss:']);
+/**
+ * Cut text to a length, marking the cut.
+ *
+ * @param text - Text to cut
+ * @param maxLength - Maximum length
+ * @returns Text, or its start followed by "..."
+ */
+function truncateEnd(text, maxLength) {
+    return text.length > maxLength ? text.substring(0, maxLength - 3) + '...' : text;
+}
+/**
+ * Shorten a long host/path by eliding its middle segments.
+ *
+ * @param host - Host (with port)
+ * @param path - Path without the leading slash
+ * @param maxLength - Maximum length
+ * @returns e.g. "example.com/docs/.../page"
+ */
+function shortenPath(host, path, maxLength) {
+    const parts = path.split('/');
+    const first = parts[0];
+    const last = parts[parts.length - 1];
+    if (parts.length <= 2 || !first || !last)
+        return truncateEnd(`${host}/${path}`, maxLength);
+    const elided = `${host}/${first}/.../${last}`;
+    return elided.length <= maxLength ? elided : `${host}/${first}/.../${last.substring(0, 8)}`;
 }
 export function pluralize(count, singular, plural) {
     const word = count === 1 ? singular : (plural ?? singular + 's');

package/dist/ui/logging/logger.d.ts

@@ -29,7 +29,7 @@ export type LogLevel = 'info' | 'debug';
  * Log contexts for different components.
  * Used to prefix log messages with component name.
  */
-export type LogContext = 'bdg' | 'launcher' | 'daemon' | 'worker' | 'client' | 'cleanup' | 'session' | 'chrome' | 'cdp' | 'ipc' | 'http' | 'dialogs' | 'navigation' | 'console' | 'dom' | 'network' | 'diagnostics' | 'readiness' | 'atomic-file' | 'object-expander' | 'fetcher';
+export type LogContext = 'bdg' | 'launcher' | 'daemon' | 'client' | 'cleanup' | 'session' | 'chrome' | 'cdp' | 'ipc' | 'http' | 'dialogs' | 'navigation' | 'console' | 'dom' | 'network' | 'diagnostics' | 'readiness' | 'atomic-file' | 'object-expander' | 'fetcher' | 'targets';
 /**
  * Logger instance with support for different log levels.
  */