@agentrhq/webcmd 0.2.5 → 0.3.1

package/dist/src/command-surface.js

@@ -0,0 +1,205 @@
+import { Command } from 'commander';
+import { ArgumentError } from './errors.js';
+export const OUTPUT_FORMATS = ['table', 'plain', 'json', 'yaml', 'yml', 'md', 'markdown', 'csv'];
+export const TRACE_MODES = ['off', 'on', 'retain-on-failure'];
+const BROWSER_WINDOW_MODES = ['foreground', 'background'];
+const SITE_SESSION_MODES = ['ephemeral', 'persistent'];
+/** Identifies the one parser failure whose public bytes are owned by Commander. */
+export class MissingRequiredPositionalError extends ArgumentError {
+    argumentName;
+    constructor(argumentName, help) {
+        super(`Argument "${argumentName}" is required.`, help);
+        this.argumentName = argumentName;
+    }
+}
+/** Raw structural failure bytes/status owned by Commander. */
+export class CommanderStructuralError extends Error {
+    output;
+    exitCode;
+    constructor(output, exitCode) {
+        super(output.trimEnd());
+        this.output = output;
+        this.exitCode = exitCode;
+        this.name = 'CommanderStructuralError';
+    }
+}
+/** Register the adapter argument grammar and its shared execution options. */
+export function configureCommandSurface(command, metadata) {
+    for (const arg of metadata.args) {
+        if (arg.positional) {
+            const bracket = arg.required ? `<${arg.name}>` : `[${arg.name}]`;
+            command.argument(bracket, arg.help ?? '');
+            continue;
+        }
+        const expectsValue = arg.required || arg.valueRequired;
+        const flag = expectsValue ? `--${arg.name} <value>` : `--${arg.name} [value]`;
+        if (arg.required)
+            command.requiredOption(flag, arg.help ?? '');
+        else if (arg.default != null)
+            command.option(flag, arg.help ?? '', String(arg.default));
+        else
+            command.option(flag, arg.help ?? '');
+    }
+    command
+        .option('-f, --format <fmt>', `Output format: ${OUTPUT_FORMATS.join(', ')}`, 'table')
+        .option('--trace <mode>', `Trace capture: ${TRACE_MODES.join(', ')}`, 'off')
+        .option('-v, --verbose', 'Debug output', false);
+    if (metadata.browser) {
+        command
+            .option('--window <mode>', `Browser window mode: ${BROWSER_WINDOW_MODES.join(' or ')}`)
+            .option('--site-session <mode>', `Adapter site session lifecycle: ${SITE_SESSION_MODES.join(' or ')}`)
+            .option('--keep-tab <bool>', 'Keep the browser tab lease after the command finishes');
+    }
+}
+/** Parse one adapter invocation without requiring a local Commander program. */
+export function parseCommandSurface(metadata, argv) {
+    const positionals = metadata.args.filter((arg) => arg.positional);
+    const defaultFormat = metadata.defaultFormat || 'table';
+    const input = {};
+    const optionSources = {};
+    const { root, command, parseArgv } = makeStructuralCommand(metadata, argv);
+    let parsedOptions = {};
+    let actionRan = false;
+    let stderr = '';
+    const commanderOutput = {
+        writeErr: (value) => { stderr += value; },
+        // Hosted mode owns help presentation; Commander is used only for its
+        // grammar, precedence, exact structural errors, and exit status.
+        writeOut: (_value) => undefined,
+    };
+    for (let current = command; current; current = current.parent) {
+        current.exitOverride().configureOutput(commanderOutput);
+    }
+    command.action((...actionArgs) => {
+        actionRan = true;
+        parsedOptions = actionArgs[positionals.length];
+        for (let index = 0; index < positionals.length; index += 1) {
+            const value = actionArgs[index];
+            if (value !== undefined) {
+                input[positionals[index].name] = value;
+                optionSources[positionals[index].name] = 'cli';
+            }
+        }
+        for (const definition of metadata.args) {
+            if (definition.positional)
+                continue;
+            const camelName = definition.name.replace(/-([a-z])/g, (_match, character) => character.toUpperCase());
+            const value = parsedOptions[definition.name] ?? parsedOptions[camelName];
+            if (value !== undefined)
+                input[definition.name] = value;
+            const source = command.getOptionValueSource(camelName) ?? command.getOptionValueSource(definition.name);
+            if (source === 'cli' || source === 'default') {
+                optionSources[definition.name] = source;
+            }
+        }
+    });
+    try {
+        root.parse(parseArgv, { from: 'user' });
+    }
+    catch (error) {
+        const commander = error;
+        if (commander.code === 'commander.helpDisplayed') {
+            return {
+                args: {},
+                optionSources: {},
+                format: parseOutputFormat(defaultFormat),
+                formatExplicit: false,
+                trace: 'off',
+                verbose: false,
+                help: true,
+            };
+        }
+        const output = stderr || `${typeof commander.message === 'string' ? commander.message : String(error)}\n`;
+        throw new CommanderStructuralError(output, typeof commander.exitCode === 'number' ? commander.exitCode : 1);
+    }
+    if (!actionRan) {
+        throw new CommanderStructuralError(`error: command '${command.name()}' did not run\n`, 1);
+    }
+    // Match the local action boundary: adapter argument coercion occurs before
+    // format validation, and trace validation occurs inside executeCommand after
+    // both. Commander has already enforced required positionals/options.
+    const args = coerceCommandArguments(metadata.args, input);
+    const formatExplicit = command.getOptionValueSource('format') === 'cli';
+    const format = parseOutputFormat(formatExplicit ? parsedOptions.format : defaultFormat);
+    const trace = parseTraceMode(parsedOptions.trace ?? 'off');
+    const verbose = parsedOptions.verbose === true;
+    return {
+        args,
+        optionSources,
+        format,
+        formatExplicit,
+        trace,
+        verbose,
+        help: false,
+    };
+}
+function makeStructuralCommand(metadata, argv) {
+    const pathParts = (metadata.command ?? '').split('/').filter(Boolean);
+    const site = metadata.site ?? (pathParts.length > 1 ? pathParts[0] : undefined);
+    const name = metadata.name ?? pathParts.at(-1) ?? 'command';
+    if (!site) {
+        const command = new Command(name);
+        configureCommandSurface(command, metadata);
+        return { root: command, command, parseArgv: [...argv] };
+    }
+    const root = new Command('webcmd');
+    const siteCommand = root.command(site);
+    const command = siteCommand.command(name);
+    configureCommandSurface(command, metadata);
+    return { root, command, parseArgv: [site, name, ...argv] };
+}
+/** Apply the adapter's required/default/type/choice contract to raw values. */
+export function coerceCommandArguments(definitions, input) {
+    const result = { ...input };
+    for (const definition of definitions) {
+        const value = result[definition.name];
+        if (definition.required && (value === undefined || value === null || value === '')) {
+            throw new ArgumentError(`Argument "${definition.name}" is required.`, definition.help ?? `Provide a value for --${definition.name}`);
+        }
+        if (value !== undefined && value !== null) {
+            if (definition.type === 'int' || definition.type === 'number') {
+                const parsed = Number(value);
+                if (Number.isNaN(parsed)) {
+                    throw new ArgumentError(`Argument "${definition.name}" must be a valid number. Received: "${String(value)}"`);
+                }
+                result[definition.name] = parsed;
+            }
+            else if (definition.type === 'boolean' || definition.type === 'bool') {
+                if (typeof value === 'string') {
+                    const normalized = value.toLowerCase();
+                    if (normalized === 'true' || normalized === '1')
+                        result[definition.name] = true;
+                    else if (normalized === 'false' || normalized === '0')
+                        result[definition.name] = false;
+                    else {
+                        throw new ArgumentError(`Argument "${definition.name}" must be a boolean (true/false). Received: "${String(value)}"`);
+                    }
+                }
+                else {
+                    result[definition.name] = Boolean(value);
+                }
+            }
+            const coercedValue = result[definition.name];
+            if (definition.choices && definition.choices.length > 0
+                && !definition.choices.map(String).includes(String(coercedValue))) {
+                throw new ArgumentError(`Argument "${definition.name}" must be one of: ${definition.choices.join(', ')}. Received: "${String(coercedValue)}"`);
+            }
+        }
+        else if (definition.default !== undefined) {
+            // Preserve the historical local contract: defaults are adapter-owned
+            // values and are not re-coerced or revalidated by the CLI boundary.
+            result[definition.name] = definition.default;
+        }
+    }
+    return result;
+}
+export function parseOutputFormat(value) {
+    // Preserve the long-standing local behavior: unknown format names flow to
+    // output.ts, whose default switch branch renders a table.
+    return String(value);
+}
+function parseTraceMode(value) {
+    if (TRACE_MODES.includes(value))
+        return value;
+    throw new ArgumentError(`--trace must be one of: ${TRACE_MODES.join(', ')}. Received: "${String(value)}"`);
+}

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

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

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

