@agentrhq/webcmd 0.3.0 → 0.3.1

package/dist/src/build-manifest.test.js

@@ -3,7 +3,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { cli, getRegistry, Strategy } from './registry.js';
-import { ManifestImportError, diffRemovedEntries, findManifestMetadataIssues, loadManifestEntries, normalizeManifestPath, parseBuildManifestArgs, scanClisDir, serializeManifest, } from './build-manifest.js';
+import { ManifestImportError, buildManifestArtifacts, diffRemovedEntries, findManifestMetadataIssues, loadManifestEntries, normalizeManifestPath, parseBuildManifestArgs, scanClisDir, serializeManifest, } from './build-manifest.js';
 describe('manifest helper rules', () => {
     const tempDirs = [];
     afterEach(() => {
@@ -81,6 +81,62 @@ describe('manifest helper rules', () => {
         expect(entries[0].sourceFile).not.toContain('\\');
         getRegistry().delete(key);
     });
+    it('preserves file metadata and builds both artifacts from one normalized snapshot', async () => {
+        const site = `manifest-files-${Date.now()}`;
+        const key = `${site}/upload`;
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-manifest-'));
+        tempDirs.push(dir);
+        const file = path.join(dir, `${site}.ts`);
+        fs.writeFileSync(file, `export const command = cli({ site: '${site}', name: 'upload', access: 'write' });`);
+        const entries = await loadManifestEntries(file, site, async () => ({
+            command: cli({
+                site,
+                name: 'upload',
+                access: 'write',
+                description: 'upload a document',
+                strategy: Strategy.PUBLIC,
+                browser: false,
+                args: [{
+                        name: 'path',
+                        type: 'str',
+                        positional: true,
+                        required: true,
+                        help: 'Document path',
+                        file: {
+                            direction: 'input',
+                            pathKind: 'file',
+                            contentTypes: ['application/pdf'],
+                            maxBytes: 5_000_000,
+                        },
+                    }],
+            }),
+        }));
+        expect(entries[0].args[0].file).toEqual({
+            direction: 'input',
+            pathKind: 'file',
+            contentTypes: ['application/pdf'],
+            maxBytes: 5_000_000,
+        });
+        const artifacts = buildManifestArtifacts(entries, '7.6.5', []);
+        expect(JSON.parse(artifacts.manifestJson)).toEqual(entries);
+        expect(JSON.parse(artifacts.hostedContractJson)).toMatchObject({
+            schemaVersion: 1,
+            webcmdVersion: '7.6.5',
+            commands: [{
+                    command: `${site}/upload`,
+                    fileArguments: [{
+                            name: 'path',
+                            direction: 'input',
+                            pathKind: 'file',
+                            multiple: false,
+                            required: true,
+                            contentTypes: ['application/pdf'],
+                            maxBytes: 5_000_000,
+                        }],
+                }],
+        });
+        getRegistry().delete(key);
+    });
     it('serializes freshPage for persistent browser commands', async () => {
         const site = `manifest-fresh-page-${Date.now()}`;
         const key = `${site}/checkout`;

package/dist/src/builtin-command-surface.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+export declare const LIST_COMMAND_DESCRIPTION = "List all available CLI commands";
+export declare const LIST_FORMAT_DESCRIPTION = "Output format: table, json, yaml, md, csv";
+export declare const COMPLETION_COMMAND_DESCRIPTION = "Output shell completion script";
+export declare const COMPLETION_SHELL_DESCRIPTION = "Shell type: bash, zsh, or fish";
+/** Configure built-in grammar shared by the local and hosted runtimes. */
+export declare function configureListCommandSurface(command: Command): Command;
+/** Configure completion grammar shared by the local and hosted runtimes. */
+export declare function configureCompletionCommandSurface(command: Command): Command;

package/dist/src/builtin-command-surface.js

@@ -0,0 +1,16 @@
+export const LIST_COMMAND_DESCRIPTION = 'List all available CLI commands';
+export const LIST_FORMAT_DESCRIPTION = 'Output format: table, json, yaml, md, csv';
+export const COMPLETION_COMMAND_DESCRIPTION = 'Output shell completion script';
+export const COMPLETION_SHELL_DESCRIPTION = 'Shell type: bash, zsh, or fish';
+/** Configure built-in grammar shared by the local and hosted runtimes. */
+export function configureListCommandSurface(command) {
+    return command
+        .description(LIST_COMMAND_DESCRIPTION)
+        .option('-f, --format <fmt>', LIST_FORMAT_DESCRIPTION, 'table');
+}
+/** Configure completion grammar shared by the local and hosted runtimes. */
+export function configureCompletionCommandSurface(command) {
+    return command
+        .description(COMPLETION_COMMAND_DESCRIPTION)
+        .argument('<shell>', COMPLETION_SHELL_DESCRIPTION);
+}

package/dist/src/check-hosted-contract.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/check-hosted-contract.test.js

@@ -0,0 +1,56 @@
+import { createHash } from 'node:crypto';
+import { copyFileSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+import { afterEach, describe, expect, it } from 'vitest';
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const checkerPath = path.join(packageRoot, 'scripts/check-hosted-contract.mjs');
+const committedArtifactNames = ['cli-manifest.json'];
+const fixtureRoots = [];
+afterEach(() => {
+    for (const fixtureRoot of fixtureRoots.splice(0)) {
+        rmSync(fixtureRoot, { recursive: true, force: true });
+    }
+});
+function createCommittedArtifactFixture() {
+    const fixtureRoot = mkdtempSync(path.join(tmpdir(), 'webcmd-contract-committed-'));
+    fixtureRoots.push(fixtureRoot);
+    for (const artifactName of committedArtifactNames) {
+        copyFileSync(path.join(packageRoot, artifactName), path.join(fixtureRoot, artifactName));
+    }
+    return fixtureRoot;
+}
+function rootArtifactHashes() {
+    return Object.fromEntries(committedArtifactNames.map((artifactName) => [
+        artifactName,
+        createHash('sha256').update(readFileSync(path.join(packageRoot, artifactName))).digest('hex'),
+    ]));
+}
+function runChecker(committedRoot) {
+    return spawnSync(process.execPath, [checkerPath], {
+        cwd: packageRoot,
+        encoding: 'utf8',
+        env: { ...process.env, WEBCMD_CONTRACT_COMMITTED_ROOT: committedRoot },
+    });
+}
+describe('hosted contract reproducibility checker', () => {
+    it('accepts a byte-identical committed manifest and generates the package contract', () => {
+        const result = runChecker(createCommittedArtifactFixture());
+        expect(result.status).toBe(0);
+        expect(result.stdout).toContain('hosted-contract.json generated successfully.');
+    }, 10_000);
+    it('rejects one stale byte without mutating root artifacts', () => {
+        const before = rootArtifactHashes();
+        const fixtureRoot = createCommittedArtifactFixture();
+        const stalePath = path.join(fixtureRoot, 'cli-manifest.json');
+        const staleBytes = readFileSync(stalePath);
+        staleBytes[0] ^= 1;
+        writeFileSync(stalePath, staleBytes);
+        const result = runChecker(fixtureRoot);
+        expect(result.status).toBe(1);
+        expect(result.stderr).toContain('cli-manifest.json');
+        expect(rootArtifactHashes()).toEqual(before);
+    }, 10_000);
+});

package/dist/src/cli.js

@@ -9,17 +9,18 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import * as readline from 'node:readline/promises';
 import { fileURLToPath } from 'node:url';
-import { Command, InvalidArgumentError, Option } from 'commander';
+import { Command, Option } from 'commander';
 import { findPackageRoot, getBuiltEntryCandidates } from './package-paths.js';
-import { fullName, getRegistry, strategyLabel } from './registry.js';
-import { serializeCommand, formatArgSummary } from './serialization.js';
+import { getRegistry } from './registry.js';
+import { commandListPresentation, toPresentableCommand } from './command-presentation.js';
+import { configureCompletionCommandSurface, configureListCommandSurface } from './builtin-command-surface.js';
 import { render as renderOutput } from './output.js';
 import { PKG_VERSION } from './version.js';
 import { printCompletionScript } from './completion.js';
 import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled, formatExternalCliLabel } from './external.js';
 import { installWebcmdSkill, listWebcmdSkills, updateWebcmdSkill } from './skills.js';
 import { registerAllCommands } from './commanderAdapter.js';
-import { classifyAdapter, formatRootAdapterHelpText, installCommanderNamespaceStructuredHelp, installStructuredHelp, leadingPositionalFromUsage, rootHelpData } from './help.js';
+import { buildRootHelpPresentation, classifyAdapter, installCommanderNamespaceStructuredHelp, installRootPresentationHelp, leadingPositionalFromUsage, rootHelpData } from './help.js';
 import { EXIT_CODES, getErrorMessage, BrowserConnectError, CliError, ArgumentError } from './errors.js';
 import { TargetError } from './browser/target-errors.js';
 import { resolveTargetJs, getTextResolvedJs, getValueResolvedJs, getAttributesResolvedJs, selectResolvedJs, isAutocompleteResolvedJs } from './browser/target-resolver.js';
@@ -32,6 +33,7 @@ import { parseFilter, shapeMatchesFilter } from './browser/shape-filter.js';
 import { buildHtmlTreeJs } from './browser/html-tree.js';
 import { buildExtractHtmlJs, runExtractFromHtml } from './browser/extract.js';
 import { analyzeSite } from './browser/analyze.js';
+import { browserOptionValueParser } from './browser/command-catalog.js';
 import { registerAuthCommands } from './commands/auth.js';
 import { daemonRestart, daemonStatus, daemonStop } from './commands/daemon.js';
 import { log } from './logger.js';
@@ -41,6 +43,7 @@ import { aliasForContextId, loadProfileConfig, profileRouteParams, renameProfile
 import { formatDaemonVersion, isDaemonStale } from './browser/daemon-version.js';
 import { DEFAULT_BROWSER_CONNECT_TIMEOUT } from './browser/config.js';
 import { CLI_COMMAND } from './brand.js';
+import { configureRootCommandSurface } from './root-command-surface.js';
 const CLI_FILE = fileURLToPath(import.meta.url);
 const BROWSER_TAB_OPTION_DESCRIPTION = 'Target tab/page identity returned by "browser open", "browser tab new", or "browser tab list"';
 const FOLLOW_POLL_MS = 1_000;
@@ -632,16 +635,6 @@ function parsePositiveIntOption(val, label, fallback) {
     }
     return parsed;
 }
-function parseScreenshotDim(val, label) {
-    if (!/^\d+$/.test(val)) {
-        throw new InvalidArgumentError(`--${label} must be a positive integer (got "${val}")`);
-    }
-    const parsed = parseInt(val, 10);
-    if (parsed <= 0) {
-        throw new InvalidArgumentError(`--${label} must be a positive integer (got "${val}")`);
-    }
-    return parsed;
-}
 function applyVerbose(opts) {
     if (opts.verbose)
         process.env.WEBCMD_VERBOSE = '1';
@@ -666,93 +659,30 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
     // prerequisite for passThroughOptions to forward --help/--version to external binaries
     program
         .name('webcmd')
-        .description('Make any website your CLI. Zero setup. AI-powered.')
-        .version(PKG_VERSION)
-        .option('--profile <name>', 'Chrome profile/context alias for browser runtime commands')
-        .enablePositionalOptions();
+        .description('Make any website your CLI. Zero setup. AI-powered.');
+    configureRootCommandSurface(program);
     // ── Built-in: list ────────────────────────────────────────────────────────
-    program
-        .command('list')
-        .description('List all available CLI commands')
-        .option('-f, --format <fmt>', 'Output format: table, json, yaml, md, csv', 'table')
+    configureListCommandSurface(program.command('list'))
         .action((opts) => {
-        const registry = getRegistry();
-        const commands = [...new Set(registry.values())].sort((a, b) => fullName(a).localeCompare(fullName(b)));
-        const fmt = opts.format;
-        const isStructured = fmt === 'json' || fmt === 'yaml';
-        if (fmt !== 'table') {
-            const rows = isStructured
-                ? commands.map(serializeCommand)
-                : commands.map(c => ({
-                    command: fullName(c),
-                    site: c.site,
-                    name: c.name,
-                    aliases: c.aliases?.join(', ') ?? '',
-                    description: c.description,
-                    access: c.access,
-                    strategy: strategyLabel(c),
-                    browser: !!c.browser,
-                    args: formatArgSummary(c.args),
-                }));
-            renderOutput(rows, {
-                fmt,
-                columns: ['command', 'site', 'name', 'aliases', 'description', 'access', 'strategy', 'browser', 'args',
-                    ...(isStructured ? ['columns', 'domain'] : [])],
-                title: 'webcmd/list',
-                source: 'webcmd list',
-            });
+        const externalClis = opts.format === 'table' ? loadExternalClis() : [];
+        const presentation = commandListPresentation([...new Set(getRegistry().values())].map(toPresentableCommand), opts.format, {
+            externalClis: externalClis.map((external) => ({
+                label: formatExternalCliLabel(external),
+                installed: isBinaryInstalled(external.binary),
+                ...(external.description ? { description: external.description } : {}),
+            })),
+        });
+        if (presentation.displayLines) {
+            for (const line of presentation.displayLines)
+                console.log(line);
             return;
         }
-        // Table (default) — grouped by adapter kind (app vs site), then by site name.
-        // classifyAdapter() reads the `domain` field: DNS-style domains are sites;
-        // localhost/loopback endpoints and bare app names are apps.
-        const appsBySite = new Map();
-        const sitesBySite = new Map();
-        for (const cmd of commands) {
-            const target = classifyAdapter(cmd.domain) === 'app' ? appsBySite : sitesBySite;
-            const g = target.get(cmd.site) ?? [];
-            g.push(cmd);
-            target.set(cmd.site, g);
-        }
-        const renderSiteGroup = (site, cmds) => {
-            console.log(`  ${site}`);
-            for (const cmd of cmds) {
-                const label = strategyLabel(cmd);
-                const tag = label === 'public'
-                    ? '[public]'
-                    : `[${label}]`;
-                const aliases = cmd.aliases?.length ? ` (aliases: ${cmd.aliases.join(', ')})` : '';
-                console.log(`    ${cmd.name} ${tag}${aliases}${cmd.description ? ` — ${cmd.description}` : ''}`);
-            }
-            console.log();
-        };
-        console.log();
-        console.log('  webcmd' + ' — available commands');
-        console.log();
-        if (appsBySite.size > 0) {
-            console.log('  App adapters');
-            console.log();
-            for (const [site, cmds] of appsBySite)
-                renderSiteGroup(site, cmds);
-        }
-        if (sitesBySite.size > 0) {
-            console.log('  Site adapters');
-            console.log();
-            for (const [site, cmds] of sitesBySite)
-                renderSiteGroup(site, cmds);
-        }
-        const externalClis = loadExternalClis();
-        if (externalClis.length > 0) {
-            console.log('  external CLIs');
-            for (const ext of externalClis) {
-                const isInstalled = isBinaryInstalled(ext.binary);
-                const tag = isInstalled ? '[installed]' : '[auto-install]';
-                console.log(`    ${formatExternalCliLabel(ext)} ${tag}${ext.description ? ` — ${ext.description}` : ''}`);
-            }
-            console.log();
-        }
-        console.log(`  ${commands.length} built-in commands across ${appsBySite.size} apps + ${sitesBySite.size} sites, ${externalClis.length} external CLIs`);
-        console.log();
+        renderOutput(presentation.rows, {
+            fmt: opts.format,
+            columns: presentation.columns,
+            title: 'webcmd/list',
+            source: 'webcmd list',
+        });
     });
     // ── Built-in: validate / verify ───────────────────────────────────────────
     program
@@ -1204,8 +1134,8 @@ Examples:
     addBrowserTabOption(browser.command('screenshot').argument('[path]', 'Save to file (base64 if omitted)'))
         .option('--full-page', 'Capture the full scrollable page, not just the viewport', false)
         .option('--annotate', 'Overlay visible browser state ref labels on the screenshot', false)
-        .option('--width <n>', 'Override viewport width in CSS pixels for this screenshot only', (v) => parseScreenshotDim(v, 'width'))
-        .option('--height <n>', 'Override viewport height in CSS pixels for this screenshot only (ignored with --full-page)', (v) => parseScreenshotDim(v, 'height'))
+        .option('--width <n>', 'Override viewport width in CSS pixels for this screenshot only', (value) => browserOptionValueParser('screenshot', 'width')(value))
+        .option('--height <n>', 'Override viewport height in CSS pixels for this screenshot only (ignored with --full-page)', (value) => browserOptionValueParser('screenshot', 'height')(value))
         .description('Take screenshot')
         .action(browserAction(async (page, path, opts) => {
         const shotOpts = {
@@ -1858,8 +1788,13 @@ Examples:
             process.exitCode = EXIT_CODES.USAGE_ERROR;
             return;
         }
-        const { matches_n, match_level } = await page.click(resolvedTarget, parsed.opts);
-        console.log(JSON.stringify({ clicked: true, target: resolvedTarget, matches_n, match_level }, null, 2));
+        const { matches_n, match_level, click_method, hit, retargeted } = await page.click(resolvedTarget, parsed.opts);
+        console.log(JSON.stringify({
+            clicked: true, target: resolvedTarget, matches_n, match_level,
+            ...(click_method && { click_method }),
+            ...(hit && { hit }),
+            ...(retargeted && { retargeted }),
+        }, null, 2));
     }));
     addBrowserTabOption(addSemanticLocatorOptions(browser.command('type'))
         .argument('[targetOrText]', 'Numeric ref/CSS target, or text when using --role/--name/etc.')
@@ -2835,10 +2770,7 @@ cli({
         const report = await runBrowserDoctor({ cliVersion: PKG_VERSION });
         console.log(renderBrowserDoctorReport(report));
     });
-    program
-        .command('completion')
-        .description('Output shell completion script')
-        .argument('<shell>', 'Shell type: bash, zsh, or fish')
+    configureCompletionCommandSurface(program.command('completion'))
         .action((shell) => {
         printCompletionScript(shell);
     });
@@ -3102,12 +3034,32 @@ cli({
         .argument('<name>', 'Plugin name (lowercase, hyphens allowed)')
         .option('-d, --dir <path>', 'Output directory (default: ./<name>)')
         .option('--description <text>', 'Plugin description')
+        .option('--author-name <name>', 'Author display name')
+        .option('--author-handle <handle>', 'Author GitHub handle')
         .action(async (name, opts) => {
         const { createPluginScaffold } = await import('./plugin-scaffold.js');
         try {
+            let authorName = opts.authorName?.trim();
+            let authorHandle = opts.authorHandle?.trim();
+            if ((!authorName || !authorHandle) && process.stdin.isTTY && process.stdout.isTTY) {
+                const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+                try {
+                    if (!authorName)
+                        authorName = (await rl.question('Author name: ')).trim();
+                    if (!authorHandle)
+                        authorHandle = (await rl.question('GitHub handle: ')).trim();
+                }
+                finally {
+                    rl.close();
+                }
+            }
             const result = createPluginScaffold(name, {
                 dir: opts.dir,
                 description: opts.description,
+                author: {
+                    name: authorName ?? '',
+                    handle: authorHandle ?? '',
+                },
             });
             console.log(`✅ Plugin scaffold created at ${result.dir}`);
             console.log();
@@ -3480,7 +3432,7 @@ cli({
             applyAncestorAwareUsage(sub);
     }
     applyAncestorAwareUsage(browser);
-    installStructuredHelp(program, () => rootHelpData(program, adapterGroups), () => formatRootAdapterHelpText(adapterGroups));
+    installRootPresentationHelp(program, () => rootHelpData(program, adapterGroups), buildRootHelpPresentation(program, adapterGroups));
     // ── Unknown command fallback ──────────────────────────────────────────────
     // Security: do NOT auto-discover and register arbitrary system binaries.
     // Only explicitly registered external CLIs are allowed.

package/dist/src/cli.test.js

@@ -7,7 +7,9 @@ import { cli, getRegistry, Strategy } from './registry.js';
 import { BrowserCommandError } from './browser/daemon-client.js';
 import { TargetError } from './browser/target-errors.js';
 import { PKG_VERSION } from './version.js';
-import { classifyAdapter } from './help.js';
+import { classifyAdapter, getInstalledRootHelpPresentation } from './help.js';
+import { commandListPresentation, formatRootHelp, toPresentableCommand, } from './command-presentation.js';
+import { render as renderOutput } from './output.js';
 const { mockBrowserConnect, mockBrowserClose, mockBindTab, mockSendCommand, mockExecFileSync, browserState, } = vi.hoisted(() => ({
     mockBrowserConnect: vi.fn(),
     mockBrowserClose: vi.fn(),
@@ -94,6 +96,14 @@ describe('createProgram root help descriptions', () => {
         expect(descriptionFor(program, 'list')).toBe('List all available CLI commands');
         expect(descriptionFor(program, 'doctor')).toBe('Diagnose webcmd browser bridge connectivity');
     });
+    it('renders the actual local root through the shared root presentation seam', () => {
+        const program = createProgram('', '');
+        const presentation = getInstalledRootHelpPresentation(program);
+        const commanderHelp = program.createHelp();
+        expect(presentation).toBeDefined();
+        expect(presentation.baseText).toBe(commanderHelp.formatHelp(program, commanderHelp));
+        expect(program.helpInformation()).toBe(formatRootHelp(presentation));
+    });
     it('keeps site adapters out of root commands and lists sites in the root help tail', () => {
         const registry = getRegistry();
         const snapshot = new Map(registry);
@@ -274,6 +284,45 @@ describe('createProgram root help descriptions', () => {
                 registry.set(key, value);
         }
     });
+    it.each(['json', 'yaml', 'yml'])('renders local list %s through the shared list presentation', async (format) => {
+        const registry = getRegistry();
+        const snapshot = new Map(registry);
+        registry.clear();
+        try {
+            const command = cli({
+                site: 'github',
+                name: 'issues',
+                aliases: ['issue-list'],
+                access: 'read',
+                description: 'List repository issues',
+                strategy: Strategy.PUBLIC,
+                browser: false,
+                args: [{ name: 'limit', type: 'int', default: 20, help: 'Maximum issues' }],
+                columns: ['number', 'title'],
+            });
+            const presentation = commandListPresentation([toPresentableCommand(command)], format);
+            const outputSpy = vi.mocked(console.log);
+            outputSpy.mockClear();
+            const program = createProgram('', '');
+            await program.parseAsync(['node', 'webcmd', 'list', '-f', format]);
+            const actual = outputSpy.mock.calls.flat().join('\n');
+            outputSpy.mockClear();
+            renderOutput(presentation.rows, {
+                fmt: format,
+                columns: presentation.columns,
+                title: 'webcmd/list',
+                source: 'webcmd list',
+            });
+            const expected = outputSpy.mock.calls.flat().join('\n');
+            outputSpy.mockClear();
+            expect(actual).toBe(expected);
+        }
+        finally {
+            registry.clear();
+            for (const [key, value] of snapshot)
+                registry.set(key, value);
+        }
+    });
     it('exposes external_clis / app_adapters / site_adapters in structured help', () => {
         const registry = getRegistry();
         const snapshot = new Map(registry);
@@ -489,6 +538,7 @@ describe('createProgram root help descriptions', () => {
             expect(data.command).toBe('webcmd browser');
             expect(data.description).toBe('Browser control — navigate, click, type, extract, wait (no LLM needed)');
             expect(data.command_count).toBeGreaterThan(20);
+            expect(data.commands.map((cmd) => cmd.name)).toContain('bind');
             // `--session` is now a hidden internal option; user-facing surface is the
             // <session> positional declared via `.usage()`. Structured help drops
             // hidden options, so namespace_options shouldn't expose it.
@@ -2499,6 +2549,26 @@ describe('browser click/type commands', () => {
         expect(browserState.page.click).toHaveBeenCalledWith('#save', {});
         expect(lastJsonLog()).toEqual({ clicked: true, target: '#save', matches_n: 1, match_level: 'exact' });
     });
+    it('surfaces click hit-testing diagnostics', async () => {
+        browserState.page.click.mockResolvedValueOnce({
+            matches_n: 1,
+            match_level: 'exact',
+            click_method: 'js',
+            hit: 'other',
+            retargeted: true,
+        });
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'webcmd', 'browser', '--session', 'test', 'click', '#covered']);
+        expect(lastJsonLog()).toEqual({
+            clicked: true,
+            target: '#covered',
+            matches_n: 1,
+            match_level: 'exact',
+            click_method: 'js',
+            hit: 'other',
+            retargeted: true,
+        });
+    });
     it('clicks a unique semantic locator without a prior state call', async () => {
         browserState.page.evaluate.mockResolvedValueOnce({
             matches_n: 1,

package/dist/src/command-presentation.d.ts

@@ -0,0 +1,95 @@
+import type { Arg } from './registry.js';
+export interface PresentableCommand {
+    site: string;
+    name: string;
+    aliases: string[];
+    description: string;
+    access: 'read' | 'write';
+    strategy: string;
+    browser: boolean;
+    args: readonly Arg[];
+    columns: readonly string[];
+    defaultFormat?: string;
+    domain?: string;
+    example?: string;
+    siteSession?: string;
+}
+export interface PresentableCommandSource {
+    site: string;
+    name: string;
+    aliases?: readonly string[];
+    description: string;
+    access: string;
+    strategy?: string;
+    browser?: boolean;
+    args: readonly Arg[];
+    columns?: readonly string[];
+    defaultFormat?: string | null;
+    domain?: string | null;
+    example?: string;
+    siteSession?: string;
+}
+export interface RootHelpCommand {
+    name: string;
+    description: string;
+}
+export interface RootHelpOption {
+    flags: string;
+    description: string;
+}
+export interface RootHelpGroup {
+    label: string;
+    items: readonly string[];
+}
+export interface RootHelpPresentation {
+    description: string;
+    usage?: readonly string[];
+    commands: readonly RootHelpCommand[];
+    options: readonly RootHelpOption[];
+    /** Commander-generated body retained by local mode for byte-compatible layout. */
+    baseText?: string;
+    groups?: readonly RootHelpGroup[];
+    footer?: readonly string[];
+    localOnlyCommands?: readonly RootHelpCommand[];
+    localOnlyExplanation?: string;
+}
+export interface CommandListPresentation {
+    rows: Record<string, unknown>[];
+    columns: string[];
+    structured: boolean;
+    displayLines?: string[];
+}
+export interface PresentableExternalCli {
+    label: string;
+    installed: boolean;
+    description?: string;
+}
+export interface CompletableCommand {
+    site: string;
+    name: string;
+    aliases?: readonly string[];
+}
+export declare function toPresentableCommand(command: PresentableCommandSource): PresentableCommand;
+export declare function formatRootHelp(presentation: RootHelpPresentation): string;
+export declare function commandListRows(commands: readonly PresentableCommand[], structured: boolean): Record<string, unknown>[];
+export declare function commandListPresentation(commands: readonly PresentableCommand[], format: string, options?: {
+    externalClis?: readonly PresentableExternalCli[];
+}): CommandListPresentation;
+export type AdapterKind = 'site' | 'app';
+export declare function classifyAdapterDomain(domain: string | undefined): AdapterKind;
+export declare function getCommandCompletionCandidates(commands: readonly CompletableCommand[], words: readonly string[], cursor: number, builtins: readonly string[]): string[];
+export declare function formatCommandListTerm(command: PresentableCommand): string;
+export declare function siteHelpData(site: string, commands: readonly PresentableCommand[]): Record<string, unknown>;
+export declare function commandHelpData(command: PresentableCommand): Record<string, unknown>;
+export declare function formatCommonOptionsHelp(): string;
+export declare function formatBrowserCommonOptionsHelp(): string;
+export declare function formatSiteHelp(site: string, commands: readonly PresentableCommand[]): string;
+export declare function formatCommandHelp(command: PresentableCommand): string;
+export declare function formatSiteCommandDescription(command: PresentableCommand): string;
+export declare function wrapCommaList(items: readonly string[], opts?: {
+    width?: number;
+    indent?: string;
+}): string;
+export declare function serializePresentableArg(arg: Arg): Record<string, unknown>;
+export declare function formatArgumentSummary(args: readonly Arg[]): string;
+export declare function formatPresentableCommandExample(command: PresentableCommand): string;