browser-debugger-cli 0.15.0 → 0.16.0

package/dist/errors/CommandError.d.ts

@@ -18,6 +18,8 @@ export interface ErrorMetadata {
     fallback?: string;
     /** CDP alternative for advanced use cases */
     cdpAlternative?: string;
+    /** How the command ran despite failing (e.g. a CDP method sent though bdg's protocol lacks it) */
+    warning?: string;
 }
 /**
  * Custom error class for CLI commands with structured metadata.

package/dist/errors/issues.d.ts

@@ -7,7 +7,7 @@
  *
  * 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 type IssueCode = 'PORT_IN_USE' | 'INVALID_PORT' | 'USER_DATA_DIR_CREATE_FAILED' | 'CHROME_LAUNCH_FAILED' | 'CHROME_DIED_AFTER_LAUNCH' | 'CHROME_PORT_NOT_OPENED' | '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>;

package/dist/errors/messages.d.ts

@@ -3,6 +3,7 @@
  *
  * Centralized location for reusable error messages with consistent formatting.
  */
+import type { MissingMethodCause } from '../cdp/methodTarget.js';
 import type { DomFrame, PendingRequestInfo } from '../ipc/protocol/commands.js';
 import { type WaitCondition, type WaitSnapshot } from '../runtime/dom/waitCondition.js';
 import { type UntrustedSessionDir } from '../session/paths.js';
@@ -83,6 +84,15 @@ export declare function sessionNotRespondingError(seconds: number): ErrorWithSug
  * @param seconds - Timeout in seconds
  */
 export declare function commandTimedOutError(seconds: number): ErrorWithSuggestion;
