browser-debugger-cli 0.7.1 → 0.8.0

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

@@ -3,7 +3,41 @@
  *
  * Centralized location for Chrome diagnostics, launch errors, and troubleshooting messages.
  */
-import type { ChromeDiagnostics } from '../../connection/diagnostics.js';
+import { type ChromeDiagnostics } from '../../connection/diagnostics.js';
+import type { IssueDetails } from '../../errors/issues.js';
+import type { ChromeNoticeCode, NoticeDetails } from '../../errors/notices.js';
+/**
+ * Format a structured Chrome-related notice into a user-facing log line.
+ *
+ * Counterpart to {@link formatChromeIssue} for happy-path events. Wire a
+ * NoticeSink that does `log.info(formatChromeNotice(notice))` at the
+ * boundary so core modules stay free of UI imports.
+ */
+export declare function formatChromeNotice(notice: NoticeDetails<ChromeNoticeCode>): string;
+/**
+ * Format a structured Chrome-related issue into a user-facing message.
+ *
+ * Called at the UI boundary when a ChromeLaunchError with `issue` details
+ * reaches a CLI or daemon log sink. Core modules produce the IssueDetails;
+ * this function is the only place wording is assembled.
+ */
+export declare function formatChromeIssue(issue: IssueDetails): string;
+/**
+ * Chrome exited before its debugging port opened.
+ *
+ * @param exitCode - Chrome's exit code
+ * @param output - Chrome's last output lines
+ * @param userDataDir - Chrome profile directory
+ * @param profileInUse - Whether another Chrome has the profile open
+ * @returns Message; its first line is the error, the rest the suggestion
+ */
+export declare function chromeExitedDuringStartupError(exitCode: number | null, output: string[], userDataDir: string, profileInUse: boolean): string;
+/**
+ * Retrieve Chrome diagnostics and format for error messages.
+ *
+ * @returns Array of formatted diagnostic strings
+ */
+export declare function getFormattedDiagnostics(): string[];
 /**
  * Format Chrome diagnostics for error reporting when Chrome launch fails.
  *
@@ -18,20 +52,6 @@ import type { ChromeDiagnostics } from '../../connection/diagnostics.js';
  * ```
  */
 export declare function formatDiagnosticsForError(diagnostics: ChromeDiagnostics): string[];
-/**
- * Format Chrome diagnostics for verbose status output (bdg status --verbose).
- *
- * @param diagnostics - Chrome diagnostics information
- * @returns Array of formatted status lines
- *
- * @example
- * ```typescript
- * const diagnostics = getChromeDiagnostics();
- * const statusLines = formatDiagnosticsForStatus(diagnostics);
- * console.log(statusLines.join('\n'));
- * ```
- */
-export declare function formatDiagnosticsForStatus(diagnostics: ChromeDiagnostics): string[];
 /**
  * Generate invalid port error message.
  *
@@ -80,21 +100,6 @@ export declare function chromeExternalSkipTerminationMessage(): string;
  * @returns Formatted error message with diagnostics and troubleshooting steps
  */
 export declare function noPageTargetFoundError(port: number, availableTargets: string | null): string;
-/**
- * Generate Chrome launch success message.
- *
- * @param pid - Chrome process ID
- * @param duration - Launch duration in milliseconds
- * @returns Formatted message
- */
-export declare function chromeLaunchSuccessMessage(pid: number, duration: number): string;
-/**
- * Generate user data directory info message.
- *
- * @param dir - User data directory path
- * @returns Formatted message
- */
-export declare function chromeUserDataDirMessage(dir: string): string;
 /**
  * Generate preferences file not found error.
  *
@@ -156,74 +161,4 @@ export declare function chromeBinaryOverrideIsDirectory(path: string, source: st
  * @returns Multi-line formatted error message with troubleshooting steps
  */
 export declare function portInUseError(port: number): string;
