@agentrhq/webcmd 0.3.0 → 0.3.2

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

@@ -0,0 +1,231 @@
+import { createHash } from 'node:crypto';
+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { materializeHostedOutputs, prepareHostedFiles, rewriteHostedOutputResultPaths } from './files.js';
+let tempDir;
+afterEach(async () => {
+    if (tempDir)
+        await rm(tempDir, { recursive: true, force: true });
+    tempDir = undefined;
+});
+const fileCommand = {
+    site: 'twitter',
+    name: 'post',
+    command: 'twitter/post',
+    description: 'Post',
+    access: 'write',
+    strategy: 'UI',
+    browser: true,
+    columns: ['ok'],
+    args: [
+        { name: 'text', positional: true, required: true },
+        {
+            name: 'images',
+            file: {
+                direction: 'input',
+                pathKind: 'file',
+                multiple: true,
+                separator: ',',
+                contentTypes: ['image/png'],
+                maxBytes: 1024,
+            },
+        },
+        {
+            name: 'output',
+            file: {
+                direction: 'output',
+                pathKind: 'directory',
+                multiple: false,
+                defaultPath: './downloads',
+            },
+        },
+    ],
+};
+describe('hosted file transfer helpers', () => {
+    it('uploads declared input files and reserves declared outputs without leaking local paths', async () => {
+        tempDir = await mkdtemp(path.join(tmpdir(), 'webcmd-hosted-files-'));
+        const one = path.join(tempDir, 'one.png');
+        const two = path.join(tempDir, 'two.png');
+        await writeFile(one, 'one');
+        await writeFile(two, 'two');
+        const client = fakeClient();
+        const prepared = await prepareHostedFiles({
+            client,
+            command: fileCommand,
+            cwd: tempDir,
+            args: {
+                text: 'hello',
+                images: './one.png,./two.png',
+            },
+        });
+        expect(client.prepareExecution).toHaveBeenCalledWith({ command: 'twitter/post' });
+        expect(client.uploadExecutionArtifact).toHaveBeenCalledTimes(2);
+        expect(client.uploadExecutionArtifact).toHaveBeenNthCalledWith(1, expect.objectContaining({
+            executionId: 'exec_prepared',
+            argument: 'images',
+            filename: 'one.png',
+            contentType: 'image/png',
+            body: new Uint8Array(Buffer.from('one')),
+        }));
+        expect(prepared.args).toEqual({
+            text: 'hello',
+            images: [
+                { $webcmdArtifact: { id: 'artifact_1', direction: 'input' } },
+                { $webcmdArtifact: { id: 'artifact_2', direction: 'input' } },
+            ],
+            output: {
+                $webcmdArtifact: {
+                    direction: 'output',
+                    filename: 'downloads',
+                    contentType: 'application/octet-stream',
+                },
+            },
+        });
+        expect(prepared.outputs).toEqual([{
+                argument: 'output',
+                pathKind: 'directory',
+                localPath: path.join(tempDir, 'downloads'),
+            }]);
+        expect(JSON.stringify(prepared.args)).not.toContain(tempDir);
+    });
+    it('downloads output receipts, verifies hashes, and writes files atomically', async () => {
+        tempDir = await mkdtemp(path.join(tmpdir(), 'webcmd-hosted-files-'));
+        const body = new Uint8Array(Buffer.from('hello cloud'));
+        const client = {
+            downloadExecutionArtifact: vi.fn(async () => body),
+        };
+        const response = responseWithArtifact({
+            artifactId: 'artifact_out',
+            relativePath: 'nested/result.txt',
+            byteSize: body.byteLength,
+            sha256: sha256Hex(body),
+        });
+        const materialized = await materializeHostedOutputs({
+            client,
+            response,
+            outputs: [{
+                    argument: 'output',
+                    pathKind: 'directory',
+                    localPath: path.join(tempDir, 'downloads'),
+                }],
+        });
+        await expect(readFile(path.join(tempDir, 'downloads', 'nested', 'result.txt'), 'utf8')).resolves.toBe('hello cloud');
+        expect(rewriteHostedOutputResultPaths({
+            file: '📁 /private/cloud-artifacts/output-directory/nested/result.txt',
+        }, materialized)).toEqual({
+            file: `📁 ${path.join(tempDir, 'downloads', 'nested', 'result.txt')}`,
+        });
+        expect(client.downloadExecutionArtifact).toHaveBeenCalledWith({
+            executionId: 'exec_success',
+            artifactId: 'artifact_out',
+        });
+    });
+    it('validates local inputs before creating a prepared cloud execution', async () => {
+        tempDir = await mkdtemp(path.join(tmpdir(), 'webcmd-hosted-files-'));
+        const client = fakeClient();
+        await expect(prepareHostedFiles({
+            client,
+            command: fileCommand,
+            cwd: tempDir,
+            args: {
+                text: 'hello',
+                images: './missing.png',
+            },
+        })).rejects.toMatchObject({ code: 'HOSTED_FILE_NOT_FOUND' });
+        expect(client.prepareExecution).not.toHaveBeenCalled();
+        expect(client.uploadExecutionArtifact).not.toHaveBeenCalled();
+    });
+    it('rejects unsafe relative output paths before downloading', async () => {
+        tempDir = await mkdtemp(path.join(tmpdir(), 'webcmd-hosted-files-'));
+        const client = {
+            downloadExecutionArtifact: vi.fn(),
+        };
+        await expect(materializeHostedOutputs({
+            client,
+            response: responseWithArtifact({
+                artifactId: 'artifact_out',
+                relativePath: '../escape.txt',
+                byteSize: 0,
+            }),
+            outputs: [{
+                    argument: 'output',
+                    pathKind: 'directory',
+                    localPath: path.join(tempDir, 'downloads'),
+                }],
+        })).rejects.toMatchObject({ code: 'HOSTED_FILE_OUTPUT_INVALID' });
+        expect(client.downloadExecutionArtifact).not.toHaveBeenCalled();
+    });
+    it('removes temporary files when download hash verification fails', async () => {
+        tempDir = await mkdtemp(path.join(tmpdir(), 'webcmd-hosted-files-'));
+        const client = {
+            downloadExecutionArtifact: vi.fn(async () => new Uint8Array(Buffer.from('bad body'))),
+        };
+        await expect(materializeHostedOutputs({
+            client,
+            response: responseWithArtifact({
+                artifactId: 'artifact_out',
+                relativePath: 'result.txt',
+                byteSize: 8,
+                sha256: sha256Hex(new Uint8Array(Buffer.from('expected'))),
+            }),
+            outputs: [{
+                    argument: 'output',
+                    pathKind: 'directory',
+                    localPath: path.join(tempDir, 'downloads'),
+                }],
+        })).rejects.toMatchObject({ code: 'HOSTED_FILE_HASH_MISMATCH' });
+        const entries = await readdir(path.join(tempDir, 'downloads')).catch(() => []);
+        expect(entries.filter(entry => entry.includes('.tmp'))).toEqual([]);
+    });
+});
+function fakeClient() {
+    let uploads = 0;
+    return {
+        prepareExecution: vi.fn(async () => ({
+            ok: true,
+            execution: { id: 'exec_prepared', command: 'twitter/post', status: 'queued' },
+            fileArguments: [],
+        })),
+        uploadExecutionArtifact: vi.fn(async (input) => {
+            uploads += 1;
+            return {
+                ok: true,
+                artifact: {
+                    artifactId: `artifact_${uploads}`,
+                    argument: input.argument,
+                    direction: 'input',
+                    pathKind: 'file',
+                    filename: `file_${uploads}.png`,
+                    contentType: 'image/png',
+                    byteSize: 3,
+                    expiresAt: '2026-07-15T00:00:00.000Z',
+                },
+                reference: { $webcmdArtifact: { id: `artifact_${uploads}`, direction: 'input' } },
+            };
+        }),
+    };
+}
+function responseWithArtifact(input) {
+    return {
+        ok: true,
+        result: [{ ok: true }],
+        execution: { id: 'exec_success', command: 'twitter/post', status: 'succeeded' },
+        artifacts: [{
+                artifactId: input.artifactId,
+                argument: 'output',
+                direction: 'output',
+                pathKind: 'file',
+                filename: path.basename(input.relativePath),
+                contentType: 'text/plain',
+                byteSize: input.byteSize,
+                ...(input.sha256 !== undefined ? { sha256: input.sha256 } : {}),
+                relativePath: input.relativePath,
+                expiresAt: '2026-07-15T00:00:00.000Z',
+            }],
+    };
+}
+function sha256Hex(body) {
+    return createHash('sha256').update(body).digest('hex');
+}

