browser-debugger-cli 0.7.1 → 0.8.0

package/dist/utils/selectorFilters.js

@@ -0,0 +1,224 @@
+/**
+ * Playwright-style selector filters: `:has-text("…")`, `:text-is("…")` and
+ * `:visible`.
+ *
+ * They are not CSS, so the selector is split here (in Node) into the CSS the
+ * browser runs and the filters the page applies to its matches. They are only
+ * supported at the end of the last compound of each selector in a list
+ * (`li.item:has-text("x"):visible`, `a:text-is("Home"), button:visible`):
+ * there they narrow down the elements the CSS part matched. Anywhere else
+ * (`div:has-text("x") > button`, `:not(:visible)`) they would have to be
+ * evaluated inside the browser's selector matching, which bdg cannot do.
+ */
+import { CommandError } from '../errors/index.js';
+import { invalidSelectorFilterError, misplacedSelectorFilterError } from '../errors/messages.js';
+import { EXIT_CODES } from './exitCodes.js';
+/** Cheap pre-check: selectors without any of the names are plain CSS. */
+const FILTER_NAME_HINT = /:(?:has-text|text-is|visible)/i;
+/** A filter name at a given position (sticky). */
+const FILTER_NAME = /:(has-text|text-is|visible)(?![\w-])/iy;
+/** CSS ending in a (not escaped) combinator still needs an element selector. */
+const ENDS_IN_COMBINATOR = /(^|[^\\])[\s>+~]$/;
+/**
+ * Split a selector into the CSS part and filters of each selector of its
+ * list.
+ *
+ * @param selector - Selector as the user gave it
+ * @returns The parts, or null for plain CSS (no filters anywhere), which runs unchanged
+ * @throws CommandError (81) for a filter that is not at the end, or a malformed one
+ */
+export function parseSelectorFilters(selector) {
+    if (!FILTER_NAME_HINT.test(selector))
+        return null;
+    const parts = splitSelectorList(selector).map((part) => parsePart(part, selector));
+    return parts.some((part) => part.filters.length > 0) ? parts : null;
+}
+/**
+ * Split a selector list at its top-level commas (not inside quotes,
+ * attribute brackets or parentheses).
+ *
+ * @param selector - Selector list
+ * @returns The selectors, untrimmed
+ */
+export function splitSelectorList(selector) {
+    const parts = [];
+    let partStart = 0;
+    scan(selector, (index, depth) => {
+        if (selector[index] !== ',' || depth > 0)
+            return index;
+        parts.push(selector.slice(partStart, index));
+        partStart = index + 1;
+        return index;
+    });
+    parts.push(selector.slice(partStart));
+    return parts;
+}
+/**
+ * Walk a selector, calling `visit` for every character outside quotes,
+ * escapes and attribute brackets, with the parenthesis depth.
+ *
+ * @param text - Selector text
+ * @param visit - Returns the index to continue after (to skip what it consumed)
+ */
+function scan(text, visit) {
+    let depth = 0;
+    let inBrackets = false;
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (char === '\\') {
+            i++;
+        }
+        else if (char === '"' || char === "'") {
+            i = quotedEnd(text, i) - 1;
+        }
+        else if (inBrackets) {
+            inBrackets = char !== ']';
+        }
+        else if (char === '[') {
+            inBrackets = true;
+        }
+        else if (char === '(' || char === ')') {
+            depth += char === '(' ? 1 : -1;
+        }
+        else {
+            i = visit(i, depth);
+        }
+    }
+}
+/**
+ * End of a quoted string.
+ *
+ * @param text - Text containing the string
+ * @param start - Index of the opening quote
+ * @returns Index after the closing quote, or the text length when unterminated
+ */
+function quotedEnd(text, start) {
+    const end = closingQuote(text, start);
+    return end === -1 ? text.length : end + 1;
+}
+/**
+ * Index of the quote closing the string opened at `start` (backslash escapes skipped).
+ *
+ * @param text - Text containing the string
+ * @param start - Index of the opening quote
+ * @returns Index of the closing quote, or -1 when unterminated
+ */
+function closingQuote(text, start) {
+    for (let i = start + 1; i < text.length; i++) {
+        if (text[i] === '\\')
+            i++;
+        else if (text[i] === text[start])
+            return i;
+    }
+    return -1;
+}
+/**
+ * Split one selector of a list into its CSS part and trailing filters.
+ *
+ * @param part - One selector of the list
+ * @param selector - Whole selector, for error messages
+ * @returns CSS part (`*` when only filters are given) and filters
+ * @throws CommandError (81) when a filter is not at the end
+ */
+function parsePart(part, selector) {
+    const matches = findFilters(part, selector);
+    const first = matches[0];
+    if (!first)
+        return { css: part.trim(), filters: [] };
+    const misplaced = matches.find((match, i) => match.depth > 0 || match.end !== (matches[i + 1]?.start ?? part.trimEnd().length));
+    if (misplaced) {
+        const err = misplacedSelectorFilterError(selector, part.slice(misplaced.start, misplaced.end));
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    const css = part.slice(0, first.start);
+    const needsElement = css.trim() === '' || ENDS_IN_COMBINATOR.test(css);
+    return {
+        css: (needsElement ? `${css}*` : css).trim(),
+        filters: matches.map((match) => match.filter),
+    };
+}
+/**
+ * Find every filter in a selector (at any parenthesis depth, outside quotes
+ * and attribute brackets).
+ *
+ * @param part - One selector of a list
+ * @param selector - Whole selector, for error messages
+ * @returns Filters in order
+ */
+function findFilters(part, selector) {
+    const matches = [];
+    scan(part, (index, depth) => {
+        FILTER_NAME.lastIndex = index;
+        const name = FILTER_NAME.exec(part)?.[1]?.toLowerCase();
+        if (!name)
+            return index;
+        const nameEnd = FILTER_NAME.lastIndex;
+        const { filter, end } = name === 'visible'
+            ? { filter: { kind: 'visible' }, end: nameEnd }
+            : readTextFilter(part, nameEnd, name, selector);
+        matches.push({ start: index, end, depth, filter });
+        return end - 1;
+    });
+    return matches;
+}
+/**
+ * Read the `("text")` argument of a text filter.
+ *
+ * @param part - Selector text
+ * @param start - Index after the filter name
+ * @param name - `has-text` or `text-is`
+ * @param selector - Whole selector, for error messages
+ * @returns The filter (text whitespace-normalized) and the index after it
+ * @throws CommandError (81) when the argument is missing or not closed
+ */
+function readTextFilter(part, start, name, selector) {
+    const argument = part[start] === '(' ? readArgument(part, start + 1) : null;
+    if (!argument) {
+        const err = invalidSelectorFilterError(selector, `:${name}`);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    const text = argument.text.replace(/\s+/g, ' ').trim();
+    const filter = name === 'has-text'
+        ? { kind: 'has-text', text: text.toLowerCase() }
+        : { kind: 'text-is', text };
+    return { filter, end: argument.end };
+}
+/**
+ * Read a filter argument: a single- or double-quoted string (backslash
+ * escapes allowed) or unquoted text, up to the closing parenthesis.
+ *
+ * @param part - Selector text
+ * @param start - Index after the opening parenthesis
+ * @returns Argument text and the index after the closing parenthesis, or null when malformed
+ */
+function readArgument(part, start) {
+    const valueStart = start + (part.slice(start).length - part.slice(start).trimStart().length);
+    const quote = part[valueStart];
+    if (quote === '"' || quote === "'") {
+        const close = closingQuote(part, valueStart);
+        const after = close === -1 ? -1 : part.indexOf(')', close);
+        if (after === -1 || part.slice(close + 1, after).trim() !== '')
+            return null;
+        return { text: part.slice(valueStart + 1, close).replace(/\\(.)/gs, '$1'), end: after + 1 };
+    }
+    const close = matchingParenthesis(part, start);
+    return close === -1 ? null : { text: part.slice(start, close), end: close + 1 };
+}
+/**
+ * Index of the parenthesis closing an unquoted argument (nested pairs skipped).
+ *
+ * @param part - Selector text
+ * @param start - Index after the opening parenthesis
+ * @returns Index of the closing parenthesis, or -1 when there is none
+ */
+function matchingParenthesis(part, start) {
+    let depth = 0;
+    for (let i = start; i < part.length; i++) {
+        if (part[i] === '(')
+            depth++;
+        else if (part[i] === ')' && depth-- === 0)
+            return i;
+    }
+    return -1;
+}
+//# sourceMappingURL=selectorFilters.js.map

package/dist/utils/suggestions.js

@@ -1,7 +1,7 @@
 /**
  * Suggestion utilities for typo detection and helpful error messages.
  */
-import { levenshteinDistance } from '../utils/levenshtein.js';
+import { levenshteinDistance } from './levenshtein.js';
 function normalizeForComparison(str, caseInsensitive) {
     return caseInsensitive ? str.toLowerCase() : str;
 }

package/dist/utils/taskMappings.js

@@ -50,6 +50,11 @@ export const TASK_MAPPINGS = {
         description: 'Get detailed element information',
         cdpAlternative: 'Runtime.evaluate with property extraction',
     },
+    inspect_event_listeners: {
+        commands: ['dom listeners'],
+        description: 'List event listeners for an element, incl. delegated ones on ancestors/document/window',
+        cdpAlternative: 'DOMDebugger.getEventListeners on the element and each ancestor',
+    },
     accessibility_tree: {
         commands: ['dom a11y'],
         description: 'Get accessibility tree for page or element',
@@ -93,7 +98,7 @@ export const TASK_MAPPINGS = {
     preview_data: {
         commands: ['peek'],
         description: 'Preview collected network and console data',
-        cdpAlternative: 'Multiple IPC queries to worker state',
+        cdpAlternative: 'Multiple IPC queries to session state',
     },
     live_monitoring: {
         commands: ['peek --follow', 'tail'],
@@ -103,7 +108,7 @@ export const TASK_MAPPINGS = {
     get_full_details: {
         commands: ['details network', 'details console'],
         description: 'Get complete request/response or console message details',
-        cdpAlternative: 'Worker state query + response body fetch',
+        cdpAlternative: 'Session state query + response body fetch',
     },
     check_session_status: {
         commands: ['status'],

package/dist/utils/typeGuards.js

@@ -8,8 +8,8 @@
  * runtime errors. Type guards provide actual runtime validation while
  * maintaining type safety.
  */
-import { CommandError } from '../ui/errors/index.js';
-import { EXIT_CODES } from '../utils/exitCodes.js';
+import { CommandError } from '../errors/index.js';
+import { EXIT_CODES } from './exitCodes.js';
 /**
  * Type guard to check if a value is a valid NetworkRequest.
  *

package/dist/utils/url.d.ts

@@ -1,6 +1,7 @@
 /**
  * URL normalization, validation, and parsing utilities.
  */
+import { type ValidationResult } from './validation.js';
 /**
  * Normalize a URL by adding http:// protocol if missing.
  *
@@ -49,11 +50,7 @@ export declare function normalizeUrl(url: string): string;
  * All URLs are normalized before validation to support convenient formats like
  * 'localhost:3000' or 'example.com'.
  */
-export declare function validateUrl(url: string): {
-    valid: boolean;
-    error?: string;
-    suggestion?: string;
-};
+export declare function validateUrl(url: string): ValidationResult;
 /**
  * Safely parse a URL string with automatic protocol detection.
  *
@@ -71,6 +68,17 @@ export declare function validateUrl(url: string): {
  * ```
  */
 export declare function safeParseUrl(input: string): URL | null;
+/**
+ * Validate a `--chrome-ws-url` value.
+ *
+ * Accepted schemes: `ws://` and `wss://`. Rejects other schemes, malformed
+ * URLs, and empty input so users hear about the problem at the CLI boundary
+ * instead of after a daemon round-trip.
+ *
+ * @param url - ws URL to validate
+ * @returns Validation result with error/suggestion when invalid
+ */
+export declare function validateChromeWsUrl(url: string): ValidationResult;
 /**
  * Extract hostname from a URL string safely.
  *

package/dist/utils/url.js

@@ -1,6 +1,7 @@
 /**
  * URL normalization, validation, and parsing utilities.
  */
+import { invalid, valid } from './validation.js';
 /**
  * Dangerous URL protocols that must be explicitly blocked.
  *
@@ -102,40 +103,26 @@ export function normalizeUrl(url) {
  */
 export function validateUrl(url) {
     if (!url || url.trim().length === 0) {
-        return {
-            valid: false,
-            error: 'URL cannot be empty',
-            suggestion: 'Provide a valid URL, e.g.: http://localhost:3000',
-        };
+        return invalid('URL cannot be empty', 'Provide a valid URL, e.g.: http://localhost:3000');
     }
     if (url.includes(' ')) {
-        return {
-            valid: false,
-            error: `Invalid URL format: '${url}' (contains spaces)`,
-            suggestion: 'URLs cannot contain spaces. If your URL has query parameters, wrap it in quotes: bdg "https://example.com/search?q=test"',
-        };
-    }
-    // Check for signs of shell glob expansion issues
-    // If URL looks like it might have been mangled by shell expansion
-    if (!url.includes('?') && !url.includes('&') && /^[a-z]+:\/\/[^/]+\/[^/]+$/.test(url)) {
-        // URL has path but no query params - might be fine, continue validation
+        return invalid(`Invalid URL format: '${url}' (contains spaces)`, 'Encode spaces as %20, e.g. bdg "https://example.com/search?q=a%20b"');
     }
     // Detect if URL looks truncated (common when shell expands ? as glob)
     if (url.endsWith('?') || url.endsWith('&')) {
-        return {
-            valid: false,
-            error: `URL appears truncated: '${url}'`,
-            suggestion: 'URLs with query parameters (? or &) must be quoted: bdg "https://example.com/search?q=test"',
-        };
+        return invalid(`URL appears truncated: '${url}'`, 'URLs with query parameters (? or &) must be quoted: bdg "https://example.com/search?q=test"');
+    }
+    const scheme = /^([a-z][a-z0-9+.-]*):\/\//i.exec(url)?.[1]?.toLowerCase();
+    if (scheme && !VALID_PROTOCOLS.includes(`${scheme}:`)) {
+        return invalid(`Unsupported protocol: '${scheme}:'`, 'bdg opens http://, https://, file://, about:, chrome:, and data: URLs');
     }
     const normalized = normalizeUrl(url);
     const urlLower = url.toLowerCase();
+    if (urlLower.startsWith('javascript:')) {
+        return invalid(`Cannot start a session on a javascript: URL`, `Open a page first, then run the script: bdg about:blank && bdg dom eval '...'`);
+    }
     if (urlLower.startsWith('vbscript:')) {
-        return {
-            valid: false,
-            error: `Dangerous protocol: 'vbscript:' is not allowed`,
-            suggestion: 'Use http://, https://, or other safe protocols',
-        };
+        return invalid(`Dangerous protocol: 'vbscript:' is not allowed`, 'Use http://, https://, or other safe protocols');
     }
     const isSpecialProtocol = urlLower.startsWith('javascript:') ||
         urlLower.startsWith('data:') ||
@@ -143,45 +130,26 @@ export function validateUrl(url) {
     if (!isSpecialProtocol) {
         const beforePath = url.split('/')[0] ?? '';
         if (/[!@#$%^&*()=+[\]{}\\|;'",<>?]/.test(beforePath)) {
-            return {
-                valid: false,
-                error: `Invalid URL format: '${url}' (contains invalid characters)`,
-                suggestion: 'URLs cannot contain special characters like !, @, #, etc. in hostname or protocol',
-            };
+            return invalid(`Invalid URL format: '${url}' (contains invalid characters)`, 'URLs cannot contain special characters like !, @, #, etc. in hostname or protocol');
         }
     }
     try {
         const parsed = new URL(normalized);
         // Explicitly block dangerous protocols (CodeQL js/incomplete-url-scheme-check)
         if (DANGEROUS_PROTOCOLS.includes(parsed.protocol)) {
-            return {
-                valid: false,
-                error: `Blocked dangerous protocol: '${parsed.protocol}'`,
-                suggestion: 'This protocol is not allowed for security reasons',
-            };
+            return invalid(`Blocked dangerous protocol: '${parsed.protocol}'`, 'This protocol is not allowed for security reasons');
         }
         if (!VALID_PROTOCOLS.includes(parsed.protocol)) {
-            return {
-                valid: false,
-                error: `Invalid protocol: '${parsed.protocol}'`,
-                suggestion: 'URLs must use http://, https://, or other valid protocols',
-            };
+            return invalid(`Invalid protocol: '${parsed.protocol}'`, 'URLs must use http://, https://, or other valid protocols');
         }
-        if ((parsed.protocol === 'http:' || parsed.protocol === 'https:') && !parsed.hostname) {
-            return {
-                valid: false,
-                error: `Invalid URL format: '${url}' (missing hostname)`,
-                suggestion: 'URLs must include a valid hostname, e.g.: http://example.com',
-            };
+        const isWeb = parsed.protocol === 'http:' || parsed.protocol === 'https:';
+        if (isWeb && !/[a-z0-9]/i.test(parsed.hostname)) {
+            return invalid(`Invalid URL format: '${url}' (missing hostname)`, 'URLs must include a valid hostname, e.g.: http://example.com');
         }
-        return { valid: true };
+        return valid();
     }
     catch {
-        return {
-            valid: false,
-            error: `Invalid URL format: '${url}'`,
-            suggestion: 'URLs must include a valid protocol (http:// or https://). If URL has query parameters, quote it: bdg "https://example.com?q=test"',
-        };
+        return invalid(`Invalid URL format: '${url}'`, 'URLs must include a valid protocol (http:// or https://). If URL has query parameters, quote it: bdg "https://example.com?q=test"');
     }
 }
 /**
@@ -213,6 +181,39 @@ export function safeParseUrl(input) {
         }
     }
 }
+/**
+ * Validate a `--chrome-ws-url` value.
+ *
+ * Accepted schemes: `ws://` and `wss://`. Rejects other schemes, malformed
+ * URLs, and empty input so users hear about the problem at the CLI boundary
+ * instead of after a daemon round-trip.
+ *
+ * @param url - ws URL to validate
+ * @returns Validation result with error/suggestion when invalid
+ */
+export function validateChromeWsUrl(url) {
+    const trimmed = url.trim();
+    if (!trimmed) {
+        return invalid('--chrome-ws-url cannot be empty', 'Expected: ws://host:port/devtools/browser/<uuid>');
+    }
+    let parsed;
+    try {
+        parsed = new URL(trimmed);
+    }
+    catch {
+        return invalid(`--chrome-ws-url is not a valid URL: '${url}'`, 'Expected: ws://host:port/devtools/browser/<uuid>');
+    }
+    if (parsed.protocol !== 'ws:' && parsed.protocol !== 'wss:') {
+        return invalid(`--chrome-ws-url must use ws:// or wss://, got '${parsed.protocol}'`, `Find it with: curl -s http://${parsed.host || '127.0.0.1:9222'}/json/version | jq -r .webSocketDebuggerUrl`);
+    }
+    if (!parsed.hostname) {
+        return invalid(`--chrome-ws-url is missing a hostname: '${url}'`, 'Expected: ws://host:port/devtools/browser/<uuid>');
+    }
+    if (!/^\/devtools\/(browser|page)\/[^/]+$/.test(parsed.pathname)) {
+        return invalid(`--chrome-ws-url must point to /devtools/browser/<id> or /devtools/page/<id>, got '${parsed.pathname}'`, `Find it with: curl -s http://${parsed.host}/json/version | jq -r .webSocketDebuggerUrl`);
+    }
+    return valid();
+}
 /**
  * Extract hostname from a URL string safely.
  *

package/dist/utils/validation.d.ts

@@ -1,101 +1,23 @@
 /**
- * @deprecated This validation module is deprecated. Use `@/commands/shared/validation.ts` instead.
+ * Shared validation-result shape used across URL, argument, and config validators.
  *
- * Migration guide:
- * - `parseOptionalIntOption()` → `optionalIntRule()` with `validateOptions()`
- * - `parsePositiveIntOption()` → `positiveIntRule()` with `validateOptions()`
- * - `parseIntOption()` → `positiveIntRule()` with custom options
- *
- * The new validation layer provides:
- * - Structured CommandError instances with proper exit codes
- * - Type-safe validation rules
- * - Consistent error formatting
- * - Composable validation patterns
- *
- * @see commands/shared/validation.ts
- */
-/**
- * Parse and validate an integer option with range constraints.
- *
- * @deprecated Use `positiveIntRule()` from `@/commands/shared/validation.ts` instead
- *
- * @param name - The option name for error messages
- * @param value - The string value to parse (or undefined)
- * @param options - Validation configuration
- * @returns Parsed integer value or undefined if not required and not provided
- * @throws Error if validation fails
- *
- * @example
- * ```typescript
- * // Required with default
- * const lastN = parseIntOption('last', options.last, {
- *   defaultValue: 10,
- *   min: 1,
- *   max: 1000
- * });
- *
- * // Optional
- * const timeout = parseIntOption('timeout', options.timeout, {
- *   required: false,
- *   min: 1,
- *   max: 3600
- * });
- * ```
+ * Discriminated on `valid` so callers get exhaustive narrowing: `error` and
+ * `suggestion` are only accessible after a `!result.valid` check.
  */
-export declare function parseIntOption(name: string, value: string | undefined, options?: {
-    required?: boolean;
-    defaultValue?: number;
-    min?: number;
-    max?: number;
-    errorFormatter?: (value: string | undefined) => string;
-}): number | undefined;
+export type ValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    error: string;
+    suggestion?: string;
+};
 /**
- * Parse and validate a positive integer option with range constraints.
- *
- * @deprecated Use `positiveIntRule()` from `@/commands/shared/validation.ts` instead
- *
- * @param name - The option name for error messages
- * @param value - The string value to parse (or undefined)
- * @param options - Validation configuration
- * @returns Parsed integer value
- * @throws Error if validation fails
- *
- * @example
- * ```typescript
- * const lastN = parsePositiveIntOption('last', options.last, {
- *   defaultValue: 10,
- *   min: 1,
- *   max: 1000
- * });
- * ```
+ * Build a successful validation result.
  */
-export declare function parsePositiveIntOption(name: string, value: string | undefined, options?: {
-    defaultValue?: number;
-    min?: number;
-    max?: number;
-    errorFormatter?: (value: string | undefined) => string;
-}): number;
+export declare function valid(): ValidationResult;
 /**
- * Parse an optional integer option (returns undefined if not provided).
- *
- * @deprecated Use `optionalIntRule()` from `@/commands/shared/validation.ts` instead
- *
- * @param name - The option name for error messages
- * @param value - The string value to parse (or undefined)
- * @param options - Validation configuration
- * @returns Parsed integer or undefined
- * @throws Error if value is provided but invalid
- *
- * @example
- * ```typescript
- * const timeout = parseOptionalIntOption('timeout', options.timeout, {
- *   min: 1,
- *   max: 3600
- * });
- * ```
+ * Build a failed validation result with a required error and optional
+ * recovery suggestion.
  */
-export declare function parseOptionalIntOption(name: string, value: string | undefined, options?: {
-    min?: number;
-    max?: number;
-}): number | undefined;
+export declare function invalid(error: string, suggestion?: string): ValidationResult;
 //# sourceMappingURL=validation.d.ts.map