@agentrhq/webcmd 0.3.0 → 0.3.1

package/dist/src/hosted/runner.js

@@ -1,103 +1,320 @@
-import { writeFileSync } from 'node:fs';
-import yaml from 'js-yaml';
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command, CommanderError } from 'commander';
+import { configureCompletionCommandSurface, configureListCommandSurface } from '../builtin-command-surface.js';
 import { BrowserSessionArgvError, rewriteBrowserArgv } from '../cli-argv-preprocess.js';
-import { ConfigError, EXIT_CODES, toEnvelope } from '../errors.js';
-import { render as renderOutput } from '../output.js';
-import { HostedClient } from './client.js';
+import { CommanderStructuralError, MissingRequiredPositionalError } from '../command-surface.js';
+import { formatRootHelp, getCommandCompletionCandidates } from '../command-presentation.js';
+import { HOSTED_BUILTIN_COMMANDS, HOSTED_ROOT_HELP, LOCAL_ONLY_COMMAND_HELP, } from '../completion-shared.js';
+import { CliError, ConfigError, EXIT_CODES, toEnvelope } from '../errors.js';
+import { getRequestedHelpFormat, renderStructuredHelp } from '../help.js';
+import { findPackageRoot } from '../package-paths.js';
+import { formatErrorEnvelope, render as renderOutput } from '../output.js';
+import { StreamWriteError, writeToStream } from '../stream-write.js';
+import { PKG_VERSION } from '../version.js';
+import { getCompletionScriptFast } from '../completion-fast.js';
+import { browserCommandCatalog } from '../browser/command-catalog.js';
+import { HostedClient, HostedClientError } from './client.js';
 import { parseHostedInvocation } from './args.js';
-import { findHostedCommand, hostedListRows, isLocalOnlyHostedCommand, renderHostedCommandHelp, renderHostedSiteHelp, siteNames, commandNamesForSite, } from './manifest.js';
+import { HostedBrowserHelp, parseHostedBrowserStructure } from './browser-args.js';
+import { materializeHostedOutputs, prepareHostedFiles, rewriteHostedOutputResultPaths } from './files.js';
+import { findHostedCommand, hostedCommandHelpData, hostedCommands, hostedListPresentation, hostedSiteHelpData, isLocalOnlyHostedCommand, renderHostedCommandHelp, renderHostedSiteHelp, } from './manifest.js';
 import { isHostedConfig, loadWebcmdConfig } from './config.js';
+import { resolveHostedApiKey } from './credentials.js';
+import { parseHostedRootCommandSurface } from '../root-command-surface.js';
+class CommanderCompatibleError extends Error {
+    output;
+    exitCode;
+    stdoutOutput;
+    constructor(output, exitCode, stdoutOutput) {
+        super(output.trimEnd());
+        this.output = output;
+        this.exitCode = exitCode;
+        this.stdoutOutput = stdoutOutput;
+    }
+}
+const hostedBrowserCommandsByPath = new Map(browserCommandCatalog.map(command => [command.command, command]));
 export async function runHostedCli(argv, opts = {}) {
-    const config = opts.config ?? loadWebcmdConfig();
+    const config = opts.config ?? loadWebcmdConfig({ env: opts.env, homeDir: opts.homeDir });
     if (!isHostedConfig(config))
         return { handled: false, exitCode: EXIT_CODES.SUCCESS };
     const stdout = opts.stdout ?? process.stdout;
     const stderr = opts.stderr ?? process.stderr;
-    const client = new HostedClient({
-        apiBaseUrl: config.hosted.apiBaseUrl,
-        apiKey: config.hosted.apiKey,
-        fetchImpl: opts.fetchImpl,
-    });
     try {
-        await dispatchHosted(argv, client, stdout);
+        const credential = await resolveHostedApiKey(config, {
+            credentialStore: opts.credentialStore,
+            env: opts.env,
+            homeDir: opts.homeDir,
+            platform: opts.platform,
+            randomUUID: opts.randomUUID,
+            migrate: opts.config === undefined,
+        });
+        const client = new HostedClient({
+            apiBaseUrl: config.hosted.apiBaseUrl,
+            apiKey: credential.apiKey,
+            fetchImpl: opts.fetchImpl,
+        });
+        await dispatchHosted(argv, client, stdout, stderr, opts.now ?? Date.now);
         return { handled: true, exitCode: EXIT_CODES.SUCCESS };
     }
     catch (err) {
-        stderr.write(yaml.dump(toEnvelope(err), { sortKeys: false, lineWidth: 120, noRefs: true }));
+        if (err instanceof StreamWriteError)
+            throw err;
+        if (err instanceof CliError && err.code === 'UNSUPPORTED_SHELL')
+            throw err;
+        if (err instanceof CommanderStructuralError) {
+            await writeToStream(stderr, err.output);
+            return { handled: true, exitCode: err.exitCode };
+        }
+        if (err instanceof CommanderCompatibleError) {
+            await writeToStream(stderr, err.output);
+            if (err.stdoutOutput)
+                await writeToStream(stdout, err.stdoutOutput);
+            return { handled: true, exitCode: err.exitCode };
+        }
+        if (err instanceof MissingRequiredPositionalError) {
+            await writeToStream(stderr, `error: missing required argument '${err.argumentName}'\n`);
+            return { handled: true, exitCode: EXIT_CODES.GENERIC_ERROR };
+        }
+        await writeToStream(stderr, formatErrorEnvelope(toEnvelope(err), {
+            cmdName: hostedCommandName(argv),
+            traceMode: hostedTraceMode(argv),
+        }));
         return {
             handled: true,
             exitCode: errorExitCode(err),
         };
     }
 }
