browser-debugger-cli 0.7.2 → 0.9.0

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

@@ -3,6 +3,7 @@
  *
  * User-facing messages for the console command output and formatting.
  */
+import type { ConsoleSkipped } from '../formatters/console/shared.js';
 /**
  * Generate message for following console output.
  *
@@ -16,9 +17,12 @@ export declare function followingConsoleMessage(): string;
  */
 export declare function stoppedFollowingConsoleMessage(): string;
 /**
- * Generate message when no console data is available.
+ * Note under a console list whose indices skip messages: the indices are
+ * positions in the session's message list (what `bdg details console <n>`
+ * takes), and the messages in between were left out by the filters.
  *
- * @returns Error message with context
+ * @param skipped - Messages left out between the first and last listed index
+ * @returns e.g. `[n] are positions in the session's message list; not listed in between: 1 message from another page load (-H lists all)`
  */
-export declare function noConsoleDataMessage(): string;
+export declare function consoleIndexGapNote(skipped: ConsoleSkipped): string;
 //# sourceMappingURL=consoleMessages.d.ts.map

package/dist/ui/messages/consoleMessages.js

@@ -3,6 +3,7 @@
  *
  * User-facing messages for the console command output and formatting.
  */
+import { pluralize } from '../formatting.js';
 /**
  * Generate message for following console output.
  *
@@ -20,11 +21,19 @@ export function stoppedFollowingConsoleMessage() {
     return 'Stopped streaming console messages';
 }
 /**
- * Generate message when no console data is available.
+ * Note under a console list whose indices skip messages: the indices are
+ * positions in the session's message list (what `bdg details console <n>`
+ * takes), and the messages in between were left out by the filters.
  *
- * @returns Error message with context
+ * @param skipped - Messages left out between the first and last listed index
+ * @returns e.g. `[n] are positions in the session's message list; not listed in between: 1 message from another page load (-H lists all)`
  */