-/**
- * Generate message for starting Chrome cleanup process.
- *
- * @returns Formatted message
- *
- * @example
- * ```typescript
- * console.error(cleanupChromeAttemptingMessage());
- * ```
- */
-export declare function cleanupChromeAttemptingMessage(): string;
-/**
- * Generate warning message when Chrome PID is not found in cache.
- *
- * @returns Multi-line formatted warning message
- *
- * @example
- * ```typescript
- * console.error(cleanupChromePidNotFoundMessage());
- * ```
- */
-export declare function cleanupChromePidNotFoundMessage(): string;
-/**
- * Generate message indicating Chrome process is being killed.
- *
- * @param pid - Chrome process ID
- * @returns Formatted message
- *
- * @example
- * ```typescript
- * console.error(cleanupChromeKillingMessage(12345));
- * // Output: "Killing Chrome process (PID: 12345)..."
- * ```
- */
-export declare function cleanupChromeKillingMessage(pid: number): string;
-/**
- * Generate success message after Chrome process is killed.
- *
- * @returns Formatted success message
- *
- * @example
- * ```typescript
- * console.error(cleanupChromeSuccessMessage());
- * ```
- */
-export declare function cleanupChromeSuccessMessage(): string;
-/**
- * Generate error message when Chrome cleanup fails.
- *
- * @param error - Error message
- * @returns Multi-line formatted error message with troubleshooting
- *
- * @example
- * ```typescript
- * console.error(cleanupChromeFailedMessage('Process not found'));
- * ```
- */
-export declare function cleanupChromeFailedMessage(error: string): string;
-/**
- * Generate generic error message for Chrome cleanup process failure.
- *
- * @param error - Error message
- * @returns Formatted error message
- *
- * @example
- * ```typescript
- * console.error(cleanupChromeProcessFailedMessage('Cannot read PID file'));
- * ```
- */
-export declare function cleanupChromeProcessFailedMessage(error: string): string;
 //# sourceMappingURL=chrome.d.ts.map

package/dist/ui/messages/chrome.js

@@ -3,7 +3,105 @@
  *
  * Centralized location for Chrome diagnostics, launch errors, and troubleshooting messages.
  */
