browser-debugger-cli 0.14.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,8 +3,10 @@
  *
  * 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';
 import type { DocumentRequestState, IndexSource } from '../types.js';
 /**
  * Generate "session already running" error message (commands carry
@@ -82,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.
  *
@@ -258,6 +269,13 @@ 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;
+/**
+ * "Did you mean" for one or more close candidates, joined as a sentence.
+ *
+ * @param candidates - Close matches, e.g. ["form", "frames"]
+ * @returns e.g. "Did you mean: form or frames?" or "Did you mean: a, b or c?"
+ */
+export declare function didYouMeanSuggestion(candidates: string[]): string;
 /**
  * Suggestion for a command-line usage error (missing argument, invalid value,
  * unknown option without a close match).
@@ -360,6 +378,21 @@ export declare function sessionDirIsFileError(dir: string): ErrorWithSuggestion;
  * @param reason - File-system error
  */
 export declare function sessionDirNotWritableError(dir: string, reason: string): ErrorWithSuggestion;
+/**
+ * The session directory, or one above it, is not safe to use: another user
+ * could replace the daemon socket or plant files there.
+ *
+ * @param untrusted - Untrusted directory and why
+ */
+export declare function untrustedSessionDirError(untrusted: UntrustedSessionDir): ErrorWithSuggestion;
+/**
+ * The daemon log cannot be opened for writing (a symlink there is refused,
+ * not followed).
+ *
+ * @param logPath - Daemon log path
+ * @param code - File-system error code
+ */
+export declare function daemonLogNotOpenedError(logPath: string, code: string): ErrorWithSuggestion;
 /**
  * The daemon socket path exceeds the OS limit for Unix sockets.
  *
@@ -1037,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

@@ -3,6 +3,7 @@
  *
  * Centralized location for reusable error messages with consistent formatting.
  */
+import * as os from 'os';
 import * as path from 'path';
 import { countedMatches, } from '../runtime/dom/waitCondition.js';
 import { getSessionBaseDir, getSessionName } from '../session/paths.js';
@@ -108,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.
  *
@@ -370,6 +385,17 @@ export function unknownHelpTopicError(topic, closest) {
             : `Run "bdg ${parent ? `${parent} ` : ''}--help" for commands`,
     };
 }
