browser-debugger-cli 0.8.0 → 0.9.0

package/dist/commands/dom/DomElementResolver.js

@@ -11,17 +11,17 @@
  * ```typescript
  * const resolver = DomElementResolver.getInstance();
  *
- * const target = await resolver.resolve('0');
+ * const target = await resolver.resolve('0', undefined, 'click');
  * // { success: true, selector: '.cached-selector', backendNodeId: 42 }
  *
- * const target = await resolver.resolve('button.submit');
+ * const target = await resolver.resolve('button.submit', undefined, 'click');
  * // { success: true, selector: 'button.submit' }
  * ```
  */
 import { noActiveSessionError } from '../shared/CommandRunner.js';
 import { CommandError } from '../../errors/index.js';
-import { indexOutOfRangeError, indexWithIndexOptionError, staleNodeError, } from '../../errors/messages.js';
-import { QueryCacheManager } from '../../session/QueryCacheManager.js';
+import { cachedIndexOutOfRangeError, indexWithIndexOptionError, staleNodeError, } from '../../errors/messages.js';
+import { QueryCacheManager, indexSourceOf, } from '../../session/QueryCacheManager.js';
 import { isDaemonAlive } from '../../session/daemonSocket.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /**
@@ -58,14 +58,15 @@ export class DomElementResolver {
      *
      * @param selectorOrIndex - CSS selector or numeric index from query results
      * @param explicitIndex - Optional explicit --index flag value (0-based, selectors only)
+     * @param command - `bdg dom` subcommand being run, e.g. "click" (for suggestions)
      * @returns Resolution result
      */
-    async resolve(selectorOrIndex, explicitIndex) {
+    async resolve(selectorOrIndex, explicitIndex, command) {
         if (!this.isNumericIndex(selectorOrIndex)) {
             return { success: true, selector: selectorOrIndex, index: explicitIndex };
         }
         if (explicitIndex !== undefined) {
-            const err = indexWithIndexOptionError(selectorOrIndex);
+            const err = indexWithIndexOptionError(selectorOrIndex, command);
             return {
                 success: false,
                 error: err.message,
@@ -74,10 +75,9 @@ export class DomElementResolver {
             };
         }
         try {
-            const index = parseInt(selectorOrIndex, 10);
-            const { node, selector } = await this.lookup(index);
+            const { node, selector, source } = await this.lookup(parseInt(selectorOrIndex, 10));
             if (node.nodeId <= 0) {
-                const err = staleNodeError(index);
+                const err = staleNodeError(source.index, source);
                 return {
                     success: false,
                     error: err.message,
@@ -85,7 +85,13 @@ export class DomElementResolver {
                     suggestion: err.suggestion,
                 };
             }
-            return { success: true, selector: node.selector ?? selector, backendNodeId: node.nodeId };
+            return {
+                success: true,
+                selector: node.selector ?? selector,
+                backendNodeId: node.nodeId,
+                source,
+                preview: cachedNodePreview(node),
+            };
         }
         catch (error) {
             if (!(error instanceof CommandError))
@@ -107,14 +113,14 @@ export class DomElementResolver {
      *   or the element is no longer in the page (87)
      */
     async getNodeIdForIndex(index) {
-        const { node } = await this.lookup(index);
+        const { node, source } = await this.lookup(index);
         if (node.nodeId <= 0) {
-            const err = staleNodeError(index);
+            const err = staleNodeError(index, source);
             throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
         }
         const { assertNodeAttached } = await import('./helpers/index.js');
-        await assertNodeAttached(node.nodeId, index);
-        return node;
+        await assertNodeAttached(node.nodeId, source);
+        return { nodeId: node.nodeId, source };
     }
     /**
      * Check if the argument is a numeric index.
@@ -140,12 +146,24 @@ export class DomElementResolver {
             throw new CommandError(validation.error ?? 'No cached query results found', validation.suggestion ? { suggestion: validation.suggestion } : {}, EXIT_CODES.INVALID_ARGUMENTS);
         }
         const { nodes, selector } = validation.cache;
+        const source = indexSourceOf(index, selector);
         const node = nodes.find((n) => n.index === index);
         if (!node) {
-            const err = indexOutOfRangeError(index, nodes.length - 1);
-            throw new CommandError(`${err.message} in the last query ("${selector}")`, { suggestion: nodes.length > 0 ? err.suggestion : 'Re-run the query' }, EXIT_CODES.STALE_CACHE);
+            const err = cachedIndexOutOfRangeError(source, nodes.length);
+            throw new CommandError(err.message, { suggestion: err.suggestion }, EXIT_CODES.STALE_CACHE);
         }
-        return { node, selector };
+        return { node, selector, source };
     }
 }
+/**
+ * What a cached element was when it was listed.
+ *
+ * @param node - Cached node
+ * @returns e.g. `h3 "Welcome"`, `button`; undefined without a tag
+ */
+function cachedNodePreview(node) {
+    if (!node.tag)
+        return undefined;
+    return node.preview ? `${node.tag} "${node.preview}"` : node.tag;
+}
 //# sourceMappingURL=DomElementResolver.js.map

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

@@ -9,6 +9,16 @@
  * Uses IPC/callCDP pattern for consistency with other DOM commands.
  */
 import type { Command } from 'commander';
+import type { A11yQueryResult } from '../../types.js';
+/**
+ * The matches to list: the first `limit` (all with 0), counting the rest as
+ * omitted. All of them are cached, so their indices work either way.
+ *
+ * @param result - Query result
+ * @param limit - Matches to list (0 = all)
+ * @returns The result with the listed matches
+ */
+export declare function limitMatches(result: A11yQueryResult, limit: number): A11yQueryResult;
 /**
  * Register accessibility commands under 'bdg dom a11y'
  *

package/dist/commands/dom/a11y.js

@@ -12,12 +12,15 @@ import { DomElementResolver } from './DomElementResolver.js';
 import { getDomContext, resolveBackendNodeIds } from './helpers/index.js';
 import { runCommand, runJsonCommand } from '../shared/CommandRunner.js';
 import { jsonOption } from '../shared/commonOptions.js';
+import { integerOption } from '../shared/validation.js';
 import { CommandError } from '../../errors/index.js';
 import { elementNotFoundError, invalidQueryPatternError, noA11yNodesFoundError, notInAccessibilityTreeError, } from '../../errors/messages.js';
-import { QueryCacheManager } from '../../session/QueryCacheManager.js';
+import { A11Y_CACHE_SELECTOR_PREFIX, QueryCacheManager } from '../../session/QueryCacheManager.js';
 import { a11yIgnoredReasons, collectA11yTree, queryA11yTree, parseQueryPattern, resolveA11yNode, } from '../../telemetry/a11y.js';
 import { formatA11yTree, formatA11yQueryResult, formatA11yNodeWithContext, } from '../../ui/formatters/a11y.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
+/** Matches `dom a11y query` lists by default in human output (a page can have hundreds of links; JSON lists all) */
+const A11Y_QUERY_LIMIT = 50;
 /**
  * Handle bdg dom a11y tree command
  *
@@ -61,7 +64,8 @@ function quoteQueryValue(text) {
  * Handle bdg dom a11y query <pattern> command
  *
  * Queries the accessibility tree using role/name/description patterns via IPC.
- * Pattern format: "role:button name:Submit" (space-separated key:value pairs)
+ * Pattern format: "role:button name:Submit" (key:value or key=value pairs; a
+ * name or description may contain spaces and colons)
  *
  * @param pattern - Query pattern string
  * @param options - Command options
@@ -88,17 +92,34 @@ async function handleA11yQuery(pattern, options) {
         }
         const indexed = { ...result, nodes: result.nodes.map((node, index) => ({ ...node, index })) };
         await QueryCacheManager.getInstance().set({
-            selector: `a11y ${pattern}`,
+            selector: `${A11Y_CACHE_SELECTOR_PREFIX}${pattern}`,
             count: indexed.count,
             nodes: indexed.nodes.map((node) => ({
                 index: node.index,
                 nodeId: node.backendDOMNodeId ?? 0,
                 tag: node.role,
+                ...(node.name && { preview: node.name }),
             })),
         });
-        return { success: true, data: indexed };
+        return {
+            success: true,
+            data: limitMatches(indexed, options.limit ?? (options.json ? 0 : A11Y_QUERY_LIMIT)),
+        };
     }, options, formatA11yQueryResult);
 }
+/**
+ * The matches to list: the first `limit` (all with 0), counting the rest as
+ * omitted. All of them are cached, so their indices work either way.
+ *
+ * @param result - Query result
+ * @param limit - Matches to list (0 = all)
+ * @returns The result with the listed matches
+ */
+export function limitMatches(result, limit) {
+    if (limit === 0 || result.nodes.length <= limit)
+        return result;
+    return { ...result, nodes: result.nodes.slice(0, limit), omitted: result.nodes.length - limit };
+}
 /**
  * Handle bdg dom a11y describe <selectorOrIndex> command
  *
@@ -192,7 +213,8 @@ export function registerA11yCommands(domCmd) {
     a11y
         .command('query')
         .description('Query elements by accessibility properties (e.g., "role:button", "name:Submit")')
-        .argument('<pattern>', 'Fields role, name, description as key:value or key=value, separated by spaces or commas; * is a wildcard (e.g. "role:button name:Submit", "role=link,name=Google Chrome")')
+        .argument('<pattern>', "Fields role, name, description as key:value or key=value, separated by spaces or commas; * is a wildcard. A name or description runs to the next field or the end, so it may contain spaces and colons; quote the whole pattern (e.g. 'role=button name=Sign in', 'name=E-mail address:')")
+        .option('--limit <n>', `Matches to list (default: ${A11Y_QUERY_LIMIT}, all with --json; 0 = all); all are indexed`, integerOption(0))
         .addOption(jsonOption())
         .action(async (pattern, options) => {
         await handleA11yQuery(pattern, options);

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

@@ -7,7 +7,9 @@
  */
 import type { DomEvalCommandOptions } from '../shared/optionTypes.js';
 /**
- * Handle `bdg dom eval <script> [--frame <frame>]`.
+ * Handle `bdg dom eval <script> [--frame <frame>]`. With `--frame`, the
+ * frame the script ran in is a `Frame:` line on stderr (JSON: `frame`), so
+ * stdout stays the bare value for pipes.
  */
 export declare function handleDomEval(script: string, options: DomEvalCommandOptions): Promise<void>;
 //# sourceMappingURL=eval.d.ts.map

package/dist/commands/dom/eval.js

@@ -5,13 +5,17 @@
  * CLI-side handler. Actual evaluation happens in the daemon via the
  * `dom_eval` IPC command so the session's persistent CDP connection is reused.
  */
+import { documentReadyState } from './helpers/query.js';
 import { runCommand } from '../shared/CommandRunner.js';
-import { emptyScriptError } from '../../errors/messages.js';
+import { emptyScriptError, withLoadingHint } from '../../errors/messages.js';
 import { domEval } from '../../ipc/client.js';
 import { formatDomEval } from '../../ui/formatters/dom.js';
+import { evalFrameLine } from '../../ui/messages/commands.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 /**
- * Handle `bdg dom eval <script> [--frame <frame>]`.
+ * Handle `bdg dom eval <script> [--frame <frame>]`. With `--frame`, the
+ * frame the script ran in is a `Frame:` line on stderr (JSON: `frame`), so
+ * stdout stays the bare value for pipes.
  */
 export async function handleDomEval(script, options) {
     await runCommand(async () => {
@@ -26,18 +30,39 @@ export async function handleDomEval(script, options) {
         }
         const response = await domEval(script, options.frame);
         if (response.status === 'error' || !response.data) {
+            const suggestion = await frameErrorSuggestion(response, options.frame);
             return {
                 success: false,
                 error: response.error ?? 'Failed to evaluate script',
                 exitCode: response.exitCode ?? EXIT_CODES.CDP_CONNECTION_FAILURE,
-                ...(response.suggestion && { errorContext: { suggestion: response.suggestion } }),
+                ...(suggestion && { errorContext: { suggestion } }),
             };
         }
         const { value, type, subtype, frame } = response.data;
         return {
             success: true,
-            data: { result: value, type, ...(subtype && { subtype }), ...(frame && { frame }) },
+            data: {
+                result: value,
+                type,
+                ...(subtype && { subtype }),
+                ...(frame !== undefined && { frame }),
+            },
+            ...(frame !== undefined && !options.json && { hint: evalFrameLine(frame) }),
         };
     }, options, formatDomEval);
 }
+/**
+ * Suggestion of a failed eval; a frame not found (83) while the page is
+ * still loading says so (its iframes may not exist yet).
+ *
+ * @param response - Error response
+ * @param frame - The --frame given, if any
+ * @returns Suggestion, if any
+ */
+async function frameErrorSuggestion(response, frame) {
+    if (frame === undefined || response.exitCode !== EXIT_CODES.RESOURCE_NOT_FOUND) {
+        return response.suggestion;
+    }
+    return withLoadingHint(response.suggestion ?? '', await documentReadyState()) || undefined;
+}
 //# sourceMappingURL=eval.js.map

package/dist/commands/dom/form.js

@@ -4,6 +4,7 @@
  * Discovers forms on the page with semantic labels, current values,
  * validation state, and suggested commands for agent consumption.
  */
+import { calculateSummary, orderForms, primaryButtonIndex } from './formSummary.js';
 import { resolveBackendNodeIds } from './helpers/index.js';
 import { runCommand } from '../shared/CommandRunner.js';
 import { jsonOption } from '../shared/commonOptions.js';
@@ -177,6 +178,7 @@ function transformField(raw) {
         name: raw.name,
         placeholder: raw.placeholder,
         required: raw.required,
+        groupLabel: raw.groupLabel,
         disabled: raw.disabled,
         readOnly: raw.readOnly,
         hidden: raw.hidden,
@@ -195,76 +197,21 @@ function transformField(raw) {
  * Transform raw button to structured FormButton.
  *
  * @param raw - Raw button data
+ * @param primaryIndex - Index of the form's primary button, if any
  * @returns Structured FormButton
  */
-function transformButton(raw) {
+function transformButton(raw, primaryIndex) {
     return {
         index: raw.index,
         selector: raw.selector,
         label: raw.label,
         type: raw.type,
-        primary: raw.isPrimary,
+        primary: raw.index === primaryIndex,
         enabled: !raw.disabled,
         disabledReason: raw.disabled ? 'Button is disabled' : undefined,
         command: `bdg dom click ${raw.index}`,
     };
 }
-/**
- * Calculate form summary statistics.
- *
- * @param fields - Transformed form fields
- * @param buttons - Transformed form buttons
- * @returns Form summary
- */
-function calculateSummary(fields, buttons) {
-    const visibleFields = fields.filter((f) => !f.hidden);
-    const editableFields = visibleFields.filter((f) => !f.disabled && !f.readOnly);
-    const requiredFields = editableFields.filter((f) => f.required);
-    const filledFields = editableFields.filter((f) => f.state === 'filled' || f.state === 'checked');
-    const validFields = editableFields.filter((f) => f.validation.valid);
-    const invalidFields = editableFields.filter((f) => !f.validation.valid);
-    const emptyRequired = requiredFields.filter((f) => f.state === 'empty' || f.state === 'unchecked');
-    const blockers = [];
-    for (const field of emptyRequired) {
-        blockers.push({
-            index: field.index,
-            label: field.label,
-            reason: 'Required field is empty',
-            command: field.command,
-        });
-    }
-    for (const field of invalidFields) {
-        if (!emptyRequired.includes(field)) {
-            blockers.push({
-                index: field.index,
-                label: field.label,
-                reason: field.validation.message ?? 'Validation failed',
-                command: field.command,
-            });
-        }
-    }
-    const submitButton = buttons.find((b) => b.type === 'submit' && b.primary);
-    if (submitButton && !submitButton.enabled) {
-        blockers.push({
-            index: submitButton.index,
-            label: submitButton.label,
-            reason: submitButton.disabledReason ?? 'Submit button is disabled',
-            command: submitButton.command,
-        });
-    }
-    return {
-        totalFields: editableFields.length,
-        filledFields: filledFields.length,
-        emptyFields: editableFields.length - filledFields.length,
-        validFields: validFields.length,
-        invalidFields: invalidFields.length,
-        requiredTotal: requiredFields.length,
-        requiredFilled: requiredFields.length - emptyRequired.length,
-        requiredRemaining: emptyRequired.length,
-        readyToSubmit: blockers.length === 0,
-        blockers,
-    };
-}
 /**
  * Transform raw form to structured DiscoveredForm.
  *
@@ -273,7 +220,8 @@ function calculateSummary(fields, buttons) {
  */
 function transformForm(raw) {
     const fields = raw.fields.map(transformField);
-    const buttons = raw.buttons.map(transformButton);
+    const primaryIndex = primaryButtonIndex(raw.buttons);
+    const buttons = raw.buttons.map((button) => transformButton(button, primaryIndex));
     return {
         index: raw.index,
         name: raw.name,
@@ -281,6 +229,8 @@ function transformForm(raw) {
         method: raw.method,
         step: raw.step ?? undefined,
         relevanceScore: raw.relevanceScore,
+        hidden: raw.hidden === true,
+        inDialog: raw.inDialog === true,
         fields,
         buttons,
         summary: calculateSummary(fields, buttons),
@@ -340,7 +290,7 @@ async function handleFormCommand(options) {
             };
         }
         if (rawData.forms.length === 0) {
-            const err = noFormsFoundError();
+            const err = noFormsFoundError(rawData.readyState);
             return {
                 success: false,
                 error: err.message,
@@ -358,7 +308,7 @@ async function handleFormCommand(options) {
                 errorContext: { suggestion: err.suggestion },
             };
         }
-        const allForms = rawData.forms.map(transformForm);
+        const allForms = orderForms(rawData.forms).map(transformForm);
         const forms = options.all ? allForms : [allForms[0]];
         // Cache ALL forms so global indices work with bdg dom fill/click
         await cacheFormElements(allForms);
@@ -370,7 +320,11 @@ async function handleFormCommand(options) {
                 otherForms: allForms.slice(1).map((form) => ({
                     index: form.index,
                     name: form.name,
-                    fieldCount: form.fields.filter((field) => !field.hidden).length,
+                    fieldCount: form.hidden
+                        ? form.fields.length
+                        : form.fields.filter((field) => !field.hidden).length,
+                    hidden: form.hidden,
+                    inDialog: form.inDialog,
                 })),
             }),
             brief: options.brief,