-import { pluralize, joinLines } from '../../ui/formatting.js';
+import { getChromeDiagnostics } from '../../connection/diagnostics.js';
+import { pluralize, joinLines } from '../formatting.js';
+/**
+ * Format a structured Chrome-related notice into a user-facing log line.
+ *
+ * Counterpart to {@link formatChromeIssue} for happy-path events. Wire a
+ * NoticeSink that does `log.info(formatChromeNotice(notice))` at the
+ * boundary so core modules stay free of UI imports.
+ */
+export function formatChromeNotice(notice) {
+    const ctx = notice.context ?? {};
+    switch (notice.code) {
+        case 'EXTERNAL_CHROME_CONNECTING':
+            return chromeExternalConnectionMessage();
+        case 'EXTERNAL_CHROME_WS_URL':
+            return chromeExternalWebSocketMessage(ctx['wsUrl']);
+        case 'EXTERNAL_CHROME_NO_PID':
+            return chromeExternalNoPidMessage();
+        case 'EXTERNAL_CHROME_SKIP_TERMINATION':
+            return chromeExternalSkipTerminationMessage();
+    }
+}
+/**
+ * Format a structured Chrome-related issue into a user-facing message.
+ *
+ * Called at the UI boundary when a ChromeLaunchError with `issue` details
+ * reaches a CLI or daemon log sink. Core modules produce the IssueDetails;
+ * this function is the only place wording is assembled.
+ */
+export function formatChromeIssue(issue) {
+    const ctx = issue.context ?? {};
+    switch (issue.code) {
+        case 'PORT_IN_USE':
+            return portInUseError(ctx['port']);
+        case 'INVALID_PORT':
+            return invalidPortError(ctx['port']);
+        case 'USER_DATA_DIR_CREATE_FAILED':
+            return userDataDirError(ctx['userDataDir'], ctx['reason'] ?? '');
+        case 'CHROME_LAUNCH_FAILED':
+        case 'CHROME_DIED_AFTER_LAUNCH': {
+            const port = ctx['port'];
+            const reason = ctx['reason'];
+            const pid = typeof ctx['pid'] === 'number' ? ctx['pid'] : 'unknown';
+            const header = issue.code === 'CHROME_DIED_AFTER_LAUNCH'
+                ? `Chrome died immediately after launch (PID: ${pid})`
+                : reason
+                    ? chromeLaunchFailedError(reason)
+                    : `Chrome failed to launch`;
+            const diagnostics = getFormattedDiagnostics();
+            return joinLines(header, '', 'Possible causes:', `  - Port ${port} conflict (check: lsof -ti:${port})`, `  - Chrome binary not found`, `  - Insufficient permissions`, `  - Chrome crashed on startup`, '', ...diagnostics, '', 'Try:', `  - bdg cleanup`, `  - See what uses the port: lsof -i :${port}`, `  - Use different port: bdg <url> --port ${port + 1}`, `  - In a container where Chrome's sandbox fails: BDG_NO_SANDBOX=1 bdg <url>`);
+        }
+        case 'CHROME_EXITED_DURING_STARTUP':
+            return chromeExitedDuringStartupError(ctx['exitCode'], ctx['output'] ?? [], ctx['userDataDir'], ctx['profileInUse'] === true);
+        case 'NO_PAGE_TARGET_FOUND':
+            return noPageTargetFoundError(ctx['port'], ctx['availableTargets']);
+        case 'CHROME_BINARY_NOT_FOUND': {
+            const diagnostics = getFormattedDiagnostics();
+            return joinLines(chromeBinaryOverrideNotFound(ctx['chromePath'], ctx['source']), '', ...diagnostics);
+        }
+        case 'CHROME_BINARY_IS_DIRECTORY':
+            return chromeBinaryOverrideIsDirectory(ctx['chromePath'], ctx['source']);
+        case 'CHROME_BINARY_NOT_EXECUTABLE': {
+            const reason = ctx['reason'];
+            const base = chromeBinaryOverrideNotExecutable(ctx['chromePath'], ctx['source']);
+            return reason ? `${base}\n\n${reason}` : base;
+        }
+        case 'PREFS_FILE_NOT_FOUND':
+            return prefsFileNotFoundError(ctx['file']);
+        case 'PREFS_INVALID_FORMAT':
+            return invalidPrefsFormatError(ctx['file'], ctx['actualType']);
+        case 'PREFS_LOAD_FAILED':
+            return prefsLoadError(ctx['file'], ctx['reason'] ?? '');
+        case 'PREFS_NOT_JSON_SERIALIZABLE':
+            return `Chrome preferences must be JSON-serializable: ${ctx['reason'] ?? 'unknown error'}`;
+    }
+}
+/**
+ * Chrome exited before its debugging port opened.
+ *
+ * @param exitCode - Chrome's exit code
+ * @param output - Chrome's last output lines
+ * @param userDataDir - Chrome profile directory
+ * @param profileInUse - Whether another Chrome has the profile open
+ * @returns Message; its first line is the error, the rest the suggestion
+ */
+export function chromeExitedDuringStartupError(exitCode, output, userDataDir, profileInUse) {
+    if (profileInUse) {
+        return joinLines(`The Chrome profile ${userDataDir} is in use by another Chrome`, 'Close that Chrome, or use another profile directory: bdg <url> -u ./other-profile');
+    }
+    return joinLines(`Chrome exited during startup (exit code ${exitCode ?? 'none'})`, ...(output.length > 0 ? ['Chrome said:', ...output.map((line) => `  ${line}`)] : []), 'Check --chrome-flags and BDG_CHROME_FLAGS (an unknown flag or value can stop Chrome)');
+}
+/**
+ * Retrieve Chrome diagnostics and format for error messages.
+ *
+ * @returns Array of formatted diagnostic strings
+ */
+export function getFormattedDiagnostics() {
+    return formatDiagnosticsForError(getChromeDiagnostics());
+}
 /**
  * Format Chrome diagnostics for error reporting when Chrome launch fails.
  *
@@ -39,38 +137,6 @@ export function formatDiagnosticsForError(diagnostics) {
     }
     return lines;
 }
-/**
- * Format Chrome diagnostics for verbose status output (bdg status --verbose).
- *
- * @param diagnostics - Chrome diagnostics information
- * @returns Array of formatted status lines
- *
- * @example
- * ```typescript
- * const diagnostics = getChromeDiagnostics();
- * const statusLines = formatDiagnosticsForStatus(diagnostics);
- * console.log(statusLines.join('\n'));
- * ```
- */
-export function formatDiagnosticsForStatus(diagnostics) {
-    const lines = [];
-    if (diagnostics.defaultPath) {
-        lines.push(`Binary:           ${diagnostics.defaultPath}`);
-    }
-    else {
-        lines.push('Binary:           Could not determine');
-    }
-    lines.push(`Installations:    ${diagnostics.installationCount} found`);
-    if (diagnostics.installationCount > 0 && diagnostics.installationCount <= 3) {
-        diagnostics.installations.forEach((path, index) => {
-            lines.push(`  ${index + 1}. ${path}`);
-        });
-    }
-    else if (diagnostics.installationCount > 3) {
-        lines.push(`  (Use 'bdg cleanup --aggressive' to see all)`);
-    }
-    return lines;
-}
 /**
  * Generate invalid port error message.
  *
@@ -131,26 +197,8 @@ export function chromeExternalSkipTerminationMessage() {
  * @returns Formatted error message with diagnostics and troubleshooting steps
  */
 export function noPageTargetFoundError(port, availableTargets) {
-    return joinLines('No page target found after Chrome launch\n', 'Possible causes:', `  1. Port conflict (${port})`, `     → Check: lsof -ti:${port}`, `     → Kill: pkill -f "chrome.*${port}"`, '  2. Chrome failed to create default target', '  3. Stale session', '     → Fix: bdg cleanup && bdg <url>\n', `Available Chrome targets:\n${availableTargets ?? '  (none)'}\n`, 'Try:', '  - Clean up and retry: bdg cleanup && bdg <url>', `  - Use different port: bdg <url> --port ${port + 1}`);
-}
-/**
- * Generate Chrome launch success message.
- *
- * @param pid - Chrome process ID
- * @param duration - Launch duration in milliseconds
- * @returns Formatted message
- */
-export function chromeLaunchSuccessMessage(pid, duration) {
-    return `Chrome launched successfully (PID: ${pid}, ${duration}ms)`;
-}
-/**
- * Generate user data directory info message.
- *
- * @param dir - User data directory path
- * @returns Formatted message
- */
-export function chromeUserDataDirMessage(dir) {
-    return `User data directory: ${dir}`;
+    return joinLines(`Chrome started but opened no page to attach to (port ${port})`, 'Retry: bdg <url>. If it keeps failing, another program may use the port (lsof -i :' +
+        `${port}) or a crashed session may be left over: bdg cleanup && bdg <url>`, ...(availableTargets ? ['', `Chrome targets:\n${availableTargets}`] : []));
 }
 /**
  * Generate preferences file not found error.
@@ -228,88 +276,6 @@ export function chromeBinaryOverrideIsDirectory(path, source) {
  * @returns Multi-line formatted error message with troubleshooting steps
  */
 export function portInUseError(port) {
-    return joinLines(`Port ${port} is already in use.\n`, 'This usually means Chrome is still running from a previous session.\n', 'Try:', `  - bdg cleanup --aggressive  (kills all Chrome processes)`, `  - bdg cleanup --force       (removes session files + kills Chrome on port ${port})`, `  - lsof -ti:${port} | xargs kill -9  (force kill process on port)`, `  - Use different port: bdg <url> --port ${port + 1}`);
-}
-/**
- * Generate message for starting Chrome cleanup process.
- *
- * @returns Formatted message
- *
- * @example
- * ```typescript
- * console.error(cleanupChromeAttemptingMessage());
- * ```
- */
-export function cleanupChromeAttemptingMessage() {
-    return '\nAttempting to kill stale Chrome processes...';
-}
-/**
- * Generate warning message when Chrome PID is not found in cache.
- *
- * @returns Multi-line formatted warning message
- *
- * @example
- * ```typescript
- * console.error(cleanupChromePidNotFoundMessage());
- * ```
- */
-export function cleanupChromePidNotFoundMessage() {
-    return joinLines('Warning: No Chrome PID found in cache', '   Either Chrome was already running, or no Chrome was launched by bdg\n');
-}
-/**
- * Generate message indicating Chrome process is being killed.
- *
- * @param pid - Chrome process ID
- * @returns Formatted message
- *
- * @example
- * ```typescript
- * console.error(cleanupChromeKillingMessage(12345));
- * // Output: "Killing Chrome process (PID: 12345)..."
- * ```
- */
-export function cleanupChromeKillingMessage(pid) {
-    return `Killing Chrome process (PID: ${pid})...`;
-}
-/**
- * Generate success message after Chrome process is killed.
- *
- * @returns Formatted success message
- *
- * @example
- * ```typescript
- * console.error(cleanupChromeSuccessMessage());
- * ```
- */
-export function cleanupChromeSuccessMessage() {
-    return 'Chrome process killed successfully';
-}
-/**
- * Generate error message when Chrome cleanup fails.
- *
- * @param error - Error message
- * @returns Multi-line formatted error message with troubleshooting
- *
- * @example
- * ```typescript
- * console.error(cleanupChromeFailedMessage('Process not found'));
- * ```
- */
-export function cleanupChromeFailedMessage(error) {
-    return joinLines(`Error: Failed to kill Chrome process: ${error}`, '   Try manually killing Chrome processes if issues persist\n');
-}
-/**
- * Generate generic error message for Chrome cleanup process failure.
- *
- * @param error - Error message
- * @returns Formatted error message
- *
- * @example
- * ```typescript
- * console.error(cleanupChromeProcessFailedMessage('Cannot read PID file'));
- * ```
- */
-export function cleanupChromeProcessFailedMessage(error) {
-    return `Error: Failed to cleanup Chrome processes: ${error}\n`;
+    return joinLines(`Port ${port} is already in use.\n`, 'Another program (or a Chrome left from a previous session) is listening on it.\n', 'Try:', `  - Use a different port: bdg <url> --port ${port + 1}`, `  - If a bdg session is stuck: bdg cleanup --force  (stops bdg's own daemon and Chrome only)`, `  - See what uses the port: lsof -i :${port}`);
 }
 //# sourceMappingURL=chrome.js.map

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

