browser-debugger-cli 0.8.0 → 0.9.0

package/dist/utils/suggestions.js

@@ -31,4 +31,77 @@ export function formatSuggestions(suggestions, options = {}) {
 export function getSuggestion(input, candidates, options = {}) {
     return formatSuggestions(findSimilar(input, candidates, options), options);
 }
+/** Most similar ids or classes suggested for a selector that matched nothing */
+const MAX_SIMILAR_NAMES = 3;
+/**
+ * Length of the common start of two strings.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @returns Characters they share from the start
+ */
+function commonPrefixLength(a, b) {
+    let length = 0;
+    while (length < a.length && length < b.length && a[length] === b[length])
+        length++;
+    return length;
+}
+/**
+ * Length of the common end of two strings.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @returns Characters they share from the end
+ */
+function commonSuffixLength(a, b) {
+    let length = 0;
+    while (length < a.length &&
+        length < b.length &&
+        a[a.length - 1 - length] === b[b.length - 1 - length]) {
+        length++;
+    }
+    return length;
+}
+/**
+ * Names (ids or classes) similar to one that matched nothing, best first, at
+ * most three: near-typos first (Levenshtein distance up to a fifth of the
+ * length, at least 2), then names sharing a long end, then names sharing a
+ * long start (at least a third of the name, at least 4 characters). The end
+ * ranks before the start because ids tend to name an action before the item
+ * (`add-to-cart-backpack` becomes `remove-backpack` once clicked).
+ *
+ * @param name - Id or class that matched nothing
+ * @param candidates - Ids or classes on the page
+ * @returns Up to three similar names
+ */
+export function findSimilarNames(name, candidates) {
+    const others = [...new Set(candidates)].filter((candidate) => candidate !== name);
+    const maxDistance = Math.max(2, Math.floor(name.length / 5));
+    const minAffix = Math.max(4, Math.ceil(name.length / 3));
+    const typos = findMatches(name, others, maxDistance, false).map((match) => match.value);
+    const byAffix = (length) => others
+        .map((candidate) => ({ candidate, length: length(candidate) }))
+        .filter((entry) => entry.length >= minAffix)
+        .sort((a, b) => b.length - a.length)
+        .map((entry) => entry.candidate);
+    const ranked = [
+        ...typos,
+        ...byAffix((candidate) => commonSuffixLength(name, candidate)),
+        ...byAffix((candidate) => commonPrefixLength(name, candidate)),
+    ];
+    return [...new Set(ranked)].slice(0, MAX_SIMILAR_NAMES);
+}
+/**
+ * Whether a selector is a single id or class (the kind "did you mean" can
+ * suggest for).
+ *
+ * @param selector - CSS selector
+ * @returns The id or class, or null for any other selector
+ */
+export function parseSingleNameSelector(selector) {
+    const match = /^([#.])(-?[_a-zA-Z][\w-]*)$/.exec(selector.trim());
+    if (!match)
+        return null;
+    return { kind: match[1] === '#' ? 'id' : 'class', name: match[2] };
+}
 //# sourceMappingURL=suggestions.js.map

package/dist/utils/taskMappings.js

@@ -35,6 +35,11 @@ export const TASK_MAPPINGS = {
         description: 'Fill form input field by selector',
         cdpAlternative: 'Runtime.evaluate with value assignment',
     },
+    wait_for_element: {
+        commands: ['dom wait'],
+        description: 'Wait until an element appears, becomes visible, contains a text or is gone (or the page loads)',
+        cdpAlternative: 'Runtime.evaluate polling with querySelector (awaitPromise)',
+    },
     click_element: {
         commands: ['dom click'],
         description: 'Click element by selector',
@@ -55,6 +60,11 @@ export const TASK_MAPPINGS = {
         description: 'List event listeners for an element, incl. delegated ones on ancestors/document/window',
         cdpAlternative: 'DOMDebugger.getEventListeners on the element and each ancestor',
     },
+    element_layout: {
+        commands: ['dom layout'],
+        description: 'Where elements are (page/viewport coordinates, size), whether they are in view, hidden or covered',
+        cdpAlternative: 'Runtime.evaluate with getBoundingClientRect, getComputedStyle and elementFromPoint',
+    },
     accessibility_tree: {
         commands: ['dom a11y'],
         description: 'Get accessibility tree for page or element',

package/dist/utils/url.d.ts

@@ -68,11 +68,21 @@ export declare function validateUrl(url: string): ValidationResult;
  * ```
  */
 export declare function safeParseUrl(input: string): URL | null;
+/**
+ * The HTTP DevTools endpoint a `--chrome-ws-url` value names instead of a
+ * WebSocket URL: a port (`9222`), `host:port` (nothing after it), or an
+ * `http(s)://` URL of the endpoint (any path is ignored).
+ *
+ * @param value - Option value
+ * @returns Endpoint origin, e.g. `http://127.0.0.1:9222`, or null for anything else
+ */
+export declare function devToolsHttpEndpoint(value: string): string | 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
+ * Accepted: `ws://` and `wss://` DevTools URLs, or the HTTP endpoint they come
+ * from ({@link devToolsHttpEndpoint}). 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

package/dist/utils/url.js

@@ -1,6 +1,7 @@
 /**
  * URL normalization, validation, and parsing utilities.
  */
+import { sessionCommand } from '../ui/messages/sessionCommand.js';
 import { invalid, valid } from './validation.js';
 /**
  * Dangerous URL protocols that must be explicitly blocked.
@@ -119,7 +120,7 @@ export function validateUrl(url) {
     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 '...'`);
+        return invalid(`Cannot start a session on a javascript: URL`, `Open a page first, then run the script: ${sessionCommand('bdg about:blank')} && ${sessionCommand("bdg dom eval '...'")}`);
     }
     if (urlLower.startsWith('vbscript:')) {
         return invalid(`Dangerous protocol: 'vbscript:' is not allowed`, 'Use http://, https://, or other safe protocols');
@@ -181,11 +182,67 @@ export function safeParseUrl(input) {
         }
     }
 }
+/**
+ * The HTTP DevTools endpoint a `--chrome-ws-url` value names instead of a
+ * WebSocket URL: a port (`9222`), `host:port` (nothing after it), or an
+ * `http(s)://` URL of the endpoint (any path is ignored).
+ *
+ * @param value - Option value
+ * @returns Endpoint origin, e.g. `http://127.0.0.1:9222`, or null for anything else
+ */
+export function devToolsHttpEndpoint(value) {
+    const trimmed = value.trim();
+    if (/^\d{1,5}$/.test(trimmed)) {
+        return isValidPort(Number(trimmed)) ? `http://127.0.0.1:${trimmed}` : null;
+    }
+    const candidate = /^https?:\/\//i.test(trimmed)
+        ? trimmed
+        : /^[^/\s]+:\d{1,5}\/?$/.test(trimmed)
+            ? `http://${trimmed}`
+            : null;
+    if (candidate === null)
+        return null;
+    try {
+        const url = new URL(candidate);
+        return url.port === '' || isValidPort(Number(url.port)) ? url.origin : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a number is a usable TCP port (1-65535).
+ *
+ * @param port - Port number
+ * @returns True if in range
+ */
+function isValidPort(port) {
+    return Number.isInteger(port) && port >= 1 && port <= 65535;
+}
+/** A `--chrome-ws-url` value shaped like a port or `host:port` (port possibly missing) */
+const PORT_SHAPED_VALUE = /^(?:[^/\s]+:)?(\d*)\/?$/;
+/**
+ * Why a port-shaped `--chrome-ws-url` value (`99999`, `0`, `localhost:`) has
+ * no usable port.
+ *
+ * @param value - Trimmed option value that is not a valid endpoint
+ * @returns Error and suggestion, or null when the value is not port-shaped
+ */
+function portShapedValueError(value) {
+    const match = PORT_SHAPED_VALUE.exec(value);
+    if (!match || /^[a-z][a-z0-9+.-]*:\/\//i.test(value))
+        return null;
+    const digits = match[1] ?? '';
+    return invalid(digits === ''
+        ? `--chrome-ws-url is missing the port: '${value}'`
+        : `--chrome-ws-url port ${digits} is out of range (1-65535)`, 'Expected: the DevTools port (9222), host:port, or ws://host:port/devtools/browser/<uuid>');
+}
 /**
  * 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
+ * Accepted: `ws://` and `wss://` DevTools URLs, or the HTTP endpoint they come
+ * from ({@link devToolsHttpEndpoint}). 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
@@ -194,20 +251,25 @@ export function safeParseUrl(input) {
 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>');
+        return invalid('--chrome-ws-url cannot be empty', 'Expected: the DevTools port (9222), host:port, or ws://host:port/devtools/browser/<uuid>');
     }
+    if (devToolsHttpEndpoint(trimmed) !== null)
+        return valid();
+    const portError = portShapedValueError(trimmed);
+    if (portError)
+        return portError;
     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>');
+        return invalid(`--chrome-ws-url is not a valid URL: '${url}'`, 'Expected: the DevTools port (9222), host:port, or 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`);
+        return invalid(`--chrome-ws-url must use ws:// or wss://, got '${parsed.protocol}'`, `Give the DevTools port instead, e.g. --chrome-ws-url ${parsed.hostname || '127.0.0.1'}:9222`);
     }
     if (!parsed.hostname) {
-        return invalid(`--chrome-ws-url is missing a hostname: '${url}'`, 'Expected: ws://host:port/devtools/browser/<uuid>');
+        return invalid(`--chrome-ws-url is missing a hostname: '${url}'`, 'Expected: the DevTools port (9222), host:port, or 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`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "browser-debugger-cli",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "DevTools telemetry in your terminal. For humans and agents. Direct WebSocket to Chrome's debugging port.",
   "type": "module",
   "bin": {

package/dist/ui/formatters/sessionFormatters.d.ts

@@ -1,58 +0,0 @@
-/**
- * Session-related formatting helpers for landing page sections.
- *
- * Provides well-structured, TSDoc'd helpers for building each section
- * of the landing page, organized by priority (high-level commands first).
- */
-/**
- * Builds the common tasks section showing task-to-command mappings.
- *
- * Provides agents with clear intent-to-command examples.
- *
- * @returns Formatted common tasks section
- */
-export declare function buildCommonTasksSection(): string;
-/**
- * Builds the domain commands section with expanded command coverage.
- *
- * Shows all 12+ high-level commands organized by domain (DOM, Network, Console).
- * Previously showed only 2 commands, now provides comprehensive coverage.
- *
- * @returns Formatted domain commands section
- */
-export declare function buildDomainCommandsSection(): string;
-/**
- * Builds the live monitoring section.
- *
- * Shows commands for real-time data inspection during active sessions.
- *
- * @returns Formatted live monitoring section
- */
-export declare function buildLiveMonitoringSection(): string;
-/**
- * Builds the session management section.
- *
- * Shows commands for controlling the daemon and session lifecycle.
- *
- * @returns Formatted session management section
- */
-export declare function buildSessionManagementSection(): string;
-/**
- * Builds the CDP access section positioned as advanced fallback.
- *
- * Provides raw CDP protocol access for advanced use cases not covered
- * by high-level commands. Intentionally positioned after domain commands
- * to guide agents toward wrapper commands first.
- *
- * @returns Formatted CDP section
- */
-export declare function buildCdpSection(): string;
-/**
- * Builds the discovery section for AI agents.
- *
- * Points agents to machine-readable schemas and documentation resources.
- *
- * @returns Formatted discovery section
- */
-export declare function buildDiscoverySection(): string;
-//# sourceMappingURL=sessionFormatters.d.ts.map

package/dist/ui/formatters/sessionFormatters.js

@@ -1,121 +0,0 @@
-/**
- * Session-related formatting helpers for landing page sections.
- *
- * Provides well-structured, TSDoc'd helpers for building each section
- * of the landing page, organized by priority (high-level commands first).
- */
-import { getProtocolCounts } from '../../cdp/schema.js';
-import { section } from '../formatting.js';
-/**
- * Builds the common tasks section showing task-to-command mappings.
- *
- * Provides agents with clear intent-to-command examples.
- *
- * @returns Formatted common tasks section
- */
-export function buildCommonTasksSection() {
-    return section('Common Tasks:', [
-        'Screenshot    bdg dom screenshot output.png',
-        'Fill forms    bdg dom fill "#email" "test@test.com"',
-        'Click button  bdg dom click "button.submit"',
-        'Press Enter   bdg dom pressKey "input" Enter',
-        'Query DOM     bdg dom query "article h2"',
-        'Get cookies   bdg network getCookies',
-        'Export HAR    bdg network har output.har',
-    ]);
-}
-/**
- * Builds the domain commands section with expanded command coverage.
- *
- * Shows all 12+ high-level commands organized by domain (DOM, Network, Console).
- * Previously showed only 2 commands, now provides comprehensive coverage.
- *
- * @returns Formatted domain commands section
- */
-export function buildDomainCommandsSection() {
-    return section('Domain Commands:', [
-        'DOM:',
-        '  bdg dom query <selector>          Query elements (returns JSON)',
-        '  bdg dom get <selector|index>      Get element details',
-        '  bdg dom eval <javascript>         Execute JavaScript in page context',
-        '  bdg dom screenshot <path>         Capture full page screenshot',
-        '  bdg dom fill <selector> <value>   Fill form input',
-        '  bdg dom click <selector>          Click element',
-        '  bdg dom pressKey <selector> <key> Press key (Enter, Tab, Escape, etc.)',
-        '  bdg dom a11y [search]             Accessibility search (tree, query, describe)',
-        '  bdg dom listeners <selector>      Event listeners (incl. delegated)',
-        '',
-        'Network:',
-        '  bdg network har [path]            Export HTTP Archive (HAR)',
-        '  bdg network getCookies            List all cookies',
-        '  bdg network headers [id]          HTTP headers (default: main document)',
-        '',
-        'Console:',
-        '  bdg console [options]             Query console logs',
-    ]);
-}
-/**
- * Builds the live monitoring section.
- *
- * Shows commands for real-time data inspection during active sessions.
- *
- * @returns Formatted live monitoring section
- */
-export function buildLiveMonitoringSection() {
-    return section('Live Monitoring:', [
-        'bdg peek                  Preview collected data (last 10 items)',
-        'bdg peek --follow         Live updates every second',
-        'bdg tail                  Continuous monitoring (like tail -f)',
-        'bdg details network <id>  Full request/response details',
-        'bdg details console <id>  Full console message details',
-    ]);
-}
-/**
- * Builds the session management section.
- *
- * Shows commands for controlling the daemon and session lifecycle.
- *
- * @returns Formatted session management section
- */
-export function buildSessionManagementSection() {
-    return section('Session Management:', [
-        'bdg status        Check session state',
-        'bdg status --verbose     Include Chrome diagnostics',
-        'bdg stop          End session',
-        'bdg cleanup       Clean stale sessions',
-    ]);
-}
-/**
- * Builds the CDP access section positioned as advanced fallback.
- *
- * Provides raw CDP protocol access for advanced use cases not covered
- * by high-level commands. Intentionally positioned after domain commands
- * to guide agents toward wrapper commands first.
- *
- * @returns Formatted CDP section
- */
-export function buildCdpSection() {
-    const counts = getProtocolCounts();
-    return section(`Advanced: Raw CDP Access (${counts.domains} domains, ${counts.methods} methods):`, [
-        'bdg cdp --list                      List all domains',
-        `bdg cdp Network --list              List Network methods (${counts.methodsIn('Network')} methods)`,
-        'bdg cdp --search cookie             Search methods by keyword',
-        'bdg cdp Runtime.evaluate --params \'{"expression":"document.title"}\'',
-        '',
-        'Use high-level commands above when possible for better efficiency.',
-    ]);
-}
-/**
- * Builds the discovery section for AI agents.
- *
- * Points agents to machine-readable schemas and documentation resources.
- *
- * @returns Formatted discovery section
- */
-export function buildDiscoverySection() {
-    return section('Discovery (for AI agents):', [
-        'bdg --help --json          Machine-readable schema (commands, options, exit codes)',
-        'bdg cdp --search <term>    Find CDP methods by keyword',
-    ]);
-}
-//# sourceMappingURL=sessionFormatters.js.map