browser-debugger-cli 0.7.1 → 0.8.0

package/dist/{ui/errors → errors}/CommandError.js

@@ -3,7 +3,7 @@
  *
  * Provides CommandError class for throwing errors with metadata and exit codes.
  */
-import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { EXIT_CODES } from '../utils/exitCodes.js';
 /**
  * Custom error class for CLI commands with structured metadata.
  *

package/dist/{ui/errors → errors}/index.d.ts

@@ -4,5 +4,7 @@
  * Provides structured error classes for CLI commands.
  */
 export { CommandError, type ErrorMetadata } from './CommandError.js';
+export type { IssueCode, IssueDetails } from './issues.js';
+export type { ChromeNoticeCode, HintCode, HintDetails, NoticeCode, NoticeDetails, NoticeSink, } from './notices.js';
 export { isDaemonConnectionError } from './utils.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/errors/issues.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Typed issue contract for structured error reporting.
+ *
+ * Core modules attach `IssueDetails` to thrown errors so callers can format
+ * them deterministically. The `message` field on the error stays as a
+ * fallback for consumers that don't branch on the code.
+ *
+ * Add new codes here as vertical slices migrate away from raw string messages.
+ */
+export type IssueCode = 'PORT_IN_USE' | 'INVALID_PORT' | 'USER_DATA_DIR_CREATE_FAILED' | 'CHROME_LAUNCH_FAILED' | 'CHROME_DIED_AFTER_LAUNCH' | 'CHROME_EXITED_DURING_STARTUP' | 'NO_PAGE_TARGET_FOUND' | 'CHROME_BINARY_NOT_FOUND' | 'CHROME_BINARY_NOT_EXECUTABLE' | 'CHROME_BINARY_IS_DIRECTORY' | 'PREFS_FILE_NOT_FOUND' | 'PREFS_INVALID_FORMAT' | 'PREFS_LOAD_FAILED' | 'PREFS_NOT_JSON_SERIALIZABLE';
+export interface IssueDetails {
+    code: IssueCode;
+    context?: Record<string, unknown>;
+    suggestion?: string;
+}
+//# sourceMappingURL=issues.d.ts.map

package/dist/errors/issues.js

@@ -0,0 +1,11 @@
+/**
+ * Typed issue contract for structured error reporting.
+ *
+ * Core modules attach `IssueDetails` to thrown errors so callers can format
+ * them deterministically. The `message` field on the error stays as a
+ * fallback for consumers that don't branch on the code.
+ *
+ * Add new codes here as vertical slices migrate away from raw string messages.
+ */
+export {};
+//# sourceMappingURL=issues.js.map

package/dist/errors/messages.d.ts

