@agentrhq/webcmd 0.3.0 → 0.3.2

package/dist/src/help.js

@@ -1,54 +1,6 @@
 import yaml from 'js-yaml';
-import { fullName } from './registry.js';
-import { formatCommandExample } from './serialization.js';
 import { CLI_COMMAND } from './brand.js';
-const COMMON_OPTIONS = [
-    {
-        flags: '-f, --format <fmt>',
-        name: 'format',
-        help: 'Output format: table, plain, json, yaml, md, csv',
-        default: 'table',
-        choices: ['table', 'plain', 'json', 'yaml', 'md', 'csv'],
-    },
-    {
-        flags: '--trace <mode>',
-        name: 'trace',
-        help: 'Trace capture: off, on, retain-on-failure',
-        default: 'off',
-        choices: ['off', 'on', 'retain-on-failure'],
-    },
-    {
-        flags: '-v, --verbose',
-        name: 'verbose',
-        help: 'Debug output',
-        default: false,
-    },
-    {
-        flags: '-h, --help',
-        name: 'help',
-        help: 'display help for command',
-    },
-];
-const BROWSER_COMMON_OPTIONS = [
-    {
-        flags: '--window <mode>',
-        name: 'window',
-        help: 'Browser window mode: foreground or background',
-        choices: ['foreground', 'background'],
-    },
-    {
-        flags: '--site-session <mode>',
-        name: 'site-session',
-        help: 'Adapter site session lifecycle: ephemeral or persistent',
-        choices: ['ephemeral', 'persistent'],
-    },
-    {
-        flags: '--keep-tab <bool>',
-        name: 'keep-tab',
-        help: 'Keep the browser tab lease after the command finishes',
-        choices: ['true', 'false'],
-    },
-];
+import { classifyAdapterDomain, commandHelpData as buildCommandHelpData, formatBrowserCommonOptionsHelp, formatCommandHelp, formatCommandListTerm as buildCommandListTerm, formatCommonOptionsHelp, formatSiteCommandDescription as buildSiteCommandDescription, formatSiteHelp, formatRootHelp, siteHelpData as buildSiteHelpData, toPresentableCommand, wrapCommaList as wrapPresentationCommaList, } from './command-presentation.js';
 function normalizeStructuredHelpFormat(value) {
     const normalized = value?.toLowerCase();
     if (normalized === 'yaml' || normalized === 'yml')
@@ -78,41 +30,49 @@ export function renderStructuredHelp(data, format) {
     return yaml.dump(data, { sortKeys: false, lineWidth: 120, noRefs: true });
 }
 export function wrapCommaList(items, opts = {}) {
-    const width = Math.max(opts.width ?? process.stdout.columns ?? 100, 40);
-    const indent = opts.indent ?? '  ';
-    const sorted = [...items].sort((a, b) => a.localeCompare(b));
-    const lines = [];
-    let line = indent;
-    sorted.forEach((item, index) => {
-        const token = `${item}${index < sorted.length - 1 ? ',' : ''}`;
-        const prefix = line === indent ? '' : ' ';
-        if (line.length + prefix.length + token.length > width && line.trim()) {
-            lines.push(line);
-            line = `${indent}${token}`;
-        }
-        else {
-            line += `${prefix}${token}`;
-        }
-    });
-    if (line.trim())
-        lines.push(line);
-    return lines.join('\n');
-}
-function isLocalIpDomain(domain) {
-    if (domain === '::1' || domain === '[::1]')
-        return true;
-    const parts = domain.split('.');
-    if (parts.length !== 4)
-        return false;
-    return parts.every(part => /^\d+$/.test(part) && Number(part) >= 0 && Number(part) <= 255)
-        && Number(parts[0]) === 127;
+    return wrapPresentationCommaList(items, opts);
 }
 export function classifyAdapter(domain) {
-    if (!domain)
-        return 'site';
-    if (isLocalIpDomain(domain))
-        return 'app';
-    return domain.includes('.') ? 'site' : 'app';
+    return classifyAdapterDomain(domain);
+}
+const installedRootHelpPresentations = new WeakMap();
+export function buildRootHelpPresentation(program, groups) {
+    const adapterNames = new Set([...groups.external.map((cli) => cli.name), ...groups.apps, ...groups.sites]);
+    const commanderHelp = program.createHelp();
+    const options = commanderHelp.visibleOptions(program).map((option) => ({
+        flags: option.flags,
+        description: option.description,
+    }));
+    return {
+        description: program.description(),
+        usage: [`${program.name()} [options] [command]`],
+        baseText: commanderHelp.formatHelp(program, commanderHelp),
+        options,
+        commands: program.commands
+            .filter((command) => !adapterNames.has(command.name()))
+            .map((command) => ({ name: command.name(), description: command.description() })),
+        groups: [
+            { label: `External CLIs (${groups.external.length})`, items: groups.external.map((cli) => cli.label) },
+            { label: `App adapters (${groups.apps.length})`, items: groups.apps },
+            { label: `Site adapters (${groups.sites.length})`, items: groups.sites },
+        ],
+        footer: [
+            `Run '${CLI_COMMAND} list' for full command details, or '${CLI_COMMAND} <site> --help' to inspect one site.`,
+            `Agent tip: use '${CLI_COMMAND} <site> --help -f yaml' for all command args/options in one structured response.`,
+        ],
+    };
+}
+export function getInstalledRootHelpPresentation(command) {
+    return installedRootHelpPresentations.get(command);
+}
+export function installRootPresentationHelp(command, data, presentation) {
+    installedRootHelpPresentations.set(command, presentation);
+    command.helpInformation = (() => {
+        const format = getRequestedHelpFormat();
+        if (format)
+            return renderStructuredHelp(data(), format);
+        return formatRootHelp(presentation);
+    });
 }
 function formatGroupSection(label, names) {
     if (names.length === 0)
@@ -136,27 +96,6 @@ export function formatRootAdapterHelpText(groups) {
     lines.push('');
     return lines.join('\n');
 }
-function compactArg(arg) {
-    return {
-        name: arg.name,
-        ...(arg.type && arg.type !== 'string' ? { type: arg.type } : {}),
-        ...(arg.positional ? { positional: true } : {}),
-        ...(arg.required ? { required: true } : {}),
-        ...(arg.valueRequired ? { valueRequired: true } : {}),
-        ...(arg.default !== undefined ? { default: arg.default } : {}),
-        ...(arg.choices?.length ? { choices: arg.choices } : {}),
-        ...(arg.help ? { help: arg.help } : {}),
-    };
-}
-function compactCommonOption(option) {
-    return {
-        name: option.name,
-        flags: option.flags,
-        help: option.help,
-        ...('default' in option ? { default: option.default } : {}),
-        ...('choices' in option ? { choices: option.choices } : {}),
-    };
-}
 function compactCommanderArgument(arg) {
     return {
         name: arg.name(),
@@ -343,49 +282,8 @@ export function installCommanderNamespaceStructuredHelp(namespaceRoot, opts = {}
         }
     }
 }
-function positionals(cmd) {
-    return cmd.args.filter(arg => arg.positional);
-}
-function commandOptions(cmd) {
-    return cmd.args.filter(arg => !arg.positional);
-}
-function formatPositionals(args) {
-    return args
-        .map(arg => arg.required ? `<${arg.name}>` : `[${arg.name}]`)
-        .join(' ');
-}
-function formatCommandOptionTerm(arg) {
-    if (arg.required || arg.valueRequired)
-        return `--${arg.name} <value>`;
-    return `--${arg.name} [value]`;
-}
 export function formatCommandListTerm(cmd) {
-    const positionalText = formatPositionals(positionals(cmd));
-    const optionText = commandOptions(cmd).length > 0 ? ' [options]' : '';
-    return `${cmd.name}${positionalText ? ` ${positionalText}` : ''}${optionText}`;
-}
-function formatUsage(cmd) {
-    const positionalText = formatPositionals(positionals(cmd));
-    return `${CLI_COMMAND} ${cmd.site} ${cmd.name}${positionalText ? ` ${positionalText}` : ''} [options]`;
-}
-function compactCommand(cmd) {
-    return {
-        name: cmd.name,
-        command: `${CLI_COMMAND} ${cmd.site} ${cmd.name}`,
-        usage: formatUsage(cmd),
-        access: cmd.access,
-        description: cmd.description,
-        browser: !!cmd.browser,
-        ...(cmd.domain ? { domain: cmd.domain } : {}),
-        ...(cmd.aliases?.length ? { aliases: cmd.aliases } : {}),
-        positionals: positionals(cmd).map(compactArg),
-        command_options: commandOptions(cmd).map(compactArg),
-        ...(cmd.browser ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
-        example: formatCommandExample(cmd),
-        ...(cmd.siteSession ? { siteSession: cmd.siteSession } : {}),
-        ...(cmd.defaultFormat ? { defaultFormat: cmd.defaultFormat } : {}),
-        ...(cmd.columns?.length ? { columns: cmd.columns } : {}),
-    };
+    return buildCommandListTerm(toPresentableCommand(cmd));
 }
 export function rootHelpData(program, groups) {
     const adapterNames = new Set([...groups.external.map(cli => cli.name), ...groups.apps, ...groups.sites]);
@@ -421,124 +319,22 @@ export function rootHelpData(program, groups) {
     };
 }
 export function siteHelpData(site, commands) {
-    const unique = [...new Map(commands.map(cmd => [fullName(cmd), cmd])).values()]
-        .sort((a, b) => a.name.localeCompare(b.name));
-    return {
-        site,
-        command_count: unique.length,
-        commands: unique.map(cmd => compactCommand(cmd)),
-        common_options: COMMON_OPTIONS.map(compactCommonOption),
-        ...(unique.some(cmd => cmd.browser) ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
-        next: [
-            `${CLI_COMMAND} ${site} <command> --help -f yaml`,
-            `${CLI_COMMAND} ${site} <command> -f yaml`,
-        ],
-    };
+    return buildSiteHelpData(site, commands.map(toPresentableCommand));
 }
 export function commandHelpData(cmd) {
-    return {
-        site: cmd.site,
-        ...compactCommand(cmd),
-        common_options: COMMON_OPTIONS.map(compactCommonOption),
-        ...(cmd.browser ? { browser_common_options: BROWSER_COMMON_OPTIONS.map(compactCommonOption) } : {}),
-        output_formats: ['table', 'plain', 'yaml', 'json', 'md', 'csv'],
-    };
-}
-function formatRows(rows) {
-    if (rows.length === 0)
-        return [];
-    const width = Math.min(Math.max(...rows.map(([left]) => left.length)), 34);
-    return rows.map(([left, right]) => `  ${left.padEnd(width + 2)}${right}`);
-}
-function formatArgHelp(arg) {
-    const parts = [];
-    if (arg.help)
-        parts.push(arg.help);
-    if (arg.default !== undefined)
-        parts.push(`default: ${arg.default}`);
-    if (arg.choices?.length)
-        parts.push(`choices: ${arg.choices.join(', ')}`);
-    return parts.join('  ');
+    return buildCommandHelpData(toPresentableCommand(cmd));
 }
 export function formatCommonOptionsHelpText() {
-    const rows = COMMON_OPTIONS.map(option => {
-        const details = [option.help];
-        if ('default' in option)
-            details.push(`default: ${option.default}`);
-        if ('choices' in option)
-            details.push(`choices: ${option.choices.join(', ')}`);
-        return [option.flags, details.join('  ')];
-    });
-    return ['Common options:', ...formatRows(rows)].join('\n');
+    return formatCommonOptionsHelp();
 }
 export function formatBrowserCommonOptionsHelpText() {
-    const rows = BROWSER_COMMON_OPTIONS.map(option => {
-        const details = [option.help];
-        if ('choices' in option)
-            details.push(`choices: ${option.choices.join(', ')}`);
-        return [option.flags, details.join('  ')];
-    });
-    return ['Browser common options:', ...formatRows(rows)].join('\n');
+    return formatBrowserCommonOptionsHelp();
 }
 export function formatSiteHelpText(site, commands) {
-    const unique = [...new Map(commands.map(cmd => [fullName(cmd), cmd])).values()]
-        .sort((a, b) => a.name.localeCompare(b.name));
-    const lines = [
-        `Usage: ${CLI_COMMAND} ${site} <command> [args] [options]`,
-        '',
-        wrapCommaList(unique.map(cmd => cmd.name), { indent: '' }),
-        '',
-        'Commands:',
-        ...formatRows(unique.map(cmd => [formatCommandListTerm(cmd), formatSiteCommandDescription(cmd)])),
-        '',
-        formatCommonOptionsHelpText(),
-        ...(unique.some(cmd => cmd.browser) ? ['', formatBrowserCommonOptionsHelpText()] : []),
-        '',
-        `Agent tip: use '${CLI_COMMAND} ${site} --help -f yaml' to get all command args/options in one structured response.`,
-        '',
-    ];
-    return lines.join('\n');
+    return formatSiteHelp(site, commands.map(toPresentableCommand));
 }
 export function formatCommandHelpText(cmd) {
-    const lines = [
-        `Usage: ${formatUsage(cmd)}`,
-        '',
-        cmd.description,
-        '',
-    ];
-    const positionalRows = positionals(cmd).map(arg => [
-        arg.name,
-        formatArgHelp(arg),
-    ]);
-    if (positionalRows.length) {
-        lines.push('Arguments:', ...formatRows(positionalRows), '');
-    }
-    const optionRows = commandOptions(cmd).map(arg => [
-        formatCommandOptionTerm(arg),
-        formatArgHelp(arg),
-    ]);
-    if (optionRows.length) {
-        lines.push('Command options:', ...formatRows(optionRows), '');
-    }
-    lines.push(formatCommonOptionsHelpText(), '');
-    if (cmd.browser)
-        lines.push(formatBrowserCommonOptionsHelpText(), '');
-    const meta = [];
-    meta.push(`Access: ${cmd.access}`);
-    meta.push(`Browser: ${cmd.browser ? 'yes' : 'no'}`);
-    if (cmd.domain)
-        meta.push(`Domain: ${cmd.domain}`);
-    if (cmd.defaultFormat)
-        meta.push(`Default format: ${cmd.defaultFormat}`);
-    if (cmd.aliases?.length)
-        meta.push(`Aliases: ${cmd.aliases.join(', ')}`);
-    lines.push(meta.join(' | '));
-    lines.push(`Example: ${formatCommandExample(cmd)}`);
-    if (cmd.columns?.length)
-        lines.push(`Output columns: ${cmd.columns.join(', ')}`);
-    lines.push("Agent tip: use '--help -f yaml' for structured args/options.");
-    lines.push('');
-    return lines.join('\n');
+    return formatCommandHelp(toPresentableCommand(cmd));
 }
 export function installStructuredHelp(command, data, textSuffix) {
     const original = command.helpInformation.bind(command);
@@ -551,6 +347,5 @@ export function installStructuredHelp(command, data, textSuffix) {
     });
 }
 export function formatSiteCommandDescription(cmd) {
-    const access = cmd.access === 'write' ? '[write]' : '[read]';
-    return `${access} ${cmd.description}`;
+    return buildSiteCommandDescription(toPresentableCommand(cmd));
 }

package/dist/src/help.test.js

@@ -1,5 +1,19 @@
 import { describe, it, expect } from 'vitest';
-import { classifyAdapter, formatRootAdapterHelpText } from './help.js';
+import { classifyAdapter, commandHelpData, formatCommandHelpText, formatRootAdapterHelpText, formatSiteHelpText, siteHelpData, } from './help.js';
+import { commandHelpData as sharedCommandHelpData, formatCommandHelp, formatSiteHelp, siteHelpData as sharedSiteHelpData, toPresentableCommand, } from './command-presentation.js';
+import { Strategy } from './registry.js';
+const presentableFixture = {
+    site: 'github',
+    name: 'issues',
+    aliases: ['issue-list'],
+    description: 'List repository issues',
+    access: 'read',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [{ name: 'owner', positional: true, required: true, help: 'Repository owner' }],
+    columns: ['number', 'title'],
+    domain: 'github.com',
+};
 describe('classifyAdapter', () => {
     it('classifies DNS-style domains as site', () => {
         expect(classifyAdapter('www.youtube.com')).toBe('site');
@@ -56,3 +70,15 @@ describe('formatRootAdapterHelpText', () => {
         expect(text).toContain("'webcmd <site> --help -f yaml'");
     });
 });
+describe('shared presentation delegation', () => {
+    it('keeps local site and command text byte-identical to the pure model', () => {
+        const presentable = toPresentableCommand(presentableFixture);
+        expect(formatSiteHelpText('github', [presentableFixture])).toBe(formatSiteHelp('github', [presentable]));
+        expect(formatCommandHelpText(presentableFixture)).toBe(formatCommandHelp(presentable));
+    });
+    it('keeps local structured help byte-identical to the pure model', () => {
+        const presentable = toPresentableCommand(presentableFixture);
+        expect(siteHelpData('github', [presentableFixture])).toEqual(sharedSiteHelpData('github', [presentable]));
+        expect(commandHelpData(presentableFixture)).toEqual(sharedCommandHelpData(presentable));
+    });
+});

package/dist/src/hosted/args.d.ts

@@ -1,9 +1,4 @@
+import { type ParsedCommandSurface } from '../command-surface.js';
 import type { HostedCommand } from './types.js';
-export interface ParsedHostedInvocation {
-    args: Record<string, unknown>;
-    format: string;
-    trace: string;
-    profile?: string;
-    help: boolean;
-}
+export type ParsedHostedInvocation = ParsedCommandSurface;
 export declare function parseHostedInvocation(command: HostedCommand, argv: string[]): ParsedHostedInvocation;

package/dist/src/hosted/args.js

@@ -1,101 +1,4 @@
-import { ArgumentError } from '../errors.js';
+import { parseCommandSurface } from '../command-surface.js';
 export function parseHostedInvocation(command, argv) {
-    const args = {};
-    const positional = command.args.filter((arg) => arg.positional);
-    const named = new Map(command.args.filter((arg) => !arg.positional).map((arg) => [arg.name, arg]));
-    let positionalIndex = 0;
-    let format = String(command.defaultFormat || 'table');
-    let trace = 'off';
-    let profile;
-    let help = false;
-    for (let i = 0; i < argv.length; i++) {
-        const token = argv[i];
-        if (token === '--') {
-            for (const rest of argv.slice(i + 1)) {
-                const arg = positional[positionalIndex++];
-                if (!arg)
-                    throw new ArgumentError(`Unexpected positional argument: ${rest}`);
-                args[arg.name] = coerceValue(rest, arg.type);
-            }
-            break;
-        }
-        if (token === '-h' || token === '--help') {
-            help = true;
-            continue;
-        }
-        if (token === '-f' || token === '--format') {
-            format = readValue(argv, ++i, token);
-            continue;
-        }
-        if (token === '--trace') {
-            trace = readValue(argv, ++i, token);
-            continue;
-        }
-        if (token === '--profile') {
-            profile = readValue(argv, ++i, token);
-            continue;
-        }
-        if (token.startsWith('--')) {
-            const eqIndex = token.indexOf('=');
-            const rawName = token.slice(2, eqIndex === -1 ? undefined : eqIndex);
-            const arg = named.get(rawName);
-            if (!arg)
-                throw new ArgumentError(`Unknown option for hosted command ${command.command}: --${rawName}`);
-            const inlineValue = eqIndex === -1 ? undefined : token.slice(eqIndex + 1);
-            if (arg.type === 'bool' || arg.type === 'boolean') {
-                args[arg.name] = inlineValue === undefined ? true : coerceValue(inlineValue, arg.type);
-            }
-            else {
-                args[arg.name] = coerceValue(inlineValue ?? readValue(argv, ++i, token), arg.type);
-            }
-            continue;
-        }
-        const arg = positional[positionalIndex++];
-        if (!arg)
-            throw new ArgumentError(`Unexpected positional argument: ${token}`);
-        args[arg.name] = coerceValue(token, arg.type);
-    }
-    for (const arg of command.args) {
-        if (args[arg.name] === undefined && arg.default !== undefined)
-            args[arg.name] = arg.default;
-        if (arg.required && args[arg.name] === undefined) {
-            throw new ArgumentError(`Missing required argument for hosted command ${command.command}: ${arg.name}`);
-        }
-    }
-    return {
-        args,
-        format,
-        trace,
-        ...(profile ? { profile } : {}),
-        help,
-    };
-}
-function readValue(argv, index, flag) {
-    const value = argv[index];
-    if (value === undefined || value.startsWith('--')) {
-        throw new ArgumentError(`${flag} requires a value.`);
-    }
-    return value;
-}
-function coerceValue(value, type) {
-    if (type === 'int') {
-        const parsed = Number.parseInt(value, 10);
-        if (!Number.isFinite(parsed))
-            throw new ArgumentError(`Expected integer value, got "${value}".`);
-        return parsed;
-    }
-    if (type === 'number') {
-        const parsed = Number(value);
-        if (!Number.isFinite(parsed))
-            throw new ArgumentError(`Expected number value, got "${value}".`);
-        return parsed;
-    }
-    if (type === 'bool' || type === 'boolean') {
-        if (value === 'true' || value === '1')
-            return true;
-        if (value === 'false' || value === '0')
-            return false;
-        throw new ArgumentError(`Expected boolean value, got "${value}".`);
-    }
-    return value;
+    return parseCommandSurface(command, argv);
 }

package/dist/src/hosted/args.test.js

@@ -12,6 +12,7 @@ const command = {
         { name: 'query', positional: true, required: true, type: 'string' },
         { name: 'limit', type: 'int', default: 10 },
         { name: 'include-forks', type: 'boolean', default: false },
+        { name: 'sort', type: 'string', choices: ['updated', 'stars'] },
     ],
     columns: ['name'],
 };
@@ -24,12 +25,25 @@ describe('parseHostedInvocation', () => {
                 limit: 5,
                 'include-forks': true,
             },
+            optionSources: {
+                query: 'cli',
+                limit: 'cli',
+                'include-forks': 'cli',
+            },
             format: 'json',
+            formatExplicit: true,
             trace: 'on',
+            verbose: false,
             help: false,
         });
     });
     it('rejects missing required positional args', () => {
-        expect(() => parseHostedInvocation(command, [])).toThrow('Missing required argument');
+        expect(() => parseHostedInvocation(command, [])).toThrow("error: missing required argument 'query'");
+    });
+    it.each([
+        { name: 'partial integers', argv: ['webcmd', '--limit', '12x'], message: /limit.*number/i },
+        { name: 'invalid choices', argv: ['webcmd', '--sort', 'recent'], message: /sort.*one of.*updated.*stars/i },
+    ])('rejects $name', ({ argv, message }) => {
+        expect(() => parseHostedInvocation(command, argv)).toThrow(message);
     });
 });

