browser-debugger-cli 0.7.2 → 0.9.0

package/dist/ui/formatters/status.js

@@ -1,31 +1,41 @@
-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 { colorSchemeLabel, sessionActiveLine } from '../messages/commands.js';
+import { lastSessionEndText } from '../messages/session.js';
+import { noActiveSessionMessage, sessionCommand } from '../messages/sessionCommand.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
+ * @param sessionName - Name of a named session
  */
-export function formatSessionStatus(metadata, pid, activity, pageState, verbose = false) {
+export function formatSessionStatus(metadata, pid, activity, pageState, verbose = false, sessionName) {
     const duration = calculateDuration(metadata.startTime);
     const chromeAlive = metadata.chromePid ? isProcessAlive(metadata.chromePid) : false;
     const fmt = new OutputFormatter();
+    fmt.text(sessionActiveLine(pageState)).blank();
     fmt.text('Session Status').separator('━', 50);
     fmt.keyValueList([
+        ...(sessionName ? [['Session', sessionName]] : []),
         ['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);
@@ -33,6 +43,7 @@ export function formatSessionStatus(metadata, pid, activity, pageState, verbose
         if (pageState.title) {
             fmt.keyValue('Title', pageState.title, 18);
         }
+        fmt.keyValueList(appearanceLines(metadata, pageState), 18);
     }
     if (activity) {
         fmt.blank().text('Activity').separator('━', 50);
@@ -52,35 +63,65 @@ 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>',
+        `Peek data:       ${sessionCommand('bdg peek', sessionName ?? null)}`,
+        `Run JavaScript:  ${sessionCommand('bdg dom eval <script>', sessionName ?? null)}`,
+        `End session:     ${sessionCommand('bdg stop', sessionName ?? null)}`,
     ]);
     return fmt.build();
 }
+/**
+ * Viewport and color scheme lines of the target: what the page renders with,
+ * and whether `--viewport` / `--color-scheme` set it or it is the system's.
+ * The color scheme is the `prefers-color-scheme` the page sees, not its theme.
+ *
+ * @param metadata - Session metadata (the start options)
+ * @param pageState - Page state (what the page reported)
+ * @returns Key-value pairs (none for what is unknown)
+ */
+export function appearanceLines(metadata, pageState) {
+    const viewport = pageState.viewport ?? metadata.viewport;
+    const scheme = pageState.colorScheme ?? metadata.colorScheme;
+    return [
+        ...(viewport
+            ? [
+                [
+                    'Viewport',
+                    `${viewport.width}×${viewport.height}${metadata.viewport ? ` (--viewport ${metadata.viewport.width}x${metadata.viewport.height})` : ''}`,
+                ],
+            ]
+            : []),
+        ...(scheme
+            ? [
+                ['Color scheme', colorSchemeLabel(scheme, metadata.colorScheme !== undefined)],
+            ]
+            : []),
+    ];
+}
 /**
  * Convert status data to JSON format
  */
 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 +130,17 @@ 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,
+        chromePid: metadata.chromePid !== undefined && metadata.chromePid > 0 ? metadata.chromePid : null,
+        ...(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() }),
+        ...(metadata.viewport && { viewport: metadata.viewport }),
+        ...(metadata.colorScheme && { colorScheme: metadata.colorScheme }),
         targetId: metadata.targetId,
         webSocketDebuggerUrl: metadata.webSocketDebuggerUrl,
         telemetry: metadata.activeTelemetry ?? ['network', 'console', 'dom'],
@@ -106,14 +149,32 @@ 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 "${sessionCommand('bdg <url>', data.session ?? null)}" returns.`)
+            .build();
+    }
+    if (data.ending) {
+        return fmt.text('The session is ending (its Chrome is being closed)').build();
+    }
+    const session = data.session ?? null;
+    fmt.text(noActiveSessionMessage(session));
+    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:', [
-        'Start a new session:     bdg <url>',
-        'List Chrome tabs:        bdg tabs',
+        .hints('Suggestions:', [
+        `Start a new session:     ${sessionCommand('bdg <url>', session)}`,
+        data.orphanedChromePid
+            ? `Close that Chrome:       ${sessionCommand('bdg cleanup', session)}`
+            : `Clean up after a crash:  ${sessionCommand('bdg cleanup', session)}`,
     ])
         .build();
 }

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

@@ -0,0 +1,36 @@
+/**
+ * Human output of the network requests a DOM action triggered.
+ */
+import type { TriggeredRequest } from '../../ipc/protocol/domTypes.js';
+/** Requests listed in human output (JSON lists up to 50) */
+export declare const MAX_TRIGGERED_REQUESTS_SHOWN = 10;
+/**
+ * Title of the list, with how many requests there were in all (the listed
+ * rows, the "... and N more" note and the assets line add up to it).
+ *
+ * @param requests - Triggered requests in the result
+ * @param omitted - Requests the result left out
+ * @returns e.g. "Requests during the action (18):"
+ */
+export declare function formatTriggeredRequestsTitle(requests: TriggeredRequest[], omitted?: number): string;
+/**
+ * One request as a line, e.g. `POST 127.0.0.1:8080/api/save → 200 (85ms)`,
+ * or `GET 127.0.0.1:8080/events → 200 (loading)` while its body still loads.
+ *
+ * @param request - Triggered request
+ * @returns Line text
+ */
+export declare function formatTriggeredRequest(request: TriggeredRequest): string;
+/**
+ * Lines listing the triggered requests: the first
+ * {@link MAX_TRIGGERED_REQUESTS_SHOWN} notable ones (documents, XHR, fetch,
+ * WebSocket, failures; see {@link isNotableRequest}), how many more there
+ * are and where to find them (JSON, or the network list when JSON left some
+ * out too), then one line counting the static assets that loaded.
+ *
+ * @param requests - Triggered requests, in start order
+ * @param omitted - Requests the result already left out
+ * @returns Lines (empty when there are none)
+ */
+export declare function formatTriggeredRequestLines(requests: TriggeredRequest[], omitted?: number): string[];
+//# sourceMappingURL=triggeredRequests.d.ts.map

package/dist/ui/formatters/triggeredRequests.js

@@ -0,0 +1,65 @@
+/**
+ * Human output of the network requests a DOM action triggered.
+ */
+import { assetTypeNames, isNotableRequest } from '../../telemetry/requestKinds.js';
+import { formatRequestStatus } from './requestStatus.js';
+import { formatDuration, truncateUrl } from '../formatting.js';
+import { assetRequestsNote, moreMatchesNote, moreRequestsNote, triggeredRequestsTitle, } from '../messages/commands.js';
+/** Requests listed in human output (JSON lists up to 50) */
+export const MAX_TRIGGERED_REQUESTS_SHOWN = 10;
+/** Longest URL shown before it is shortened */
+const URL_MAX_LENGTH = 60;
+/**
+ * Title of the list, with how many requests there were in all (the listed
+ * rows, the "... and N more" note and the assets line add up to it).
+ *
+ * @param requests - Triggered requests in the result
+ * @param omitted - Requests the result left out
+ * @returns e.g. "Requests during the action (18):"
+ */
+export function formatTriggeredRequestsTitle(requests, omitted = 0) {
+    return triggeredRequestsTitle(requests.length + omitted);
+}
+/**
+ * One request as a line, e.g. `POST 127.0.0.1:8080/api/save → 200 (85ms)`,
+ * or `GET 127.0.0.1:8080/events → 200 (loading)` while its body still loads.
+ *
+ * @param request - Triggered request
+ * @returns Line text
+ */
+export function formatTriggeredRequest(request) {
+    const httpStatus = request.failed ? 0 : request.status;
+    const status = formatRequestStatus({
+        ...(httpStatus !== undefined && { status: httpStatus }),
+        ...(request.errorText !== undefined && { errorText: request.errorText }),
+    });
+    const duration = request.loading
+        ? ' (loading)'
+        : request.durationMs === undefined
+            ? ''
+            : ` (${formatDuration(request.durationMs)})`;
+    return `${request.method} ${truncateUrl(request.url, URL_MAX_LENGTH)} → ${status}${duration}`;
+}
+/**
+ * Lines listing the triggered requests: the first
+ * {@link MAX_TRIGGERED_REQUESTS_SHOWN} notable ones (documents, XHR, fetch,
+ * WebSocket, failures; see {@link isNotableRequest}), how many more there
+ * are and where to find them (JSON, or the network list when JSON left some
+ * out too), then one line counting the static assets that loaded.
+ *
+ * @param requests - Triggered requests, in start order
+ * @param omitted - Requests the result already left out
+ * @returns Lines (empty when there are none)
+ */
+export function formatTriggeredRequestLines(requests, omitted = 0) {
+    const notable = requests.filter(isNotableRequest);
+    const assets = requests.filter((request) => !isNotableRequest(request));
+    const lines = notable.slice(0, MAX_TRIGGERED_REQUESTS_SHOWN).map(formatTriggeredRequest);
+    const hidden = notable.length - lines.length + omitted;
+    if (hidden > 0)
+        lines.push(omitted > 0 ? moreRequestsNote(hidden) : moreMatchesNote(hidden));
+    if (assets.length > 0)
+        lines.push(assetRequestsNote(assets.length, assetTypeNames(assets)));
+    return lines;
+}
+//# sourceMappingURL=triggeredRequests.js.map

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,15 +27,50 @@ 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;
+/**
+ * A URL for one line: host and path without the scheme (`www.example.com`
+ * for the root), cut in the middle when too long, keeping the host, the
+ * start of the path and the end of the path and query, where requests to
+ * one API differ (`api.example.com/v1/users/…/orders?page=2`).
+ *
+ * @param url - URL
+ * @param maxLength - Maximum length
+ * @returns Shortened URL; non-web URLs (data:, blob:) cut at the end
+ */
 export declare function truncateUrl(url: string, maxLength?: number): string;
 export declare function pluralize(count: number, singular: string, plural?: string): string;
 export declare function formatDuration(ms: 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
@@ -71,32 +138,56 @@ export function truncateText(text, maxLines = 3) {
     const hiddenCount = lines.length - maxLines;
     return `${truncated}\n  ... (${hiddenCount} more lines)`;
 }
+/**
+ * A URL for one line: host and path without the scheme (`www.example.com`
+ * for the root), cut in the middle when too long, keeping the host, the
+ * start of the path and the end of the path and query, where requests to
+ * one API differ (`api.example.com/v1/users/…/orders?page=2`).
+ *
+ * @param url - URL
+ * @param maxLength - Maximum length
+ * @returns Shortened URL; non-web URLs (data:, blob:) cut at the end
+ */
 export function truncateUrl(url, maxLength = 60) {
     const parsed = safeParseUrl(url);
-    if (!parsed) {
-        return url.length > maxLength ? url.substring(0, maxLength - 3) + '...' : url;
-    }
-    const domain = parsed.hostname.replace(/^www\./, '');
-    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) + '...';
-        }
+    if (!parsed || !WEB_PROTOCOLS.has(parsed.protocol)) {
+        return truncateEnd(url, maxLength);
     }
-    return result;
+    const host = parsed.host;
+    const rest = `${parsed.pathname.substring(1)}${parsed.search}`;
+    const shown = parsed.pathname.length > 1 ? `${host}/${rest}` : `${host}${parsed.search}`;
+    if (shown.length <= maxLength)
+        return shown;
+    const room = maxLength - host.length - 2;
+    if (room < MIN_URL_END_SHOWN)
+        return cutMiddle(shown, maxLength);
+    const start = Math.floor(room / 3);
+    return `${host}/${rest.substring(0, start)}…${rest.substring(rest.length - (room - start))}`;
+}
+/** Characters of path and query a shortened URL keeps at least besides its host */
+const MIN_URL_END_SHOWN = 12;
+/**
+ * Cut text in the middle, marking the cut with "…".
+ *
+ * @param text - Text
+ * @param maxLength - Maximum length
+ * @returns Start and end of the text around "…"
+ */
+function cutMiddle(text, maxLength) {
+    const head = Math.ceil((maxLength - 1) / 2);
+    return `${text.substring(0, head)}…${text.substring(text.length - (maxLength - 1 - head))}`;
+}
+/** 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;
 }
 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.
  */