@agentrhq/webcmd 0.3.0 → 0.3.1

package/dist/src/commanderAdapter.js

@@ -10,50 +10,20 @@
  * All execution logic lives in execution.ts.
  */
 import { log } from './logger.js';
-import yaml from 'js-yaml';
 import { fullName, getRegistry } from './registry.js';
-import { render as renderOutput } from './output.js';
+import { formatErrorEnvelope, render as renderOutput } from './output.js';
 import { executeCommand, prepareCommandArgs } from './execution.js';
+import { configureCommandSurface, parseOutputFormat } from './command-surface.js';
 import { commandHelpData, formatCommandHelpText, formatCommandListTerm, formatSiteCommandDescription, formatSiteHelpText, getRequestedHelpFormat, renderStructuredHelp, siteHelpData, } from './help.js';
 import { CliError, EXIT_CODES, toEnvelope, } from './errors.js';
-/**
- * Register a single CliCommand as a Commander subcommand.
- */
-export function registerCommandToProgram(siteCmd, cmd) {
+export function registerCommandToProgram(siteCmd, cmd, runtime = {}) {
     if (siteCmd.commands.some((c) => c.name() === cmd.name))
         return;
     const subCmd = siteCmd.command(cmd.name).description(formatSiteCommandDescription(cmd));
     if (cmd.aliases?.length)
         subCmd.aliases(cmd.aliases);
-    // Register positional args first, then named options
-    const positionalArgs = [];
-    for (const arg of cmd.args) {
-        if (arg.positional) {
-            const bracket = arg.required ? `<${arg.name}>` : `[${arg.name}]`;
-            subCmd.argument(bracket, arg.help ?? '');
-            positionalArgs.push(arg);
-        }
-        else {
-            const expectsValue = arg.required || arg.valueRequired;
-            const flag = expectsValue ? `--${arg.name} <value>` : `--${arg.name} [value]`;
-            if (arg.required)
-                subCmd.requiredOption(flag, arg.help ?? '');
-            else if (arg.default != null)
-                subCmd.option(flag, arg.help ?? '', String(arg.default));
-            else
-                subCmd.option(flag, arg.help ?? '');
-        }
-    }
-    subCmd
-        .option('-f, --format <fmt>', 'Output format: table, plain, json, yaml, md, csv', 'table')
-        .option('--trace <mode>', 'Trace capture: off, on, retain-on-failure', 'off')
-        .option('-v, --verbose', 'Debug output', false);
-    if (cmd.browser) {
-        subCmd
-            .option('--window <mode>', 'Browser window mode: foreground or background')
-            .option('--site-session <mode>', 'Adapter site session lifecycle: ephemeral or persistent')
-            .option('--keep-tab <bool>', 'Keep the browser tab lease after the command finishes');
-    }
+    const positionalArgs = cmd.args.filter((arg) => arg.positional);
+    configureCommandSurface(subCmd, cmd);
     const originalHelpInformation = subCmd.helpInformation.bind(subCmd);
     subCmd.helpInformation = ((contextOptions) => {
         const format = getRequestedHelpFormat();
@@ -67,7 +37,8 @@ export function registerCommandToProgram(siteCmd, cmd) {
     subCmd.action(async (...actionArgs) => {
         const actionOpts = actionArgs[positionalArgs.length] ?? {};
         const optionsRecord = typeof actionOpts === 'object' && actionOpts !== null ? actionOpts : {};
-        const startTime = Date.now();
+        const now = runtime.now ?? Date.now;
+        const startTime = now();
         // ── Execute + render ────────────────────────────────────────────────
         try {
             // ── Collect kwargs ────────────────────────────────────────────────
@@ -99,7 +70,7 @@ export function registerCommandToProgram(siteCmd, cmd) {
             }
             const kwargs = prepareCommandArgs(cmd, rawKwargs);
             const verbose = optionsRecord.verbose === true;
-            let format = typeof optionsRecord.format === 'string' ? optionsRecord.format : 'table';
+            let format = parseOutputFormat(optionsRecord.format ?? 'table');
             const formatExplicit = subCmd.getOptionValueSource('format') === 'cli';
             if (verbose)
                 process.env.WEBCMD_VERBOSE = '1';
@@ -122,14 +93,15 @@ export function registerCommandToProgram(siteCmd, cmd) {
             if (verbose && (!result || (Array.isArray(result) && result.length === 0))) {
                 log.warn('Command returned an empty result.');
             }
-            renderOutput(result, {
+            await renderOutput(result, {
                 fmt: format,
                 fmtExplicit: formatExplicit,
                 columns: resolved.columns,
                 title: `${resolved.site}/${resolved.name}`,
-                elapsed: (Date.now() - startTime) / 1000,
+                elapsed: (now() - startTime) / 1000,
                 source: fullName(resolved),
                 footerExtra: resolved.footerExtra?.(kwargs),
+                ...(runtime.stdout ? { stdout: runtime.stdout } : {}),
             });
         }
         catch (err) {
@@ -145,28 +117,13 @@ function resolveExitCode(err) {
     return EXIT_CODES.GENERIC_ERROR;
 }
 // ── Error rendering ─────────────────────────────────────────────────────────
-/** Emit AutoFix hint for repairable adapter errors (skipped if trace already exported). */
-function emitAutoFixHint(envelope, cmdName, traceMode) {
-    if (traceMode === 'on' || traceMode === 'retain-on-failure')
-        return envelope;
-    const runnable = cmdName.replace('/', ' ');
-    return envelope
-        + `# AutoFix: re-run with --trace=retain-on-failure for trace artifact\n`
-        + `# webcmd ${runnable} --trace retain-on-failure\n`;
-}
 function renderError(err, cmdName, verbose, traceMode) {
     const envelope = toEnvelope(err);
     // In verbose mode, include stack trace for debugging
     if (verbose && err instanceof Error && err.stack) {
         envelope.error.stack = err.stack;
     }
-    let output = yaml.dump(envelope, { sortKeys: false, lineWidth: 120, noRefs: true });
-    // Append AutoFix hint for repairable errors
-    const code = envelope.error.code;
-    if (code === 'SELECTOR' || code === 'EMPTY_RESULT' || code === 'ADAPTER_LOAD' || code === 'UNKNOWN') {
-        output = emitAutoFixHint(output, cmdName, traceMode);
-    }
-    process.stderr.write(output);
+    process.stderr.write(formatErrorEnvelope(envelope, { cmdName, traceMode }));
 }
 /**
  * Register all commands from the registry onto a Commander program.

package/dist/src/commanderAdapter.test.js

@@ -12,9 +12,13 @@ vi.mock('./execution.js', async () => {
         executeCommand: mockExecuteCommand,
     };
 });
-vi.mock('./output.js', () => ({
-    render: mockRenderOutput,
-}));
+vi.mock('./output.js', async () => {
+    const actual = await vi.importActual('./output.js');
+    return {
+        ...actual,
+        render: mockRenderOutput,
+    };
+});
 import { registerCommandToProgram } from './commanderAdapter.js';
 describe('commanderAdapter arg passing', () => {
     const cmd = {
@@ -248,6 +252,14 @@ describe('commanderAdapter default formats', () => {
         await program.parseAsync(['node', 'webcmd', 'gemini', 'ask', '--format', 'json']);
         expect(mockRenderOutput).toHaveBeenCalledWith([{ response: 'hello' }], expect.objectContaining({ fmt: 'json' }));
     });
+    it('preserves the legacy fallback for an unknown explicit format', async () => {
+        const program = new Command();
+        const siteCmd = program.command('gemini');
+        registerCommandToProgram(siteCmd, cmd);
+        await program.parseAsync(['node', 'webcmd', 'gemini', 'ask', '--format', 'xml']);
+        expect(mockExecuteCommand).toHaveBeenCalled();
+        expect(mockRenderOutput).toHaveBeenCalledWith([{ response: 'hello' }], expect.objectContaining({ fmt: 'xml', fmtExplicit: true }));
+    });
 });
 describe('commanderAdapter error envelope output', () => {
     const cmd = {

package/dist/src/community-plugin-sync.d.ts

@@ -0,0 +1,11 @@
+import { type PluginManifest } from './plugin-manifest.js';
+export declare const COMMUNITY_PLUGINS_START = "<!-- webcmd-community-plugins:start -->";
+export declare const COMMUNITY_PLUGINS_END = "<!-- webcmd-community-plugins:end -->";
+export interface CommunityPluginOutputs {
+    rootManifest: PluginManifest;
+    readme: string;
+}
+/** Build generated catalog outputs without writing them. */
+export declare function buildCommunityPluginOutputs(repoRoot: string): CommunityPluginOutputs;
+/** Build and write the root manifest and README catalog. */
+export declare function writeCommunityPluginOutputs(repoRoot: string): CommunityPluginOutputs;

package/dist/src/community-plugin-sync.js

@@ -0,0 +1,138 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { validatePluginAuthor, } from './plugin-manifest.js';
+export const COMMUNITY_PLUGINS_START = '<!-- webcmd-community-plugins:start -->';
+export const COMMUNITY_PLUGINS_END = '<!-- webcmd-community-plugins:end -->';
+/** Build generated catalog outputs without writing them. */
+export function buildCommunityPluginOutputs(repoRoot) {
+    const rootManifestPath = path.join(repoRoot, 'webcmd-plugin.json');
+    const rootManifest = readObject(rootManifestPath, 'webcmd-plugin.json');
+    const plugins = readRepositoryPlugins(repoRoot);
+    const readmePath = path.join(repoRoot, 'README.md');
+    const readme = fs.readFileSync(readmePath, 'utf-8');
+    const marketplaces = readExternalMarketplaces(repoRoot);
+    return {
+        rootManifest: { ...rootManifest, plugins },
+        readme: replaceGeneratedSection(readme, renderCommunityPlugins(plugins, marketplaces)),
+    };
+}
+/** Build and write the root manifest and README catalog. */
+export function writeCommunityPluginOutputs(repoRoot) {
+    const generated = buildCommunityPluginOutputs(repoRoot);
+    fs.writeFileSync(path.join(repoRoot, 'webcmd-plugin.json'), `${JSON.stringify(generated.rootManifest, null, 2)}\n`);
+    fs.writeFileSync(path.join(repoRoot, 'README.md'), generated.readme);
+    return generated;
+}
+function readRepositoryPlugins(repoRoot) {
+    const pluginsDir = path.join(repoRoot, 'plugins');
+    const directoryNames = fs.readdirSync(pluginsDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .sort((a, b) => a.localeCompare(b));
+    const plugins = {};
+    for (const directoryName of directoryNames) {
+        const relativeManifestPath = `plugins/${directoryName}/webcmd-plugin.json`;
+        const manifestPath = path.join(repoRoot, relativeManifestPath);
+        const manifest = readObject(manifestPath, relativeManifestPath);
+        const name = requiredString(manifest, 'name', relativeManifestPath);
+        if (name !== directoryName) {
+            throw new Error(`${relativeManifestPath}: name must match directory "${directoryName}"`);
+        }
+        let author;
+        try {
+            author = validatePluginAuthor(manifest.author);
+        }
+        catch (err) {
+            throw new Error(`${relativeManifestPath}: ${errorMessage(err)}`);
+        }
+        plugins[name] = {
+            path: `plugins/${directoryName}`,
+            version: requiredString(manifest, 'version', relativeManifestPath),
+            description: requiredString(manifest, 'description', relativeManifestPath),
+            webcmd: requiredString(manifest, 'webcmd', relativeManifestPath),
+            author,
+        };
+    }
+    return plugins;
+}
+function readExternalMarketplaces(repoRoot) {
+    const catalog = readObject(path.join(repoRoot, 'plugin-catalog.json'), 'plugin-catalog.json');
+    if (!Array.isArray(catalog.sources)) {
+        throw new Error('plugin-catalog.json: sources must be an array');
+    }
+    return catalog.sources.flatMap((source, index) => {
+        if (!isObject(source) || typeof source.source !== 'string') {
+            throw new Error(`plugin-catalog.json: sources[${index}].source must be a string`);
+        }
+        const match = /^github:([\w.-]+)\/([\w.-]+)$/.exec(source.source);
+        if (!match)
+            return [];
+        const repository = `${match[1]}/${match[2]}`;
+        return repository === 'agentrhq/webcmd' ? [] : [repository];
+    }).sort((a, b) => a.localeCompare(b));
+}
+function renderCommunityPlugins(plugins, marketplaces) {
+    const lines = [
+        COMMUNITY_PLUGINS_START,
+        '### Community plugins',
+        '',
+        '| Plugin | Description | Author |',
+        '| --- | --- | --- |',
+    ];
+    for (const [name, plugin] of Object.entries(plugins)) {
+        const author = plugin.author;
+        lines.push(`| [\`${markdownCell(name)}\`](./plugins/${name}/) | ${markdownCell(plugin.description)} | [${markdownCell(author.name)}](https://github.com/${author.handle}) |`);
+    }
+    if (marketplaces.length > 0) {
+        lines.push('', '### Plugin marketplaces', '', '| Marketplace |', '| --- |');
+        for (const marketplace of marketplaces) {
+            lines.push(`| [${markdownCell(marketplace)}](https://github.com/${marketplace}) |`);
+        }
+    }
+    lines.push(COMMUNITY_PLUGINS_END);
+    return lines.join('\n');
+}
+function replaceGeneratedSection(readme, section) {
+    const start = readme.indexOf(COMMUNITY_PLUGINS_START);
+    const end = readme.indexOf(COMMUNITY_PLUGINS_END);
+    if (start < 0 || end < start) {
+        throw new Error(`README.md: expected ${COMMUNITY_PLUGINS_START} and ${COMMUNITY_PLUGINS_END}`);
+    }
+    if (readme.indexOf(COMMUNITY_PLUGINS_START, start + COMMUNITY_PLUGINS_START.length) >= 0
+        || readme.indexOf(COMMUNITY_PLUGINS_END, end + COMMUNITY_PLUGINS_END.length) >= 0) {
+        throw new Error('README.md: community plugin markers must appear exactly once');
+    }
+    return `${readme.slice(0, start)}${section}${readme.slice(end + COMMUNITY_PLUGINS_END.length)}`;
+}
+function readObject(filePath, label) {
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch (err) {
+        throw new Error(`${label}: malformed JSON (${errorMessage(err)})`);
+    }
+    if (!isObject(parsed))
+        throw new Error(`${label}: expected an object`);
+    return parsed;
+}
+function requiredString(value, key, label) {
+    const result = typeof value[key] === 'string' ? value[key].trim() : '';
+    if (!result)
+        throw new Error(`${label}: ${key} must be a non-empty string`);
+    return result;
+}
+function markdownCell(value) {
+    return value
+        .replace(/\\/g, '\\\\')
+        .replace(/\|/g, '\\|')
+        .replace(/\[/g, '\\[')
+        .replace(/\]/g, '\\]')
+        .replace(/\r?\n/g, ' ');
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/src/community-plugin-sync.test.d.ts

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

package/dist/src/community-plugin-sync.test.js

@@ -0,0 +1,123 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { buildCommunityPluginOutputs, writeCommunityPluginOutputs } from './community-plugin-sync.js';
+const START_MARKER = '<!-- webcmd-community-plugins:start -->';
+const END_MARKER = '<!-- webcmd-community-plugins:end -->';
+describe('community plugin sync', () => {
+    let repoRoot;
+    beforeEach(() => {
+        repoRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'webcmd-plugin-generator-'));
+        writeJson('webcmd-plugin.json', {
+            name: 'webcmd',
+            version: '0.2.0',
+            description: 'Webcmd plugin collection',
+            webcmd: '>=0.2.0',
+            plugins: { stale: { path: 'plugins/stale' } },
+        });
+        writeJson('plugin-catalog.json', {
+            version: 1,
+            sources: [
+                {
+                    id: 'agentrhq/webcmd',
+                    source: 'github:agentrhq/webcmd',
+                    manifestUrl: 'https://raw.githubusercontent.com/agentrhq/webcmd/main/webcmd-plugin.json',
+                },
+                {
+                    id: 'other/plugins',
+                    source: 'github:other/plugins',
+                    manifestUrl: 'https://raw.githubusercontent.com/other/plugins/main/webcmd-plugin.json',
+                },
+            ],
+        });
+        fs.writeFileSync(path.join(repoRoot, 'README.md'), [
+            '# Webcmd',
+            '',
+            '## Plugins',
+            '',
+            START_MARKER,
+            'old generated content',
+            END_MARKER,
+            '',
+            '## Writing adapters',
+            '',
+        ].join('\n'));
+        writePlugin('zeta', {
+            name: 'zeta',
+            version: '0.1.0',
+            description: 'Last plugin',
+            webcmd: '>=0.2.0',
+            author: { name: 'Zed', handle: 'zed-user' },
+        });
+        writePlugin('alpha', {
+            name: 'alpha',
+            version: '1.0.0',
+            description: 'Forecasts | alerts',
+            webcmd: '>=0.3.0',
+            author: { name: 'Alice', handle: 'alice' },
+        });
+    });
+    afterEach(() => {
+        fs.rmSync(repoRoot, { recursive: true, force: true });
+    });
+    it('builds a sorted root manifest and three-column README catalog', () => {
+        const result = buildCommunityPluginOutputs(repoRoot);
+        expect(Object.keys(result.rootManifest.plugins ?? {})).toEqual(['alpha', 'zeta']);
+        expect(result.rootManifest).toMatchObject({
+            name: 'webcmd',
+            version: '0.2.0',
+            plugins: {
+                alpha: {
+                    path: 'plugins/alpha',
+                    version: '1.0.0',
+                    description: 'Forecasts | alerts',
+                    webcmd: '>=0.3.0',
+                    author: { name: 'Alice', handle: 'alice' },
+                },
+            },
+        });
+        expect(result.readme).toContain('| Plugin | Description | Author |');
+        expect(result.readme).toContain('| [`alpha`](./plugins/alpha/) | Forecasts \\| alerts | [Alice](https://github.com/alice) |');
+        expect(result.readme.indexOf('`alpha`')).toBeLessThan(result.readme.indexOf('`zeta`'));
+        expect(result.readme).toContain('### Plugin marketplaces');
+        expect(result.readme).toContain('[other/plugins](https://github.com/other/plugins)');
+        expect(result.readme).not.toContain('[agentrhq/webcmd](https://github.com/agentrhq/webcmd)');
+    });
+    it('writes the generated files', () => {
+        const result = writeCommunityPluginOutputs(repoRoot);
+        expect(JSON.parse(fs.readFileSync(path.join(repoRoot, 'webcmd-plugin.json'), 'utf-8'))).toEqual(result.rootManifest);
+        expect(fs.readFileSync(path.join(repoRoot, 'README.md'), 'utf-8')).toBe(result.readme);
+    });
+    it('fails with the plugin path when author metadata is missing', () => {
+        writePlugin('alpha', {
+            name: 'alpha',
+            version: '1.0.0',
+            description: 'Forecasts',
+            webcmd: '>=0.3.0',
+        });
+        expect(() => buildCommunityPluginOutputs(repoRoot)).toThrow('plugins/alpha/webcmd-plugin.json: Invalid author');
+    });
+    it('fails with the plugin path for malformed JSON', () => {
+        fs.writeFileSync(path.join(repoRoot, 'plugins/alpha/webcmd-plugin.json'), '{broken');
+        expect(() => buildCommunityPluginOutputs(repoRoot)).toThrow('plugins/alpha/webcmd-plugin.json: malformed JSON');
+    });
+    it('rejects directory and manifest name mismatches', () => {
+        writePlugin('alpha', {
+            name: 'different',
+            version: '1.0.0',
+            description: 'Forecasts',
+            webcmd: '>=0.3.0',
+            author: { name: 'Alice', handle: 'alice' },
+        });
+        expect(() => buildCommunityPluginOutputs(repoRoot)).toThrow('plugins/alpha/webcmd-plugin.json: name must match directory "alpha"');
+    });
+    function writeJson(relativePath, value) {
+        const filePath = path.join(repoRoot, relativePath);
+        fs.mkdirSync(path.dirname(filePath), { recursive: true });
+        fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`);
+    }
+    function writePlugin(name, manifest) {
+        writeJson(`plugins/${name}/webcmd-plugin.json`, manifest);
+    }
+});

package/dist/src/completion-fast.d.ts

@@ -16,7 +16,7 @@ export declare function hasAllManifests(manifestPaths: string[]): boolean;
  * bypassing full CLI discovery and adapter loading.
  */
 export declare function getCompletionsFromManifest(words: string[], cursor: number, manifestPaths: string[]): string[];
-/**
- * Print completion script for the given shell. Returns true if handled, false if unknown shell.
- */
-export declare function printCompletionScriptFast(shell: string): boolean;
+/** Return a generated shell script without taking ownership of stdout. */
+export declare function getCompletionScriptFast(shell: string): string | undefined;
+/** Return a supported shell script or the canonical local completion error. */
+export declare function requireCompletionScriptFast(shell: string): string;

package/dist/src/completion-fast.js

@@ -5,6 +5,8 @@
  * It only reads pre-compiled cli-manifest.json files synchronously.
  */
 import * as fs from 'node:fs';
+import { getCommandCompletionCandidates } from './command-presentation.js';
+import { CliError } from './errors.js';
 import { BUILTIN_COMMANDS, bashCompletionScript, zshCompletionScript, fishCompletionScript, } from './completion-shared.js';
 /**
  * Returns true only if ALL manifest files exist and are readable.
@@ -29,32 +31,9 @@ export function hasAllManifests(manifestPaths) {
  */
 export function getCompletionsFromManifest(words, cursor, manifestPaths) {
     const entries = loadManifestEntries(manifestPaths);
-    if (entries === null) {
+    if (entries === null)
         return [];
-    }
-    if (cursor <= 1) {
-        const sites = new Set();
-        for (const entry of entries) {
-            sites.add(entry.site);
-        }
-        return [...BUILTIN_COMMANDS, ...sites].sort();
-    }
-    const site = words[0];
-    if (BUILTIN_COMMANDS.includes(site)) {
-        return [];
-    }
-    if (cursor === 2) {
-        const subcommands = [];
-        for (const entry of entries) {
-            if (entry.site === site) {
-                subcommands.push(entry.name);
-                if (entry.aliases?.length)
-                    subcommands.push(...entry.aliases);
-            }
-        }
-        return [...new Set(subcommands)].sort();
-    }
-    return [];
+    return getCommandCompletionCandidates(entries, words, cursor, BUILTIN_COMMANDS);
 }
 // ── Shell script generators (re-exported from shared, no registry dependency) ───────
 const SHELL_SCRIPTS = {
@@ -62,15 +41,17 @@ const SHELL_SCRIPTS = {
     zsh: zshCompletionScript,
     fish: fishCompletionScript,
 };
-/**
- * Print completion script for the given shell. Returns true if handled, false if unknown shell.
- */
-export function printCompletionScriptFast(shell) {
-    const gen = SHELL_SCRIPTS[shell];
-    if (!gen)
-        return false;
-    process.stdout.write(gen());
-    return true;
+/** Return a generated shell script without taking ownership of stdout. */
+export function getCompletionScriptFast(shell) {
+    return SHELL_SCRIPTS[shell]?.();
+}
+/** Return a supported shell script or the canonical local completion error. */
+export function requireCompletionScriptFast(shell) {
+    const script = getCompletionScriptFast(shell);
+    if (script === undefined) {
+        throw new CliError('UNSUPPORTED_SHELL', `Unsupported shell: ${shell}. Supported: bash, zsh, fish`);
+    }
+    return script;
 }
 function loadManifestEntries(manifestPaths) {
     const entries = [];

package/dist/src/completion-shared.d.ts

@@ -4,10 +4,14 @@
  * This module MUST remain lightweight (no registry, no discovery imports).
  * Both completion.ts (full path) and completion-fast.ts (manifest path) import from here.
  */
+import type { RootHelpPresentation } from './command-presentation.js';
 /**
  * Built-in (non-dynamic) top-level commands.
  */
 export declare const BUILTIN_COMMANDS: string[];
+export declare const LOCAL_ONLY_COMMAND_HELP = "Run `webcmd setup` and choose local mode to use local-only commands.";
+export declare const HOSTED_ROOT_HELP: RootHelpPresentation;
+export declare const HOSTED_BUILTIN_COMMANDS: string[];
 export declare function bashCompletionScript(): string;
 export declare function zshCompletionScript(): string;
 export declare function fishCompletionScript(): string;

package/dist/src/completion-shared.js

@@ -20,6 +20,44 @@ export const BUILTIN_COMMANDS = [
     'external',
     'completion',
 ];
+export const LOCAL_ONLY_COMMAND_HELP = 'Run `webcmd setup` and choose local mode to use local-only commands.';
+export const HOSTED_ROOT_HELP = {
+    description: 'Make any website your CLI. Zero setup. AI-powered.',
+    usage: [
+        `${CLI_COMMAND} <site> <command> [args] [options]`,
+        `${CLI_COMMAND} browser <session> <command> [args] [options]`,
+        `${CLI_COMMAND} list [options]`,
+        `${CLI_COMMAND} setup`,
+    ],
+    options: [
+        { flags: '--profile <name>', description: 'Browser profile/context alias for browser runtime commands' },
+        { flags: '-V, --version', description: 'Output the version number' },
+        { flags: '-h, --help', description: 'Display help for command' },
+    ],
+    commands: [
+        { name: 'browser', description: 'Browser control through a hosted browser session' },
+        { name: 'completion <shell>', description: 'Output a shell completion script' },
+        { name: 'list', description: 'List all available hosted CLI commands' },
+        { name: 'setup', description: 'Configure local or hosted mode' },
+    ],
+    localOnlyCommands: [
+        { name: 'adapter', description: 'Manage adapters installed on this computer' },
+        { name: 'antigravity', description: 'Run the local Antigravity proxy' },
+        { name: 'auth', description: 'Inspect credentials in the local browser runtime' },
+        { name: 'convention-audit', description: 'Audit adapter source files on this computer' },
+        { name: 'daemon', description: 'Manage the local Webcmd daemon' },
+        { name: 'doctor', description: 'Diagnose local browser bridge connectivity' },
+        { name: 'external', description: 'Manage local CLI passthrough commands' },
+        { name: 'plugin', description: 'Manage plugins installed on this computer' },
+        { name: 'profile', description: 'Manage profiles in the local browser runtime' },
+        { name: 'skills', description: 'Manage bundled skills on this computer' },
+        { name: 'validate', description: 'Validate local CLI definitions' },
+        { name: 'verify', description: 'Validate and smoke-test local adapters' },
+    ],
+    localOnlyExplanation: LOCAL_ONLY_COMMAND_HELP,
+};
+export const HOSTED_BUILTIN_COMMANDS = HOSTED_ROOT_HELP.commands
+    .map((command) => command.name.split(/\s/, 1)[0]);
 // ── Shell script generators ────────────────────────────────────────────────
 export function bashCompletionScript() {
     return `# Bash completion for ${CLI_COMMAND}

package/dist/src/completion.js

@@ -6,6 +6,7 @@
  *  - Dynamic completion logic that returns candidates for the current cursor position
  */
 import { getRegistry } from './registry.js';
+import { getCommandCompletionCandidates, toPresentableCommand } from './command-presentation.js';
 import { CliError } from './errors.js';
 import { BUILTIN_COMMANDS, bashCompletionScript, zshCompletionScript, fishCompletionScript, } from './completion-shared.js';
 // Re-export shell scripts so existing callers (cli.ts) don't break
@@ -19,33 +20,8 @@ export { bashCompletionScript, zshCompletionScript, fishCompletionScript };
  * @param cursor - 1-based position of the word being completed (1 = first arg)
  */
 export function getCompletions(words, cursor) {
-    // cursor === 1 → completing the first argument (site name or built-in command)
-    if (cursor <= 1) {
-        const sites = new Set();
-        for (const [, cmd] of getRegistry()) {
-            sites.add(cmd.site);
-        }
-        return [...BUILTIN_COMMANDS, ...sites].sort();
-    }
-    const site = words[0];
-    // If the first word is a built-in command, no further completion
-    if (BUILTIN_COMMANDS.includes(site)) {
-        return [];
-    }
-    // cursor === 2 → completing the sub-command name under a site
-    if (cursor === 2) {
-        const subcommands = [];
-        for (const [, cmd] of getRegistry()) {
-            if (cmd.site === site) {
-                subcommands.push(cmd.name);
-                if (cmd.aliases?.length)
-                    subcommands.push(...cmd.aliases);
-            }
-        }
-        return [...new Set(subcommands)].sort();
-    }
-    // cursor >= 3 → no further completion
-    return [];
+    const commands = [...new Set(getRegistry().values())].map(toPresentableCommand);
+    return getCommandCompletionCandidates(commands, words, cursor, BUILTIN_COMMANDS);
 }
 // ── Shell script generators ────────────────────────────────────────────────
 /**