browser-debugger-cli 0.7.1 → 0.8.0

package/dist/commands/dom/frames.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `bdg dom frames` — list the page's iframes (the values `dom eval --frame` accepts).
+ *
+ * CLI-side handler. Frames are discovered in the daemon via the `dom_frames`
+ * IPC command, out-of-process (cross-site) ones included.
+ */
+import type { DomFramesCommandOptions } from '../shared/optionTypes.js';
+/**
+ * Handle `bdg dom frames`.
+ */
+export declare function handleDomFrames(options: DomFramesCommandOptions): Promise<void>;
+//# sourceMappingURL=frames.d.ts.map

package/dist/commands/dom/frames.js

@@ -0,0 +1,28 @@
+/**
+ * `bdg dom frames` — list the page's iframes (the values `dom eval --frame` accepts).
+ *
+ * CLI-side handler. Frames are discovered in the daemon via the `dom_frames`
+ * IPC command, out-of-process (cross-site) ones included.
+ */
+import { runCommand } from '../shared/CommandRunner.js';
+import { domFrames } from '../../ipc/client.js';
+import { formatDomFrames } from '../../ui/formatters/dom.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+/**
+ * Handle `bdg dom frames`.
+ */
+export async function handleDomFrames(options) {
+    await runCommand(async () => {
+        const response = await domFrames();
+        if (response.status === 'error' || !response.data) {
+            return {
+                success: false,
+                error: response.error ?? 'Failed to list frames',
+                exitCode: response.exitCode ?? EXIT_CODES.CDP_CONNECTION_FAILURE,
+                ...(response.suggestion && { errorContext: { suggestion: response.suggestion } }),
+            };
+        }
+        return { success: true, data: { frames: response.data.frames } };
+    }, options, formatDomFrames);
+}
+//# sourceMappingURL=frames.js.map

package/dist/commands/dom/get.d.ts

@@ -0,0 +1,20 @@
+/**
+ * `bdg dom get` — retrieve element details by selector or cached index.
+ *
+ * Two output modes:
+ * - Semantic (default): a11y role + name + DOM context
+ * - Raw: full HTML, attributes, and classes
+ */
+import type { DomGetCommandOptions } from '../shared/optionTypes.js';
+/**
+ * Handle `bdg dom get [selectorOrIndex] [--node-id <id>]`.
+ *
+ * `--node-id` reads that node directly (raw output); otherwise dispatches to
+ * the selector or index handler based on whether the argument parses as a
+ * numeric index.
+ *
+ * @param selectorOrIndex - CSS selector or cached index (optional with --node-id)
+ * @param options - Command options
+ */
+export declare function handleDomGet(selectorOrIndex: string | undefined, options: DomGetCommandOptions): Promise<void>;
+//# sourceMappingURL=get.d.ts.map

package/dist/commands/dom/get.js