@@ -0,0 +1,545 @@
+/**
+ * Common error messages and patterns.
+ *
+ * Centralized location for reusable error messages with consistent formatting.
+ */
+import type { DomFrame } from '../ipc/protocol/commands.js';
+/**
+ * Generate "session already running" error message.
+ *
+ * @param pid - Process ID of running session
+ * @param duration - Session duration in milliseconds
+ * @param targetUrl - Optional target URL to show
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * const message = sessionAlreadyRunningError(12345, 60000, 'http://localhost:3000');
+ * console.error(message);
+ * ```
+ */
+export declare function sessionAlreadyRunningError(pid: number, duration: number, targetUrl?: string): string;
+/** What to do when `bdg <url>` finds a session already running */
+export declare const ALREADY_RUNNING_SUGGESTION = "Use the running session (bdg status), or stop it first: bdg stop && bdg <url>";
+/**
+ * Human-readable description of a bdg-launched Chrome (as opposed to one
+ * reached via `--chrome-ws-url`). Used in mismatch errors where the active
+ * session or the caller's intent is launched-mode.
+ */
+export declare const LAUNCHED_CHROME_DESCRIPTION = "launched Chrome (bdg-managed)";
+/**
+ * Generate "session target mismatch" error message.
+ *
+ * Raised when a new start-session request names a different Chrome target
+ * (or switches between launched and attached modes) while an active session
+ * is healthy. Distinct from `sessionAlreadyRunningError` so agents can react
+ * programmatically via exit code + IPC error code.
+ *
+ * @param currentTarget - Target URL / ws URL / description of the active session
+ * @param requestedTarget - The ws URL / description of what the caller asked for
+ * @returns Formatted error message
+ */
+export declare function sessionTargetMismatchError(currentTarget: string | undefined, requestedTarget: string | undefined): string;
+/**
+ * Context for daemon error messages.
+ */
+export interface DaemonErrorContext {
+    /** Whether stale PID file was cleaned up */
+    staleCleanedUp?: boolean;
+    /** Whether to suggest checking status (for commands that expect daemon) */
+    suggestStatus?: boolean;
+    /** Whether to suggest retrying (for transient errors) */
+    suggestRetry?: boolean;
+    /** Last error message if available */
+    lastError?: string;
+}
+/**
+ * The daemon accepted the connection but did not answer in time (frozen or
+ * overloaded).
+ *
+ * @param seconds - How long the command waited
+ * @returns Message and suggestion
+ */
+export declare function sessionNotRespondingError(seconds: number): ErrorWithSuggestion;
+/**
+ * The daemon answered, but the command did not finish in time (slow or
+ * frozen page work).
+ *
+ * @param seconds - Timeout in seconds
+ */
+export declare function commandTimedOutError(seconds: number): ErrorWithSuggestion;
+/**
+ * What to do when a command finds no session to work with.
+ *
+ * @param exitCode - 85 while a start is in progress, otherwise 83
+ * @returns Suggestion
+ */
+export declare function sessionUnavailableSuggestion(exitCode: number): string;
+/**
+ * Generate unified "daemon not running" error message with context.
+ *
+ * This replaces the three previous variants:
+ * - daemonNotRunningError()
+ * - daemonConnectionFailedError()
+ * - daemonNotRunningWithCleanup()
+ *
+ * @param context - Optional context about the error
+ * @returns Formatted error message with suggestions
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * console.error(daemonNotRunningError());
+ *
+ * // With stale cleanup
+ * console.error(daemonNotRunningError({ staleCleanedUp: true }));
+ *
+ * // With status suggestion
+ * console.error(daemonNotRunningError({ suggestStatus: true }));
+ * ```
+ */
+export declare function daemonNotRunningError(context?: DaemonErrorContext): string;
+/**
+ * Generate generic error message with optional context.
+ *
+ * @param message - Error message
+ * @param context - Optional additional context
+ * @returns Formatted error message
+ *
+ * @example
+ * ```typescript
+ * console.error(genericError('Operation failed', 'Network timeout'));
+ * ```
+ */
+export declare function genericError(message: string, context?: string): string;
+/**
+ * Generate "unknown error" message.
+ *
+ * @returns Formatted error message
+ */
+export declare function unknownError(): string;
+/**
+ * Generate "invalid response" error message.
+ *
+ * @param reason - Reason for invalid response
+ * @returns Formatted error message
+ */
+export declare function invalidResponseError(reason: string): string;
+/**
+ * Generate element not found error with shell quote detection and CDP fallback.
+ *
+ * Provides guidance for when high-level DOM commands fail to find elements.
+ * Detects shell quote damage for attribute selectors and provides specific
+ * recovery suggestions including the two-step query-then-inspect pattern.
+ *
+ * @param selector - CSS selector that failed (as received by the command)
+ * @returns Message and context-aware suggestion
+ *
+ * @example
+ * ```typescript
+ * // Simple selector - standard suggestions
+ * elementNotFoundError('#missing-element')
+ *
+ * // Attribute selector with shell damage detected
+ * elementNotFoundError('[data-test-id=value]')
+ * // Suggestion: "Shell quote handling detected: ..."
+ * ```
+ */
+export declare function elementNotFoundError(selector: string): ErrorWithSuggestion;
+/**
+ * Error with suggestion pair for CommandError usage.
+ */
+export interface ErrorWithSuggestion {
+    message: string;
+    suggestion: string;
+}
+/**
+ * Index out of range error.
+ */
+export declare function indexOutOfRangeError(index: number, max: number): ErrorWithSuggestion;
+/**
+ * CSS selector rejected by the browser. Playwright-only syntax (`:text()`,
+ * `>>`, `text=`) gets the filters bdg supports instead.
+ *
+ * @param selector - Selector as given
+ * @param detail - Browser error, if any
+ * @returns Message and suggestion
+ */
+export declare function invalidSelectorError(selector: string, detail?: string): ErrorWithSuggestion;
+/**
+ * A text or visibility filter (`:has-text()`, `:text-is()`, `:visible`) that
+ * is not at the end of a selector.
+ *
+ * @param selector - Selector as given
+ * @param filter - The misplaced filter as written
+ * @returns Message and suggestion
+ */
+export declare function misplacedSelectorFilterError(selector: string, filter: string): ErrorWithSuggestion;
+/**
+ * A text filter without its text, e.g. `:has-text` or `:text-is("x"`.
+ *
+ * @param selector - Selector as given
+ * @param filter - Filter name, e.g. ":has-text"
+ * @returns Message and suggestion
+ */
+export declare function invalidSelectorFilterError(selector: string, filter: string): ErrorWithSuggestion;
+/**
+ * `bdg help <topic>` for a command that does not exist.
+ *
+ * @param topic - Command path as typed, e.g. "dom quer"
+ * @param closest - Most similar existing command path, if any
+ */
+export declare function unknownHelpTopicError(topic: string, closest?: string): ErrorWithSuggestion;
+/**
+ * Chrome rejected a CDP method or its parameters.
+ *
+ * @param detail - Chrome's error message
+ */
+export declare function cdpRequestRejectedError(detail: string): ErrorWithSuggestion;
+/**
+ * A file the user asked for (screenshot, HAR) cannot be written.
+ *
+ * @param filePath - Path as given
+ * @param reason - What is wrong with it
+ * @param extension - Extension of the file kind, for the example (default .png)
+ */
+export declare function outputFileError(filePath: string, reason: string, extension?: string): ErrorWithSuggestion;
+/**
+ * An empty output path.
+ *
+ * @param extension - Extension of the file kind, for the example
+ */
+export declare function emptyOutputPathError(extension?: string): ErrorWithSuggestion;
+/**
+ * Start options given without the URL to open.
+ */
+export declare function missingStartUrlError(): ErrorWithSuggestion;
+/**
+ * `-u` / `--user-data-dir` given something that is not a directory path.
+ *
+ * @param value - What was given
+ * @param reason - Why it cannot be used
+ */
+export declare function invalidUserDataDirError(value: string, reason: string): ErrorWithSuggestion;
+/**
+ * The session directory exists but is not a directory.
+ *
+ * @param dir - Session directory
+ */
+export declare function sessionDirIsFileError(dir: string): ErrorWithSuggestion;
+/**
+ * The session directory cannot be created or written.
+ *
+ * @param dir - Session directory
+ * @param reason - File-system error
+ */
+export declare function sessionDirNotWritableError(dir: string, reason: string): ErrorWithSuggestion;
+/**
+ * The daemon socket path exceeds the OS limit for Unix sockets.
+ *
+ * @param socketPath - Socket path
+ * @param max - Longest path the OS accepts
+ */
+export declare function socketPathTooLongError(socketPath: string, max: number): ErrorWithSuggestion;
+/**
+ * The Chrome of `--chrome-ws-url` does not answer on its HTTP endpoint.
+ *
+ * @param endpoint - e.g. http://127.0.0.1:9222
+ * @param secure - Whether a wss: URL was given
+ */
+export declare function externalChromeUnreachableError(endpoint: string, secure: boolean): ErrorWithSuggestion;
+/**
+ * The page id of a `--chrome-ws-url` page URL does not exist.
+ *
+ * @param id - Page id from the URL
+ * @param endpoint - e.g. http://127.0.0.1:9222
+ */
+export declare function externalPageNotFoundError(id: string, endpoint: string): ErrorWithSuggestion;
+/**
+ * The browser id of a `--chrome-ws-url` browser URL is not this Chrome's.
+ *
+ * @param endpoint - e.g. http://127.0.0.1:9222
+ * @param actual - The Chrome's browser WebSocket URL
+ */
+export declare function externalBrowserIdMismatchError(endpoint: string, actual: string): ErrorWithSuggestion;
+/**
+ * Options that only apply when bdg launches Chrome, given with `--chrome-ws-url`.
+ *
+ * @param options - The conflicting options, e.g. ["--port", "-u"]
+ */
+export declare function chromeWsUrlConflictError(options: string[]): ErrorWithSuggestion;
+/**
+ * A numeric index given together with `--index`.
+ *
+ * @param index - The index argument
+ */
+export declare function indexWithIndexOptionError(index: string): ErrorWithSuggestion;
+/** Problems with `bdg dom scroll` options, and how to fix each */
+declare const SCROLL_PROBLEMS: {
+    readonly 'index-without-selector': readonly ["--index requires a selector", "Use: bdg dom scroll \"selector\" --index 2"];
+    readonly vertical: readonly ["Conflicting scroll directions: --up/--down/--top/--bottom", "Use one vertical direction"];
+    readonly horizontal: readonly ["Conflicting scroll directions: --left and --right", "Use either --left or --right"];
+    readonly 'selector-with-offset': readonly ["A selector cannot be combined with --up/--down/--left/--right/--top/--bottom", "Scroll to the element (bdg dom scroll \"footer\"), or by an offset (bdg dom scroll --down 500)"];
+    readonly 'no-target': readonly ["No scroll target specified", "Provide a selector (bdg dom scroll \"footer\") or offset (--down 500, --bottom)"];
+};
+/**
+ * Invalid `bdg dom scroll` options.
+ *
+ * @param problem - Which rule was broken
+ */
+export declare function scrollOptionsError(problem: keyof typeof SCROLL_PROBLEMS): ErrorWithSuggestion;
+/**
+ * A key name `dom pressKey` does not know.
+ *
+ * @param keyName - Key as given
+ * @param similar - Similar key names
+ */
+export declare function unknownKeyError(keyName: string, similar: string[]): ErrorWithSuggestion;
+/** Where selectors cannot look, for "not found" errors */
+export declare const UNREACHABLE_ELEMENTS_HINT = "elements in closed shadow roots and cross-origin iframes cannot be reached";
+/**
+ * Two options given together where one would be ignored.
+ *
+ * @param first - First option
+ * @param second - Option it conflicts with
+ * @returns Message
+ */
+export declare function conflictingOptionsMessage(first: string, second: string): string;
+/**
+ * A Chrome flag bdg cannot pass on.
+ *
+ * @param flag - The flag
+ */
+export declare function invalidChromeFlagError(flag: string): ErrorWithSuggestion;
+/**
+ * The session (its browser or daemon) went away while a command was running.
+ */
+export declare function sessionEndedDuringCommandError(): ErrorWithSuggestion;
+/**
+ * An option that only takes effect together with another one.
+ *
+ * @param option - Option given
+ * @param required - Option it needs
+ * @returns Message
+ */
+export declare function optionRequiresMessage(option: string, required: string): string;
+/**
+ * `bdg page navigate javascript:…`: scripts run with dom eval.
+ */
+export declare function javascriptNavigationError(): ErrorWithSuggestion;
+/**
+ * A bare word given where a URL is expected, most likely a mistyped command.
+ *
+ * @param word - The argument
+ * @param similar - Similar command names
+ */
+export declare function unknownCommandError(word: string, similar: string[]): ErrorWithSuggestion;
+/**
+ * The browser could not load the start URL at all.
+ *
+ * @param url - URL that failed
+ * @param errorText - Chrome network error (e.g. net::ERR_NAME_NOT_RESOLVED)
+ */
+export declare function navigationFailedError(url: string, errorText: string): ErrorWithSuggestion;
+/**
+ * `bdg page back/forward` at the end of the page's history.
+ *
+ * @param direction - back or forward
+ */
+export declare function noHistoryEntryError(direction: 'back' | 'forward'): ErrorWithSuggestion;
+/**
+ * The form was submitted but the wait for its result timed out.
+ *
+ * @param timeout - Timeout in ms
+ * @param waitNavigation - Whether a navigation was awaited
+ */
+export declare function submitTimeoutError(timeout: number, waitNavigation: boolean): ErrorWithSuggestion;
+/**
+ * No element has the given node id.
+ *
+ * @param nodeId - Backend node id given with --node-id
+ */
+export declare function nodeIdNotFoundError(nodeId: number): ErrorWithSuggestion;
+/**
+ * A cached node is gone (page navigated or the element was removed).
+ *
+ * @param index - Index the user gave (query or form results), if any
+ */
+export declare function staleNodeError(index?: number): ErrorWithSuggestion;
+/**
+ * Element at index not found (stale cache).
+ */
+export declare function elementAtIndexNotFoundError(index: number, selector: string): ErrorWithSuggestion;
+/** Where selectors do not reach (open shadow roots and same-origin iframes are searched) */
+export declare const CROSS_ORIGIN_FRAMES_NOTE = "Elements inside cross-origin iframes and closed shadow roots are not searched";
+/**
+ * No nodes found for selector.
+ */
+export declare function noNodesFoundError(selector: string): ErrorWithSuggestion;
+/**
+ * Element not visible/rendered.
+ */
+export declare function elementNotVisibleError(): ErrorWithSuggestion;
+/**
+ * Element has zero dimensions.
+ */
+export declare function elementZeroDimensionsError(): ErrorWithSuggestion;
+/**
+ * Missing required argument.
+ */
+export declare function missingArgumentError(usage: string): ErrorWithSuggestion;
+/**
+ * Either/or argument required.
+ */
+export declare function eitherArgumentRequiredError(arg1: string, arg2: string, example: string): ErrorWithSuggestion;
+/**
+ * Invalid query pattern.
+ */
+export declare function invalidQueryPatternError(pattern: string): ErrorWithSuggestion;
+/**
+ * A file to upload does not exist.
+ *
+ * @param file - Path that was not found
+ */
+export declare function fileNotFoundError(file: string): ErrorWithSuggestion;
+/**
+ * A directory given for a file input.
+ *
+ * @param file - Resolved path
+ */
+export declare function uploadDirectoryError(file: string): ErrorWithSuggestion;
+/**
+ * Several files given for a file input that accepts one.
+ *
+ * @param count - Number of files given
+ */
+export declare function singleFileInputError(count: number): ErrorWithSuggestion;
+/**
+ * Unknown field in an a11y query pattern.
+ *
+ * @param field - The unrecognized key
+ */
+export declare function unknownQueryFieldError(field: string): ErrorWithSuggestion;
+/**
+ * No a11y nodes matching pattern.
+ */
+export declare function noA11yNodesFoundError(pattern: string): ErrorWithSuggestion;
+/**
+ * An element that exists but has no node in the accessibility tree.
+ *
+ * @param target - Selector or index the user gave
+ * @param reasons - Why Chrome leaves it out
+ */
+export declare function notInAccessibilityTreeError(target: string, reasons: string[]): ErrorWithSuggestion;
+/**
+ * Fillable element not found.
+ */
+export declare function fillableElementNotFoundError(selector: string): ErrorWithSuggestion;
+/**
+ * Clickable element not found.
+ */
+export declare function clickableElementNotFoundError(selector: string): ErrorWithSuggestion;
+/**
+ * Click target disappeared between locating and clicking it.
+ */
+export declare function clickTargetDetachedError(selector: string): ErrorWithSuggestion;
+/**
+ * Key press failed.
+ */
+export declare function keyPressFailedError(details: string): ErrorWithSuggestion;
+/**
+ * A `bdg dom eval` script ran too long and was terminated.
+ *
+ * @param timeoutMs - Time limit in ms
+ * @returns Error with suggestion
+ */
+export declare function scriptTimeoutError(timeoutMs: number): ErrorWithSuggestion;
+/**
+ * The page was kept busy by a script (e.g. a loop started from a timer) and
+ * bdg terminated it.
+ *
+ * @param timeoutMs - Time waited
+ */
+export declare function pageBusyError(timeoutMs: number): ErrorWithSuggestion;
+/**
+ * The page did not answer because a navigation is still waiting for the
+ * server (Chrome holds commands for the page until the new document arrives).
+ *
+ * @param url - URL being loaded
+ */
+export declare function navigationPendingError(url: string): ErrorWithSuggestion;
+/**
+ * `dom eval` given an empty script (often a shell variable that was not set).
+ */
+export declare function emptyScriptError(): ErrorWithSuggestion;
+/**
+ * A promise returned by `dom eval` that did not settle in time.
+ *
+ * @param timeoutMs - Time waited
+ */
+export declare function promiseTimeoutError(timeoutMs: number): ErrorWithSuggestion;
+/**
+ * `dom eval --frame` given an empty frame.
+ */
+export declare function emptyFrameError(): ErrorWithSuggestion;
+/**
+ * `dom eval --frame` matching no iframe.
+ *
+ * @param query - Requested frame
+ * @param frames - Frames of the page
+ */
+export declare function frameNotFoundError(query: string, frames: DomFrame[]): ErrorWithSuggestion;
+/**
+ * `dom eval --frame` matching more than one iframe.
+ *
+ * @param query - Requested frame
+ * @param candidates - Matching frames
+ */
+export declare function ambiguousFrameError(query: string, candidates: DomFrame[]): ErrorWithSuggestion;
+/**
+ * An iframe without a JavaScript context (still loading, or sandboxed without scripts).
+ *
+ * @param url - Frame URL
+ */
+export declare function frameNotReadyError(url: string): ErrorWithSuggestion;
+/**
+ * Script execution error with shell quote detection.
+ *
+ * Shows the script as received to help diagnose shell quote stripping issues.
+ * Detects common patterns like `querySelector(input)` that indicate shell damage.
+ *
+ * @param errorMessage - The JavaScript error message
+ * @param receivedScript - The script as received by the command (optional for backwards compat)
+ * @returns Error with context-aware suggestions
+ */
+export declare function scriptExecutionError(errorMessage: string, receivedScript?: string): ErrorWithSuggestion;
+/**
+ * Unexpected CDP response format.
+ */
+export declare function unexpectedResponseFormatError(context: string): ErrorWithSuggestion;
+/**
+ * Generic operation failure with dynamic error message.
+ */
+export declare function operationFailedError(operation: string, errorMessage: string): ErrorWithSuggestion;
+/**
+ * The browser does not offer `DOMDebugger.getEventListeners` (non-Chrome
+ * targets, or browsers that disable the DOMDebugger domain).
+ *
+ * @param detail - Chrome's error
+ * @returns Message and suggestion
+ */
+export declare function eventListenersUnavailableError(detail: string): ErrorWithSuggestion;
+/**
+ * Internal error (should not happen in normal usage).
+ */
+export declare function internalError(context: string): ErrorWithSuggestion;
+/**
+ * No forms found on page.
+ */
+export declare function noFormsFoundError(): ErrorWithSuggestion;
+/**
+ * Form in iframe (cross-origin or same-origin).
+ */
+export declare function formInIframeError(iframeUrl: string, crossOrigin: boolean): ErrorWithSuggestion;
+export {};
+//# sourceMappingURL=messages.d.ts.map