+/**
+ * A screenshot interrupted by Ctrl-C or SIGTERM: the daemon skips the
+ * capture if it has not started and puts the page's emulation back before
+ * any later page command runs.
+ *
+ * @param signal - The signal that stopped it
+ * @returns Message and suggestion
+ */
+export declare function screenshotInterruptedError(signal: 'SIGINT' | 'SIGTERM'): ErrorWithSuggestion;
 /**
  * What to do when a command finds no session to work with.
  *
@@ -1060,6 +1070,54 @@ export declare function formInIframeError(iframeUrl: string, crossOrigin: boolea
 export declare function cdpCallError(method: string, message: string): ErrorWithSuggestion & {
     notFound: boolean;
 };
+/**
+ * `bdg cdp` when Chrome answered -32601: it has no such method (for the
+ * page target). What it says depends on why, as far as the bundled protocol
+ * tells: an unknown domain, a redirect to a method the protocol lacks, a
+ * Chrome older than the protocol, or a method only Chrome could know (typed
+ * in one case, it gets a reminder that such names are case-sensitive).
+ *
+ * @param method - CDP method
+ * @param chromeMessage - Chrome's error, e.g. "'Foo.bar' wasn't found"
+ * @param cause - Why Chrome may lack it
+ * @returns Message and suggestion
+ */
+export declare function cdpMethodNotImplementedError(method: string, chromeMessage: string, cause: MissingMethodCause): ErrorWithSuggestion;
+/**
+ * `bdg cdp <Domain.Type>` without `--describe`: a type cannot be called.
+ *
+ * @param name - Full type name, e.g. Network.CookieSameSite
+ * @returns Message and suggestion
+ */
+export declare function cdpTypeNotMethodError(name: string): ErrorWithSuggestion;
+/**
+ * `bdg cdp <name>` for a close typo of bundled methods, or a name that is
+ * not `Domain.method`.
+ *
+ * @param input - Name as typed
+ * @param similar - Methods to suggest
+ * @param listHint - First suggestion line (how to find methods)
+ * @returns Message and suggestion
+ */
+export declare function cdpMethodNotFoundError(input: string, similar: string[], listHint: string): ErrorWithSuggestion;
+/**
+ * `bdg cdp <name>` for a close typo of bundled methods or domains: did you
+ * mean, or how to send it as typed (a method newer than the bundled protocol).
+ *
+ * @param input - Name as typed
+ * @param similar - Methods to suggest
+ * @param listHint - First suggestion line (how to find methods)
+ * @returns Message and suggestion
+ */
+export declare function cdpMethodTypoError(input: string, similar: string[], listHint: string): ErrorWithSuggestion;
+/**
+ * `bdg cdp <Domain.method> --describe` for a method the bundled protocol lacks.
+ *
+ * @param method - Method as typed
+ * @param protocolVersion - Bundled devtools-protocol version
+ * @returns Message and suggestion
+ */
+export declare function cdpMethodNotInBundledProtocolError(method: string, protocolVersion: string): ErrorWithSuggestion;
 /**
  * The skill file is not where the package should have it (a broken or
  * partial install).

package/dist/errors/messages.js

@@ -109,6 +109,20 @@ export function commandTimedOutError(seconds) {
         suggestion: `Check the session with: ${sessionCommand('bdg status')}; if the page stays frozen, end it with: ${sessionCommand('bdg cleanup --force')}`,
     };
 }
+/**
+ * A screenshot interrupted by Ctrl-C or SIGTERM: the daemon skips the
+ * capture if it has not started and puts the page's emulation back before
+ * any later page command runs.
+ *
+ * @param signal - The signal that stopped it
+ * @returns Message and suggestion
+ */
+export function screenshotInterruptedError(signal) {
+    return {
+        message: `Screenshot cancelled (${signal === 'SIGINT' ? 'interrupted' : 'terminated'})`,
+        suggestion: "No file was written; run it again to capture (the next command sees the page's own emulation)",
+    };
+}
 /**
  * What to do when a command finds no session to work with.
  *
@@ -1962,6 +1976,104 @@ export function cdpCallError(method, message) {
         notFound: false,
     };
 }
+/**
+ * `bdg cdp` when Chrome answered -32601: it has no such method (for the
+ * page target). What it says depends on why, as far as the bundled protocol
+ * tells: an unknown domain, a redirect to a method the protocol lacks, a
+ * Chrome older than the protocol, or a method only Chrome could know (typed
+ * in one case, it gets a reminder that such names are case-sensitive).
+ *
+ * @param method - CDP method
+ * @param chromeMessage - Chrome's error, e.g. "'Foo.bar' wasn't found"
+ * @param cause - Why Chrome may lack it
+ * @returns Message and suggestion
+ */
+export function cdpMethodNotImplementedError(method, chromeMessage, cause) {
+    const search = sessionCommand('bdg cdp --search <keyword>');
+    switch (cause.kind) {
+        case 'unknownDomain':
+            return {
+                message: `Unknown CDP domain ${cause.domain}: it is not in bdg's bundled protocol, and this Chrome doesn't implement ${method} (${chromeMessage})`,
+                suggestion: joinLines(cause.similar.length > 0 ? `Did you mean: ${cause.similar.join(', ')}?` : undefined, `List the domains: ${sessionCommand('bdg cdp --list')}`),
+            };
+        case 'deadRedirect':
+            return {
+                message: `This Chrome doesn't implement ${method}: the protocol redirects it to ${cause.target}, which does not exist (${chromeMessage})`,
+                suggestion: cause.similar.length > 0
+                    ? `Did you mean: ${cause.similar.join(', ')}? See: ${sessionCommand(`bdg cdp ${cause.similar[0]} --describe`)}`
+                    : `Find another method: ${search}`,
+            };
+        case 'older':
+            return {
+                message: `This Chrome doesn't implement ${method} (${chromeMessage})`,
+                suggestion: `bdg's bundled protocol has it, but this Chrome is older (or ${method} is not available on a page). Use a newer Chrome, or find another method: ${search}`,
+            };
+        case 'unlisted':
+            return {
+                message: `This Chrome doesn't implement ${method} (${chromeMessage})`,
+                suggestion: cause.oneCase
+                    ? `CDP method names are case-sensitive for methods bdg doesn't know: ${method} was sent as typed. Type it in lowerCamelCase as Chrome names it (getCookies, not getcookies), or find a method: ${search}`
+                    : `Check the spelling (Chrome's method names are case-sensitive), or find a method: ${search}`,
+            };
+    }
+}
+/**
+ * `bdg cdp <Domain.Type>` without `--describe`: a type cannot be called.
+ *
+ * @param name - Full type name, e.g. Network.CookieSameSite
+ * @returns Message and suggestion
+ */
+export function cdpTypeNotMethodError(name) {
+    return {
+        message: `${name} is a protocol type, not a method`,
+        suggestion: `Use: bdg cdp ${name} --describe (to see its values or properties)`,
+    };
+}
+/**
+ * `bdg cdp <name>` for a close typo of bundled methods, or a name that is
+ * not `Domain.method`.
+ *
+ * @param input - Name as typed
+ * @param similar - Methods to suggest
+ * @param listHint - First suggestion line (how to find methods)
+ * @returns Message and suggestion
+ */
+export function cdpMethodNotFoundError(input, similar, listHint) {
+    const didYouMean = similar.length > 0 ? ['', 'Did you mean:', ...similar.map((name) => `  - ${name}`)] : [];
+    return {
+        message: `Method '${input}' not found`,
+        suggestion: [listHint, ...didYouMean].join('\n'),
+    };
+}
+/**
+ * `bdg cdp <name>` for a close typo of bundled methods or domains: did you
+ * mean, or how to send it as typed (a method newer than the bundled protocol).
+ *
+ * @param input - Name as typed
+ * @param similar - Methods to suggest
+ * @param listHint - First suggestion line (how to find methods)
+ * @returns Message and suggestion
+ */
+export function cdpMethodTypoError(input, similar, listHint) {
+    const err = cdpMethodNotFoundError(input, similar, listHint);
+    return {
+        message: err.message,
+        suggestion: `${err.suggestion}\n\nTo send it as typed (a method newer than bdg's protocol): ${sessionCommand(`bdg cdp ${input} --send-anyway`)}`,
+    };
+}
+/**
+ * `bdg cdp <Domain.method> --describe` for a method the bundled protocol lacks.
+ *
+ * @param method - Method as typed
+ * @param protocolVersion - Bundled devtools-protocol version
+ * @returns Message and suggestion
+ */
+export function cdpMethodNotInBundledProtocolError(method, protocolVersion) {
+    return {
+        message: `Method '${method}' is not in the bundled protocol (devtools-protocol ${protocolVersion})`,
+        suggestion: `bdg cdp ${method} sends it to Chrome as is, which may still have it. Methods bdg knows: bdg cdp --search <keyword>`,
+    };
+}
 /**
  * The skill file is not where the package should have it (a broken or
  * partial install).