@agentrhq/webcmd 0.2.5 → 0.3.1

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

@@ -0,0 +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

@@ -0,0 +1,47 @@
+import { commandHelpData, commandListPresentation, commandListRows, formatCommandHelp, formatSiteHelp, getCommandCompletionCandidates, siteHelpData, toPresentableCommand, } from '../command-presentation.js';
+export function isLocalOnlyHostedCommand(command) {
+    return command.strategy.toUpperCase() === 'LOCAL';
+}
+export function hostedCommands(manifest) {
+    return manifest.commands
+        .filter((command) => !isLocalOnlyHostedCommand(command))
+        .sort((a, b) => a.command.localeCompare(b.command));
+}
+export function findHostedCommand(manifest, site, name) {
+    return manifest.commands.find((command) => {
+        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 commandListRows(hostedCommands(manifest).map(presentHostedCommand), structured);
+}
+export function hostedListPresentation(manifest, format) {
+    return commandListPresentation(hostedCommands(manifest).map(presentHostedCommand), format);
+}
+export function siteNames(manifest) {
+    return getCommandCompletionCandidates(hostedCommands(manifest), [], 1, []);
+}
+export function commandNamesForSite(manifest, site) {
+    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`;
+    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) {
+    return formatCommandHelp(presentHostedCommand(command));
+}
+export function hostedCommandHelpData(command) {
+    return commandHelpData(presentHostedCommand(command));
+}

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

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

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

@@ -0,0 +1,164 @@
+import { Writable } from 'node:stream';
+import { describe, expect, it, vi } from 'vitest';
+import { commandHelpData, formatCommandHelpText, formatSiteHelpText, renderStructuredHelp, siteHelpData, } from '../help.js';
+import { serializeCommand } from '../serialization.js';
+import { Strategy } from '../registry.js';
+import { commandNamesForSite, findHostedCommand, hostedListRows, renderHostedCommandHelp, renderHostedSiteHelp, siteNames, } from './manifest.js';
+import { makeHostedConfig } from './config.js';
+import { runHostedCli } from './runner.js';
+import { formatRootHelp } from '../command-presentation.js';
+import { HOSTED_ROOT_HELP } from '../completion-shared.js';
+const manifest = {
+    userId: 'user_demo',
+    metadata: {
+        contractSchemaVersion: 1,
+        webcmdPackageVersion: '0.3.0',
+        generatedAt: '2026-07-08T00:00:00.000Z',
+    },
+    commands: [
+        {
+            site: 'github',
+            name: 'whoami',
+            aliases: ['me'],
+            command: 'github/whoami',
+            description: 'Show GitHub identity',
+            access: 'read',
+            strategy: 'COOKIE',
+            browser: true,
+            args: [],
+            columns: ['username'],
+            domain: 'github.com',
+        },
+        {
+            site: 'docker',
+            name: 'ps',
+            command: 'docker/ps',
+            description: 'Local Docker containers',
+            access: 'read',
+            strategy: 'LOCAL',
+            browser: false,
+            args: [],
+            columns: [],
+        },
+    ],
+};
+const equivalentLocalCommand = {
+    site: 'github',
+    name: 'whoami',
+    aliases: ['me'],
+    description: 'Show GitHub identity',
+    access: 'read',
+    strategy: Strategy.COOKIE,
+    browser: true,
+    args: [],
+    columns: ['username'],
+    domain: 'github.com',
+};
+function sink() {
+    let data = '';
+    return {
+        stream: new Writable({
+            write(chunk, _encoding, callback) {
+                data += String(chunk);
+                callback();
+            },
+        }),
+        text: () => data,
+    };
+}
+describe('hosted manifest helpers', () => {
+    it('filters LOCAL commands from hosted list rows', () => {
+        expect(hostedListRows(manifest, true).map((row) => row.command)).toEqual(['github/whoami']);
+    });
+    it('finds canonical commands and aliases', () => {
+        expect(findHostedCommand(manifest, 'github', 'whoami')?.command).toBe('github/whoami');
+        expect(findHostedCommand(manifest, 'github', 'me')?.command).toBe('github/whoami');
+    });
+    it('renders hosted help and completion names from supported commands', () => {
+        expect(siteNames(manifest)).toEqual(['github']);
+        expect(commandNamesForSite(manifest, 'github')).toEqual(['me', 'whoami']);
+        expect(renderHostedSiteHelp(manifest, 'github')).toContain('whoami');
+        expect(renderHostedCommandHelp(manifest.commands[0])).toContain('Output columns: username');
+    });
+    it('matches local site and command help byte-for-byte for equal metadata', () => {
+        expect(renderHostedSiteHelp(manifest, 'github')).toBe(formatSiteHelpText('github', [equivalentLocalCommand]));
+        expect(renderHostedCommandHelp(manifest.commands[0])).toBe(formatCommandHelpText(equivalentLocalCommand));
+    });
+    it('matches local structured list rows for equal metadata', () => {
+        expect(hostedListRows({ ...manifest, commands: [manifest.commands[0]] }, true))
+            .toEqual([serializeCommand(equivalentLocalCommand)]);
+    });
+    it('describes universal hosted surfaces and accepted local-only commands at the root', async () => {
+        const stdout = sink();
+        const result = await runHostedCli(['--help'], {
+            config: makeHostedConfig({ apiBaseUrl: 'https://api.example.com', apiKey: 'key' }),
+            stdout: stdout.stream,
+        });
+        expect(result).toEqual({ handled: true, exitCode: 0 });
+        expect(stdout.text()).toBe(formatRootHelp(HOSTED_ROOT_HELP));
+        expect(stdout.text()).toContain('completion');
+        expect(stdout.text()).toContain('--profile <name>');
+        expect(stdout.text()).toContain('Local-only commands:');
+        expect(stdout.text()).toContain('Run `webcmd setup` and choose local mode to use local-only commands.');
+    });
+    it('completes private hosted manifest commands without local discovery', async () => {
+        const stdout = sink();
+        const privateManifest = {
+            ...manifest,
+            commands: [
+                ...manifest.commands,
+                {
+                    site: 'private-tools',
+                    name: 'deploy-preview',
+                    aliases: ['preview'],
+                    command: 'private-tools/deploy-preview',
+                    description: 'Deploy a private preview',
+                    access: 'write',
+                    strategy: 'PUBLIC',
+                    browser: false,
+                    args: [],
+                    columns: ['url'],
+                },
+            ],
+        };
+        const fetchImpl = vi.fn(async () => new Response(JSON.stringify({ ok: true, manifest: privateManifest }), { status: 200 }));
+        const result = await runHostedCli(['--get-completions', '--cursor', '2', 'private-tools'], {
+            config: makeHostedConfig({ apiBaseUrl: 'https://api.example.com', apiKey: 'key' }),
+            stdout: stdout.stream,
+            fetchImpl,
+        });
+        expect(result).toEqual({ handled: true, exitCode: 0 });
+        expect(stdout.text().trim().split('\n')).toEqual(['deploy-preview', 'preview']);
+        expect(fetchImpl).toHaveBeenCalledTimes(1);
+    });
+    it.each([
+        ['json', 'json'],
+        ['yaml', 'yaml'],
+        ['yml', 'yaml'],
+    ])('matches local structured site and command help bytes for -f %s', async (requested, rendered) => {
+        const fetchImpl = async () => new Response(JSON.stringify({ ok: true, manifest }), { status: 200 });
+        const siteStdout = sink();
+        await runHostedCli(['github', '--help', '-f', requested], {
+            config: makeHostedConfig({ apiBaseUrl: 'https://api.example.com', apiKey: 'key' }),
+            stdout: siteStdout.stream,
+            fetchImpl,
+        });
+        expect(siteStdout.text()).toBe(renderStructuredHelp(siteHelpData('github', [equivalentLocalCommand]), rendered));
+        const commandStdout = sink();
+        await runHostedCli(['github', 'whoami', '--help', '-f', requested], {
+            config: makeHostedConfig({ apiBaseUrl: 'https://api.example.com', apiKey: 'key' }),
+            stdout: commandStdout.stream,
+            fetchImpl,
+        });
+        expect(commandStdout.text()).toBe(renderStructuredHelp(commandHelpData(equivalentLocalCommand), rendered));
+    });
+    it('uses only executable hosted root capabilities as root completion candidates', async () => {
+        const stdout = sink();
+        await runHostedCli(['--get-completions', '--cursor', '1'], {
+            config: makeHostedConfig({ apiBaseUrl: 'https://api.example.com', apiKey: 'key' }),
+            stdout: stdout.stream,
+            fetchImpl: async () => new Response(JSON.stringify({ ok: true, manifest }), { status: 200 }),
+        });
+        expect(stdout.text().trim().split('\n')).toEqual(['browser', 'completion', 'github', 'list', 'setup']);
+    });
+});