browser-debugger-cli 0.7.1 → 0.8.0

package/dist/ui/messages/commands.js

@@ -4,16 +4,16 @@
  * User-facing messages for command-specific operations like stopping sessions,
  * cleaning up stale files, and validating command arguments.
  */
-import { buildAgentDiscoveryHelp, buildCommonTaskExamples, buildUrlExamples, buildSessionManagementReminder, } from '../../ui/formatters/helpFormatters.js';
-import { joinLines } from '../../ui/formatting.js';
+import { buildAgentDiscoveryHelp, buildCommonTaskExamples, buildUrlExamples, buildSessionManagementReminder, } from '../formatters/helpFormatters.js';
+import { joinLines } from '../formatting.js';
 /**
- * Generate Chrome killed message.
+ * Chrome closed by `bdg stop` (gracefully, so the profile is saved).
  *
- * @param pid - Chrome process ID that was killed
+ * @param pid - Chrome process ID
  * @returns Formatted success message
  */
-export function chromeKilledMessage(pid) {
-    return pid ? `Killed Chrome (PID ${pid})` : 'Killed Chrome';
+export function chromeClosedMessage(pid) {
+    return pid ? `Closed Chrome (PID ${pid})` : 'Closed Chrome';
 }
 /**
  * Generate orphaned daemons cleaned message.
@@ -24,6 +24,153 @@ export function chromeKilledMessage(pid) {
 export function orphanedDaemonsCleanedMessage(count) {
     return `Cleaned up ${count} orphaned daemon process${count === 1 ? '' : 'es'}`;
 }
+/**
+ * Warning shown when a click falls back from mouse events to `el.click()`.
+ *
+ * @param reason - Why the mouse could not reach the element (e.g. "covered by another element")
+ * @returns Warning text
+ */
+export function domClickFallbackWarning(reason) {
+    return `Element is ${reason ?? 'not reachable by the mouse'}; dispatched DOM events instead of mouse events (a user could not reach it like this)`;
+}
+/**
+ * Note under a shortened list of matches.
+ *
+ * @param hidden - Matches not listed
+ * @returns e.g. "... and 1174 more (use --json for all)"
+ */
+export function moreMatchesNote(hidden) {
+    return `... and ${hidden} more (use --json for all)`;
+}
+/**
+ * Warning when a selector matched several elements and no --index was given.
+ *
+ * @param count - Number of matching elements
+ * @param action - What was done, e.g. "clicked the first visible one"
+ * @returns Warning text
+ */
+export function multipleMatchesWarning(count, action) {
+    return `${count} elements match; ${action} (use --index or a more specific selector)`;
+}
+/**
+ * Headline of `bdg dom listeners`.
+ *
+ * @param element - Inspected element, e.g. "button#save"
+ * @param count - Listeners found
+ * @returns e.g. "Event listeners for button#save (3)"
+ */
+export function listenersHeadline(element, count) {
+    return `Event listeners for ${element} (${count})`;
+}
+/**
+ * `bdg dom listeners` found nothing.
+ *
+ * @param element - Inspected element
+ * @param types - Event types asked for with --type, if any
+ * @returns e.g. "No click listeners on button#save, its ancestors, document or window"
+ */
+export function noListenersMessage(element, types) {
+    const kind = types?.length ? `${types.join('/')} listeners` : 'event listeners';
+    return `No ${kind} on ${element}, its ancestors, document or window`;
+}
+/** What `bdg dom listeners` covers, shown when it found nothing */
+export const NO_LISTENERS_HINT = 'Inline on… attributes and on… properties are included, and so are handlers frameworks delegate to ancestors (React, jQuery)';
+/**
+ * Note for event types handled only by ancestors, document or window.
+ *
+ * @param types - Event types without a listener on the element itself
+ * @returns One-line note
+ */
+export function delegatedListenersNote(types) {
+    return `Note: ${types.join(', ')} ${types.length === 1 ? 'has' : 'have'} no listener on the element itself; frameworks like React and jQuery delegate events to a root container, document or window, so these still run for it`;
+}
+/**
+ * A JavaScript dialog bdg accepted, as one line.
+ *
+ * @param dialog - Dialog type and text
+ * @returns e.g. 'alert() dialog accepted: "Saved"'
+ */
+export function dialogConsoleText(dialog) {
+    const kind = dialog.type === 'beforeunload' ? 'beforeunload' : `${dialog.type}()`;
+    return `${kind} dialog accepted${dialog.message ? `: "${dialog.message}"` : ''}`;
+}
+/** Headline of each pointer action, e.g. "Element Double-clicked" */
+export const POINTER_ACTION_DONE = {
+    click: 'Clicked',
+    double: 'Double-clicked',
+    right: 'Right-clicked',
+    hover: 'Hovered',
+};
+/** Headline of each `bdg page` action */
+export const PAGE_ACTION_DONE = {
+    navigate: 'Navigated',
+    reload: 'Reloaded',
+    back: 'Went back',
+    forward: 'Went forward',
+};
+/** Help text of the `bdg page` history commands */
+export const PAGE_ACTION_DESCRIPTIONS = {
+    reload: 'Reload the page',
+    back: 'Go back one page (like the browser button)',
+    forward: 'Go forward one page (like the browser button)',
+};
+/**
+ * `bdg page navigate` to a page that answered with an HTTP error.
+ *
+ * @param status - HTTP status
+ * @returns Warning
+ */
+export function httpErrorWarning(status) {
+    return `The page responded with HTTP ${status}`;
+}
+/**
+ * `bdg page navigate` to a URL that loaded no page.
+ *
+ * @returns Warning
+ */
+export function notAPageWarning() {
+    return 'The URL did not load a page (it may be a file download); the page did not change';
+}
+/**
+ * `bdg page` when the server did not answer in time.
+ *
+ * @param ms - Time waited
+ * @returns Warning
+ */
+export function stillLoadingWarning(ms) {
+    return `The new page has not answered within ${Math.round(ms / 1000)}s; it is still loading (check with bdg status)`;
+}
+/**
+ * One line describing an iframe: index, URL, name/id, and how it is isolated.
+ *
+ * @param frame - Frame from `bdg dom frames`
+ * @returns e.g. `[1] https://pay.example/  #checkout  cross-origin, out-of-process`
+ */
+export function frameLabel(frame) {
+    const names = [frame.name && `name=${frame.name}`, frame.id && `#${frame.id}`].filter(Boolean);
+    const isolation = [
+        frame.crossOrigin ? 'cross-origin' : 'same-origin',
+        frame.outOfProcess && 'out-of-process',
+    ].filter(Boolean);
+    return [`[${frame.index}] ${frame.url}`, ...names, isolation.join(', ')].join('  ');
+}
+/**
+ * `bdg dom frames` on a page without iframes.
+ *
+ * @returns Message
+ */
+export function noFramesMessage() {
+    return 'The page has no iframes';
+}
+/**
+ * Header of `bdg dom eval --frame` output naming the frame the script ran in.
+ *
+ * @param url - Frame URL
+ * @returns e.g. `Frame: https://pay.example/`
+ */
+export function evalFrameLine(url) {
+    return `Frame: ${url}`;
+}
 /**
  * Generate warning message.
  *

package/dist/ui/messages/consoleMessages.d.ts

@@ -15,10 +15,4 @@ export declare function followingConsoleMessage(): string;
  * @returns Status message for stderr
  */
 export declare function stoppedFollowingConsoleMessage(): string;
-/**
- * Generate message when no console data is available.
- *
- * @returns Error message with context
- */
-export declare function noConsoleDataMessage(): string;
 //# sourceMappingURL=consoleMessages.d.ts.map

package/dist/ui/messages/consoleMessages.js

@@ -19,12 +19,4 @@ export function followingConsoleMessage() {
 export function stoppedFollowingConsoleMessage() {
     return 'Stopped streaming console messages';
 }
-/**
- * Generate message when no console data is available.
- *
- * @returns Error message with context
- */
-export function noConsoleDataMessage() {
-    return 'No console data available. Console messages are captured during browser session.';
-}
 //# sourceMappingURL=consoleMessages.js.map

package/dist/ui/messages/hints.d.ts

@@ -1,23 +1,17 @@
 /**
  * Runtime hint message generators.
  *
- * Provides formatted hint messages that guide agents toward more
- * efficient command patterns during active sessions.
+ * Boundary formatter for structured `HintDetails` DTOs the session emits
+ * alongside CDP command results. Keeps hint wording out of core so the
+ * session stays free of UI imports.
  */
-import type { PatternDefinition } from '../../daemon/patternDefinitions.js';
+import type { HintDetails } from '../../errors/notices.js';
 /**
- * Generate runtime pattern hint message.
+ * Format a structured hint into a user-facing string.
  *
- * Creates a formatted hint suggesting a more efficient command alternative.
- *
- * @param pattern - Detected pattern with alternative suggestion
- * @returns Formatted hint message
- *
- * @example
- * ```typescript
- * const hint = generatePatternHint(pattern);
- * console.error(hint);
- * ```
+ * Called at the UI boundary (CLI command layer) when a `HintDetails`
+ * payload arrives from the daemon. Core emits the DTO; this is the
+ * only place hint prose is assembled.
  */
-export declare function generatePatternHint(pattern: PatternDefinition): string;
+export declare function formatHint(hint: HintDetails): string;
 //# sourceMappingURL=hints.d.ts.map

package/dist/ui/messages/hints.js

@@ -1,25 +1,26 @@
 /**
  * Runtime hint message generators.
  *
- * Provides formatted hint messages that guide agents toward more
- * efficient command patterns during active sessions.
+ * Boundary formatter for structured `HintDetails` DTOs the session emits
+ * alongside CDP command results. Keeps hint wording out of core so the
+ * session stays free of UI imports.
  */
-import { joinLines } from '../../ui/formatting.js';
+import { joinLines } from '../formatting.js';
 /**
- * Generate runtime pattern hint message.
+ * Format a structured hint into a user-facing string.
  *
- * Creates a formatted hint suggesting a more efficient command alternative.
- *
- * @param pattern - Detected pattern with alternative suggestion
- * @returns Formatted hint message
- *
- * @example
- * ```typescript
- * const hint = generatePatternHint(pattern);
- * console.error(hint);
- * ```
+ * Called at the UI boundary (CLI command layer) when a `HintDetails`
+ * payload arrives from the daemon. Core emits the DTO; this is the
+ * only place hint prose is assembled.
  */
-export function generatePatternHint(pattern) {
-    return joinLines('', `Hint: Consider using '${pattern.alternative}' instead of ${pattern.cdpMethods.join(' or ')}`, '');
+export function formatHint(hint) {
+    const ctx = hint.context ?? {};
+    switch (hint.code) {
+        case 'PATTERN_HINT': {
+            const alternative = ctx['alternative'];
+            const cdpMethods = ctx['cdpMethods'] ?? [];
+            return joinLines('', `Hint: Consider using '${alternative}' instead of ${cdpMethods.join(' or ')}`, '');
+        }
+    }
 }
 //# sourceMappingURL=hints.js.map

package/dist/ui/messages/networkMessages.d.ts

@@ -15,10 +15,4 @@ export declare function followingNetworkMessage(): string;
  * @returns Status message for stderr
  */
 export declare function stoppedFollowingNetworkMessage(): string;
-/**
- * Generate message when no network data is available.
- *
- * @returns Info message with context
- */
-export declare function noNetworkDataMessage(): string;
 //# sourceMappingURL=networkMessages.d.ts.map

package/dist/ui/messages/networkMessages.js

@@ -19,12 +19,4 @@ export function followingNetworkMessage() {
 export function stoppedFollowingNetworkMessage() {
     return '\nStopped following network requests.';
 }
-/**
- * Generate message when no network data is available.
- *
- * @returns Info message with context
- */
-export function noNetworkDataMessage() {
-    return 'No network requests collected yet.';
-}
 //# sourceMappingURL=networkMessages.js.map

package/dist/ui/messages/preview.js

@@ -18,7 +18,7 @@ export const PREVIEW_HEADERS = {
  * @returns Single-line tip for basic peek usage
  */
 export function compactTipsMessage() {
-    return 'Tip: bdg stop | bdg peek --last 50 | bdg peek --verbose';
+    return 'Tip: bdg peek --last 50 | bdg peek --verbose';
 }
 /**
  * Generate verbose mode commands section.
@@ -28,9 +28,9 @@ export function compactTipsMessage() {
 export function verboseCommandsMessage() {
     return [
         'Commands:',
-        '  Stop session:    bdg stop',
         '  Full preview:    bdg peek --last 50',
         '  Watch live:      bdg tail',
+        '  End session:     bdg stop',
     ].join('\n');
 }
 /**

package/dist/ui/messages/session.d.ts

@@ -10,7 +10,19 @@
 export interface LandingPageOptions {
     /** Target URL being monitored */
     url: string;
+    /** HTTP status of the main document (a warning is shown for 4xx/5xx) */
+    documentStatus?: number;
+    /** When `--timeout` will stop the session */
+    autoStopAt?: Date;
 }
+/**
+ * Lines shown under the target in both the full and the quiet start output:
+ * an HTTP error of the page, and when the session stops by itself.
+ *
+ * @param options - Landing page options
+ * @returns Lines (empty when there is nothing to say)
+ */
+export declare function startNotices(options: LandingPageOptions): string[];
 /**
  * Generate the landing page display for session start.
  *
@@ -41,10 +53,9 @@ export declare function landingPage(options: LandingPageOptions): string;
 /**
  * Generate "session stopped" success message.
  *
- * @param outputPath - Path to session output file
  * @returns Formatted success message
  */
-export declare function sessionStopped(outputPath: string): string;
+export declare function sessionStopped(): string;
 /**
  * Standard messages for stop command operations.
  */
@@ -52,7 +63,7 @@ export declare const STOP_MESSAGES: {
     readonly SUCCESS: "Session stopped successfully";
     readonly NO_SESSION: "No active session found";
     readonly FAILED: "Failed to stop session";
-    readonly DAEMON_NOT_RUNNING: "Daemon not running";
+    readonly DAEMON_NOT_RUNNING: "No active session";
 };
 /**
  * Generate stop session failed error message.
@@ -61,4 +72,14 @@ export declare const STOP_MESSAGES: {
  * @returns Formatted error message
  */
 export declare function stopFailedError(reason: string): string;
+/**
+ * Why the last session is gone, for `bdg status`.
+ *
+ * @param end - How and when it ended
+ * @returns One line
+ */
+export declare function lastSessionEndText(end: {
+    reason: string;
+    endedAt: number;
+}): string;
 //# sourceMappingURL=session.d.ts.map

package/dist/ui/messages/session.js

@@ -4,8 +4,24 @@
  * Centralized location for all session UI text including landing pages,
  * status displays, and session management messages.
  */
-import { buildCommonTasksSection, buildDomainCommandsSection, buildLiveMonitoringSection, buildSessionManagementSection, buildCdpSection, buildDiscoverySection, } from '../../ui/formatters/sessionFormatters.js';
-import { joinLines } from '../../ui/formatting.js';
+import { buildCommonTasksSection, buildDomainCommandsSection, buildLiveMonitoringSection, buildSessionManagementSection, buildCdpSection, buildDiscoverySection, } from '../formatters/sessionFormatters.js';
+import { joinLines } from '../formatting.js';
+/**
+ * Lines shown under the target in both the full and the quiet start output:
+ * an HTTP error of the page, and when the session stops by itself.
+ *
+ * @param options - Landing page options
+ * @returns Lines (empty when there is nothing to say)
+ */
+export function startNotices(options) {
+    const { documentStatus, autoStopAt } = options;
+    return [
+        ...(documentStatus !== undefined && documentStatus >= 400
+            ? [`⚠ The page responded with HTTP ${documentStatus}`]
+            : []),
+        ...(autoStopAt ? [`Auto-stop: at ${autoStopAt.toLocaleTimeString()} (--timeout)`] : []),
+    ];
+}
 /**
  * Generate the landing page display for session start.
  *
@@ -34,16 +50,16 @@ import { joinLines } from '../../ui/formatting.js';
  */
 export function landingPage(options) {
     const { url } = options;
-    return joinLines('', 'Session Started', '', `Target: ${url}`, '', buildCommonTasksSection(), '', buildDomainCommandsSection(), '', buildLiveMonitoringSection(), '', buildSessionManagementSection(), '', buildCdpSection(), '', buildDiscoverySection(), '');
+    const notices = startNotices(options);
+    return joinLines('', 'Session Started', '', `Target: ${url}`, '', ...(notices.length > 0 ? [...notices, ''] : []), buildCommonTasksSection(), '', buildDomainCommandsSection(), '', buildLiveMonitoringSection(), '', buildSessionManagementSection(), '', buildCdpSection(), '', buildDiscoverySection(), '');
 }
 /**
  * Generate "session stopped" success message.
  *
- * @param outputPath - Path to session output file
  * @returns Formatted success message
  */
-export function sessionStopped(outputPath) {
-    return `Session stopped. Output saved to: ${outputPath}`;
+export function sessionStopped() {
+    return 'Session stopped';
 }
 /**
  * Standard messages for stop command operations.
@@ -52,7 +68,7 @@ export const STOP_MESSAGES = {
     SUCCESS: 'Session stopped successfully',
     NO_SESSION: 'No active session found',
     FAILED: 'Failed to stop session',
-    DAEMON_NOT_RUNNING: 'Daemon not running',
+    DAEMON_NOT_RUNNING: 'No active session',
 };
 /**
  * Generate stop session failed error message.
@@ -63,4 +79,19 @@ export const STOP_MESSAGES = {
 export function stopFailedError(reason) {
     return `Stop session failed: ${reason}`;
 }
+/**
+ * Why the last session is gone, for `bdg status`.
+ *
+ * @param end - How and when it ended
+ * @returns One line
+ */
+export function lastSessionEndText(end) {
+    const why = {
+        crash: 'Chrome crashed or was closed',
+        closed: 'its page was closed',
+        timeout: 'the --timeout was reached',
+    };
+    const at = new Date(end.endedAt).toLocaleTimeString();
+    return `The last session ended at ${at}: ${why[end.reason] ?? end.reason}`;
+}
 //# sourceMappingURL=session.js.map

package/dist/ui/messages/validation.d.ts

@@ -4,49 +4,38 @@
  * User-facing messages for input validation failures across commands.
  */
 /**
- * Options for integer validation error messages.
+ * Allowed range for an integer option.
  */
 export interface IntegerValidationOptions {
     /** Minimum allowed value */
     min?: number;
     /** Maximum allowed value */
     max?: number;
-    /** Example valid value to show */
-    exampleValue?: number;
 }
 /**
- * Generate invalid integer error message with context.
+ * Generate error message for a value that is not an integer.
  *
- * @param fieldName - Name of the field being validated
  * @param value - The invalid value provided
- * @param options - Optional range and example information
- * @returns Formatted error message with suggestions
+ * @param options - Allowed range, shown when known
+ * @param name - Option name, e.g. "--port" (defaults to "value")
+ * @returns Formatted error message
  *
  * @example
  * ```typescript
- * // Basic usage
- * throw new Error(invalidIntegerError('timeout', 'abc'));
- *
- * // With range
- * throw new Error(invalidIntegerError('timeout', 'abc', { min: 1, max: 3600 }));
- *
- * // With example
- * throw new Error(invalidIntegerError('port', 'xyz', { min: 1024, max: 65535, exampleValue: 9222 }));
+ * invalidIntegerError('abc', { min: 1, max: 3600 });
+ * // 'Invalid value: "abc" is not an integer\nValid range: 1 to 3600'
+ * invalidIntegerError('abc', { min: 1, max: 65535 }, '--port');
+ * // 'Invalid --port: "abc" is not an integer\nValid range: 1 to 65535'
  * ```
  */
-export declare function invalidIntegerError(fieldName: string, value: string, options?: IntegerValidationOptions): string;
+export declare function invalidIntegerError(value: string, options?: IntegerValidationOptions, name?: string): string;
 /**
- * Generate invalid range error message for --last option.
+ * Generate error message for an integer outside the allowed range.
  *
- * @param min - Minimum allowed value
- * @param max - Maximum allowed value
+ * @param value - The out-of-range value provided
+ * @param options - Allowed range
+ * @param name - Option name, e.g. "--port" (defaults to "value")
  * @returns Formatted error message
- *
- * @example
- * ```typescript
- * throw new Error(invalidLastRangeError(0, 10000));
- * // "--last must be between 0 and 10000"
- * ```
  */
-export declare function invalidLastRangeError(min?: number, max?: number): string;
+export declare function integerOutOfRangeError(value: string, options: IntegerValidationOptions, name?: string): string;
 //# sourceMappingURL=validation.d.ts.map

package/dist/ui/messages/validation.js

@@ -3,56 +3,51 @@
  *
  * User-facing messages for input validation failures across commands.
  */
-import { joinLines } from '../../ui/formatting.js';
+import { joinLines } from '../formatting.js';
 /**
- * Generate invalid integer error message with context.
+ * Describe an integer range for error messages.
  *
- * @param fieldName - Name of the field being validated
- * @param value - The invalid value provided
- * @param options - Optional range and example information
- * @returns Formatted error message with suggestions
- *
- * @example
- * ```typescript
- * // Basic usage
- * throw new Error(invalidIntegerError('timeout', 'abc'));
- *
- * // With range
- * throw new Error(invalidIntegerError('timeout', 'abc', { min: 1, max: 3600 }));
- *
- * // With example
- * throw new Error(invalidIntegerError('port', 'xyz', { min: 1024, max: 65535, exampleValue: 9222 }));
- * ```
+ * @param options - Range bounds
+ * @returns e.g. "Valid range: 1 to 65535", or undefined without bounds
  */
-export function invalidIntegerError(fieldName, value, options) {
-    const header = `Error: Invalid ${fieldName}: "${value}" is not a valid integer`;
-    let rangeInfo;
-    if (options?.min !== undefined && options?.max !== undefined) {
-        rangeInfo = `Valid range: ${options.min} to ${options.max}`;
-    }
-    else if (options?.min !== undefined) {
-        rangeInfo = `Must be at least ${options.min}`;
+function describeRange(options) {
+    if (options?.min !== undefined && options.max !== undefined) {
+        return `Valid range: ${options.min} to ${options.max}`;
     }
-    else if (options?.max !== undefined) {
-        rangeInfo = `Must be at most ${options.max}`;
-    }
-    const example = options?.exampleValue ?? options?.min ?? 30;
-    return joinLines(header, rangeInfo, '', `Example: --${fieldName} ${example}`);
+    if (options?.min !== undefined)
+        return `Must be at least ${options.min}`;
+    if (options?.max !== undefined)
+        return `Must be at most ${options.max}`;
+    return undefined;
 }
 /**
- * Generate invalid range error message for --last option.
+ * Generate error message for a value that is not an integer.
  *
- * @param min - Minimum allowed value
- * @param max - Maximum allowed value
+ * @param value - The invalid value provided
+ * @param options - Allowed range, shown when known
+ * @param name - Option name, e.g. "--port" (defaults to "value")
  * @returns Formatted error message
  *
  * @example
  * ```typescript
- * throw new Error(invalidLastRangeError(0, 10000));
- * // "--last must be between 0 and 10000"
+ * invalidIntegerError('abc', { min: 1, max: 3600 });
+ * // 'Invalid value: "abc" is not an integer\nValid range: 1 to 3600'
+ * invalidIntegerError('abc', { min: 1, max: 65535 }, '--port');
+ * // 'Invalid --port: "abc" is not an integer\nValid range: 1 to 65535'
  * ```
  */
-export function invalidLastRangeError(min = 0, max = 10000) {
-    return `--last must be between ${min} and ${max}`;
+export function invalidIntegerError(value, options, name = 'value') {
+    return joinLines(`Invalid ${name}: "${value}" is not an integer`, describeRange(options));
+}
+/**
+ * Generate error message for an integer outside the allowed range.
+ *
+ * @param value - The out-of-range value provided
+ * @param options - Allowed range
+ * @param name - Option name, e.g. "--port" (defaults to "value")
+ * @returns Formatted error message
+ */
+export function integerOutOfRangeError(value, options, name = 'value') {
+    return joinLines(`Invalid ${name}: ${value} is out of range`, describeRange(options));
 }
 //# sourceMappingURL=validation.js.map

package/dist/utils/atomicFile.js

@@ -1,7 +1,7 @@
 import * as crypto from 'crypto';
 import * as fs from 'fs';
 import { createLogger } from '../ui/logging/index.js';
-import { getErrorMessage } from '../utils/errors.js';
+import { getErrorMessage } from './errors.js';
 const log = createLogger('atomic-file');
 /**
  * Atomic file operations using tmp-file-then-rename pattern.

package/dist/utils/decisionTrees.js

@@ -152,7 +152,7 @@ export const DECISION_TREES = {
                 noAction: 'next',
             },
             {
-                question: 'Ready to end session and save output?',
+                question: 'Ready to end session?',
                 yesCommand: 'stop',
                 noAction: 'next',
             },