@@ -0,0 +1,141 @@
+/**
+ * `bdg dom get` — retrieve element details by selector or cached index.
+ *
+ * Two output modes:
+ * - Semantic (default): a11y role + name + DOM context
+ * - Raw: full HTML, attributes, and classes
+ */
+import { DomElementResolver } from './DomElementResolver.js';
+import { getDOMElements, getDomContext, resolveA11yNodeForSelector, } from './helpers/index.js';
+import { formatSemanticNodeWithContext, queryDomContextBySelector, resolveNodeWithFallback, } from './semanticUtils.js';
+import { runCommand } from '../shared/CommandRunner.js';
+import { CommandError } from '../../errors/index.js';
+import { elementAtIndexNotFoundError, conflictingOptionsMessage, optionRequiresMessage, missingArgumentError, noNodesFoundError, } from '../../errors/messages.js';
+import { resolveA11yNode } from '../../telemetry/a11y.js';
+import { formatDomGet } from '../../ui/formatters/dom.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { filterDefined } from '../../utils/objects.js';
+async function handleIndexGetRaw(index, options) {
+    const resolver = DomElementResolver.getInstance();
+    await runCommand(async () => {
+        const targetNode = await resolver.getNodeIdForIndex(index);
+        const getOptions = filterDefined({ nodeId: targetNode.nodeId });
+        const result = await getDOMElements(getOptions);
+        return { success: true, data: result };
+    }, options, formatDomGet);
+}
+async function handleIndexGetSemantic(index, options) {
+    const resolver = DomElementResolver.getInstance();
+    await runCommand(async () => {
+        const targetNode = await resolver.getNodeIdForIndex(index);
+        const ref = { backendNodeId: targetNode.nodeId };
+        const [a11yNode, domContext] = await Promise.all([resolveA11yNode(ref), getDomContext(ref)]);
+        const node = resolveNodeWithFallback(a11yNode, domContext, targetNode.nodeId);
+        if (!node) {
+            const err = elementAtIndexNotFoundError(index, 'cached query');
+            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+        }
+        return { success: true, data: { node, domContext } };
+    }, options, formatSemanticNodeWithContext);
+}
+async function handleIndexGet(index, options) {
+    if (options.raw) {
+        await handleIndexGetRaw(index, options);
+    }
+    else {
+        await handleIndexGetSemantic(index, options);
+    }
+}
+async function handleSelectorGetRaw(selector, options) {
+    await runCommand(async () => {
+        const getOptions = filterDefined({
+            selector,
+            all: options.all,
+            nth: options.nth,
+        });
+        const result = await getDOMElements(getOptions);
+        return { success: true, data: result };
+    }, options, formatDomGet);
+}
+async function handleSelectorGetSemantic(selector, options) {
+    await runCommand(async () => {
+        const a11yNode = await resolveA11yNodeForSelector(selector);
+        let domContext = null;
+        let nodeId;
+        if (a11yNode?.backendDOMNodeId) {
+            nodeId = a11yNode.backendDOMNodeId;
+            domContext = await getDomContext({ backendNodeId: nodeId });
+        }
+        else if (!a11yNode) {
+            const queryResult = await queryDomContextBySelector(selector);
+            nodeId = queryResult.nodeId;
+            domContext = queryResult.domContext;
+        }
+        const node = resolveNodeWithFallback(a11yNode, domContext, nodeId);
+        if (!node) {
+            const err = noNodesFoundError(selector);
+            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.RESOURCE_NOT_FOUND);
+        }
+        return { success: true, data: { node, domContext } };
+    }, options, formatSemanticNodeWithContext);
+}
+async function handleSelectorGet(selector, options) {
+    if (options.raw) {
+        await handleSelectorGetRaw(selector, options);
+    }
+    else {
+        await handleSelectorGetSemantic(selector, options);
+    }
+}
+/**
+ * Options of `dom get` that cannot be combined (one would be ignored).
+ *
+ * @param selectorOrIndex - Selector or index argument
+ * @param options - Command options
+ * @returns What conflicts, or null
+ */
+function getOptionsConflict(selectorOrIndex, options) {
+    if (options.nodeId !== undefined && selectorOrIndex !== undefined) {
+        return conflictingOptionsMessage('--node-id', 'a selector or index');
+    }
+    if (options.all && options.nth !== undefined) {
+        return conflictingOptionsMessage('--all', '--nth');
+    }
+    if (!options.raw && (options.all || options.nth !== undefined)) {
+        return optionRequiresMessage(options.all ? '--all' : '--nth', '--raw');
+    }
+    return null;
+}
+/**
+ * Handle `bdg dom get [selectorOrIndex] [--node-id <id>]`.
+ *
+ * `--node-id` reads that node directly (raw output); otherwise dispatches to
+ * the selector or index handler based on whether the argument parses as a
+ * numeric index.
+ *
+ * @param selectorOrIndex - CSS selector or cached index (optional with --node-id)
+ * @param options - Command options
+ */
+export async function handleDomGet(selectorOrIndex, options) {
+    const conflict = getOptionsConflict(selectorOrIndex, options);
+    if (conflict) {
+        throw new CommandError(conflict, {}, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    const { nodeId } = options;
+    if (nodeId !== undefined) {
+        await runCommand(async () => ({ success: true, data: await getDOMElements({ nodeId }) }), options, formatDomGet);
+        return;
+    }
+    if (selectorOrIndex === undefined) {
+        const err = missingArgumentError('bdg dom get <selector|index> or bdg dom get --node-id <id>');
+        throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.INVALID_ARGUMENTS);
+    }
+    const isNumericIndex = /^\d+$/.test(selectorOrIndex);
+    if (isNumericIndex) {
+        await handleIndexGet(parseInt(selectorOrIndex, 10), options);
+    }
+    else {
+        await handleSelectorGet(selectorOrIndex, options);
+    }
+}
+//# sourceMappingURL=get.js.map

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

@@ -0,0 +1,11 @@
+/**
+ * DOM helpers using CDP relay pattern. Barrel re-exports the split modules
+ * so callers can keep importing from `@/commands/dom/helpers.js`.
+ *
+ * - `query.ts`      — selector → backend node ids (shadow roots, same-origin iframes), DOM.describeNode
+ * - `screenshot.ts` — page / element capture, element bounds, scroll helpers
+ */
+export { queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, resolveA11yNodeForSelector, assertNodeAttached, } from './query.js';
+export { capturePageScreenshot, captureElementScreenshot, getElementBounds, } from './screenshot.js';
+export type { DomQueryResult, DomGetResult, ScreenshotResult, DomGetOptions, ScreenshotOptions, DomContext, ElementBounds, } from '../../../types.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,10 @@
+/**
+ * DOM helpers using CDP relay pattern. Barrel re-exports the split modules
+ * so callers can keep importing from `@/commands/dom/helpers.js`.
+ *
+ * - `query.ts`      — selector → backend node ids (shadow roots, same-origin iframes), DOM.describeNode
+ * - `screenshot.ts` — page / element capture, element bounds, scroll helpers
+ */
+export { queryDOMElements, getDomContext, getDOMElements, resolveSelector, resolveBackendNodeIds, resolveA11yNodeForSelector, assertNodeAttached, } from './query.js';
+export { capturePageScreenshot, captureElementScreenshot, getElementBounds, } from './screenshot.js';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,78 @@
+/**
+ * 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 type { A11yNode, DomQueryResult, DomGetResult, DomGetOptions, DomContext, NodeRef } from '../../../types.js';
+/**
+ * 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 declare function textPreview(text: string): string;
+/**
+ * Query elements by selector for `bdg dom query`.
+ *
+ * @param selector - CSS selector
+ * @returns Matches with backend node ids, tags, classes and text previews
+ */
+export declare function queryDOMElements(selector: string): Promise<DomQueryResult>;
+/**
+ * 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 declare function getDomContext(ref: NodeRef): Promise<DomContext | null>;
+/**
+ * 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 declare function getDOMElements(options: DomGetOptions): Promise<DomGetResult>;
+/**
+ * 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 declare function resolveSelector(selector: string): Promise<NodeRef>;
+/**
+ * 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 declare function resolveBackendNodeIds(selectors: string[]): Promise<(number | undefined)[]>;
+/**
+ * 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 declare function resolveA11yNodeForSelector(selector: string): Promise<A11yNode | null>;
+/**
+ * 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 declare function assertNodeAttached(backendNodeId: number, index?: number): Promise<void>;
+//# sourceMappingURL=query.d.ts.map