browser-debugger-cli 0.7.2 → 0.9.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.
  *
@@ -157,73 +162,12 @@ export declare function chromeBinaryOverrideIsDirectory(path: string, source: st
  */
 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.
+ * Warning when bdg's Chrome preferences (password manager and leak check
+ * off, etc.) could not be written into the profile.
  *
- * @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'));
- * ```
+ * @param file - Preferences file
+ * @param reason - Why
+ * @returns Message
  */
-export declare function cleanupChromeProcessFailedMessage(error: string): string;
+export declare function chromePrefsNotAppliedMessage(file: string, reason: string): string;
 //# sourceMappingURL=chrome.d.ts.map

package/dist/ui/messages/chrome.js

@@ -3,7 +3,106 @@
  *
  * 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';
+import { sessionCommand } from './sessionCommand.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:', `  - ${sessionCommand('bdg cleanup')}`, `  - See what uses the port: lsof -i :${port}`, `  - Use different port: ${sessionCommand(`bdg <url> --port ${port + 1}`)}`, `  - In a container where Chrome's sandbox fails: BDG_NO_SANDBOX=1 ${sessionCommand('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: ${sessionCommand('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 +138,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 +198,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: ${sessionCommand('bdg <url>')}. If it keeps failing, another program may use the port (lsof -i :` +
+        `${port}) or a crashed session may be left over: ${sessionCommand('bdg cleanup')} && ${sessionCommand('bdg <url>')}`, ...(availableTargets ? ['', `Chrome targets:\n${availableTargets}`] : []));
 }
 /**
  * Generate preferences file not found error.
@@ -228,88 +277,17 @@ 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})...`;
+    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: ${sessionCommand(`bdg <url> --port ${port + 1}`)}`, `  - If a bdg session holds it: find it with bdg sessions, then end that one: bdg stop --session <name> (bdg cleanup --force --session <name> if it is stuck)`, `  - See what uses the port: lsof -i :${port}`);
 }
 /**
- * Generate success message after Chrome process is killed.
+ * Warning when bdg's Chrome preferences (password manager and leak check
+ * off, etc.) could not be written into the profile.
  *
- * @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'));
- * ```
+ * @param file - Preferences file
+ * @param reason - Why
+ * @returns Message
  */
-export function cleanupChromeProcessFailedMessage(error) {
-    return `Error: Failed to cleanup Chrome processes: ${error}\n`;
+export function chromePrefsNotAppliedMessage(file, reason) {
+    return `Warning: Chrome preferences not applied to ${file} (${reason}); password manager bubbles may capture clicks`;
 }
 //# sourceMappingURL=chrome.js.map