@agentrhq/webcmd 0.2.5 → 0.3.1

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
@@ -1022,11 +952,12 @@ Examples:
             const profileSelection = getBrowserProfileSelection(command);
             const contextId = profileSelection?.contextId;
             const routing = profileRouteParams(profileSelection);
+            const windowMode = getBrowserWindowMode(command, 'foreground');
             try {
                 const { BrowserBridge } = await import('./browser/index.js');
                 const bridge = new BrowserBridge();
-                await bridge.connect({ timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT, session, surface: 'browser', ...routing });
-                await fn({ session, contextId, routing }, opts);
+                await bridge.connect({ timeout: DEFAULT_BROWSER_CONNECT_TIMEOUT, session, surface: 'browser', ...routing, windowMode });
+                await fn({ session, contextId, routing, windowMode }, opts);
             }
             catch (err) {
                 if (err instanceof BrowserCommandError) {
@@ -1044,7 +975,7 @@ Examples:
         .description('Bind an existing Cloak runtime tab to the browser session named by <session>')
         .option('--page <id>', 'Cloak tab page id from `webcmd browser <session> tab list`')
         .option('--index <n>', 'Cloak tab index from `webcmd browser <session> tab list`')
-        .action(browserSessionCommandAction(async ({ session, contextId, routing }, opts) => {
+        .action(browserSessionCommandAction(async ({ session, contextId, routing, windowMode }, opts) => {
         const page = typeof opts.page === 'string' && opts.page.trim() ? opts.page.trim() : undefined;
         const rawIndex = typeof opts.index === 'string' && opts.index.trim() ? opts.index.trim() : undefined;
         if ((page && rawIndex) || (!page && !rawIndex)) {
@@ -1054,7 +985,7 @@ Examples:
             throw new BrowserCommandError('--index must be a non-negative integer.', 'invalid_request');
         }
         const index = rawIndex === undefined ? undefined : Number.parseInt(rawIndex, 10);
-        const data = await bindTab(session, { ...routing, ...(page && { page }), ...(index !== undefined && { index }) });
+        const data = await bindTab(session, { ...routing, ...(page && { page }), ...(index !== undefined && { index }), windowMode });
         saveBrowserTargetState(undefined, getBrowserScope(session, contextId));
         console.log(JSON.stringify({ session, ...((data && typeof data === 'object') ? data : { data }) }, null, 2));
     }));
@@ -1203,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 = {
@@ -1857,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.')
@@ -2834,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);
     });
@@ -3101,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();
@@ -3479,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.
@@ -1109,8 +1159,8 @@ describe('browser tab targeting commands', () => {
     it('binds an existing Cloak tab by page id into a browser session', async () => {
         const program = createProgram('', '');
         await program.parseAsync(['node', 'webcmd', 'browser', '--session', 'test', 'bind', '--page', 'tab-2']);
-        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 45, session: 'test', surface: 'browser' });
-        expect(mockBindTab).toHaveBeenCalledWith('test', { page: 'tab-2' });
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 45, session: 'test', surface: 'browser', windowMode: 'foreground' });
+        expect(mockBindTab).toHaveBeenCalledWith('test', { page: 'tab-2', windowMode: 'foreground' });
         const out = lastJsonLog();
         expect(out.session).toBe('test');
         expect(out.url).toBe('https://user.example/inbox');
@@ -1118,11 +1168,17 @@ describe('browser tab targeting commands', () => {
     it('binds an existing Cloak tab by index into a browser session', async () => {
         const program = createProgram('', '');
         await program.parseAsync(['node', 'webcmd', 'browser', '--session', 'test', 'bind', '--index', '1']);
-        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 45, session: 'test', surface: 'browser' });
-        expect(mockBindTab).toHaveBeenCalledWith('test', { index: 1 });
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 45, session: 'test', surface: 'browser', windowMode: 'foreground' });
+        expect(mockBindTab).toHaveBeenCalledWith('test', { index: 1, windowMode: 'foreground' });
         const out = lastJsonLog();
         expect(out.session).toBe('test');
     });
+    it('passes background window mode when binding a Cloak tab', async () => {
+        const program = createProgram('', '');
+        await program.parseAsync(['node', 'webcmd', 'browser', '--session', 'test', '--window', 'background', 'bind', '--page', 'tab-2']);
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 45, session: 'test', surface: 'browser', windowMode: 'background' });
+        expect(mockBindTab).toHaveBeenCalledWith('test', { page: 'tab-2', windowMode: 'background' });
+    });
     it('requires an explicit Cloak tab target for bind', async () => {
         const program = createProgram('', '');
         await program.parseAsync(['node', 'webcmd', 'browser', '--session', 'test', 'bind']);
@@ -1237,7 +1293,7 @@ describe('browser tab targeting commands', () => {
     it('unbinds a session through the daemon close-window command', async () => {
         const program = createProgram('', '');
         await program.parseAsync(['node', 'webcmd', 'browser', '--session', 'test', 'unbind']);
-        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 45, session: 'test', surface: 'browser' });
+        expect(mockBrowserConnect).toHaveBeenCalledWith({ timeout: 45, session: 'test', surface: 'browser', windowMode: 'foreground' });
         expect(mockSendCommand).toHaveBeenCalledWith('close-window', { session: 'test', surface: 'browser' });
         const out = lastJsonLog();
         expect(out).toEqual({ unbound: true, session: 'test' });
@@ -2493,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;