browser-debugger-cli 0.7.1 → 0.8.0

package/dist/commands/dom/helpers/query.js

@@ -0,0 +1,457 @@
+/**
+ * CDP-relay helpers for DOM query and read operations.
+ *
+ * Covers `bdg dom query` (find by selector) and `bdg dom get` (read details)
+ * plus selector resolution and single-node DOM context lookups.
+ *
+ * Node ids reported to users and stored in the query cache are backend node
+ * ids: they identify an element for as long as it stays in the page, across
+ * bdg invocations. Selectors are matched in the page, including open shadow
+ * roots and same-origin iframes, like a user sees the page.
+ */
+import { CommandError } from '../../../errors/index.js';
+import { noNodesFoundError, indexOutOfRangeError, eitherArgumentRequiredError, invalidSelectorError, nodeIdNotFoundError, staleNodeError, } from '../../../errors/messages.js';
+import { callCDP } from '../../../ipc/client.js';
+import { DEEP_QUERY_JS, selectorArgsJS } from '../../../runtime/dom/targetNode.js';
+import { resolveA11yNode } from '../../../telemetry/a11y.js';
+import { createLogger } from '../../../ui/logging/index.js';
+import { ConcurrencyLimiter } from '../../../utils/concurrency.js';
+import { EXIT_CODES } from '../../../utils/exitCodes.js';
+const log = createLogger('dom');
+/** Maximum concurrent CDP calls to avoid overwhelming the connection. */
+const CDP_CONCURRENCY_LIMIT = 10;
+/** Length of the text preview shown for queried elements. */
+const PREVIEW_LENGTH = 80;
+/**
+ * Convert CDP's flat attribute list to a record.
+ *
+ * @param attributes - `[name, value, name, value, ...]`
+ * @returns Attribute map
+ */
+function unpackAttributes(attributes) {
+    const result = {};
+    if (!attributes)
+        return result;
+    for (let i = 0; i < attributes.length; i += 2) {
+        const key = attributes[i];
+        const value = attributes[i + 1];
+        if (key !== undefined && value !== undefined) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Describe a node.
+ *
+ * @param ref - Node reference
+ * @returns Node description, or null if the node does not exist
+ */
+async function describeNode(ref) {
+    const response = await callCDP('DOM.describeNode', ref);
+    if (response.status === 'error')
+        return null;
+    return response.data?.result?.node ?? null;
+}
+/**
+ * Get a node's outer HTML.
+ *
+ * @param ref - Node reference
+ * @returns Outer HTML, or undefined if unavailable
+ */
+async function getOuterHTML(ref) {
+    const response = await callCDP('DOM.getOuterHTML', ref);
+    return response.data?.result?.outerHTML;
+}
+/**
+ * Page-side text of an element as a user sees it: `innerText` for a rendered
+ * element (CSS-hidden parts left out, inline elements not split apart), none
+ * for an element that is not rendered, `textContent` for SVG and other
+ * elements without `innerText` and for `display: contents` wrappers (no box
+ * of their own, but their children are shown).
+ */
+const ELEMENT_TEXT_JS = `(el) => {
+  if (typeof el.innerText !== 'string') return el.textContent || '';
+  if (!el.checkVisibility || el.checkVisibility()) return el.innerText;
+  const boxless = el.ownerDocument.defaultView.getComputedStyle(el).display === 'contents';
+  return boxless ? el.textContent || '' : '';
+}`;
+/**
+ * Short text preview of an element's text: whitespace collapsed, cut on a
+ * whole character (an emoji is never split, which would make JSON invalid).
+ *
+ * @param text - Element text as the page renders it
+ * @returns Collapsed text, truncated to {@link PREVIEW_LENGTH} characters
+ */
+export function textPreview(text) {
+    const collapsed = text.replace(/\s+/g, ' ').trim();
+    const characters = Array.from(collapsed);
+    return characters.length > PREVIEW_LENGTH
+        ? characters.slice(0, PREVIEW_LENGTH).join('') + '...'
+        : collapsed;
+}
+/** Counter giving each query its own object group (queries may run concurrently) */
+let queryCount = 0;
+/**
+ * Find the elements matching a selector, including those in open shadow roots
+ * and same-origin iframes ({@link DEEP_QUERY_JS}).
+ *
+ * @param selector - CSS selector
+ * @returns Backend node ids of all matches
+ * @throws CommandError (81) for an invalid selector
+ */
+async function selectAll(selector) {
+    const ids = await withSelection(selector, elementBackendNodeIds);
+    return ids.filter((id) => id !== undefined);
+}
+/**
+ * Run the selector in the page and use the array of matches.
+ *
+ * @param selector - CSS selector
+ * @param use - Reads what it needs from the page-side array
+ * @returns What `use` returns
+ * @throws CommandError (81) for an invalid selector
+ */
+async function withSelection(selector, use) {
+    await callCDP('DOM.enable', {});
+    const objectGroup = `bdg-query-${process.pid}-${++queryCount}`;
+    const evaluated = await callCDP('Runtime.evaluate', {
+        expression: `(${DEEP_QUERY_JS})(${selectorArgsJS(selector)})`,
+        objectGroup,
+    });
+    try {
+        return await use(selectionObjectId(selector, evaluated));
+    }
+    finally {
+        await callCDP('Runtime.releaseObjectGroup', { objectGroup });
+    }
+}
+/** Where each element of a page-side array lives (an iframe and/or a shadow root), and its text */
+const ELEMENT_DETAILS_FUNCTION = `function () {
+  const describe = (node) => node.tagName.toLowerCase() + (node.id ? '#' + node.id : '');
+  const textOf = ${ELEMENT_TEXT_JS};
+  return Array.from(this, (el) => {
+    const parts = [];
+    for (let doc = el.ownerDocument; doc && doc.defaultView && doc.defaultView.frameElement; ) {
+      const frame = doc.defaultView.frameElement;
+      parts.unshift(describe(frame));
+      doc = frame.ownerDocument;
+    }
+    const root = el.getRootNode();
+    if (root.host) parts.push('shadow root of <' + describe(root.host) + '>');
+    return { context: parts.join(' > '), text: textOf(el) };
+  });
+}`;
+/**
+ * Backend node ids of the elements in a page-side array, each with where it
+ * lives (empty for the main document) and its text.
+ *
+ * @param arrayObjectId - Remote object id of the array
+ * @returns Elements in array order (ones that cannot be described are left out)
+ */
+async function elementsWithDetails(arrayObjectId) {
+    const response = await callCDP('Runtime.callFunctionOn', {
+        objectId: arrayObjectId,
+        functionDeclaration: ELEMENT_DETAILS_FUNCTION,
+        returnByValue: true,
+    });
+    const value = response.data?.result?.result
+        ?.value;
+    const details = (Array.isArray(value) ? value : []);
+    const ids = await elementBackendNodeIds(arrayObjectId);
+    return ids.flatMap((backendNodeId, index) => backendNodeId === undefined
+        ? []
+        : [
+            {
+                backendNodeId,
+                context: details[index]?.context ?? '',
+                text: details[index]?.text ?? '',
+            },
+        ]);
+}
+/**
+ * The page-side array of a selector query, or the error explaining why there
+ * is none: a selector the browser rejects (a `SyntaxError` DOMException) is the
+ * user's (81); anything else (no session, a page navigating away) is not.
+ *
+ * @param selector - CSS selector
+ * @param evaluated - `Runtime.evaluate` response
+ * @returns Remote object id of the array of matches
+ * @throws CommandError (81) for an invalid selector, (101) otherwise
+ */
+function selectionObjectId(selector, evaluated) {
+    const { result, exceptionDetails } = (evaluated.data?.result ??
+        {});
+    const description = exceptionDetails?.exception?.description;
+    if (description?.startsWith('SyntaxError')) {
+        const detail = description.split('\n')[0];
+        const err = invalidSelectorError(selector, detail);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    if (evaluated.status === 'error' || exceptionDetails || !result?.objectId) {
+        const detail = exceptionDetails?.exception?.description ?? evaluated.error ?? 'no result';
+        throw new CommandError(`Could not search the page for "${selector}": ${detail.split('\n')[0]}`, { suggestion: 'Check that the page has finished loading, then retry' }, EXIT_CODES.CDP_CONNECTION_FAILURE);
+    }
+    return result.objectId;
+}
+/**
+ * Backend node ids of the elements in a page-side array.
+ *
+ * @param arrayObjectId - Remote object id of the array
+ * @returns Backend node ids in array order (`undefined` where an element
+ *   cannot be described, so positions match the array)
+ */
+async function elementBackendNodeIds(arrayObjectId) {
+    const response = await callCDP('Runtime.getProperties', {
+        objectId: arrayObjectId,
+        ownProperties: true,
+    });
+    const properties = response.data?.result?.result ?? [];
+    const elementIds = properties
+        .filter((property) => /^\d+$/.test(property.name))
+        .sort((a, b) => Number(a.name) - Number(b.name))
+        .map((property) => property.value?.objectId);
+    const ids = await mapConcurrently(elementIds, async (objectId) => {
+        if (!objectId)
+            return undefined;
+        const described = await callCDP('DOM.describeNode', { objectId });
+        return described.data?.result?.node
+            .backendNodeId;
+    });
+    return ids;
+}
+/**
+ * Run an async mapper over items with bounded CDP concurrency.
+ *
+ * @param items - Items to map
+ * @param mapper - Async mapper
+ * @returns Mapped results in input order
+ */
+function mapConcurrently(items, mapper) {
+    const limiter = new ConcurrencyLimiter(CDP_CONCURRENCY_LIMIT);
+    return Promise.all(items.map((item, index) => limiter.run(() => mapper(item, index))));
+}
+/**
+ * Query elements by selector for `bdg dom query`.
+ *
+ * @param selector - CSS selector
+ * @returns Matches with backend node ids, tags, classes and text previews
+ */
+export async function queryDOMElements(selector) {
+    const elements = await withSelection(selector, elementsWithDetails);
+    if (elements.length > 20) {
+        log.debug(`Querying ${elements.length} elements with selector: ${selector}`);
+    }
+    const nodes = await mapConcurrently(elements, async ({ backendNodeId, context, text }, index) => {
+        const desc = await describeNode({ backendNodeId });
+        if (!desc)
+            return { index, nodeId: 0 };
+        const attributes = unpackAttributes(desc.attributes);
+        const classes = attributes['class']?.split(/\s+/).filter(Boolean);
+        const preview = textPreview(text);
+        return {
+            index,
+            nodeId: desc.backendNodeId,
+            tag: desc.nodeName.toLowerCase(),
+            ...identifyingAttributes(attributes),
+            ...(classes && { classes }),
+            ...(preview && { preview }),
+            ...(context && { context }),
+        };
+    });
+    return { selector, count: nodes.length, nodes };
+}
+/**
+ * The attributes that tell similar elements apart (form fields especially).
+ *
+ * @param attributes - Element attributes
+ * @returns id, name and type when present
+ */
+function identifyingAttributes(attributes) {
+    return {
+        ...(attributes['id'] && { id: attributes['id'] }),
+        ...(attributes['name'] && { name: attributes['name'] }),
+        ...(attributes['type'] && { type: attributes['type'] }),
+    };
+}
+/**
+ * The text of one element as the page renders it ({@link ELEMENT_TEXT_JS}).
+ *
+ * @param ref - Node reference
+ * @returns Element text, or empty when the node cannot be read
+ */
+async function elementText(ref) {
+    const objectGroup = `bdg-text-${process.pid}-${++queryCount}`;
+    const resolved = await callCDP('DOM.resolveNode', { ...ref, objectGroup });
+    const objectId = resolved.data?.result?.object
+        .objectId;
+    if (!objectId)
+        return '';
+    try {
+        const response = await callCDP('Runtime.callFunctionOn', {
+            objectId,
+            functionDeclaration: `function () { return (${ELEMENT_TEXT_JS})(this); }`,
+            returnByValue: true,
+        });
+        const value = response.data?.result?.result
+            ?.value;
+        return typeof value === 'string' ? value : '';
+    }
+    finally {
+        await callCDP('Runtime.releaseObjectGroup', { objectGroup });
+    }
+}
+/**
+ * Get DOM context (tag, classes, text preview) for a node.
+ *
+ * @param ref - Node reference
+ * @returns DOM context, or null if the node does not exist
+ */
+export async function getDomContext(ref) {
+    await callCDP('DOM.enable', {});
+    const desc = await describeNode(ref);
+    if (!desc) {
+        log.debug(`No DOM context for ${JSON.stringify(ref)}`);
+        return null;
+    }
+    const classes = unpackAttributes(desc.attributes)['class']?.split(/\s+/).filter(Boolean);
+    const preview = textPreview(await elementText(ref));
+    return {
+        tag: desc.nodeName.toLowerCase(),
+        ...(classes && classes.length > 0 && { classes }),
+        ...(preview && { preview }),
+    };
+}
+/**
+ * Pick the nodes `dom get --raw` should report for a selector.
+ *
+ * @param selector - CSS selector
+ * @param options - `nth` / `all` options
+ * @returns Node references to describe
+ */
+async function selectForGet(selector, options) {
+    const backendNodeIds = await selectAll(selector);
+    if (backendNodeIds.length === 0) {
+        const err = noNodesFoundError(selector);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+    }
+    if (options.all)
+        return backendNodeIds.map((backendNodeId) => ({ backendNodeId }));
+    const position = options.nth ?? 0;
+    const backendNodeId = backendNodeIds[position];
+    if (backendNodeId === undefined) {
+        const err = indexOutOfRangeError(position, backendNodeIds.length - 1);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    return [{ backendNodeId }];
+}
+/**
+ * Get full details (attributes, outer HTML) for `bdg dom get --raw`.
+ *
+ * @param options - Selector (with nth/all) or a backend node id
+ * @returns Node details; `nodeId` is the backend node id
+ * @throws CommandError (83) when a node id does not exist
+ */
+export async function getDOMElements(options) {
+    let refs;
+    if (options.nodeId !== undefined) {
+        await callCDP('DOM.enable', {});
+        await assertNodeAttached(options.nodeId).catch(() => {
+            const err = nodeIdNotFoundError(options.nodeId ?? 0);
+            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+        });
+        refs = [{ backendNodeId: options.nodeId }];
+    }
+    else if (options.selector) {
+        refs = await selectForGet(options.selector, options);
+    }
+    else {
+        const err = eitherArgumentRequiredError('selector', 'nodeId', 'bdg dom get <selector> or bdg dom get --node-id <id>');
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    const nodes = await mapConcurrently(refs, async (ref) => {
+        const desc = await describeNode(ref);
+        if (!desc) {
+            const err = nodeIdNotFoundError(options.nodeId ?? 0);
+            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+        }
+        const attributes = unpackAttributes(desc.attributes);
+        const classes = attributes['class']?.split(/\s+/).filter(Boolean);
+        const outerHTML = await getOuterHTML(ref);
+        return {
+            nodeId: desc.backendNodeId,
+            tag: desc.nodeName.toLowerCase(),
+            ...(Object.keys(attributes).length > 0 && { attributes }),
+            ...(classes && { classes }),
+            ...(outerHTML && { outerHTML }),
+        };
+    });
+    return { nodes };
+}
+/**
+ * Resolve a selector to its first match.
+ *
+ * @param selector - CSS selector
+ * @returns Reference to the first matching node (valid within this command)
+ * @throws CommandError (83) when nothing matches
+ */
+export async function resolveSelector(selector) {
+    const backendNodeId = (await selectAll(selector))[0];
+    if (backendNodeId === undefined) {
+        const err = noNodesFoundError(selector);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+    }
+    return { backendNodeId };
+}
+/**
+ * Resolve selectors to backend node ids (first match each).
+ *
+ * @param selectors - CSS selectors
+ * @returns Backend node id per selector, or undefined when it matches nothing
+ */
+export async function resolveBackendNodeIds(selectors) {
+    return mapConcurrently(selectors, async (selector) => (await selectAll(selector))[0]);
+}
+/**
+ * Accessibility node of the first element matching a selector.
+ *
+ * @param selector - CSS selector
+ * @returns A11y node, or null when nothing matches or the node is not exposed
+ */
+export async function resolveA11yNodeForSelector(selector) {
+    const [backendNodeId] = await resolveBackendNodeIds([selector]);
+    return backendNodeId === undefined ? null : resolveA11yNode({ backendNodeId });
+}
+/**
+ * Check that a cached element is still part of the current page.
+ *
+ * `DOM.describeNode` still answers for nodes of a previous document, so
+ * existence is checked by resolving the node into the page's JavaScript
+ * context, which fails for other documents, and by `isConnected`, which is
+ * false for removed elements.
+ *
+ * @param backendNodeId - Backend node id from the query cache
+ * @param index - Index the user gave, for the error message
+ * @throws CommandError (87) when the element is gone
+ */
+export async function assertNodeAttached(backendNodeId, index) {
+    const resolved = await callCDP('DOM.resolveNode', { backendNodeId, objectGroup: 'bdg-check' });
+    const objectId = resolved.data?.result?.object
+        .objectId;
+    let attached = false;
+    if (resolved.status !== 'error' && objectId) {
+        const check = await callCDP('Runtime.callFunctionOn', {
+            objectId,
+            functionDeclaration: 'function () { return this.isConnected; }',
+            returnByValue: true,
+        });
+        attached =
+            check.data?.result?.result?.value === true;
+        await callCDP('Runtime.releaseObjectGroup', { objectGroup: 'bdg-check' });
+    }
+    if (!attached) {
+        const err = staleNodeError(index);
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
+    }
+}
+//# sourceMappingURL=query.js.map

package/dist/commands/dom/helpers/runElementCommand.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Shared helper for DOM element commands (fill, click, submit, pressKey).
+ *
+ * Captures the common flow: resolve selector/index → call IPC → normalize errors.
+ * Keeps individual command handlers focused on option wiring and output formatting.
+ */
+interface IpcResponse<T> {
+    status: string;
+    data?: T;
+    error?: string;
+    exitCode?: number;
+    suggestion?: string;
+}
+interface ResultPayload {
+    success: boolean;
+    error?: string | undefined;
+    suggestion?: string | undefined;
+    exitCode?: number | undefined;
+}
+interface CommandResult<T> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    exitCode?: number;
+    errorContext?: {
+        suggestion: string;
+    };
+}
+/**
+ * Options for running a DOM element command.
+ */
+export interface ElementCommandOptions<Req, Res extends ResultPayload> {
+    /** Raw selector or numeric index string from CLI args. */
+    selectorOrIndex: string;
+    /** Optional --index flag value. */
+    index: number | undefined;
+    /** Build the IPC request params given the resolved selector + index. */
+    buildRequest: (target: {
+        selector: string;
+        index?: number;
+        backendNodeId?: number;
+    }) => Req;
+    /** Invoke the IPC client function. */
+    call: (req: Req) => Promise<IpcResponse<Res>>;
+    /** Operation label used in fallback error messages (e.g. "fill element"). */
+    action: string;
+    /** Fallback suggestion when the result reports failure without one. */
+    failureSuggestion: string;
+}
+/**
+ * Resolve an element target, invoke the IPC call, and normalize failures
+ * into the structured `CommandRunner` result shape.
+ */
+export declare function runElementCommand<Req, Res extends ResultPayload>(options: ElementCommandOptions<Req, Res>): Promise<CommandResult<Omit<Res, 'success'>>>;
+export {};
+//# sourceMappingURL=runElementCommand.d.ts.map

package/dist/commands/dom/helpers/runElementCommand.js

@@ -0,0 +1,63 @@
+/**
+ * Shared helper for DOM element commands (fill, click, submit, pressKey).
+ *
+ * Captures the common flow: resolve selector/index → call IPC → normalize errors.
+ * Keeps individual command handlers focused on option wiring and output formatting.
+ */
+import { DomElementResolver } from '../DomElementResolver.js';
+import { UNREACHABLE_ELEMENTS_HINT, staleNodeError } from '../../../errors/messages.js';
+import { EXIT_CODES } from '../../../utils/exitCodes.js';
+/**
+ * Resolve an element target, invoke the IPC call, and normalize failures
+ * into the structured `CommandRunner` result shape.
+ */
+export async function runElementCommand(options) {
+    const { selectorOrIndex, index, buildRequest, call, action, failureSuggestion } = options;
+    const target = await DomElementResolver.getInstance().resolve(selectorOrIndex, index);
+    if (!target.success) {
+        return {
+            success: false,
+            error: target.error ?? 'Failed to resolve element target',
+            exitCode: target.exitCode ?? EXIT_CODES.INVALID_ARGUMENTS,
+            ...(target.suggestion && { errorContext: { suggestion: target.suggestion } }),
+        };
+    }
+    const request = buildRequest({
+        selector: target.selector,
+        ...(target.index !== undefined && { index: target.index }),
+        ...(target.backendNodeId !== undefined && { backendNodeId: target.backendNodeId }),
+    });
+    const response = await call(request);
+    if (response.status === 'error' || !response.data) {
+        const staleIndex = response.exitCode === EXIT_CODES.STALE_CACHE && /^\d+$/.test(selectorOrIndex)
+            ? staleNodeError(Number(selectorOrIndex)).message
+            : undefined;
+        return {
+            success: false,
+            error: staleIndex ?? response.error ?? `Failed to ${action}`,
+            exitCode: response.exitCode ?? EXIT_CODES.INVALID_ARGUMENTS,
+            ...(response.suggestion && { errorContext: { suggestion: response.suggestion } }),
+        };
+    }
+    const result = response.data;
+    if (!result.success) {
+        const exitCode = result.exitCode ??
+            (result.error?.includes('not found')
+                ? EXIT_CODES.RESOURCE_NOT_FOUND
+                : EXIT_CODES.INVALID_ARGUMENTS);
+        const suggestion = result.suggestion ?? failureSuggestion;
+        return {
+            success: false,
+            error: result.error ?? `Failed to ${action}`,
+            exitCode,
+            errorContext: {
+                suggestion: exitCode === EXIT_CODES.RESOURCE_NOT_FOUND
+                    ? `${suggestion} (${UNREACHABLE_ELEMENTS_HINT})`
+                    : suggestion,
+            },
+        };
+    }
+    const { success: _success, ...data } = result;
+    return { success: true, data };
+}
+//# sourceMappingURL=runElementCommand.js.map

package/dist/commands/dom/helpers/screenshot.d.ts

@@ -0,0 +1,30 @@
+/**
+ * CDP-relay helpers for screenshot capture.
+ *
+ * Covers page, element, and element-bounds operations plus the scroll-into-
+ * view primitives used by page screenshots with `--scroll`.
+ */
+import type { ScreenshotResult, ScreenshotOptions, ElementBounds, NodeRef } from '../../../types.js';
+/**
+ * Get the bounding box (border box, so padding and border are included) of an
+ * element via CDP DOM.getBoxModel.
+ *
+ * @param ref - Node reference
+ * @returns Element bounds in CSS pixels
+ */
+export declare function getElementBounds(ref: NodeRef): Promise<ElementBounds>;
+/**
+ * Capture a screenshot of the page. Auto-resizes oversized pages by default
+ * to keep Claude Vision token cost bounded; falls back to viewport capture
+ * when the page is taller than the tall-page threshold.
+ */
+export declare function capturePageScreenshot(outputPath: string, options?: ScreenshotOptions): Promise<ScreenshotResult>;
+/**
+ * Capture a screenshot of a single element, clipped to its bounding box.
+ */
+export declare function captureElementScreenshot(outputPath: string, ref: NodeRef, options?: {
+    format?: 'png' | 'jpeg';
+    quality?: number;
+    noResize?: boolean;
+}): Promise<ScreenshotResult>;
+//# sourceMappingURL=screenshot.d.ts.map