browser-debugger-cli 0.12.0 → 0.14.0

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

@@ -9,7 +9,7 @@ import { writeOutputFile } from '../../shared/outputFile.js';
 import { CDPConnectionError } from '../../../connection/errors.js';
 import { CommandError } from '../../../errors/index.js';
 import { noNodesFoundError, elementNotVisibleError, elementZeroDimensionsError, } from '../../../errors/messages.js';
-import { callCDP } from '../../../ipc/client.js';
+import { callBdgScript, callCDP } from '../../../ipc/client.js';
 import { DEEP_QUERY_JS, selectorArgsJS } from '../../../runtime/dom/targetNode.js';
 import { viewportOverride } from '../../../runtime/page/emulation.js';
 import { readSessionMetadata } from '../../../session/metadata.js';
@@ -26,7 +26,7 @@ const STABILITY_CHECK_INTERVAL_MS = 50;
  */
 async function waitForPostScrollStability() {
     const deadline = Date.now() + POST_SCROLL_MAX_WAIT_MS;
-    await callCDP('Runtime.evaluate', {
+    await callBdgScript('Runtime.evaluate', {
         expression: `
       (() => {
         window.__bdg_scrollStability = {
@@ -66,7 +66,7 @@ async function waitForPostScrollStability() {
     });
     try {
         while (Date.now() < deadline) {
-            const checkResult = await callCDP('Runtime.evaluate', {
+            const checkResult = await callBdgScript('Runtime.evaluate', {
                 expression: `
           (() => {
             const state = window.__bdg_scrollStability;
@@ -91,7 +91,7 @@ async function waitForPostScrollStability() {
         log.debug('Post-scroll stability timeout, proceeding anyway');
     }
     finally {
-        await callCDP('Runtime.evaluate', {
+        await callBdgScript('Runtime.evaluate', {
             expression: `
         (() => {
           const state = window.__bdg_scrollStability;
@@ -111,7 +111,7 @@ async function waitForPostScrollStability() {
  * position so it can be restored afterwards.
  */
 async function scrollToElement(selector) {
-    const result = await callCDP('Runtime.evaluate', {
+    const result = await callBdgScript('Runtime.evaluate', {
         expression: `
       (() => {
         const el = (${DEEP_QUERY_JS})(${selectorArgsJS(selector)})[0];
@@ -133,7 +133,7 @@ async function scrollToElement(selector) {
     return { x: value.originalX ?? 0, y: value.originalY ?? 0 };
 }
 async function restoreScrollPosition(position) {
-    await callCDP('Runtime.evaluate', {
+    await callBdgScript('Runtime.evaluate', {
         expression: `window.scrollTo(${position.x}, ${position.y})`,
         returnByValue: true,
     });
@@ -147,7 +147,7 @@ async function restoreScrollPosition(position) {
  * @returns Width and height in CSS px
  */
 async function windowSize(viewport) {
-    const response = await callCDP('Runtime.evaluate', {
+    const response = await callBdgScript('Runtime.evaluate', {
         expression: '[window.innerWidth, window.innerHeight]',
         returnByValue: true,
     });
@@ -245,7 +245,7 @@ export async function capturePageScreenshot(outputPath, options = {}) {
     if (options.scroll) {
         originalScrollPosition = await scrollToElement(options.scroll);
     }
-    const dprResponse = await callCDP('Runtime.evaluate', {
+    const dprResponse = await callBdgScript('Runtime.evaluate', {
         expression: 'window.devicePixelRatio',
         returnByValue: true,
     });
@@ -266,7 +266,7 @@ export async function capturePageScreenshot(outputPath, options = {}) {
     const restoreMetrics = await useUnitPixelRatio(devicePixelRatio, viewport);
     if (devicePixelRatio !== 1) {
         if (options.scroll) {
-            await callCDP('Runtime.evaluate', {
+            await callBdgScript('Runtime.evaluate', {
                 expression: `(${DEEP_QUERY_JS})(${selectorArgsJS(options.scroll)})[0]?.scrollIntoView({ block: 'center', behavior: 'instant' })`,
                 returnByValue: true,
             });
@@ -461,7 +461,7 @@ async function measureInView(ref, padding) {
     const scrolledFrom = await scrollPosition();
     const dx = bounds.x + bounds.width / 2 - view.width / 2;
     const dy = bounds.y + bounds.height / 2 - view.height / 2;
-    await callCDP('Runtime.evaluate', { expression: `window.scrollBy(${dx}, ${dy})` });
+    await callBdgScript('Runtime.evaluate', { expression: `window.scrollBy(${dx}, ${dy})` });
     try {
         box = await getElementBounds(ref);
         bounds = await captureArea(ref, box, padding);
@@ -501,7 +501,7 @@ async function restoreViewport() {
  * @returns Scroll offsets in CSS px
  */
 async function scrollPosition() {
-    const response = await callCDP('Runtime.evaluate', {
+    const response = await callBdgScript('Runtime.evaluate', {
         expression: '[window.scrollX, window.scrollY]',
         returnByValue: true,
     });
@@ -544,7 +544,7 @@ async function captureArea(ref, bounds, padding) {
 async function paintedArea(ref, bounds) {
     const objectGroup = `bdg-shot-${process.pid}`;
     try {
-        const resolved = await callCDP('DOM.resolveNode', { ...ref, objectGroup });
+        const resolved = await callBdgScript('DOM.resolveNode', { ...ref, objectGroup });
         const objectId = resolved.data?.result?.object
             .objectId;
         if (!objectId)
@@ -586,7 +586,7 @@ export async function captureElementScreenshot(outputPath, ref, options = {}) {
     const format = options.format ?? 'png';
     const quality = format === 'jpeg' ? (options.quality ?? 90) : undefined;
     const noResize = options.noResize ?? false;
-    const dprResponse = await callCDP('Runtime.evaluate', {
+    const dprResponse = await callBdgScript('Runtime.evaluate', {
         expression: 'window.devicePixelRatio',
         returnByValue: true,
     });

package/dist/commands/dom/index.js

@@ -17,19 +17,23 @@
  */
 import { Option } from 'commander';
 import { registerA11yCommands } from './a11y.js';
+import { registerAuditCommand } from './audit.js';
 import { handleDomEval } from './eval.js';
 import { registerFormCommand } from './form.js';
 import { handleDomFrames } from './frames.js';
 import { DOM_GET_DEFAULT_SELECTOR, handleDomGet } from './get.js';
+import { QUERY_CACHE_LIMIT } from './helpers/query.js';
 import { registerInspectCommand } from './inspect.js';
-import { registerAuditCommand } from './audit.js';
 import { registerLayoutCommand } from './layout.js';
 import { registerListenersCommand } from './listeners.js';
-import { handleDomQuery } from './query.js';
+import { handleDomQuery, QUERY_LIST_LIMIT } from './query.js';
 import { handleDomScreenshot } from './screenshot.js';
 import { registerWaitCommand } from './wait.js';
 import { SELECTOR_OR_INDEX_ARGUMENT, SELECTOR_SCOPE_HELP, } from '../shared/commonOptions.js';
 import { integerOption, screenshotFormatOption } from '../shared/validation.js';
+import { MAX_VALUE_LENGTH, QUERY_JSON_LIST_LIMIT } from '../../constants.js';
+/** Help of `--full` on `dom eval` and the `eval` shortcut */
+const EVAL_FULL_HELP = `Print the whole value (default: the first ${MAX_VALUE_LENGTH} characters; a string result in JSON too)`;
 /**
  * Register DOM telemetry commands on the root Commander program.
  */
@@ -49,6 +53,7 @@ export function registerDomCommands(program) {
         .command('query')
         .description('Find elements by CSS selector')
         .argument('<selector>', 'CSS selector (e.g., ".error", "#app", "button")')
+        .option('--limit <n>', `Matches to list (default: ${QUERY_LIST_LIMIT}, ${QUERY_JSON_LIST_LIMIT} with --json; 0 = all); the first ${QUERY_CACHE_LIMIT} (or more with a higher limit) are indexed`, integerOption(0))
         .option('-j, --json', 'Output as JSON')
         .addHelpText('after', SELECTOR_SCOPE_HELP)
         .action(async (selector, options) => {
@@ -59,6 +64,7 @@ export function registerDomCommands(program) {
         .description('Evaluate JavaScript expression in the page context')
         .argument('<script>', 'JavaScript to execute (e.g., "document.title", "window.location.href")')
         .option('--frame <frame>', 'Evaluate in an iframe, cross-origin ones included: index (from dom frames; 87 when stale), name/id attribute, or part of the name, id or URL')
+        .option('--full', EVAL_FULL_HELP)
         .option('-j, --json', 'Output as JSON')
         .action(async (script, options) => {
         await handleDomEval(script, options);
@@ -68,6 +74,7 @@ export function registerDomCommands(program) {
         .description('Shortcut for: bdg dom eval')
         .argument('<script>', 'JavaScript to execute')
         .option('--frame <frame>', 'Evaluate in an iframe (see dom frames)')
+        .option('--full', EVAL_FULL_HELP)
         .option('-j, --json', 'Output as JSON')
         .action(async (script, options) => {
         await handleDomEval(script, options);
@@ -84,7 +91,7 @@ export function registerDomCommands(program) {
         .description('Get semantic accessibility structure (default) or raw HTML (--raw)')
         .argument('[selectorOrIndex]', `${SELECTOR_OR_INDEX_ARGUMENT} (e.g. ".error", "#app", 0); default: ${DOM_GET_DEFAULT_SELECTOR}`)
         .option('--raw', 'Output raw HTML with all filtering options')
-        .option('--full', 'Show all of the element text (default: the first 500 characters)')
+        .option('--full', `Show all of the element text (default: the first 500 characters); with --raw, all of the HTML (default: the first ${MAX_VALUE_LENGTH} characters)`)
         .option('--all', 'Get all matches (only with --raw)')
         .option('--index <n>', 'Element index if selector matches multiple (0-based)', integerOption(0))
         .addOption(new Option('--nth <n>', 'Alias of --index').argParser(integerOption(0)).hideHelp())

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

@@ -2,13 +2,31 @@
  * `bdg dom query` — find elements by CSS selector and populate the query cache.
  */
 import type { DomQueryCommandOptions } from '../shared/optionTypes.js';
+import type { DomQueryResult } from '../../types.js';
+/** Matches `dom query` lists without `--limit` (human output) */
+export declare const QUERY_LIST_LIMIT = 50;
 /**
  * Handle `bdg dom query <selector>`.
  *
- * Runs the selector, caches the result set so later commands can reference
- * elements by index, and renders the result either as JSON or human output.
+ * Runs the selector, caches the described matches so later commands can
+ * reference elements by index, and lists the first `--limit` of them (50,
+ * or {@link QUERY_JSON_LIST_LIMIT} with `--json`; 0 = all) with the total
+ * count. The first {@link QUERY_CACHE_LIMIT} are indexed whatever is listed.
  * No match exits 83, like `dom get` and `dom a11y`, and clears the cache so
  * indices of an earlier query are not used by mistake.
  */
 export declare function handleDomQuery(selector: string, options: DomQueryCommandOptions): Promise<void>;
+/**
+ * The matches to list: the first `limit` (all with 0), with how many were
+ * left out and, when not every match was described, how many can be used by
+ * index. Nothing is added when the limit cut nothing (a match that could not
+ * be described is just missing, as before). When more than
+ * {@link VIEWPORT_HINT_LIMIT} are listed, `viewportChecked` says that only
+ * the first ones have a viewport position.
+ *
+ * @param result - Query result with every described match
+ * @param limit - Matches to list (0 = all)
+ * @returns Result to output
+ */
+export declare function listedMatches(result: DomQueryResult, limit: number): DomQueryResult;
 //# sourceMappingURL=query.d.ts.map

package/dist/commands/dom/query.js

@@ -1,22 +1,30 @@
 /**
  * `bdg dom query` — find elements by CSS selector and populate the query cache.
  */
-import { noMatchesError, queryDOMElements } from './helpers/index.js';
+import { noMatchesError, pageDocumentId, queryDOMElements } from './helpers/index.js';
+import { VIEWPORT_HINT_LIMIT } from './helpers/query.js';
 import { runCommand } from '../shared/CommandRunner.js';
+import { QUERY_JSON_LIST_LIMIT } from '../../constants.js';
 import { QueryCacheManager } from '../../session/QueryCacheManager.js';
 import { formatDomQuery } from '../../ui/formatters/dom.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
+/** Matches `dom query` lists without `--limit` (human output) */
+export const QUERY_LIST_LIMIT = 50;
 /**
  * Handle `bdg dom query <selector>`.
  *
- * Runs the selector, caches the result set so later commands can reference
- * elements by index, and renders the result either as JSON or human output.
+ * Runs the selector, caches the described matches so later commands can
+ * reference elements by index, and lists the first `--limit` of them (50,
+ * or {@link QUERY_JSON_LIST_LIMIT} with `--json`; 0 = all) with the total
+ * count. The first {@link QUERY_CACHE_LIMIT} are indexed whatever is listed.
  * No match exits 83, like `dom get` and `dom a11y`, and clears the cache so
  * indices of an earlier query are not used by mistake.
  */
 export async function handleDomQuery(selector, options) {
+    const limit = options.limit ?? (options.json ? QUERY_JSON_LIST_LIMIT : QUERY_LIST_LIMIT);
     await runCommand(async () => {
-        const result = await queryDOMElements(selector);
+        const document = await pageDocumentId();
+        const result = await queryDOMElements(selector, limit);
         const cache = QueryCacheManager.getInstance();
         if (result.count === 0) {
             await cache.clear();
@@ -28,8 +36,33 @@ export async function handleDomQuery(selector, options) {
                 errorContext: { suggestion: err.suggestion },
             };
         }
-        await cache.set(result);
-        return { success: true, data: result };
+        await cache.set(result, document);
+        return { success: true, data: listedMatches(result, limit) };
     }, options, formatDomQuery);
 }
+/**
+ * The matches to list: the first `limit` (all with 0), with how many were
+ * left out and, when not every match was described, how many can be used by
+ * index. Nothing is added when the limit cut nothing (a match that could not
+ * be described is just missing, as before). When more than
+ * {@link VIEWPORT_HINT_LIMIT} are listed, `viewportChecked` says that only
+ * the first ones have a viewport position.
+ *
+ * @param result - Query result with every described match
+ * @param limit - Matches to list (0 = all)
+ * @returns Result to output
+ */
+export function listedMatches(result, limit) {
+    const listed = limit === 0 || result.count <= limit
+        ? result
+        : {
+            ...result,
+            nodes: result.nodes.slice(0, limit),
+            omitted: result.count - Math.min(limit, result.nodes.length),
+            ...(result.nodes.length < result.count && { indexed: result.nodes.length }),
+        };
+    return listed.nodes.length > VIEWPORT_HINT_LIMIT
+        ? { ...listed, viewportChecked: VIEWPORT_HINT_LIMIT }
+        : listed;
+}
 //# sourceMappingURL=query.js.map

package/dist/commands/dom/screenshot.js

@@ -14,6 +14,7 @@ import { OutputBuilder, buildSuccessResponse } from '../../ui/OutputBuilder.js';
 import { formatDomScreenshot } from '../../ui/formatters/dom.js';
 import { createLogger } from '../../ui/logging/index.js';
 import { delay } from '../../utils/async.js';
+import { makeDirectory } from '../../utils/directories.js';
 import { getErrorMessage } from '../../utils/errors.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
 import { filterDefined } from '../../utils/objects.js';
@@ -110,7 +111,7 @@ function ensureDirectory(dirPath, fs) {
         throw new CommandError(`--follow needs a directory, but ${dirPath} is a file`, { suggestion: 'Give a directory for the frames, e.g. bdg dom screenshot ./frames --follow' }, EXIT_CODES.INVALID_ARGUMENTS);
     }
     try {
-        fs.mkdirSync(dirPath, { recursive: true });
+        makeDirectory(dirPath);
     }
     catch (error) {
         throw outputPathError(dirPath, error);
@@ -188,6 +189,7 @@ async function handleSequenceCapture(outputDir, options) {
 /**
  * End a capture sequence on an error (e.g. the element disappeared): print
  * it (one JSON line with `--json`, like the frames) and exit with its code.
+ * It stays compact on a terminal too, since it ends the NDJSON frame stream.
  *
  * @param error - Capture error
  * @param captured - Frames captured before it

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

@@ -21,10 +21,11 @@ export interface SemanticNodeWithContext {
  * link's href, a field's type and name), like `dom query` does, and is
  * followed by up to 500 characters of the element's text
  * (all of it with `dom get --full`) when it is longer than the one-line
- * preview, or, for an element without text or name, what it holds.
+ * preview or the role line shows an accessible name other than the text,
+ * or, for an element without text or name, what it holds.
  *
  * @param data - Accessibility node and optional DOM context
- * @returns Role line, plus a text line for elements with longer text
+ * @returns Role line, plus a text line for elements with longer or differently named text
  */
 export declare function formatSemanticNodeWithContext(data: SemanticNodeWithContext): string;
 /**

package/dist/commands/dom/semanticUtils.js

@@ -5,7 +5,7 @@
  * their surrounding DOM context and to fall back gracefully when only one
  * of the two data sources is available.
  */
-import { MASKED_VALUE } from '../../runtime/dom/elementInfo.js';
+import { MASKED_VALUE, isLabelClass } from '../../runtime/dom/elementInfo.js';
 import { synthesizeA11yNode } from '../../telemetry/roleInference.js';
 import { keyAttributeItems } from '../../ui/formatters/keyAttributes.js';
 import { joinLines } from '../../ui/formatting.js';
@@ -29,9 +29,8 @@ function buildContextText(node, domContext) {
     }
     if (domContext) {
         const tagPart = `<${domContext.tag}`;
-        const classPart = domContext.classes && domContext.classes.length > 0
-            ? `.${domContext.classes.slice(0, 3).join('.')}`
-            : '';
+        const classes = (domContext.classes ?? []).filter(isLabelClass).slice(0, 3);
+        const classPart = classes.length > 0 ? `.${classes.join('.')}` : '';
         const previewPart = domContext.preview && !domContext.text ? ` "${domContext.preview}"` : '';
         return ` ${tagPart}${classPart}>${previewPart}`;
     }
@@ -86,10 +85,11 @@ function buildPropertiesText(node) {
  * link's href, a field's type and name), like `dom query` does, and is
  * followed by up to 500 characters of the element's text
  * (all of it with `dom get --full`) when it is longer than the one-line
- * preview, or, for an element without text or name, what it holds.
+ * preview or the role line shows an accessible name other than the text,
+ * or, for an element without text or name, what it holds.
  *
  * @param data - Accessibility node and optional DOM context
- * @returns Role line, plus a text line for elements with longer text
+ * @returns Role line, plus a text line for elements with longer or differently named text
  */
 export function formatSemanticNodeWithContext(data) {
     const { node, domContext } = data;
@@ -99,13 +99,44 @@ export function formatSemanticNodeWithContext(data) {
     const propsText = buildPropertiesText(node);
     const inferredText = node.inferred ? ' (inferred from DOM)' : '';
     const line = `${roleText}${contextText}${keysText}${propsText}${inferredText}`;
-    if (domContext?.text)
-        return joinLines(line, elementTextLine(domContext.text));
+    const text = textNotOnRoleLine(node, domContext);
+    if (text)
+        return joinLines(line, elementTextLine(text));
     if (domContext?.childCount !== undefined && !node.name) {
-        return joinLines(line, emptyElementLine(domContext.children ?? [], domContext.childCount));
+        return joinLines(line, emptyElementLine(domContext.children ?? [], domContext.childCount, domContext.shadowChildren));
     }
     return line;
 }
+/**
+ * The element's text when the role line does not show it: text longer than
+ * the one-line preview, or the visible text of an element whose accessible
+ * name is something else (an editor named by its aria-label), unless its
+ * name or value shows that text (a long heading with inline children is
+ * named by all of it). Texts are compared ignoring case and whitespace.
+ * A sensitive field's text is never shown.
+ *
+ * @param node - Accessibility node
+ * @param domContext - DOM context with the text
+ * @returns Text for the text line, or undefined
+ */
+function textNotOnRoleLine(node, domContext) {
+    if (domContext?.sensitive)
+        return undefined;
+    const text = domContext?.text ?? (node.name ? domContext?.preview : undefined);
+    if (!text)
+        return undefined;
+    const shown = [node.name, node.value].map((value) => comparableText(value ?? ''));
+    return shown.includes(comparableText(text)) ? undefined : text;
+}
+/**
+ * Text in the form texts are compared in.
+ *
+ * @param text - Text
+ * @returns Lowercased text with whitespace collapsed
+ */
+function comparableText(text) {
+    return text.replace(/\s+/g, ' ').trim().toLowerCase();
+}
 /**
  * Resolve an a11y node, falling back to a DOM-synthesized one when only
  * DOM context is available. Returns null when neither source can produce one.

package/dist/commands/helpJson.d.ts

@@ -78,9 +78,30 @@ export interface CommandMetadata {
     arguments: ArgumentMetadata[];
     /** Command options */
     options: OptionMetadata[];
+    /** Text shown after the options in `--help` (examples, output legend) */
+    helpText?: string;
     /** Subcommands */
     subcommands: CommandMetadata[];
 }
+/**
+ * Command summary for the compact root help: one-line description, arguments
+ * and flags with their descriptions (behaviors, defaults and choices are in
+ * `bdg <command> --help --json`).
+ */
+export interface CompactCommand {
+    /** Command name */
+    name: string;
+    /** Command aliases (only when it has some) */
+    aliases?: readonly string[];
+    /** First line of the description */
+    description: string;
+    /** Arguments as in usage, e.g. "<selector> [index]" (only when it takes some) */
+    arguments?: string;
+    /** Visible options: flags to description */
+    options?: Record<string, string>;
+    /** Subcommands (only for command groups) */
+    subcommands?: CompactCommand[];
+}
 /**
  * Runtime state information for dynamic command availability.
  */
@@ -112,7 +133,7 @@ export interface Capabilities {
     };
 }
 /**
- * Root machine-readable help structure.
+ * Root machine-readable help structure (`bdg --help --json --full`).
  */
 export interface MachineReadableHelp {
     /** CLI name */
@@ -142,10 +163,34 @@ export interface MachineReadableHelp {
     capabilities: Capabilities;
 }
 /**
- * Generates machine-readable help from a Commander program.
+ * Compact root help (`bdg --help --json`): the full help with a command tree
+ * of names, one-line descriptions and flags.
+ */
+export interface CompactHelp extends Omit<MachineReadableHelp, 'command'> {
+    /** Where the details are */
+    details: string;
+    /** Root command summary */
+    command: CompactCommand;
+}
+/**
+ * Help for one command (`bdg <command> --help --json`): its full metadata
+ * (option behaviors, defaults, choices, help text), its subcommands in compact
+ * form, and the exit codes.
+ */
+export interface CommandHelp extends Pick<MachineReadableHelp, 'name' | 'version' | 'description' | 'exitCodes'> {
+    /** Full command path, e.g. "bdg dom query" */
+    path: string;
+    /** Command metadata; subcommands summarized (ask each for its details) */
+    command: Omit<CommandMetadata, 'subcommands'> & {
+        subcommands: CompactCommand[];
+    };
+}
+/**
+ * Generates the full machine-readable help from a Commander program
+ * (`bdg --help --json --full`).
  *
  * Includes comprehensive metadata for agent discovery:
- * - Command structure and options
+ * - Command structure and options with behaviors
  * - Exit codes with semantic meanings
  * - Task-to-command mappings with CDP alternatives
  * - Runtime state and command availability
@@ -154,34 +199,52 @@ export interface MachineReadableHelp {
  *
  * @param program - Commander program instance
  * @returns Machine-readable help structure
+ */
+export declare function generateMachineReadableHelp(program: Command): MachineReadableHelp;
+/**
+ * Generates the compact root help (`bdg --help --json`): the full help with
+ * the command tree reduced to names, one-line descriptions and flags.
+ *
+ * @param program - Commander program instance
+ * @returns Compact help structure
+ */
+export declare function generateCompactHelp(program: Command): CompactHelp;
+/**
+ * The command a command line addresses: follows the words that name
+ * subcommands and skips the others (option values, arguments), stopping at a
+ * command without subcommands.
+ *
+ * @param program - Root Commander program instance
+ * @param words - Command-line words, e.g. ['dom', 'query', '.item']
+ * @returns The addressed command (the program when no word names one)
  *
  * @example
  * ```typescript
- * import { program } from 'commander';
- * import { generateMachineReadableHelp } from './help/machineReadableHelp.js';
- *
- * const help = generateMachineReadableHelp(program);
- * console.log(JSON.stringify(help, null, 2));
+ * resolveCommand(program, ['--session', 'a', 'dom', 'query', '.item']).name(); // 'query'
  * ```
  */
-export declare function generateMachineReadableHelp(program: Command): MachineReadableHelp;
+export declare function resolveCommand(program: Command, words: string[]): Command;
 /**
- * Generates machine-readable help for a specific subcommand.
+ * Full command path, e.g. "bdg dom query".
  *
- * Returns the same structure as generateMachineReadableHelp but with
- * the command field focused on the requested subcommand. If the subcommand
- * is not found, falls back to full root help.
+ * @param command - Commander command instance
+ * @returns Names from the program down to the command
+ */
+export declare function commandPath(command: Command): string;
+/**
+ * Generates machine-readable help for one command: its full metadata,
+ * compact subcommands (a group lists them like the root help does) and the
+ * exit codes.
  *
  * @param program - Root Commander program instance
- * @param commandPath - Array of command names (e.g., ['dom', 'query'])
- * @returns Machine-readable help structure for the subcommand
+ * @param command - The command (from {@link resolveCommand})
+ * @returns Help for the command
  *
  * @example
  * ```typescript
- * // Get help for 'bdg dom query'
- * const help = generateSubcommandHelp(program, ['dom', 'query']);
- * console.log(help.command.name); // 'query'
+ * const help = generateCommandHelp(program, resolveCommand(program, ['dom', 'query']));
+ * console.log(help.path); // 'bdg dom query'
  * ```
  */
-export declare function generateSubcommandHelp(program: Command, commandPath: string[]): MachineReadableHelp;
+export declare function generateCommandHelp(program: Command, command: Command): CommandHelp;
 //# sourceMappingURL=helpJson.d.ts.map