+/**
+ * "Did you mean" for one or more close candidates, joined as a sentence.
+ *
+ * @param candidates - Close matches, e.g. ["form", "frames"]
+ * @returns e.g. "Did you mean: form or frames?" or "Did you mean: a, b or c?"
+ */
+export function didYouMeanSuggestion(candidates) {
+    const last = candidates.at(-1) ?? '';
+    const rest = candidates.slice(0, -1);
+    return `Did you mean: ${rest.length > 0 ? `${rest.join(', ')} or ${last}` : last}?`;
+}
 /**
  * Suggestion for a command-line usage error (missing argument, invalid value,
  * unknown option without a close match).
@@ -498,7 +524,7 @@ export function invalidSessionNameError(name, maxLength) {
 export function sessionNameSocketTooLongError(name, socketPath, max) {
     return {
         message: `Session name "${name}" makes the daemon socket path too long (${Buffer.byteLength(socketPath)} bytes, at most ${max}): ${socketPath}`,
-        suggestion: 'Use a shorter session name, or a shorter BDG_SESSION_DIR (e.g. /tmp/bdg)',
+        suggestion: `Use a shorter session name, or a shorter BDG_SESSION_DIR (e.g. ${privateSessionDirExample()})`,
     };
 }
 /**
@@ -524,15 +550,36 @@ export function purgeRefusedError(dir, reason) {
         suggestion: `End the session first (${sessionCommand('bdg cleanup --force')}), then retry: ${sessionCommand('bdg cleanup --purge')}`,
     };
 }
-/** Fix for an unusable session directory */
-const SESSION_DIR_SUGGESTION = 'Set BDG_SESSION_DIR to a short, writable directory, e.g. BDG_SESSION_DIR=/tmp/bdg';
+/**
+ * A short session directory only the user can use, for suggestions: in
+ * `$XDG_RUNTIME_DIR` (Linux, private to the user) when set, else a per-user
+ * name in the OS temp directory (per-user on macOS). Never the shared
+ * `/tmp/bdg`, which another user can create first.
+ *
+ * @returns Absolute directory path
+ */
+function privateSessionDirExample() {
+    const runtimeDir = process.env['XDG_RUNTIME_DIR']?.trim();
+    if (runtimeDir)
+        return path.join(runtimeDir, 'bdg');
+    const uid = process.getuid?.();
+    return path.join(os.tmpdir(), uid === undefined ? 'bdg' : `bdg-${uid}`);
+}
+/**
+ * Fix for an unusable session directory.
+ *
+ * @returns Suggestion naming a private, short directory
+ */
+function sessionDirSuggestion() {
+    return `Set BDG_SESSION_DIR to a short directory only you can write to, e.g. BDG_SESSION_DIR=${privateSessionDirExample()}`;
+}
 /**
  * The session directory exists but is not a directory.
  *
  * @param dir - Session directory
  */
 export function sessionDirIsFileError(dir) {
-    return { message: `Session directory ${dir} is a file`, suggestion: SESSION_DIR_SUGGESTION };
+    return { message: `Session directory ${dir} is a file`, suggestion: sessionDirSuggestion() };
 }
 /**
  * The session directory cannot be created or written.
@@ -543,7 +590,54 @@ export function sessionDirIsFileError(dir) {
 export function sessionDirNotWritableError(dir, reason) {
     return {
         message: `Session directory ${dir} is not writable (${reason})`,
-        suggestion: SESSION_DIR_SUGGESTION,
+        suggestion: sessionDirSuggestion(),
+    };
+}
+/**
+ * The session directory, or one above it, is not safe to use: another user
+ * could replace the daemon socket or plant files there.
+ *
+ * @param untrusted - Untrusted directory and why
+ */
+export function untrustedSessionDirError(untrusted) {
+    return {
+        message: `Session directory ${untrusted.dir} is not safe to use: ${untrusted.reason}`,
+        suggestion: untrustedSessionDirSuggestion(untrusted),
+    };
+}
+/**
+ * Fix for an untrusted session directory: remove a symlink, use a
+ * subdirectory of a shared sticky directory (`BDG_SESSION_DIR=/tmp`), chmod
+ * a directory bdg owns (`~/.bdg`, `sessions/`, `sessions/<name>`), else
+ * choose another `BDG_SESSION_DIR`.
+ *
+ * @param untrusted - Untrusted directory and why
+ * @returns Suggestion
+ */
+function untrustedSessionDirSuggestion(untrusted) {
+    const { dir, kind, bdgOwned } = untrusted;
+    const example = `BDG_SESSION_DIR=${privateSessionDirExample()}`;
+    if (kind === 'symlink') {
+        return `Remove the link (rm ${dir}) or point BDG_SESSION_DIR at the real directory`;
+    }
+    if (kind === 'shared') {
+        return `${dir} is shared by all users; use a subdirectory only you can write to, e.g. ${example}`;
+    }
+    if (bdgOwned)
+        return `Run chmod 700 ${dir} (or remove it if it is not yours), then retry`;
+    return `Use a directory you own that others cannot write to, e.g. ${example} (or chmod 700 ${dir} if it is yours)`;
+}
+/**
+ * The daemon log cannot be opened for writing (a symlink there is refused,
+ * not followed).
+ *
+ * @param logPath - Daemon log path
+ * @param code - File-system error code
+ */
+export function daemonLogNotOpenedError(logPath, code) {
+    return {
+        message: `Cannot open the daemon log ${logPath} (${code === 'ELOOP' ? 'it is a symbolic link' : code})`,
+        suggestion: `Remove ${logPath} if you did not create it, then retry`,
     };
 }
 /**
@@ -555,7 +649,7 @@ export function sessionDirNotWritableError(dir, reason) {
 export function socketPathTooLongError(socketPath, max) {
     return {
         message: `Session directory path is too long for the daemon socket (${Buffer.byteLength(socketPath)} bytes, at most ${max}): ${socketPath}`,
-        suggestion: SESSION_DIR_SUGGESTION,
+        suggestion: sessionDirSuggestion(),
     };
 }
 /**
@@ -1882,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).