package/dist/src/hosted/availability.d.ts

@@ -0,0 +1,13 @@
+import { Strategy } from '../registry.js';
+export type HostedAvailability = {
+    mode: 'hosted';
+} | {
+    mode: 'local-only';
+    reason: 'desktop-app' | 'local-tool' | 'browser-bind';
+};
+export interface HostedAvailabilityMetadata {
+    strategy?: Strategy | string;
+    domain?: string;
+}
+export declare function deriveHostedAvailability(command: HostedAvailabilityMetadata): HostedAvailability;
+export declare function deriveBrowserAvailability(command: string): HostedAvailability;

package/dist/src/hosted/availability.js

@@ -0,0 +1,16 @@
+import { classifyAdapter } from '../help.js';
+import { Strategy } from '../registry.js';
+export function deriveHostedAvailability(command) {
+    if (String(command.strategy).toLowerCase() === Strategy.LOCAL) {
+        return { mode: 'local-only', reason: 'local-tool' };
+    }
+    if (classifyAdapter(command.domain) === 'app') {
+        return { mode: 'local-only', reason: 'desktop-app' };
+    }
+    return { mode: 'hosted' };
+}
+export function deriveBrowserAvailability(command) {
+    return command === 'bind'
+        ? { mode: 'local-only', reason: 'browser-bind' }
+        : { mode: 'hosted' };
+}

package/dist/src/hosted/availability.test.d.ts

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