@@ -4,13 +4,14 @@
  * User-facing messages for command-specific operations like stopping sessions,
  * cleaning up stale files, and validating command arguments.
  */
+import type { DomFrame } from '../../ipc/protocol/commands.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 declare function chromeKilledMessage(pid?: number): string;
+export declare function chromeClosedMessage(pid?: number): string;
 /**
  * Generate orphaned daemons cleaned message.
  *
@@ -18,6 +19,123 @@ export declare function chromeKilledMessage(pid?: number): string;
  * @returns Formatted success message
  */
 export declare function orphanedDaemonsCleanedMessage(count: number): string;
+/**
+ * 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 declare function domClickFallbackWarning(reason: string | null | undefined): string;
+/**
+ * Note under a shortened list of matches.
+ *
+ * @param hidden - Matches not listed
+ * @returns e.g. "... and 1174 more (use --json for all)"
+ */
+export declare function moreMatchesNote(hidden: number): string;
+/**
+ * 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 declare function multipleMatchesWarning(count: number, action: string): string;
+/**
+ * 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 declare function listenersHeadline(element: string, count: number): string;
+/**
+ * `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 declare function noListenersMessage(element: string, types?: string[]): string;
+/** What `bdg dom listeners` covers, shown when it found nothing */
+export declare const NO_LISTENERS_HINT = "Inline on\u2026 attributes and on\u2026 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 declare function delegatedListenersNote(types: string[]): string;
+/**
+ * A JavaScript dialog bdg accepted, as one line.
+ *
+ * @param dialog - Dialog type and text
+ * @returns e.g. 'alert() dialog accepted: "Saved"'
+ */
+export declare function dialogConsoleText(dialog: {
+    type: string;
+    message: string;
+}): string;
+/** Headline of each pointer action, e.g. "Element Double-clicked" */
+export declare const POINTER_ACTION_DONE: {
+    readonly click: "Clicked";
+    readonly double: "Double-clicked";
+    readonly right: "Right-clicked";
+    readonly hover: "Hovered";
+};
+/** Headline of each `bdg page` action */
+export declare const PAGE_ACTION_DONE: {
+    readonly navigate: "Navigated";
+    readonly reload: "Reloaded";
+    readonly back: "Went back";
+    readonly forward: "Went forward";
+};
+/** Help text of the `bdg page` history commands */
+export declare const PAGE_ACTION_DESCRIPTIONS: {
+    readonly reload: "Reload the page";
+    readonly back: "Go back one page (like the browser button)";
+    readonly 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 declare function httpErrorWarning(status: number): string;
+/**
+ * `bdg page navigate` to a URL that loaded no page.
+ *
+ * @returns Warning
+ */
+export declare function notAPageWarning(): string;
+/**
+ * `bdg page` when the server did not answer in time.
+ *
+ * @param ms - Time waited
+ * @returns Warning
+ */
+export declare function stillLoadingWarning(ms: number): string;
+/**
+ * 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 declare function frameLabel(frame: DomFrame): string;
+/**
+ * `bdg dom frames` on a page without iframes.
+ *
+ * @returns Message
+ */
+export declare function noFramesMessage(): string;
+/**
+ * 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 declare function evalFrameLine(url: string): string;
 /**
  * Generate warning message.
  *