@@ -0,0 +1,406 @@
+import { describe, expect, it } from 'vitest';
+import { Command } from 'commander';
+import { CommanderStructuralError, coerceCommandArguments, configureCommandSurface, parseCommandSurface, parseOutputFormat, } from './command-surface.js';
+const metadata = {
+    command: 'demo/search',
+    browser: false,
+    defaultFormat: 'plain',
+    args: [
+        { name: 'query', positional: true, required: true, type: 'string' },
+        { name: 'scope', positional: true, type: 'string' },
+        { name: 'limit', type: 'int', default: 10 },
+        { name: 'ratio', type: 'number' },
+        { name: 'mode', type: 'string', choices: ['open', 'closed'] },
+        { name: 'enabled', type: 'boolean', default: false },
+        { name: 'label', type: 'string', valueRequired: true },
+    ],
+};
+describe('parseCommandSurface', () => {
+    it.each([
+        {
+            name: 'required and optional positionals',
+            argv: ['needle', 'issues'],
+            args: { query: 'needle', scope: 'issues', limit: 10, enabled: false },
+            sources: { query: 'cli', scope: 'cli', limit: 'default', enabled: 'default' },
+        },
+        {
+            name: 'a leading-dash positional after the option separator',
+            argv: ['--', '-opaque-id'],
+            args: { query: '-opaque-id', limit: 10, enabled: false },
+            sources: { query: 'cli', limit: 'default', enabled: 'default' },
+        },
+        {
+            name: 'separate and inline named option values',
+            argv: ['needle', '--label', 'triage', '--limit=12'],
+            args: { query: 'needle', label: 'triage', limit: 12, enabled: false },
+            sources: { query: 'cli', label: 'cli', limit: 'cli', enabled: 'default' },
+        },
+        {
+            name: 'a required option value beginning with a dash',
+            argv: ['needle', '--label', '-opaque'],
+            args: { query: 'needle', label: '-opaque', limit: 10, enabled: false },
+            sources: { query: 'cli', label: 'cli', limit: 'default', enabled: 'default' },
+        },
+        {
+            name: 'a valueless boolean flag',
+            argv: ['needle', '--enabled'],
+            args: { query: 'needle', limit: 10, enabled: true },
+            sources: { query: 'cli', limit: 'default', enabled: 'cli' },
+        },
+        {
+            name: 'an explicit separate boolean value',
+            argv: ['needle', '--enabled', 'false'],
+            args: { query: 'needle', limit: 10, enabled: false },
+            sources: { query: 'cli', limit: 'default', enabled: 'cli' },
+        },
+        {
+            name: 'an explicit inline boolean value',
+            argv: ['needle', '--enabled=true'],
+            args: { query: 'needle', limit: 10, enabled: true },
+            sources: { query: 'cli', limit: 'default', enabled: 'cli' },
+        },
+        {
+            name: 'a finite number and a valid choice',
+            argv: ['needle', '--ratio=-1.25', '--mode', 'closed'],
+            args: { query: 'needle', limit: 10, ratio: -1.25, mode: 'closed', enabled: false },
+            sources: { query: 'cli', limit: 'default', ratio: 'cli', mode: 'cli', enabled: 'default' },
+        },
+    ])('parses $name', ({ argv, args, sources }) => {
+        expect(parseCommandSurface(metadata, argv)).toEqual({
+            args,
+            optionSources: sources,
+            format: 'plain',
+            formatExplicit: false,
+            trace: 'off',
+            verbose: false,
+            help: false,
+        });
+    });
+    it.each(['table', 'plain', 'json', 'yaml', 'yml', 'md', 'markdown', 'csv'])('accepts the %s output format', (format) => {
+        expect(parseCommandSurface(metadata, ['needle', `--format=${format}`])).toMatchObject({
+            format,
+            formatExplicit: true,
+        });
+    });
+    it.each(['off', 'on', 'retain-on-failure'])('accepts the %s trace mode', (trace) => {
+        expect(parseCommandSurface(metadata, ['needle', '--trace', trace])).toMatchObject({ trace });
+    });
+    it('lets Commander help terminate before action-level global values are observed', () => {
+        expect(parseCommandSurface(metadata, ['--verbose', '--help'])).toMatchObject({
+            verbose: false,
+            help: true,
+        });
+    });
+    it.each([
+        { name: 'a missing required positional', argv: [], message: /missing required argument 'query'/i },
+        { name: 'an extra positional', argv: ['needle', 'issues', 'extra'], message: /too many arguments.*search/i },
+        { name: 'a missing required option value', argv: ['needle', '--label'], message: /--label.*argument missing/i },
+        { name: 'an unknown flag', argv: ['needle', '--unknown'], message: /unknown option/i },
+        { name: 'a partial integer', argv: ['needle', '--limit', '12x'], message: /limit.*number/i },
+        { name: 'an invalid choice', argv: ['needle', '--mode', 'merged'], message: /mode.*one of.*open.*closed/i },
+        { name: 'an invalid boolean', argv: ['needle', '--enabled=maybe'], message: /enabled.*boolean/i },
+        { name: 'an invalid trace mode', argv: ['needle', '--trace', 'always'], message: /trace.*one of/i },
+    ])('rejects $name', ({ argv, message }) => {
+        expect(() => parseCommandSurface(metadata, argv)).toThrow(message);
+    });
+});
+describe('coerceCommandArguments', () => {
+    it('applies typed defaults and preserves non-definition compatibility metadata', () => {
+        expect(coerceCommandArguments(metadata.args, {
+            query: 'needle',
+            __webcmdOptionSources: { limit: 'cli' },
+        })).toEqual({
+            query: 'needle',
+            limit: 10,
+            enabled: false,
+            __webcmdOptionSources: { limit: 'cli' },
+        });
+    });
+    it('preserves adapter-owned defaults without coercing them again', () => {
+        expect(coerceCommandArguments([
+            { name: 'limit', type: 'int', default: '10' },
+            { name: 'mode', choices: ['open', 'closed'], default: 'open' },
+        ], {})).toEqual({ limit: '10', mode: 'open' });
+    });
+    it('preserves legacy numeric and unknown-format coercion', () => {
+        expect(coerceCommandArguments([
+            { name: 'count', type: 'int' },
+            { name: 'ratio', type: 'number' },
+        ], { count: '1.5', ratio: 'Infinity' })).toEqual({ count: 1.5, ratio: Infinity });
+        expect(parseCommandSurface(metadata, ['needle', '--format', 'xml'])).toMatchObject({
+            format: 'xml',
+            formatExplicit: true,
+        });
+    });
+});
+describe('configureCommandSurface', () => {
+    it.each([
+        { browser: false, expected: [] },
+        { browser: true, expected: ['--window', '--site-session', '--keep-tab'] },
+    ])('registers browser globals only when browser is $browser', ({ browser, expected }) => {
+        const command = new Command('search');
+        configureCommandSurface(command, { ...metadata, browser });
+        const longFlags = command.options.map((option) => option.long);
+        for (const flag of expected)
+            expect(longFlags).toContain(flag);
+        if (!browser) {
+            expect(longFlags).not.toContain('--window');
+            expect(longFlags).not.toContain('--site-session');
+            expect(longFlags).not.toContain('--keep-tab');
+        }
+        expect(longFlags).toEqual(expect.arrayContaining([
+            '--limit',
+            '--ratio',
+            '--mode',
+            '--enabled',
+            '--label',
+            '--format',
+            '--trace',
+            '--verbose',
+        ]));
+        expect(command.registeredArguments.map((argument) => argument.name())).toEqual(['query', 'scope']);
+    });
+});
+function classifyError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/unknown option/i.test(message))
+        return { kind: 'unknown' };
+    if (/argument missing|requires a value/i.test(message))
+        return { kind: 'missing' };
+    return { kind: 'invalid' };
+}
+async function parseWithCommander(surface, argv) {
+    const command = new Command('parity')
+        .exitOverride()
+        .configureOutput({ writeErr: () => undefined, writeOut: () => undefined });
+    configureCommandSurface(command, surface);
+    const positionals = surface.args.filter((argument) => argument.positional);
+    let parsed;
+    command.action((...actionArgs) => {
+        const options = actionArgs[positionals.length];
+        const raw = {};
+        for (let index = 0; index < positionals.length; index += 1) {
+            if (actionArgs[index] !== undefined)
+                raw[positionals[index].name] = actionArgs[index];
+        }
+        for (const argument of surface.args) {
+            if (argument.positional)
+                continue;
+            const camelName = argument.name.replace(/-([a-z])/g, (_match, character) => character.toUpperCase());
+            const value = options[argument.name] ?? options[camelName];
+            if (value !== undefined)
+                raw[argument.name] = value;
+        }
+        parsed = coerceCommandArguments(surface.args, raw);
+    });
+    try {
+        await command.parseAsync(argv, { from: 'user' });
+        return { kind: 'success', args: parsed ?? {} };
+    }
+    catch (error) {
+        return classifyError(error);
+    }
+}
+function parseWithShared(surface, argv) {
+    try {
+        return { kind: 'success', args: parseCommandSurface(surface, argv).args };
+    }
+    catch (error) {
+        return classifyError(error);
+    }
+}
+describe('Commander parity for dash-prefixed numeric tokens', () => {
+    it.each([
+        {
+            name: 'integer positional accepts a negative integer',
+            args: [{ name: 'count', positional: true, required: true, type: 'int' }],
+            argv: ['-1'],
+            kind: 'success',
+        },
+        {
+            name: 'number positional accepts a negative decimal',
+            args: [{ name: 'ratio', positional: true, required: true, type: 'number' }],
+            argv: ['-1.25'],
+            kind: 'success',
+        },
+        {
+            name: 'required string positional accepts a strict negative number operand',
+            args: [{ name: 'label', positional: true, required: true, type: 'string' }],
+            argv: ['-1'],
+            kind: 'success',
+        },
+        {
+            name: 'optional string positional accepts a strict negative number operand',
+            args: [{ name: 'label', positional: true, type: 'string' }],
+            argv: ['-1'],
+            kind: 'success',
+        },
+        {
+            name: 'untyped positional accepts a strict negative number operand',
+            args: [{ name: 'label', positional: true, required: true }],
+            argv: ['-1'],
+            kind: 'success',
+        },
+        {
+            name: 'integer positional rejects a malformed numeric prefix as an unknown option',
+            args: [{ name: 'count', positional: true, required: true, type: 'int' }],
+            argv: ['-1x'],
+            kind: 'unknown',
+        },
+        {
+            name: 'string positional rejects a malformed numeric prefix as an unknown option',
+            args: [{ name: 'label', positional: true, required: true, type: 'string' }],
+            argv: ['-1x'],
+            kind: 'unknown',
+        },
+        {
+            name: 'option separator preserves a malformed dash token as a string positional',
+            args: [{ name: 'label', positional: true, required: true, type: 'string' }],
+            argv: ['--', '-1x'],
+            kind: 'success',
+        },
+        {
+            name: 'required integer option consumes a valid negative value',
+            args: [{ name: 'count', type: 'int', valueRequired: true }],
+            argv: ['--count', '-1'],
+            kind: 'success',
+        },
+        {
+            name: 'required integer option consumes then validates a malformed dash value',
+            args: [{ name: 'count', type: 'int', valueRequired: true }],
+            argv: ['--count', '-1x'],
+            kind: 'invalid',
+        },
+        {
+            name: 'optional integer option consumes a valid negative value',
+            args: [{ name: 'count', type: 'int' }],
+            argv: ['--count', '-1'],
+            kind: 'success',
+        },
+        {
+            name: 'optional integer option leaves a malformed dash value as an unknown option',
+            args: [{ name: 'count', type: 'int' }],
+            argv: ['--count', '-1x'],
+            kind: 'unknown',
+        },
+        {
+            name: 'required string option consumes a dash-prefixed value',
+            args: [{ name: 'label', type: 'string', valueRequired: true }],
+            argv: ['--label', '-opaque'],
+            kind: 'success',
+        },
+        {
+            name: 'optional string option leaves a dash-prefixed token as an unknown option',
+            args: [{ name: 'label', type: 'string' }],
+            argv: ['--label', '-opaque'],
+            kind: 'unknown',
+        },
+        {
+            name: 'required option without a following value reports a missing value',
+            args: [{ name: 'count', type: 'int', valueRequired: true }],
+            argv: ['--count'],
+            kind: 'missing',
+        },
+    ])('$name', async ({ args, argv, kind }) => {
+        const surface = { args };
+        const commander = await parseWithCommander(surface, [...argv]);
+        const shared = parseWithShared(surface, [...argv]);
+        expect(commander.kind).toBe(kind);
+        expect(shared).toEqual(commander);
+    });
+});
+const precedenceSurface = {
+    command: 'parity/check',
+    site: 'parity',
+    name: 'check',
+    args: [
+        { name: 'account', positional: true, required: true, type: 'string' },
+        { name: 'scope', positional: true, type: 'string' },
+        { name: 'token', required: true, valueRequired: true, type: 'string' },
+        { name: 'mode', type: 'string', choices: ['valid'] },
+    ],
+};
+function captureReferenceSurface(argv) {
+    let stderr = '';
+    let outcome;
+    const root = new Command('webcmd')
+        .exitOverride()
+        .configureOutput({ writeErr: value => { stderr += value; }, writeOut: () => undefined });
+    const command = root.command(precedenceSurface.site).command(precedenceSurface.name);
+    configureCommandSurface(command, precedenceSurface);
+    const positionals = precedenceSurface.args.filter(argument => argument.positional);
+    command.action((...actionArgs) => {
+        try {
+            const options = actionArgs[positionals.length];
+            const raw = {};
+            for (let index = 0; index < positionals.length; index += 1) {
+                if (actionArgs[index] !== undefined)
+                    raw[positionals[index].name] = actionArgs[index];
+            }
+            for (const argument of precedenceSurface.args) {
+                if (argument.positional)
+                    continue;
+                const value = options[argument.name];
+                if (value !== undefined)
+                    raw[argument.name] = value;
+            }
+            const args = coerceCommandArguments(precedenceSurface.args, raw);
+            const format = parseOutputFormat(options.format ?? 'table');
+            const trace = String(options.trace ?? 'off');
+            if (!['off', 'on', 'retain-on-failure'].includes(trace)) {
+                throw new Error(`--trace must be one of: off, on, retain-on-failure. Received: "${trace}"`);
+            }
+            outcome = { kind: 'success', args, format, trace };
+        }
+        catch (error) {
+            outcome = { kind: 'semantic', message: error instanceof Error ? error.message : String(error) };
+        }
+    });
+    try {
+        root.parse([precedenceSurface.site, precedenceSurface.name, ...argv], { from: 'user' });
+        return outcome ?? { kind: 'success', args: {}, format: 'table', trace: 'off' };
+    }
+    catch (error) {
+        const commander = error;
+        if (commander.code === 'commander.helpDisplayed')
+            return { kind: 'help' };
+        return { kind: 'structural', stderr, exitCode: commander.exitCode ?? 1 };
+    }
+}
+function captureSharedSurface(argv) {
+    try {
+        const parsed = parseCommandSurface(precedenceSurface, argv);
+        if (parsed.help)
+            return { kind: 'help' };
+        return { kind: 'success', args: parsed.args, format: parsed.format, trace: parsed.trace };
+    }
+    catch (error) {
+        if (error instanceof CommanderStructuralError) {
+            return { kind: 'structural', stderr: error.output, exitCode: error.exitCode };
+        }
+        return { kind: 'semantic', message: error instanceof Error ? error.message : String(error) };
+    }
+}
+describe('complete Commander structural grammar and precedence parity', () => {
+    it.each([
+        { name: 'help before unknown option', argv: ['--help', '--unknown'] },
+        { name: 'unknown option before help', argv: ['--unknown', '--help'] },
+        { name: 'help with a missing format value', argv: ['--help', '-f'] },
+        { name: 'help with excess positionals', argv: ['--help', 'one', 'two', 'three'] },
+        { name: 'help with invalid choice, format, and trace', argv: ['--help', '--mode', 'bad', '-f', 'xml', '--trace', 'bad'] },
+        { name: 'missing required named with invalid format', argv: ['account', '-f', 'xml'] },
+        { name: 'missing required named with invalid trace', argv: ['account', '--trace', 'bad'] },
+        { name: 'missing required named with invalid choice', argv: ['account', '--mode', 'bad'] },
+        { name: 'missing positional with invalid format', argv: ['--token', 'secret', '-f', 'xml'] },
+        { name: 'missing positional with invalid trace', argv: ['--token', 'secret', '--trace', 'bad'] },
+        { name: 'missing positional with invalid choice', argv: ['--token', 'secret', '--mode', 'bad'] },
+        { name: 'invalid choice precedes invalid format and trace', argv: ['account', '--token', 'secret', '--mode', 'bad', '-f', 'xml', '--trace', 'bad'] },
+        { name: 'invalid format precedes invalid trace', argv: ['account', '--token', 'secret', '-f', 'xml', '--trace', 'bad'] },
+        { name: 'ordinary unknown option', argv: ['account', '--token', 'secret', '--unknown'] },
+        { name: 'ordinary missing required option value', argv: ['account', '--token'] },
+        { name: 'ordinary excess positional', argv: ['account', 'scope', 'extra', '--token', 'secret'] },
+        { name: 'dash-leading positional after separator', argv: ['--token', 'secret', '--', '-account'] },
+    ])('$name', ({ argv }) => {
+        expect(captureSharedSurface(argv)).toEqual(captureReferenceSurface(argv));
+    });
+});

package/dist/src/commanderAdapter.d.ts

@@ -14,7 +14,11 @@ import { type CliCommand } from './registry.js';
 /**
  * Register a single CliCommand as a Commander subcommand.
  */
-export declare function registerCommandToProgram(siteCmd: Command, cmd: CliCommand): void;
+export interface CommanderAdapterRuntime {
+    stdout?: NodeJS.WritableStream;
+    now?: () => number;
+}
+export declare function registerCommandToProgram(siteCmd: Command, cmd: CliCommand, runtime?: CommanderAdapterRuntime): void;
 /**
  * Register all commands from the registry onto a Commander program.
  */