package/dist/src/hosted/main-lifecycle.test.d.ts

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

package/dist/src/hosted/main-lifecycle.test.js

@@ -0,0 +1,213 @@
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createServer } from 'node:http';
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { afterEach, describe, expect, it } from 'vitest';
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const entrypoint = path.join(packageRoot, 'src/main.ts');
+const largeOutput = 'hosted-lifecycle-chunk\n'.repeat(64 * 1024);
+const traceReceipt = 'https://api.example.test/v1/traces/exec_lifecycle';
+const tempRoots = [];
+const servers = [];
+const command = {
+    site: 'lifecycle',
+    name: 'stream',
+    command: 'lifecycle/stream',
+    description: 'Exercise hosted process lifecycle',
+    access: 'read',
+    strategy: 'PUBLIC',
+    browser: false,
+    args: [],
+    columns: ['value'],
+    defaultFormat: 'plain',
+};
+afterEach(async () => {
+    await Promise.all(servers.splice(0).map(server => new Promise((resolve, reject) => {
+        server.close(error => error ? reject(error) : resolve());
+    })));
+    await Promise.all(tempRoots.splice(0).map(root => rm(root, { recursive: true, force: true })));
+});
+describe('hosted CLI process lifecycle', () => {
+    it.each([
+        { name: 'version', argv: ['--version'] },
+        { name: 'shell completion', argv: ['completion', 'bash'] },
+    ])('preserves the legacy immediate-exit behavior for a backpressured $name fast path', async ({ argv }) => {
+        const fixture = await createHostedFixture('success');
+        const preload = await createDelayedStdoutPreload(path.dirname(fixture.discoverySentinel));
+        const result = await runCli(argv, fixture.env, [preload]);
+        expect(result.status).toBe(0);
+        expect(result.stdout).toBe('');
+        expect(result.stderr).toBe('');
+        await expect(readFile(fixture.discoverySentinel, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+    }, 20_000);
+    it('flushes delayed output and trace bytes, returns success, and never enters local discovery', async () => {
+        const fixture = await createHostedFixture('success');
+        const result = await runCli(['lifecycle', 'stream', '-f', 'plain', '--trace', 'on'], fixture.env);
+        expect(result.status).toBe(0);
+        expect(createHash('sha256').update(result.stdout).digest('hex'))
+            .toBe(createHash('sha256').update(`${largeOutput}\n`).digest('hex'));
+        expect(result.stdout).toBe(`${largeOutput}\n`);
+        expect(result.stderr).toBe(`Webcmd trace artifact: ${traceReceipt}\n`);
+        await expect(readFile(fixture.discoverySentinel, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+    }, 20_000);
+    it('flushes the typed error envelope and returns its public exit status without local discovery', async () => {
+        const fixture = await createHostedFixture('failure');
+        const result = await runCli(['lifecycle', 'stream', '-f', 'plain'], fixture.env);
+        expect(result.status).toBe(69);
+        expect(result.stdout).toBe('');
+        expect(result.stderr).toBe([
+            'ok: false',
+            'error:',
+            '  code: LIFECYCLE_FAILURE',
+            '  message: The hosted lifecycle fixture failed.',
+            '  help: Retry the lifecycle fixture.',
+            '  exitCode: 69',
+            '',
+        ].join('\n'));
+        await expect(readFile(fixture.discoverySentinel, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+    }, 20_000);
+    it('keeps an unknown first site authoritative with trailing tokens and never enters local discovery', async () => {
+        const fixture = await createHostedFixture('success');
+        const result = await runCli(['missing-site', 'child', '--format', 'json'], fixture.env);
+        expect(result.status).toBe(2);
+        expect(result.stderr).toBe("error: unknown command 'missing-site'\n");
+        expect(result.stdout).toContain('Local-only commands:');
+        await expect(readFile(fixture.discoverySentinel, 'utf8')).rejects.toMatchObject({ code: 'ENOENT' });
+    }, 20_000);
+});
+async function createHostedFixture(outcome) {
+    const root = await mkdtemp(path.join(tmpdir(), 'webcmd-hosted-lifecycle-'));
+    tempRoots.push(root);
+    const configDir = path.join(root, 'config');
+    const userClis = path.join(root, '.webcmd', 'clis', 'lifecycle-sentinel');
+    const discoverySentinel = path.join(root, 'local-discovery-ran');
+    await mkdir(configDir, { recursive: true });
+    await mkdir(userClis, { recursive: true });
+    await writeFile(path.join(userClis, 'sentinel.js'), [
+        "import { writeFileSync } from 'node:fs';",
+        `writeFileSync(${JSON.stringify(discoverySentinel)}, 'read');`,
+        "export const sentinel = 'cli(';",
+        '',
+    ].join('\n'));
+    const server = createServer((request, response) => {
+        if (request.url === '/v1/manifest') {
+            sendChunkedJson(response, {
+                ok: true,
+                manifest: {
+                    userId: 'user_lifecycle',
+                    metadata: {
+                        contractSchemaVersion: 1,
+                        webcmdPackageVersion: '0.3.0',
+                        generatedAt: '2026-07-14T00:00:00.000Z',
+                    },
+                    commands: [command],
+                },
+            });
+            return;
+        }
+        if (request.url === '/v1/execute' && request.method === 'POST') {
+            if (outcome === 'failure') {
+                sendChunkedJson(response, {
+                    ok: false,
+                    error: {
+                        code: 'LIFECYCLE_FAILURE',
+                        message: 'The hosted lifecycle fixture failed.',
+                        help: 'Retry the lifecycle fixture.',
+                        exitCode: 69,
+                    },
+                    execution: { id: 'exec_lifecycle', command: command.command, status: 'failed' },
+                }, 422);
+                return;
+            }
+            sendChunkedJson(response, {
+                ok: true,
+                result: { value: largeOutput },
+                columns: ['value'],
+                execution: { id: 'exec_lifecycle', command: command.command, status: 'succeeded' },
+                trace: { executionId: 'exec_lifecycle', receipt: traceReceipt },
+            });
+            return;
+        }
+        response.writeHead(404).end();
+    });
+    servers.push(server);
+    await new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    if (!address || typeof address === 'string')
+        throw new Error('Expected TCP lifecycle fixture address');
+    await writeFile(path.join(configDir, 'config.json'), `${JSON.stringify({
+        mode: 'hosted',
+        updatedAt: '2026-07-14T00:00:00.000Z',
+        hosted: {
+            apiBaseUrl: `http://127.0.0.1:${address.port}`,
+            apiKeyRef: 'wcmd_cred_lifecycle',
+            credentialBackend: 'file-fallback',
+        },
+    })}\n`);
+    await writeFile(path.join(configDir, 'hosted-credentials.json'), `${JSON.stringify({
+        version: 1,
+        credentials: { wcmd_cred_lifecycle: 'wcmd_lifecycle' },
+        updatedAt: '2026-07-14T00:00:00.000Z',
+    })}\n`, { mode: 0o600 });
+    return {
+        discoverySentinel,
+        env: {
+            ...process.env,
+            HOME: root,
+            WEBCMD_CONFIG_DIR: configDir,
+            WEBCMD_NO_UPDATE_CHECK: '1',
+        },
+    };
+}
+function sendChunkedJson(response, value, status = 200) {
+    const body = JSON.stringify(value);
+    const split = Math.floor(body.length / 2);
+    response.writeHead(status, { 'content-type': 'application/json' });
+    response.write(body.slice(0, split));
+    setTimeout(() => response.end(body.slice(split)), 25);
+}
+function runCli(args, env, imports = []) {
+    return new Promise((resolve, reject) => {
+        const importArgs = imports.flatMap(specifier => ['--import', pathToFileURL(specifier).href]);
+        const child = spawn(process.execPath, [...importArgs, '--import', 'tsx', entrypoint, ...args], {
+            cwd: packageRoot,
+            env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on('data', chunk => stdout.push(Buffer.from(chunk)));
+        child.stderr.on('data', chunk => stderr.push(Buffer.from(chunk)));
+        child.once('error', reject);
+        child.once('close', status => resolve({
+            status,
+            stdout: Buffer.concat(stdout).toString('utf8'),
+            stderr: Buffer.concat(stderr).toString('utf8'),
+        }));
+    });
+}
+async function createDelayedStdoutPreload(root) {
+    const preload = path.join(root, 'delay-stdout.mjs');
+    await writeFile(preload, [
+        'const originalWrite = process.stdout.write.bind(process.stdout);',
+        'process.stdout.write = function delayedWrite(chunk, encoding, callback) {',
+        "  const actualEncoding = typeof encoding === 'string' ? encoding : undefined;",
+        "  const done = typeof encoding === 'function' ? encoding : callback;",
+        '  setTimeout(() => {',
+        '    originalWrite(chunk, actualEncoding, (error) => {',
+        '      done?.(error);',
+        "      process.stdout.emit('drain');",
+        '    });',
+        '  }, 75);',
+        '  return false;',
+        '};',
+        '',
+    ].join('\n'));
+    return preload;
+}

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

@@ -1,9 +1,14 @@
+import { type PresentableCommand, type CommandListPresentation } from '../command-presentation.js';
 import type { HostedCommand, HostedManifest } from './types.js';
 export declare function isLocalOnlyHostedCommand(command: HostedCommand): boolean;
 export declare function hostedCommands(manifest: HostedManifest): HostedCommand[];
 export declare function findHostedCommand(manifest: HostedManifest, site: string, name: string): HostedCommand | null;
+export declare function presentHostedCommand(command: HostedCommand): PresentableCommand;
 export declare function hostedListRows(manifest: HostedManifest, structured: boolean): Record<string, unknown>[];
+export declare function hostedListPresentation(manifest: HostedManifest, format: string): CommandListPresentation;
 export declare function siteNames(manifest: HostedManifest): string[];
 export declare function commandNamesForSite(manifest: HostedManifest, site: string): string[];
 export declare function renderHostedSiteHelp(manifest: HostedManifest, site: string): string;
+export declare function hostedSiteHelpData(manifest: HostedManifest, site: string): Record<string, unknown> | null;
 export declare function renderHostedCommandHelp(command: HostedCommand): string;
+export declare function hostedCommandHelpData(command: HostedCommand): Record<string, unknown>;

package/dist/src/hosted/manifest.js

@@ -1,4 +1,4 @@
-import { formatArgSummary } from '../serialization.js';
+import { commandHelpData, commandListPresentation, commandListRows, formatCommandHelp, formatSiteHelp, getCommandCompletionCandidates, siteHelpData, toPresentableCommand, } from '../command-presentation.js';
 export function isLocalOnlyHostedCommand(command) {
     return command.strategy.toUpperCase() === 'LOCAL';
 }
@@ -12,81 +12,36 @@ export function findHostedCommand(manifest, site, name) {
         return command.site === site && (command.name === name || command.aliases?.includes(name));
     }) ?? null;
 }
+export function presentHostedCommand(command) {
+    return toPresentableCommand(command);
+}
 export function hostedListRows(manifest, structured) {
-    return hostedCommands(manifest).map((command) => {
-        const row = {
-            command: command.command,
-            site: command.site,
-            name: command.name,
-            aliases: command.aliases ?? [],
-            description: command.description,
-            access: command.access,
-            strategy: command.strategy.toLowerCase(),
-            browser: command.browser,
-            args: command.args,
-            columns: command.columns ?? [],
-            domain: command.domain ?? null,
-        };
-        if (structured)
-            return row;
-        return {
-            ...row,
-            aliases: command.aliases?.join(', ') ?? '',
-            args: formatArgSummary(command.args.map((arg) => ({
-                name: arg.name,
-                type: arg.type,
-                required: arg.required,
-                valueRequired: arg.valueRequired,
-                positional: arg.positional,
-                help: arg.help,
-                choices: arg.choices?.map(String),
-                default: arg.default,
-            }))),
-        };
-    });
+    return commandListRows(hostedCommands(manifest).map(presentHostedCommand), structured);
+}
+export function hostedListPresentation(manifest, format) {
+    return commandListPresentation(hostedCommands(manifest).map(presentHostedCommand), format);
 }
 export function siteNames(manifest) {
-    return [...new Set(hostedCommands(manifest).map((command) => command.site))].sort((a, b) => a.localeCompare(b));
+    return getCommandCompletionCandidates(hostedCommands(manifest), [], 1, []);
 }
 export function commandNamesForSite(manifest, site) {
-    return hostedCommands(manifest)
-        .filter((command) => command.site === site)
-        .flatMap((command) => [command.name, ...(command.aliases ?? [])])
-        .sort((a, b) => a.localeCompare(b));
+    return getCommandCompletionCandidates(hostedCommands(manifest), [site], 2, []);
 }
 export function renderHostedSiteHelp(manifest, site) {
     const commands = hostedCommands(manifest).filter((command) => command.site === site);
     if (commands.length === 0)
         return `Unknown hosted Webcmd site: ${site}\n`;
-    const lines = [`Usage: webcmd ${site} <command> [options]`, '', 'Commands:'];
-    for (const command of commands) {
-        const tag = `[${command.strategy.toLowerCase()}]`;
-        lines.push(`  ${command.name.padEnd(18)} ${tag} ${command.description}`);
-    }
-    return `${lines.join('\n')}\n`;
+    return formatSiteHelp(site, commands.map(presentHostedCommand));
+}
+export function hostedSiteHelpData(manifest, site) {
+    const commands = hostedCommands(manifest).filter((command) => command.site === site);
+    if (commands.length === 0)
+        return null;
+    return siteHelpData(site, commands.map(presentHostedCommand));
 }
 export function renderHostedCommandHelp(command) {
-    const lines = [
-        `Usage: webcmd ${command.site} ${command.name} ${formatArgSummary(command.args.map((arg) => ({
-            name: arg.name,
-            type: arg.type,
-            required: arg.required,
-            valueRequired: arg.valueRequired,
-            positional: arg.positional,
-            help: arg.help,
-            choices: arg.choices?.map(String),
-            default: arg.default,
-        })))} [options]`,
-        '',
-        command.description,
-        '',
-        `Access: ${command.access}`,
-        `Strategy: ${command.strategy.toLowerCase()}`,
-        `Browser: ${command.browser ? 'yes' : 'no'}`,
-    ];
-    if (command.domain)
-        lines.push(`Domain: ${command.domain}`);
-    if (command.columns?.length)
-        lines.push(`Output columns: ${command.columns.join(', ')}`);
-    return `${lines.join('\n')}\n`;
+    return formatCommandHelp(presentHostedCommand(command));
+}
+export function hostedCommandHelpData(command) {
+    return commandHelpData(presentHostedCommand(command));
 }