-export function noConsoleDataMessage() {
-    return 'No console data available. Console messages are captured during browser session.';
+export function consoleIndexGapNote(skipped) {
+    const reasons = [
+        skipped.otherLevels > 0 && `${pluralize(skipped.otherLevels, 'message')} of another level`,
+        skipped.otherPages > 0 &&
+            `${pluralize(skipped.otherPages, 'message')} from another page load (-H lists all)`,
+    ].filter(Boolean);
+    return `[n] are positions in the session's message list; not listed in between: ${reasons.join(', ')}`;
 }
 //# 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,27 @@
 /**
  * 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';
+import { sessionCommand } from './sessionCommand.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 '${sessionCommand(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

@@ -4,6 +4,7 @@
  * User-facing messages for the peek command, including empty states,
  * tips, and interactive command suggestions.
  * */
+import { sessionCommand } from './sessionCommand.js';
 export const PREVIEW_EMPTY_STATES = {
     NO_DATA: '(none)',
     NO_NETWORK_REQUESTS: 'No network requests yet',
@@ -18,7 +19,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: ${sessionCommand('bdg peek --last 50')} | ${sessionCommand('bdg peek --verbose')}`;
 }
 /**
  * Generate verbose mode commands section.
@@ -28,9 +29,9 @@ export function compactTipsMessage() {
 export function verboseCommandsMessage() {
     return [
         'Commands:',
-        '  Stop session:    bdg stop',
-        '  Full preview:    bdg peek --last 50',
-        '  Watch live:      bdg tail',
+        `  Full preview:    ${sessionCommand('bdg peek --last 50')}`,
+        `  Watch live:      ${sessionCommand('bdg tail')}`,
+        `  End session:     ${sessionCommand('bdg stop')}`,
     ].join('\n');
 }
 /**

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

@@ -4,55 +4,61 @@
  * Centralized location for all session UI text including landing pages,
  * status displays, and session management messages.
  */
+import type { PageLoadingState } from '../../ipc/protocol/commands.js';
 /**
  * Options for the landing page display.
  */
 export interface LandingPageOptions {
     /** Target URL being monitored */
     url: string;
+    /** HTTP status of the main document (a warning is shown for 4xx/5xx) */
+    documentStatus?: number;
+    /** The page had not finished loading (a warning names what it waits on) */
+    loading?: PageLoadingState;
+    /** When `--timeout` will stop the session */
+    autoStopAt?: Date;
+    /** Name of a named session (`--session`) */
+    session?: string;
 }
 /**
- * Generate the landing page display for session start.
+ * Lines shown under the target in both the full and the quiet start output:
+ * the session name, an HTTP error of the page, a page still loading, and
+ * when the session stops by itself.
  *
- * Shows a clean, organized overview of available commands grouped by priority.
- * High-level commands are presented first to guide agents toward token-efficient
- * wrappers before falling back to verbose CDP commands.
- *
- * Section order optimized for agent discoverability:
- * 1. Common tasks with token savings estimates
- * 2. Comprehensive domain command coverage (12+ commands)
- * 3. Live monitoring capabilities
- * 4. Session management
- * 5. Advanced CDP access (positioned as fallback)
- * 6. Discovery resources for agents
+ * @param options - Landing page options
+ * @returns Lines (empty when there is nothing to say)
+ */
+export declare function startNotices(options: LandingPageOptions): string[];
+/**
+ * Generate the start output: the target, the notices of {@link startNotices},
+ * one line of next commands and where to find the rest. Kept to a few lines
+ * because agents read it on every start; `bdg --help` lists everything.
  *
  * @param options - Landing page options
- * @returns Formatted landing page string
+ * @returns Formatted start output
  *
  * @example
  * ```typescript
- * const message = landingPage({
- *   url: 'http://localhost:3000'
- * });
- * console.log(message);
+ * landingPage({ url: 'http://localhost:3000' });
+ * // Session Started
+ * // Target: http://localhost:3000
+ * // Next: bdg dom layout <selector>, bdg dom query <selector>, ...
+ * // More: bdg --help (bdg --help --json for agents)
  * ```
  */
 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.
  */
 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";
 };
 /**
  * Generate stop session failed error message.
@@ -61,4 +67,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,55 +4,73 @@
  * 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 { joinLines } from '../formatting.js';
+import { pageLoadingWarning } from './commands.js';
 /**
- * Generate the landing page display for session start.
+ * Lines shown under the target in both the full and the quiet start output:
+ * the session name, an HTTP error of the page, a page still loading, and
+ * when the session stops by itself.
  *
- * Shows a clean, organized overview of available commands grouped by priority.
- * High-level commands are presented first to guide agents toward token-efficient
- * wrappers before falling back to verbose CDP commands.
- *
- * Section order optimized for agent discoverability:
- * 1. Common tasks with token savings estimates
- * 2. Comprehensive domain command coverage (12+ commands)
- * 3. Live monitoring capabilities
- * 4. Session management
- * 5. Advanced CDP access (positioned as fallback)
- * 6. Discovery resources for agents
+ * @param options - Landing page options
+ * @returns Lines (empty when there is nothing to say)
+ */
+export function startNotices(options) {
+    const { documentStatus, loading, autoStopAt, session } = options;
+    return [
+        ...(session
+            ? [
+                `Session: ${session} (pass --session ${session} or set BDG_SESSION=${session} on every command)`,
+            ]
+            : []),
+        ...(documentStatus !== undefined && documentStatus >= 400
+            ? [`⚠ The page responded with HTTP ${documentStatus}`]
+            : []),
+        ...(loading ? [`⚠ ${pageLoadingWarning(loading)}`] : []),
+        ...(autoStopAt ? [`Auto-stop: at ${autoStopAt.toLocaleTimeString()} (--timeout)`] : []),
+    ];
+}
+/** Most useful commands after a start, cheapest first (screenshots cost the most tokens) */
+const START_NEXT_COMMANDS = [
+    'bdg dom layout <selector>',
+    'bdg dom query <selector>',
+    'bdg dom form',
+    'bdg peek',
+    'bdg dom screenshot out.png',
+];
+/**
+ * Generate the start output: the target, the notices of {@link startNotices},
+ * one line of next commands and where to find the rest. Kept to a few lines
+ * because agents read it on every start; `bdg --help` lists everything.
  *
  * @param options - Landing page options
- * @returns Formatted landing page string
+ * @returns Formatted start output
  *
  * @example
  * ```typescript
- * const message = landingPage({
- *   url: 'http://localhost:3000'
- * });
- * console.log(message);
+ * landingPage({ url: 'http://localhost:3000' });
+ * // Session Started
+ * // Target: http://localhost:3000
+ * // Next: bdg dom layout <selector>, bdg dom query <selector>, ...
+ * // More: bdg --help (bdg --help --json for agents)
  * ```
  */
 export function landingPage(options) {
-    const { url } = options;
-    return joinLines('', 'Session Started', '', `Target: ${url}`, '', buildCommonTasksSection(), '', buildDomainCommandsSection(), '', buildLiveMonitoringSection(), '', buildSessionManagementSection(), '', buildCdpSection(), '', buildDiscoverySection(), '');
+    return joinLines('Session Started', `Target: ${options.url}`, ...startNotices(options), `Next: ${START_NEXT_COMMANDS.join(', ')}`, 'More: bdg --help (bdg --help --json for agents)');
 }
 /**
  * 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.
  */
 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',
 };
 /**
  * Generate stop session failed error message.
@@ -63,4 +81,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/sessionCommand.d.ts

@@ -0,0 +1,43 @@
+/**
+ * bdg command lines and wording for the selected session.
+ *
+ * Every hint, suggestion and error that tells the user to run a bdg command
+ * goes through {@link sessionCommand}, so a named session's hints carry
+ * `--session <name>` and following them never acts on the default session.
+ */
+/**
+ * A bdg command for the selected session: ` --session <name>` is appended
+ * when a named session is selected.
+ *
+ * @param command - Command line, e.g. `bdg stop`
+ * @param session - Session name (defaults to the selected one; null for the default session)
+ * @returns The command, scoped to the session
+ *
+ * @example
+ * ```typescript
+ * sessionCommand('bdg stop');            // 'bdg stop' (default session)
+ * sessionCommand('bdg stop', 'agent-1'); // 'bdg stop --session agent-1'
+ * ```
+ */
+export declare function sessionCommand(command: string, session?: string | null): string;
+/**
+ * "No active session", naming a named session.
+ *
+ * @param session - Session name (defaults to the selected one; null for the default session)
+ * @returns `No active session` or `No active session "<name>"`
+ */
+export declare function noActiveSessionMessage(session?: string | null): string;
+/**
+ * Shell command that deletes a directory by hand (single-quoted).
+ *
+ * @param dir - Directory
+ * @returns Command line
+ */
+export declare function removeDirCommand(dir: string): string;
+/**
+ * How to start the selected session.
+ *
+ * @returns Suggestion
+ */
+export declare function startSessionSuggestion(): string;
+//# sourceMappingURL=sessionCommand.d.ts.map

package/dist/ui/messages/sessionCommand.js

@@ -0,0 +1,52 @@
+/**
+ * bdg command lines and wording for the selected session.
+ *
+ * Every hint, suggestion and error that tells the user to run a bdg command
+ * goes through {@link sessionCommand}, so a named session's hints carry
+ * `--session <name>` and following them never acts on the default session.
+ */
+import { getSessionName } from '../../session/paths.js';
+/**
+ * A bdg command for the selected session: ` --session <name>` is appended
+ * when a named session is selected.
+ *
+ * @param command - Command line, e.g. `bdg stop`
+ * @param session - Session name (defaults to the selected one; null for the default session)
+ * @returns The command, scoped to the session
+ *
+ * @example
+ * ```typescript
+ * sessionCommand('bdg stop');            // 'bdg stop' (default session)
+ * sessionCommand('bdg stop', 'agent-1'); // 'bdg stop --session agent-1'
+ * ```
+ */
+export function sessionCommand(command, session = getSessionName()) {
+    return session === null ? command : `${command} --session ${session}`;
+}
+/**
+ * "No active session", naming a named session.
+ *
+ * @param session - Session name (defaults to the selected one; null for the default session)
+ * @returns `No active session` or `No active session "<name>"`
+ */
+export function noActiveSessionMessage(session = getSessionName()) {
+    return session === null ? 'No active session' : `No active session "${session}"`;
+}
+/**
+ * Shell command that deletes a directory by hand (single-quoted).
+ *
+ * @param dir - Directory
+ * @returns Command line
+ */
+export function removeDirCommand(dir) {
+    return `rm -rf '${dir.replaceAll("'", "'\\''")}'`;
+}
+/**
+ * How to start the selected session.
+ *
+ * @returns Suggestion
+ */
+export function startSessionSuggestion() {
+    return `Start a session with: ${sessionCommand('bdg <url>')}`;
+}
+//# sourceMappingURL=sessionCommand.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