-async function dispatchHosted(argv, client, stdout) {
-    const normalized = stripGlobalOptions(argv);
+async function dispatchHosted(argv, client, stdout, stderr, now) {
+    const normalized = parseHostedRootCommandSurface(argv);
+    if (normalized.kind === 'help') {
+        const help = formatRootHelp(HOSTED_ROOT_HELP);
+        if (normalized.exitCode !== EXIT_CODES.SUCCESS) {
+            throw new CommanderCompatibleError(help, normalized.exitCode);
+        }
+        await writeToStream(stdout, help);
+        return;
+    }
+    if (normalized.kind === 'version') {
+        await writeToStream(stdout, normalized.output);
+        return;
+    }
+    if (normalized.kind === 'completion') {
+        const manifest = await client.getManifest();
+        validateManifestContractIdentity(manifest);
+        await writeToStream(stdout, hostedCompletions(manifest, normalized.argv).join('\n') + '\n');
+        return;
+    }
     const args = normalized.argv;
-    if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
-        stdout.write('Usage: webcmd <site> <command> [options]\n       webcmd list\n       webcmd setup\n');
+    if (args[0] === 'completion') {
+        const parsed = parseHostedCompletionSurface(args.slice(1), normalized.literal);
+        if (parsed.kind === 'help') {
+            await writeToStream(stdout, parsed.output);
+            return;
+        }
+        const script = getCompletionScriptFast(parsed.shell);
+        if (script === undefined) {
+            // Run the canonical local Commander action for this rare error path so
+            // hosted mode preserves even the historical public stack bytes.
+            const { createProgram } = await import('../cli.js');
+            await createProgram('', '').parseAsync(argv, { from: 'user' });
+            throw new CliError('UNSUPPORTED_SHELL', `Unsupported shell: ${parsed.shell}. Supported: bash, zsh, fish`);
+        }
+        await writeToStream(stdout, script);
         return;
     }
     if (args[0] === 'daemon') {
-        throw new ConfigError('webcmd daemon is local-only. Hosted mode has no local daemon.', 'Run `webcmd setup` and choose local mode to manage the local daemon.');
+        throw new ConfigError('webcmd daemon is local-only. Hosted mode has no local daemon.', LOCAL_ONLY_COMMAND_HELP);
     }
     if (args[0] === 'browser') {
-        await dispatchHostedBrowser(args, normalized.profile, client, stdout);
-        return;
-    }
-    const manifest = await client.getManifest();
-    if (isCompletionRequest(args)) {
-        stdout.write(hostedCompletions(manifest, args).join('\n') + '\n');
+        const invocation = parseHostedBrowserInvocation(args, normalized.profile);
+        const manifest = await client.getManifest();
+        validateManifestContractIdentity(manifest);
+        await dispatchHostedBrowser(invocation, client, stdout);
         return;
     }
     if (args[0] === 'list') {
-        renderHostedList(manifest, args.slice(1));
+        const parsed = parseHostedListSurface(args.slice(1), normalized.literal);
+        if (parsed.kind === 'help') {
+            await writeToStream(stdout, parsed.output);
+            return;
+        }
+        const manifest = await client.getManifest();
+        validateManifestContractIdentity(manifest);
+        await renderHostedList(manifest, parsed.format, parsed.formatExplicit, stdout);
         return;
     }
+    const manifest = await client.getManifest();
+    validateManifestContractIdentity(manifest);
     const site = args[0];
     const commandName = args[1];
+    const siteExists = manifest.commands.some(command => command.site === site);
+    if (!siteExists) {
+        const unknownRoot = parseUnknownSiteRootOptions(args, normalized.literal);
+        if (unknownRoot.version) {
+            await writeToStream(stdout, `${PKG_VERSION}\n`);
+            return;
+        }
+        if (unknownRoot.help) {
+            await writeToStream(stdout, formatRootHelp(HOSTED_ROOT_HELP));
+            return;
+        }
+        throw new CommanderCompatibleError(`error: unknown command '${site}'\n`, EXIT_CODES.USAGE_ERROR, formatRootHelp(HOSTED_ROOT_HELP));
+    }
     if (!commandName || commandName === '--help' || commandName === '-h') {
-        stdout.write(renderHostedSiteHelp(manifest, site));
+        const data = hostedSiteHelpData(manifest, site);
+        if (!data) {
+            throw new CommanderCompatibleError(`error: unknown command '${site}'\n`, EXIT_CODES.USAGE_ERROR, formatRootHelp(HOSTED_ROOT_HELP));
+        }
+        await writeHostedHelp(stdout, args, data, renderHostedSiteHelp(manifest, site));
         return;
     }
     const command = findHostedCommand(manifest, site, commandName);
     if (!command) {
-        throw new ConfigError(`Unknown hosted Webcmd command: ${site}/${commandName}`);
+        if (!normalized.literal && hasTerminalBeforeSeparator(args.slice(1), token => token === '--help' || token === '-h')) {
+            const data = hostedSiteHelpData(manifest, site);
+            if (!data) {
+                throw new CommanderCompatibleError(`error: unknown command '${site}'\n`, EXIT_CODES.USAGE_ERROR, formatRootHelp(HOSTED_ROOT_HELP));
+            }
+            await writeHostedHelp(stdout, args, data, renderHostedSiteHelp(manifest, site));
+            return;
+        }
+        throw new CommanderCompatibleError(`error: unknown command '${commandName}'\n`, EXIT_CODES.GENERIC_ERROR);
     }
     if (isLocalOnlyHostedCommand(command)) {
-        throw new ConfigError(`Command ${command.command} is local-only and is not available in hosted mode.`, 'Run `webcmd setup` and choose local mode to use local-only commands.');
+        throw new ConfigError(`Command ${command.command} is local-only and is not available in hosted mode.`, LOCAL_ONLY_COMMAND_HELP);
     }
-    const parsed = parseHostedInvocation(command, [...args.slice(2), ...normalized.trailingCommandOptions]);
+    const parsed = parseHostedInvocation(command, args.slice(2));
     if (parsed.help) {
-        stdout.write(renderHostedCommandHelp(command));
+        await writeHostedHelp(stdout, args, hostedCommandHelpData(command), renderHostedCommandHelp(command));
         return;
     }
-    const response = await client.execute({
-        command: command.command,
-        args: parsed.args,
-        format: parsed.format,
-        trace: parsed.trace,
-        profile: parsed.profile ?? normalized.profile,
+    const startTime = now();
+    const response = hasPresentFileArgument(command, parsed.args)
+        ? await executeHostedFileCommand({
+            client,
+            command,
+            args: parsed.args,
+            format: parsed.format,
+            trace: parsed.trace,
+            profile: parsed.profile ?? normalized.profile,
+        })
+        : await client.execute({
+            command: command.command,
+            args: parsed.args,
+            format: parsed.format,
+            trace: parsed.trace,
+            profile: parsed.profile ?? normalized.profile,
+        });
+    let format = parsed.format;
+    if (!parsed.formatExplicit && format === 'table' && command.defaultFormat) {
+        format = command.defaultFormat;
+    }
+    const elapsed = (now() - startTime) / 1000;
+    if (response.result !== null && response.result !== undefined) {
+        await renderOutput(response.result, {
+            fmt: format,
+            fmtExplicit: parsed.formatExplicit,
+            columns: response.columns ?? command.columns,
+            title: command.command,
+            elapsed,
+            source: command.command,
+            footerExtra: response.footerExtra,
+            stdout,
+        });
+    }
+    if (parsed.trace === 'on' && response.trace) {
+        await writeToStream(stderr, `Webcmd trace artifact: ${response.trace.receipt}\n`);
+    }
+}
+function hasPresentFileArgument(command, args) {
+    return command.args.some((arg) => {
+        if (!arg.file)
+            return false;
+        const value = args[arg.name] ?? arg.default;
+        return value !== undefined && value !== null && value !== '';
+    });
+}
+async function executeHostedFileCommand(input) {
+    const prepared = await prepareHostedFiles({
+        client: input.client,
+        command: input.command,
+        args: input.args,
     });
-    const result = response.result ?? response.rows ?? response.data ?? null;
-    renderOutput(result, {
-        fmt: parsed.format,
-        fmtExplicit: true,
-        columns: response.columns ?? command.columns,
-        title: command.command,
-        source: 'webcmd cloud',
+    const response = await input.client.runPreparedExecution({
+        executionId: prepared.executionId,
+        command: input.command.command,
+        args: prepared.args,
+        format: input.format,
+        trace: input.trace,
+        ...(input.profile !== undefined ? { profile: input.profile } : {}),
     });
+    const materialized = await materializeHostedOutputs({
+        client: input.client,
+        response,
+        outputs: prepared.outputs,
+    });
+    return {
+        ...response,
+        result: rewriteHostedOutputResultPaths(response.result, materialized),
+    };
 }
-async function dispatchHostedBrowser(argv, profile, client, stdout) {
-    const invocation = parseHostedBrowserInvocation(argv, profile);
+async function dispatchHostedBrowser(invocation, client, stdout) {
+    const args = invocation.action === 'set-file-input'
+        ? materializeHostedBrowserUploadArgs(invocation.args)
+        : invocation.args;
     const response = await client.runBrowserAction(invocation.session, {
         command: invocation.command,
         action: invocation.action,
-        args: invocation.args,
+        args,
         ...(invocation.profile !== undefined ? { profile: invocation.profile } : {}),
         ...(invocation.windowMode !== undefined ? { windowMode: invocation.windowMode } : {}),
         trace: 'off',
     });
-    renderHostedBrowserResponse(stdout, invocation, response);
+    await renderHostedBrowserResponse(stdout, invocation, response);
+}
+function materializeHostedBrowserUploadArgs(args) {
+    const files = args.files;
+    if (!Array.isArray(files))
+        return args;
+    return {
+        ...args,
+        files: files.map((file) => {
+            if (typeof file !== 'string')
+                return file;
+            const body = readFileSync(file);
+            return {
+                $webcmdBrowserUpload: {
+                    filename: path.basename(file),
+                    contentType: contentTypeForUpload(file),
+                    base64: Buffer.from(body).toString('base64'),
+                },
+            };
+        }),
+    };
+}
+function contentTypeForUpload(filePath) {
+    switch (path.extname(filePath).toLowerCase()) {
+        case '.gif':
+            return 'image/gif';
+        case '.jpg':
+        case '.jpeg':
+            return 'image/jpeg';
+        case '.json':
+            return 'application/json';
+        case '.pdf':
+            return 'application/pdf';
+        case '.png':
+            return 'image/png';
+        case '.txt':
+            return 'text/plain';
+        case '.webp':
+            return 'image/webp';
+        default:
+            return 'application/octet-stream';
+    }
 }
 function parseHostedBrowserInvocation(argv, profile) {
     let rewritten;
@@ -110,37 +327,28 @@ function parseHostedBrowserInvocation(argv, profile) {
         }
         throw error;
     }
+    let structure;
+    try {
+        structure = parseHostedBrowserStructure(rewritten);
+    }
+    catch (error) {
+        if (error instanceof HostedBrowserHelp)
+            throw new CommanderCompatibleError('', 0, error.output);
+        throw error;
+    }
     if (rewritten[0] !== 'browser') {
         throw new ConfigError('Hosted browser invocation must start with browser.');
     }
-    if (rewritten[1] !== '--session' || !rewritten[2]) {
+    if (!structure.session) {
         throw new ConfigError('<session> is required for hosted browser commands.', 'Use: webcmd browser <session> <command>');
     }
-    const session = rewritten[2];
-    let index = 3;
-    let windowMode;
-    while (index < rewritten.length) {
-        const token = rewritten[index];
-        if (token === '--window') {
-            windowMode = parseWindowMode(rewritten[index + 1]);
-            index += 2;
-            continue;
-        }
-        if (token?.startsWith('--window=')) {
-            windowMode = parseWindowMode(token.slice('--window='.length));
-            index += 1;
-            continue;
-        }
-        break;
-    }
-    const leaf = rewritten[index];
-    if (!leaf || leaf === '--help' || leaf === '-h') {
+    if (!structure.commandName) {
         throw new ConfigError('Hosted browser command is required.', 'Use: webcmd browser <session> open <url>, state, screenshot, tab list, or eval <js>.');
     }
-    const rest = rewritten.slice(index + 1);
-    const parsed = parseBrowserLeaf(leaf, rest);
+    const windowMode = structure.window === undefined ? undefined : parseWindowMode(structure.window);
+    const parsed = parseBrowserLeaf(structure.commandName, structure.positionals, structure.options);
     return {
-        session,
+        session: structure.session,
         command: `browser/${parsed.commandName}`,
         action: parsed.action,
         args: parsed.args,
@@ -154,245 +362,278 @@ function parseWindowMode(value) {
         return value;
     throw new ConfigError('--window must be one of: foreground, background.');
 }
-function parseBrowserLeaf(leaf, argv) {
-    const parsed = splitOptions(argv);
-    switch (leaf) {
-        case 'bind':
+function parseBrowserLeaf(leaf, positionals, options) {
+    const contract = hostedBrowserCommandsByPath.get(leaf);
+    if (!contract || !contract.action) {
+        if (leaf === 'bind' || contract?.sessionPolicy === 'local-only') {
             throw new ConfigError('Browser bind is not supported in hosted mode.', 'Use browser state or browser tabs to inspect the active hosted page.');
-        case 'unbind':
-        case 'close':
-            return { commandName: leaf, action: 'close-window', args: {} };
-        case 'open':
-            return { commandName: 'open', action: 'navigate', args: { url: requiredPositional(parsed.positionals, 0, 'url') } };
-        case 'back':
-            return { commandName: 'back', action: 'back', args: {} };
-        case 'state':
-            return { commandName: 'state', action: 'snapshot', args: { source: parsed.options.source ?? 'dom' } };
-        case 'frames':
-            return { commandName: 'frames', action: 'frames', args: {} };
-        case 'screenshot': {
-            const localPath = parsed.positionals[0];
-            return {
-                commandName: 'screenshot',
-                action: 'screenshot',
-                args: {
-                    fullPage: parsed.options.fullPage === true,
-                    ...(parsed.options.width !== undefined ? { width: parsed.options.width } : {}),
-                    ...(parsed.options.height !== undefined ? { height: parsed.options.height } : {}),
-                },
-                ...(localPath !== undefined ? { localPath } : {}),
-            };
         }
-        case 'tab':
-            return parseBrowserTab(parsed.positionals);
-        case 'eval':
+        throw new ConfigError(`Hosted browser command is not supported yet: ${leaf}`);
+    }
+    const localPath = leaf === 'screenshot' ? positionals[0] : undefined;
+    const args = browserActionArgs(contract, positionals, options);
+    return {
+        commandName: leaf,
+        action: contract.action,
+        args,
+        ...(localPath !== undefined ? { localPath } : {}),
+    };
+}
+function browserActionArgs(contract, positionals, options) {
+    const args = compactRecord({ ...options });
+    let index = 0;
+    for (const positional of contract.positionals) {
+        if (positional.variadic) {
+            const rest = positionals.slice(index);
+            if (rest.length)
+                args[positional.name] = rest;
+            index = positionals.length;
+            continue;
+        }
+        const value = positionals[index];
+        if (value !== undefined)
+            args[positional.name] = value;
+        index += 1;
+    }
+    switch (contract.command) {
+        case 'screenshot':
+            delete args.path;
+            return args;
+        case 'tab/list':
+            return { ...args, op: 'list' };
+        case 'tab/new':
             return {
-                commandName: 'eval',
-                action: 'exec',
-                args: {
-                    js: requiredPositional(parsed.positionals, 0, 'js'),
-                    ...(parsed.options.frame !== undefined ? { frame: parsed.options.frame } : {}),
-                },
+                ...withoutKeys(args, ['url']),
+                op: 'new',
+                ...(typeof args.url === 'string' && args.url ? { url: args.url } : {}),
             };
-        case 'scroll':
+        case 'tab/select':
             return {
-                commandName: 'scroll',
-                action: 'scroll',
-                args: {
-                    direction: requiredPositional(parsed.positionals, 0, 'direction'),
-                    amount: parsed.options.amount ?? 500,
-                },
+                ...withoutKeys(args, ['targetId']),
+                op: 'select',
+                ...(typeof args.targetId === 'string' && args.targetId ? { target: args.targetId } : {}),
             };
-        case 'keys':
-            return { commandName: 'keys', action: 'press-key', args: { key: requiredPositional(parsed.positionals, 0, 'key') } };
-        case 'wait':
+        case 'tab/close':
             return {
-                commandName: 'wait',
-                action: 'wait',
-                args: {
-                    type: requiredPositional(parsed.positionals, 0, 'type'),
-                    ...(parsed.positionals[1] !== undefined ? { value: parsed.positionals[1] } : {}),
-                    ...(parsed.options.timeout !== undefined ? { timeout: parsed.options.timeout } : {}),
-                },
+                ...withoutKeys(args, ['targetId']),
+                op: 'close',
+                ...(typeof args.targetId === 'string' && args.targetId ? { target: args.targetId } : {}),
             };
-        case 'click':
-            return { commandName: 'click', action: 'click', args: { target: requiredPositional(parsed.positionals, 0, 'target') } };
         case 'type':
-            return {
-                commandName: 'type',
-                action: 'type',
-                args: {
-                    target: requiredPositional(parsed.positionals, 0, 'target'),
-                    text: requiredPositional(parsed.positionals, 1, 'text'),
-                },
-            };
+            return rewriteTextTargetArgs(args, options, 'targetOrText', 'text');
         case 'fill':
-            return {
-                commandName: 'fill',
-                action: 'fill',
-                args: {
-                    target: requiredPositional(parsed.positionals, 0, 'target'),
-                    text: requiredPositional(parsed.positionals, 1, 'text'),
-                },
-            };
+            return rewriteTextTargetArgs(args, options, 'targetOrText', 'text');
+        case 'select':
+            return rewriteTextTargetArgs(args, options, 'targetOrOption', 'option');
         case 'upload':
-            return {
-                commandName: 'upload',
-                action: 'set-file-input',
-                args: {
-                    selector: parsed.positionals[0] ?? 'input[type="file"]',
-                    files: parsed.positionals.slice(1),
-                },
-            };
-        case 'console':
-            return { commandName: 'console', action: 'console', args: parsed.options };
-        case 'network':
-            return { commandName: 'network', action: 'network', args: parsed.options };
+            return rewriteUploadArgs(args, options);
         default:
-            throw new ConfigError(`Hosted browser command is not supported yet: ${leaf}`);
+            return args;
     }
 }
-function parseBrowserTab(positionals) {
-    const op = positionals[0] ?? 'list';
-    if (op === 'list')
-        return { commandName: 'tab/list', action: 'tabs', args: { op: 'list' } };
-    if (op === 'new')
-        return { commandName: 'tab/new', action: 'tabs', args: { op: 'new', ...(positionals[1] ? { url: positionals[1] } : {}) } };
-    if (op === 'select')
-        return { commandName: 'tab/select', action: 'tabs', args: { op: 'select', target: requiredPositional(positionals, 1, 'targetId') } };
-    if (op === 'close')
-        return { commandName: 'tab/close', action: 'tabs', args: { op: 'close', target: requiredPositional(positionals, 1, 'targetId') } };
-    throw new ConfigError(`Hosted browser tab command is not supported yet: ${op}`);
-}
-function splitOptions(argv) {
-    const positionals = [];
-    const options = {};
-    let literal = false;
-    for (let i = 0; i < argv.length; i++) {
-        const token = argv[i];
-        if (literal) {
-            positionals.push(token);
-            continue;
-        }
-        if (token === '--') {
-            literal = true;
-            continue;
-        }
-        if (!token.startsWith('-') || token === '-') {
-            positionals.push(token);
-            continue;
-        }
-        if (token.startsWith('--') && token.includes('=')) {
-            const [rawKey, ...rawValue] = token.slice(2).split('=');
-            options[toCamelCase(rawKey)] = coerceOptionValue(rawValue.join('='));
-            continue;
-        }
-        const key = token.replace(/^-+/, '');
-        const next = argv[i + 1];
-        if (next !== undefined && !next.startsWith('-')) {
-            options[toCamelCase(key)] = coerceOptionValue(next);
-            i += 1;
-        }
-        else {
-            options[toCamelCase(key)] = true;
-        }
+function rewriteTextTargetArgs(args, options, firstPositionalName, valueName) {
+    const first = args[firstPositionalName];
+    const value = args[valueName];
+    const next = withoutKeys(args, [firstPositionalName, valueName]);
+    if (hasSemanticLocator(options)) {
+        return {
+            ...next,
+            ...(typeof first === 'string' ? { [valueName]: first } : {}),
+        };
     }
-    return { positionals, options };
+    return {
+        ...next,
+        ...(typeof first === 'string' ? { target: first } : {}),
+        ...(typeof value === 'string' ? { [valueName]: value } : {}),
+    };
 }
-function requiredPositional(values, index, label) {
-    const value = values[index];
-    if (value === undefined || value === '') {
-        throw new ConfigError(`Missing required browser argument: ${label}`);
+function rewriteUploadArgs(args, options) {
+    const targetOrFile = args.targetOrFile;
+    const files = Array.isArray(args.files) ? args.files.filter((entry) => typeof entry === 'string') : [];
+    const next = withoutKeys(args, ['targetOrFile', 'files']);
+    if (hasSemanticLocator(options)) {
+        return {
+            ...next,
+            files: [
+                ...(typeof targetOrFile === 'string' ? [targetOrFile] : []),
+                ...files,
+            ],
+        };
     }
-    return value;
+    return {
+        ...next,
+        selector: typeof targetOrFile === 'string' ? targetOrFile : 'input[type="file"]',
+        files,
+    };
+}
+function hasSemanticLocator(args) {
+    return ['role', 'name', 'label', 'text', 'testid'].some(key => args[key] !== undefined);
 }
-function toCamelCase(value) {
-    return value.replace(/-([a-z])/g, (_match, letter) => letter.toUpperCase());
+function compactRecord(input) {
+    return Object.fromEntries(Object.entries(input).filter(([, value]) => value !== undefined));
 }
-function coerceOptionValue(value) {
-    if (value === 'true')
-        return true;
-    if (value === 'false')
-        return false;
-    if (/^-?\d+$/.test(value))
-        return Number.parseInt(value, 10);
-    return value;
+function withoutKeys(input, keys) {
+    const blocked = new Set(keys);
+    return Object.fromEntries(Object.entries(input).filter(([key, value]) => !blocked.has(key) && value !== undefined));
 }
-function renderHostedBrowserResponse(stdout, invocation, response) {
+async function renderHostedBrowserResponse(stdout, invocation, response) {
     const result = response.result;
     if (invocation.action === 'snapshot' && result && typeof result === 'object') {
         const record = result;
-        stdout.write(`URL: ${typeof record.url === 'string' ? record.url : ''}\n\n`);
-        stdout.write(`${typeof record.snapshot === 'string' ? record.snapshot : JSON.stringify(record.snapshot, null, 2)}\n`);
+        await writeToStream(stdout, `URL: ${typeof record.url === 'string' ? record.url : ''}\n\n`);
+        await writeToStream(stdout, `${typeof record.snapshot === 'string' ? record.snapshot : JSON.stringify(record.snapshot, null, 2)}\n`);
         return;
     }
     if (invocation.action === 'screenshot' && result && typeof result === 'object') {
         const base64 = result.base64;
         if (typeof base64 === 'string' && invocation.localPath) {
             writeFileSync(invocation.localPath, Buffer.from(base64, 'base64'));
-            stdout.write(`Screenshot saved to: ${invocation.localPath}\n`);
+            await writeToStream(stdout, `Screenshot saved to: ${invocation.localPath}\n`);
             return;
         }
         if (typeof base64 === 'string') {
-            stdout.write(`${base64}\n`);
+            await writeToStream(stdout, `${base64}\n`);
             return;
         }
     }
     if (typeof result === 'string') {
-        stdout.write(`${result}\n`);
+        await writeToStream(stdout, `${result}\n`);
         return;
     }
-    stdout.write(`${JSON.stringify(result ?? response, null, 2)}\n`);
+    await writeToStream(stdout, `${JSON.stringify(result, null, 2)}\n`);
 }
-function renderHostedList(manifest, argv) {
-    const fmt = readFormat(argv);
-    const structured = fmt === 'json' || fmt === 'yaml' || fmt === 'yml';
-    renderOutput(hostedListRows(manifest, structured), {
+async function renderHostedList(manifest, fmt, explicit, stdout) {
+    const presentation = hostedListPresentation(manifest, fmt);
+    if (presentation.displayLines) {
+        for (const line of presentation.displayLines)
+            await writeToStream(stdout, `${line}\n`);
+        return;
+    }
+    await renderOutput(presentation.rows, {
         fmt,
-        fmtExplicit: true,
-        columns: ['command', 'site', 'name', 'aliases', 'description', 'access', 'strategy', 'browser', 'args',
-            ...(structured ? ['columns', 'domain'] : [])],
-        title: 'webcmd/list',
-        source: 'webcmd cloud',
+        fmtExplicit: explicit,
+        columns: presentation.columns,
+        stdout,
+    });
+}
+async function writeHostedHelp(stdout, argv, data, text) {
+    const format = getRequestedHelpFormat(argv);
+    await writeToStream(stdout, format ? renderStructuredHelp(data, format) : text);
+}
+function parseHostedListSurface(argv, literal) {
+    let stdout = '';
+    let stderr = '';
+    let parsedFormat = 'table';
+    let formatExplicit = false;
+    let actionRan = false;
+    const root = new Command('webcmd');
+    const list = configureListCommandSurface(root.command('list'));
+    const output = {
+        writeOut: (value) => { stdout += value; },
+        writeErr: (value) => { stderr += value; },
+    };
+    root.exitOverride().configureOutput(output);
+    list.exitOverride().configureOutput(output).action((options) => {
+        actionRan = true;
+        parsedFormat = options.format;
+        formatExplicit = list.getOptionValueSource('format') === 'cli';
     });
+    try {
+        root.parse(literal ? ['--', 'list', ...argv] : ['list', ...argv], { from: 'user' });
+    }
+    catch (error) {
+        if (!(error instanceof CommanderError))
+            throw error;
+        if (error.code === 'commander.helpDisplayed')
+            return { kind: 'help', output: stdout };
+        throw new CommanderStructuralError(stderr || `${error.message}\n`, error.exitCode);
+    }
+    if (!actionRan)
+        throw new CommanderStructuralError("error: command 'list' did not run\n", 1);
+    return { kind: 'run', format: parsedFormat, formatExplicit };
 }
-function readFormat(argv) {
-    for (let i = 0; i < argv.length; i++) {
-        if (argv[i] === '-f' || argv[i] === '--format')
-            return argv[i + 1] ?? 'table';
-        if (argv[i]?.startsWith('--format='))
-            return argv[i].slice('--format='.length);
-    }
-    return 'table';
+function parseHostedCompletionSurface(argv, literal) {
+    let stdout = '';
+    let stderr = '';
+    let shell;
+    const root = new Command('webcmd');
+    const completion = configureCompletionCommandSurface(root.command('completion'));
+    const output = {
+        writeOut: (value) => { stdout += value; },
+        writeErr: (value) => { stderr += value; },
+    };
+    root.exitOverride().configureOutput(output);
+    completion.exitOverride().configureOutput(output).action((value) => {
+        shell = value;
+    });
+    try {
+        root.parse(literal ? ['--', 'completion', ...argv] : ['completion', ...argv], { from: 'user' });
+    }
+    catch (error) {
+        if (!(error instanceof CommanderError))
+            throw error;
+        if (error.code === 'commander.helpDisplayed')
+            return { kind: 'help', output: stdout };
+        throw new CommanderStructuralError(stderr || `${error.message}\n`, error.exitCode);
+    }
+    if (shell === undefined) {
+        throw new CommanderStructuralError("error: missing required argument 'shell'\n", 1);
+    }
+    return { kind: 'run', shell };
 }
-function stripGlobalOptions(argv) {
-    const out = [];
-    const trailingCommandOptions = [];
+function parseUnknownSiteRootOptions(argv, literal) {
+    if (literal)
+        return { help: false, version: false };
     let profile;
-    for (let i = 0; i < argv.length; i++) {
+    let help = false;
+    for (let i = 1; i < argv.length; i += 1) {
         const token = argv[i];
+        if (token === '--')
+            break;
         if (token === '--profile') {
-            profile = argv[++i];
+            const value = argv[i + 1];
+            if (value === undefined) {
+                throw new CommanderStructuralError("error: option '--profile <name>' argument missing\n", 1);
+            }
+            profile = value;
+            i += 1;
             continue;
         }
         if (token.startsWith('--profile=')) {
             profile = token.slice('--profile='.length);
             continue;
         }
-        out.push(token);
+        if (token === '--version' || token.startsWith('-V')) {
+            return { help: false, version: true, ...(profile !== undefined ? { profile } : {}) };
+        }
+        if (token === '--help' || token === '-h')
+            help = true;
     }
-    return { argv: out, trailingCommandOptions, ...(profile ? { profile } : {}) };
+    return { help, version: false, ...(profile !== undefined ? { profile } : {}) };
 }
-function isCompletionRequest(argv) {
-    return argv.includes('--get-completions');
+function hasTerminalBeforeSeparator(argv, predicate) {
+    for (const token of argv) {
+        if (token === '--')
+            return false;
+        if (predicate(token))
+            return true;
+    }
+    return false;
 }
 function hostedCompletions(manifest, argv) {
     const index = argv.indexOf('--get-completions');
-    const words = index === -1 ? argv : argv.slice(index + 1).filter((word) => word !== '--cursor');
-    const meaningful = words.filter((word) => !/^\d+$/.test(word));
-    if (meaningful.length <= 1)
-        return ['list', 'setup', ...siteNames(manifest)];
-    return commandNamesForSite(manifest, meaningful[0]);
+    const rest = index === -1 ? argv : argv.slice(index + 1);
+    const words = [];
+    let cursor;
+    for (let i = 0; i < rest.length; i += 1) {
+        if (rest[i] === '--cursor' && i + 1 < rest.length) {
+            cursor = Number.parseInt(rest[++i], 10);
+        }
+        else {
+            words.push(rest[i]);
+        }
+    }
+    return getCommandCompletionCandidates(hostedCommands(manifest), words, Number.isFinite(cursor) ? cursor : words.length, HOSTED_BUILTIN_COMMANDS);
 }
 function errorExitCode(err) {
     if (err instanceof ConfigError)
@@ -402,3 +643,63 @@ function errorExitCode(err) {
     }
     return EXIT_CODES.GENERIC_ERROR;
 }
+function validateManifestContractIdentity(manifest) {
+    const installed = readInstalledHostedContractIdentity();
+    const installedLine = hostedContractCompatibilityLine(installed.webcmdVersion);
+    const manifestLine = hostedContractCompatibilityLine(manifest.metadata.webcmdPackageVersion);
+    if (manifest.metadata.contractSchemaVersion !== installed.schemaVersion
+        || !installedLine
+        || !manifestLine
+        || manifestLine !== installedLine) {
+        throw new HostedClientError('HOSTED_PROTOCOL', 'Webcmd Cloud manifest does not match this installed Webcmd hosted contract.');
+    }
+}
+function hostedContractCompatibilityLine(version) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
+    if (!match)
+        return undefined;
+    return `${match[1]}.${match[2]}.0`;
+}
+function readInstalledHostedContractIdentity() {
+    try {
+        const moduleFile = fileURLToPath(import.meta.url);
+        const packageRoot = findPackageRoot(moduleFile);
+        const value = JSON.parse(readFileSync(path.join(packageRoot, 'hosted-contract.json'), 'utf-8'));
+        if (!value
+            || typeof value !== 'object'
+            || typeof value.schemaVersion !== 'number'
+            || typeof value.webcmdVersion !== 'string') {
+            throw new Error('invalid hosted contract identity');
+        }
+        return value;
+    }
+    catch {
+        throw new HostedClientError('HOSTED_PROTOCOL', 'The installed Webcmd hosted contract could not be validated.');
+    }
+}
+function hostedCommandName(argv) {
+    const positionals = [];
+    const valueOptions = new Set(['--profile', '-f', '--format', '--trace']);
+    for (let i = 0; i < argv.length && positionals.length < 2; i += 1) {
+        const token = argv[i];
+        if (valueOptions.has(token)) {
+            i += 1;
+            continue;
+        }
+        if (token.startsWith('-'))
+            continue;
+        positionals.push(token);
+    }
+    if (positionals.length < 2)
+        return positionals[0];
+    return `${positionals[0]}/${positionals[1]}`;
+}
+function hostedTraceMode(argv) {
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === '--trace')
+            return argv[i + 1];
+        if (argv[i]?.startsWith('--trace='))
+            return argv[i].slice('--trace='.length);
+    }
+    return undefined;
+}