browser-debugger-cli 0.12.0 → 0.14.0

package/dist/errors/messages.d.ts

@@ -258,6 +258,21 @@ export declare function invalidSelectorFilterError(selector: string, filter: str
  * @param closest - Most similar existing command path, if any
  */
 export declare function unknownHelpTopicError(topic: string, closest?: string): ErrorWithSuggestion;
+/**
+ * Suggestion for a command-line usage error (missing argument, invalid value,
+ * unknown option without a close match).
+ *
+ * @param path - Command path, e.g. "bdg dom query"
+ */
+export declare function usageHelpSuggestion(path: string): string;
+/**
+ * A command group was run without one of its subcommands.
+ */
+export declare function missingSubcommandMessage(): string;
+/**
+ * `bdg cdp --search` with an empty or blank query (which would match every method).
+ */
+export declare function emptyCdpSearchError(): ErrorWithSuggestion;
 /**
  * Chrome rejected a CDP method or its parameters.
  *
@@ -442,15 +457,22 @@ export declare function conflictingTargetError(option: string, positional: strin
  *
  * @param first - First option
  * @param second - Option it conflicts with
- * @returns Message
+ * @returns Message and suggestion
  */
-export declare function conflictingOptionsMessage(first: string, second: string): string;
+export declare function conflictingOptionsError(first: string, second: string): ErrorWithSuggestion;
 /**
  * A Chrome flag bdg cannot pass on.
  *
  * @param flag - The flag
  */
 export declare function invalidChromeFlagError(flag: string): ErrorWithSuggestion;
+/**
+ * A page command on a page whose renderer crashed.
+ *
+ * @param crashedAt - When it crashed (epoch ms)
+ * @returns Message and the way back
+ */
+export declare function pageCrashedError(crashedAt: number): ErrorWithSuggestion;
 /**
  * The session (its browser or daemon) went away while a command was running.
  */
@@ -460,13 +482,21 @@ export declare function sessionEndedDuringCommandError(): ErrorWithSuggestion;
  *
  * @param option - Option given
  * @param required - Option it needs
- * @returns Message
+ * @returns Message and suggestion
  */
-export declare function optionRequiresMessage(option: string, required: string): string;
+export declare function optionRequiresError(option: string, required: string): ErrorWithSuggestion;
 /**
  * `bdg page navigate javascript:…`: scripts run with dom eval.
  */
 export declare function javascriptNavigationError(): ErrorWithSuggestion;
+/**
+ * A daemon request named a command the session does not have (the IPC
+ * server validates names, so this guards direct callers).
+ *
+ * @param name - Requested command name
+ * @returns Error message
+ */
+export declare function unknownSessionCommandMessage(name: string): string;
 /**
  * A bare word given where a URL is expected, most likely a mistyped command.
  *
@@ -556,9 +586,10 @@ export declare function staleNodeError(index?: number, source?: IndexSource): Er
  *
  * @param source - The index and the list it refers to
  * @param count - Number of cached results
+ * @param total - Matches the query found, when more than it cached (`dom query` caches the first 1000)
  * @returns Message and suggestion
  */
-export declare function cachedIndexOutOfRangeError(source: IndexSource, count: number): ErrorWithSuggestion;
+export declare function cachedIndexOutOfRangeError(source: IndexSource, count: number, total?: number): ErrorWithSuggestion;
 /**
  * Note for a form command (fill, submit) whose index refers to results of
  * another command and hit an element it cannot act on.
@@ -785,14 +816,32 @@ export declare const FILL_REFUSALS: {
         readonly suggestion: "Only input, textarea, select, and contenteditable elements can be filled";
     };
 };
-/**
- * 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;
+/**
+ * An action's page script threw (on a page whose built-ins all look like the
+ * browser's).
+ *
+ * @param action - The action, e.g. `fill`
+ * @param exception - What the script threw, e.g. `TypeError: x is not a function`
+ * @param selector - Selector the action was for
+ * @returns Error naming the exception
+ */
+export declare function actionScriptFailedError(action: string, exception: string, selector: string): ErrorWithSuggestion;
+/**
+ * An action's page script threw on a page that replaced built-ins it uses
+ * (anti-bot scripts make `getBoundingClientRect`, `focus` or
+ * `dispatchEvent` throw; old libraries such as MooTools 1.2 replace
+ * `Event`). All replaced built-ins are named.
+ *
+ * @param action - The action, e.g. `fill`
+ * @param exception - What the script threw, e.g. `Error: anti-bot: focus`
+ * @param replaced - Dotted names of the replaced built-ins
+ * @returns Error naming the replaced built-ins and the exception
+ */
+export declare function actionBrokenByPageError(action: string, exception: string, replaced: readonly string[]): ErrorWithSuggestion;
 /**
  * A pointer action refused under `--strict` because a real mouse could not
  * reach the element (covered, hidden, zero-size, pointer-events: none).
@@ -999,11 +1048,13 @@ export declare function skillSourceMissingError(source: string): ErrorWithSugges
 /**
  * The skill could not be written to an agent's skill directory.
  *
- * @param path - Destination SKILL.md
+ * @param path - File that could not be written
  * @param reason - The file system error
+ * @param pathIsFile - Whether a part of the path is a file (ENOTDIR, EEXIST)
+ * @param otherTargetFlag - Flag installing for the other agent only, when both were picked
  * @returns Message and suggestion
  */
-export declare function skillWriteFailedError(path: string, reason: string): ErrorWithSuggestion;
+export declare function skillWriteFailedError(path: string, reason: string, pathIsFile: boolean, otherTargetFlag?: string): ErrorWithSuggestion;
 /**
  * `bdg peek --interval` without `--follow`.
  *

package/dist/errors/messages.js

@@ -370,6 +370,30 @@ export function unknownHelpTopicError(topic, closest) {
             : `Run "bdg ${parent ? `${parent} ` : ''}--help" for commands`,
     };
 }
+/**
+ * Suggestion for a command-line usage error (missing argument, invalid value,
+ * unknown option without a close match).
+ *
+ * @param path - Command path, e.g. "bdg dom query"
+ */
+export function usageHelpSuggestion(path) {
+    return `Run "${path} --help" for usage`;
+}
+/**
+ * A command group was run without one of its subcommands.
+ */
+export function missingSubcommandMessage() {
+    return 'Missing subcommand';
+}
+/**
+ * `bdg cdp --search` with an empty or blank query (which would match every method).
+ */
+export function emptyCdpSearchError() {
+    return {
+        message: 'Empty search query',
+        suggestion: 'Search for a keyword, e.g. bdg cdp --search cookie; list domains: bdg cdp --list',
+    };
+}
 /**
  * Chrome rejected a CDP method or its parameters.
  *
@@ -687,10 +711,13 @@ export function conflictingTargetError(option, positional) {
  *
  * @param first - First option
  * @param second - Option it conflicts with
- * @returns Message
+ * @returns Message and suggestion
  */
-export function conflictingOptionsMessage(first, second) {
-    return `${first} cannot be combined with ${second}; use one of them`;
+export function conflictingOptionsError(first, second) {
+    return {
+        message: `${first} cannot be combined with ${second}`,
+        suggestion: `Use one of them: drop ${first} or ${second}`,
+    };
 }
 /**
  * A Chrome flag bdg cannot pass on.
@@ -708,6 +735,18 @@ export function invalidChromeFlagError(flag) {
             suggestion: 'Give Chrome flags as one quoted value: --chrome-flags="--lang=pl --disable-gpu"',
         };
 }
+/**
+ * A page command on a page whose renderer crashed.
+ *
+ * @param crashedAt - When it crashed (epoch ms)
+ * @returns Message and the way back
+ */
+export function pageCrashedError(crashedAt) {
+    return {
+        message: `The page crashed at ${new Date(crashedAt).toLocaleTimeString()} (its renderer is gone), so page commands cannot run`,
+        suggestion: `Load it again with: ${sessionCommand('bdg page reload')} (or start a new session: ${sessionCommand('bdg <url>')})`,
+    };
+}
 /**
  * The session (its browser or daemon) went away while a command was running.
  */
@@ -722,10 +761,13 @@ export function sessionEndedDuringCommandError() {
  *
  * @param option - Option given
  * @param required - Option it needs
- * @returns Message
+ * @returns Message and suggestion
  */
-export function optionRequiresMessage(option, required) {
-    return `${option} only works with ${required}; add ${required} or drop ${option}`;
+export function optionRequiresError(option, required) {
+    return {
+        message: `${option} only works with ${required}`,
+        suggestion: `Add ${required}, or drop ${option}`,
+    };
 }
 /**
  * `bdg page navigate javascript:…`: scripts run with dom eval.
@@ -736,6 +778,16 @@ export function javascriptNavigationError() {
         suggestion: `Run the script in the page instead: bdg dom eval '...'`,
     };
 }
+/**
+ * A daemon request named a command the session does not have (the IPC
+ * server validates names, so this guards direct callers).
+ *
+ * @param name - Requested command name
+ * @returns Error message
+ */
+export function unknownSessionCommandMessage(name) {
+    return `Unknown session command: "${name}"`;
+}
 /**
  * A bare word given where a URL is expected, most likely a mistyped command.
  *
@@ -935,15 +987,24 @@ export function staleNodeError(index, source) {
  *
  * @param source - The index and the list it refers to
  * @param count - Number of cached results
+ * @param total - Matches the query found, when more than it cached (`dom query` caches the first 1000)
  * @returns Message and suggestion
  */
-export function cachedIndexOutOfRangeError(source, count) {
-    const results = count === 1 ? '1 result' : `${count} results`;
+export function cachedIndexOutOfRangeError(source, count, total) {
+    if (total !== undefined && total > count && source.index < total) {
+        return {
+            message: `Index ${source.index} is past the ${count} matches of ${cachedListText(source)} that can be used by index (${total} in all)`,
+            suggestion: `Re-run it with --limit ${source.index + 1} (or --limit 0) to index that many`,
+        };
+    }
+    const all = total !== undefined && total > count ? total : count;
+    const results = all === 1 ? '1 result' : `${all} results`;
+    const range = all > count
+        ? `between 0 and ${count - 1}, or up to ${all - 1} after re-running it with --limit 0`
+        : `between 0 and ${count - 1}, or re-run "${refreshCommand(source)}"`;
     return {
         message: `Index ${source.index} is out of range for ${cachedListText(source)} (${results})`,
-        suggestion: count > 0
-            ? `Use an index between 0 and ${count - 1}, or re-run "${refreshCommand(source)}"`
-            : `Re-run "${refreshCommand(source)}"`,
+        suggestion: count > 0 ? `Use an index ${range}` : `Re-run "${refreshCommand(source)}"`,
     };
 }
 /**
@@ -1349,21 +1410,50 @@ export const FILL_REFUSALS = {
     },
 };
 /**
- * Clickable element not found.
+ * Click target disappeared between locating and clicking it.
  */
-export function clickableElementNotFoundError(selector) {
+export function clickTargetDetachedError(selector) {
     return {
-        message: `Element not found: ${selector}`,
-        suggestion: 'Verify the selector matches a clickable element',
+        message: `Element was removed before it could be clicked: ${selector}`,
+        suggestion: 'The page changed during the click; wait for it to settle and retry',
     };
 }
 /**
- * Click target disappeared between locating and clicking it.
+ * An action's page script threw (on a page whose built-ins all look like the
+ * browser's).
+ *
+ * @param action - The action, e.g. `fill`
+ * @param exception - What the script threw, e.g. `TypeError: x is not a function`
+ * @param selector - Selector the action was for
+ * @returns Error naming the exception
  */
-export function clickTargetDetachedError(selector) {
+export function actionScriptFailedError(action, exception, selector) {
+    const damage = detectSelectorQuoteDamage(selector);
     return {
-        message: `Element was removed before it could be clicked: ${selector}`,
-        suggestion: 'The page changed during the click; wait for it to settle and retry',
+        message: `The ${action} script failed in the page: ${exception}`,
+        suggestion: damage.damaged
+            ? `The selector looks damaged by shell quoting${damage.details ? ` (${damage.details})` : ''}; query it first with ${sessionCommand(`bdg dom query ${JSON.stringify(selector)}`)}, then act on the index`
+            : `Check the element with ${sessionCommand(`bdg dom get ${JSON.stringify(selector)}`)}, or act on it with ${sessionCommand("bdg dom eval '…'")}`,
+    };
+}
+/**
+ * An action's page script threw on a page that replaced built-ins it uses
+ * (anti-bot scripts make `getBoundingClientRect`, `focus` or
+ * `dispatchEvent` throw; old libraries such as MooTools 1.2 replace
+ * `Event`). All replaced built-ins are named.
+ *
+ * @param action - The action, e.g. `fill`
+ * @param exception - What the script threw, e.g. `Error: anti-bot: focus`
+ * @param replaced - Dotted names of the replaced built-ins
+ * @returns Error naming the replaced built-ins and the exception
+ */
+export function actionBrokenByPageError(action, exception, replaced) {
+    const fill = action === 'fill'
+        ? ' The field may already hold the value without the page having seen input or change events.'
+        : '';
+    return {
+        message: `The page replaced built-ins bdg's ${action} script uses (${replaced.join(', ')}), and the script failed: ${exception}`,
+        suggestion: `The page blocks or changes these APIs (an anti-bot script or an old library).${fill} If the page still lets scripts act, use ${sessionCommand("bdg dom eval '…'")}`,
     };
 }
 /**
@@ -1808,14 +1898,21 @@ export function skillSourceMissingError(source) {
 /**
  * The skill could not be written to an agent's skill directory.
  *
- * @param path - Destination SKILL.md
+ * @param path - File that could not be written
  * @param reason - The file system error
+ * @param pathIsFile - Whether a part of the path is a file (ENOTDIR, EEXIST)
+ * @param otherTargetFlag - Flag installing for the other agent only, when both were picked
  * @returns Message and suggestion
  */
-export function skillWriteFailedError(path, reason) {
+export function skillWriteFailedError(path, reason, pathIsFile, otherTargetFlag) {
+    const fix = pathIsFile
+        ? 'A part of that path is a file, not a directory: move it away'
+        : 'Check the permissions of that directory';
     return {
         message: `Could not write ${path}: ${reason}`,
-        suggestion: 'Check the permissions of that directory, or install for the other agent only (--claude or --agents)',
+        suggestion: otherTargetFlag
+            ? `${fix}, or install for the other agent only (${otherTargetFlag})`
+            : fix,
     };
 }
 /**