browser-debugger-cli 0.11.0 → 0.13.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,9 +482,9 @@ 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.
  */
@@ -556,9 +578,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.
@@ -691,7 +714,16 @@ export declare function elementNotVisibleError(): ErrorWithSuggestion;
  */
 export declare function elementZeroDimensionsError(): ErrorWithSuggestion;
 /**
- * Missing required argument.
+ * `bdg dom hover --off` was given an element too.
+ *
+ * @returns Message and suggestion
+ */
+export declare function hoverOffWithTargetError(): ErrorWithSuggestion;
+/**
+ * A command was given neither its argument nor a flag that replaces it.
+ *
+ * @param usage - How to call it
+ * @returns Message and suggestion
  */
 export declare function missingArgumentError(usage: string): ErrorWithSuggestion;
 /**
@@ -776,14 +808,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).
@@ -927,10 +977,16 @@ export declare function unexpectedResponseFormatError(context: string): ErrorWit
  */
 export declare function operationFailedError(operation: string, errorMessage: string): ErrorWithSuggestion;
 /**
- * `dom inspect --props` named a property the element has no value for.
+ * `--why all`: `all` resets every property, so there is no one cascade to show.
+ *
+ * @returns Message and suggestion
+ */
+export declare function whyAllPropertyError(): ErrorWithSuggestion;
+/**
+ * Names given to --props or --why that are not CSS properties.
  *
- * @param names - Unknown property names
- * @param suggestions - Similar computed property names
+ * @param names - Unknown names
+ * @param suggestions - Closest known names
  * @returns Message and suggestion
  */
 export declare function unknownCssPropertyError(names: string[], suggestions: string[]): ErrorWithSuggestion;
@@ -984,10 +1040,27 @@ 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, pathIsFile: boolean, otherTargetFlag?: string): ErrorWithSuggestion;
+/**
+ * `bdg peek --interval` without `--follow`.
+ *
  * @returns Message and suggestion
  */
-export declare function skillWriteFailedError(path: string, reason: string): ErrorWithSuggestion;
+export declare function intervalWithoutFollowError(): ErrorWithSuggestion;
+/**
+ * An unknown `dom audit` check.
+ *
+ * @param value - Name given
+ * @param similar - Closest names
+ * @param checks - Every check
+ * @returns Message
+ */
+export declare function unknownAuditCheckMessage(value: string, similar: string[], checks: readonly string[]): string;
 export {};
 //# sourceMappingURL=messages.d.ts.map

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.
@@ -935,15 +977,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)}"`,
     };
 }
 /**
@@ -1025,9 +1076,25 @@ export function noNodesFoundError(selector, context = {}) {
     const note = unreachableElementsNote(selector, context.unsearched);
     return {
         message: `No nodes found matching "${selector}"`,
-        suggestion: withLoadingHint(joinLines(context.similar, context.shadowHost && shadowBoundaryLine(context.shadowHost), `${hidden}Verify the CSS selector is correct.`, note ? note : undefined), context.readyState, selector),
+        suggestion: withLoadingHint(joinLines(context.similar, context.shadowHost && shadowBoundaryLine(context.shadowHost), shadowPseudoLine(selector), `${hidden}Verify the CSS selector is correct.`, note ? note : undefined), context.readyState, selector),
     };
 }
+/**
+ * Advice for a selector with `::part()` or `::slotted()`, which name
+ * pseudo-elements a page's stylesheet uses and never match an element.
+ *
+ * @param selector - Selector as given
+ * @returns Line, or undefined for other selectors
+ */
+function shadowPseudoLine(selector) {
+    const part = /::part\(\s*([^)\s]+)\s*\)/.exec(selector)?.[1];
+    if (part) {
+        return `::part() styles a shadow part and selects nothing; bdg searches open shadow roots, so select the part itself: [part~="${part}"]`;
+    }
+    return /::slotted\(/.test(selector)
+        ? '::slotted() selects nothing; select the slotted element itself (it is in the light DOM)'
+        : undefined;
+}
 /**
  * Quote a value for a POSIX shell command line.
  *
@@ -1176,7 +1243,21 @@ export function elementZeroDimensionsError() {
     };
 }
 /**
- * Missing required argument.
+ * `bdg dom hover --off` was given an element too.
+ *
+ * @returns Message and suggestion
+ */
+export function hoverOffWithTargetError() {
+    return {
+        message: '--off moves the mouse off the page; it takes no element',
+        suggestion: 'Use bdg dom hover --off alone, or bdg dom hover <selector> to hover an element',
+    };
+}
+/**
+ * A command was given neither its argument nor a flag that replaces it.
+ *
+ * @param usage - How to call it
+ * @returns Message and suggestion
  */
 export function missingArgumentError(usage) {
     return {
@@ -1319,21 +1400,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 '…'")}`,
     };
 }
 /**
@@ -1644,10 +1754,21 @@ export function operationFailedError(operation, errorMessage) {
     };
 }
 /**
- * `dom inspect --props` named a property the element has no value for.
+ * `--why all`: `all` resets every property, so there is no one cascade to show.
+ *
+ * @returns Message and suggestion
+ */
+export function whyAllPropertyError() {
+    return {
+        message: '--why takes one property; "all" resets every property',
+        suggestion: 'Name the property you are after (e.g. --why color), or use --all to list the set ones',
+    };
+}
+/**
+ * Names given to --props or --why that are not CSS properties.
  *
- * @param names - Unknown property names
- * @param suggestions - Similar computed property names
+ * @param names - Unknown names
+ * @param suggestions - Closest known names
  * @returns Message and suggestion
  */
 export function unknownCssPropertyError(names, suggestions) {
@@ -1767,14 +1888,43 @@ 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,
+    };
+}
+/**
+ * `bdg peek --interval` without `--follow`.
+ *
+ * @returns Message and suggestion
+ */
+export function intervalWithoutFollowError() {
+    return {
+        message: '--interval sets how often --follow refreshes',
+        suggestion: 'Add --follow, e.g. bdg peek --follow --interval 500',
     };
 }
+/**
+ * An unknown `dom audit` check.
+ *
+ * @param value - Name given
+ * @param similar - Closest names
+ * @param checks - Every check
+ * @returns Message
+ */
+export function unknownAuditCheckMessage(value, similar, checks) {
+    return `Unknown check "${value}"${similar.length > 0 ? `; did you mean ${similar[0]}?` : ''} (checks: ${checks.join(', ')})`;
+}
 //# sourceMappingURL=messages.js.map