@agentrhq/webcmd 0.3.0 → 0.3.2

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

@@ -0,0 +1,93 @@
+import { mkdtemp, readFile, rm, stat } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { _isMacOsKeychainAvailableForTest, getHostedCredentialPath, resolveHostedApiKey, storeHostedApiKey, } from './credentials.js';
+import { getConfigPath, makeHostedConfig, saveWebcmdConfig } from './config.js';
+let tempDir;
+afterEach(async () => {
+    if (tempDir)
+        await rm(tempDir, { recursive: true, force: true });
+    tempDir = undefined;
+});
+describe('hosted credential storage', () => {
+    it('honors process-level file credential backend when no explicit env is injected', () => {
+        const previous = process.env.WEBCMD_CREDENTIAL_BACKEND;
+        process.env.WEBCMD_CREDENTIAL_BACKEND = 'file';
+        try {
+            expect(_isMacOsKeychainAvailableForTest({
+                platform: 'darwin',
+                existsSync: () => true,
+            })).toBe(false);
+        }
+        finally {
+            if (previous === undefined)
+                delete process.env.WEBCMD_CREDENTIAL_BACKEND;
+            else
+                process.env.WEBCMD_CREDENTIAL_BACKEND = previous;
+        }
+    });
+    it('stores hosted API keys in the protected file fallback', async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'webcmd-creds-'));
+        const env = {
+            WEBCMD_CONFIG_DIR: tempDir,
+            WEBCMD_CREDENTIAL_BACKEND: 'file',
+        };
+        const stored = await storeHostedApiKey('wcmd_live_test', {
+            env,
+            platform: 'linux',
+            randomUUID: () => '11111111-2222-4333-8444-555555555555',
+        });
+        expect(stored).toEqual({
+            apiKeyRef: 'wcmd_cred_11111111-2222-4333-8444-555555555555',
+            credentialBackend: 'file-fallback',
+        });
+        const credentialFile = JSON.parse(await readFile(getHostedCredentialPath({ env }), 'utf8'));
+        expect(credentialFile.credentials[stored.apiKeyRef]).toBe('wcmd_live_test');
+        const credentialMode = (await stat(getHostedCredentialPath({ env }))).mode & 0o777;
+        if (process.platform !== 'win32') {
+            expect(credentialMode).toBe(0o600);
+        }
+    });
+    it('uses an injected OS credential store when available', async () => {
+        const secrets = new Map();
+        const credentialStore = {
+            backend: () => 'os',
+            put: vi.fn(async (reference, secret) => { secrets.set(reference, secret); }),
+            get: vi.fn(async (reference) => secrets.get(reference) ?? null),
+            delete: vi.fn(async (reference) => { secrets.delete(reference); }),
+        };
+        const stored = await storeHostedApiKey('wcmd_keychain_test', {
+            credentialStore,
+            randomUUID: () => 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee',
+        });
+        expect(stored).toEqual({
+            apiKeyRef: 'wcmd_cred_aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee',
+            credentialBackend: 'os',
+        });
+        expect(await credentialStore.get(stored.apiKeyRef)).toBe('wcmd_keychain_test');
+    });
+    it('migrates a legacy inline key to a credential reference without keeping the secret in config', async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'webcmd-creds-migrate-'));
+        const env = { WEBCMD_CONFIG_DIR: tempDir };
+        const legacy = makeHostedConfig({
+            apiBaseUrl: 'https://api.example.com',
+            apiKey: 'wcmd_legacy_key',
+            now: new Date('2026-07-08T00:00:00.000Z'),
+        });
+        saveWebcmdConfig(legacy, { env });
+        const resolved = await resolveHostedApiKey(legacy, {
+            env,
+            platform: 'linux',
+            randomUUID: () => 'bbbbbbbb-2222-4333-8444-555555555555',
+        });
+        expect(resolved).toMatchObject({
+            apiKey: 'wcmd_legacy_key',
+            backend: 'file-fallback',
+            migrated: true,
+        });
+        const configJson = await readFile(getConfigPath({ env }), 'utf8');
+        expect(configJson).toContain('wcmd_cred_bbbbbbbb-2222-4333-8444-555555555555');
+        expect(configJson).not.toContain('wcmd_legacy_key');
+    });
+});

package/dist/src/hosted/file-contract.test.d.ts

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

package/dist/src/hosted/file-contract.test.js

@@ -0,0 +1,174 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+const MiB = 1024 * 1024;
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const IMAGE_CONTENT_TYPES = [
+    'image/jpeg',
+    'image/png',
+    'image/gif',
+    'image/webp',
+];
+const DOCUMENT_CONTENT_TYPES = [
+    'application/pdf',
+    'text/plain',
+    'text/markdown',
+    'text/csv',
+    'application/json',
+];
+const MERCURY_RECEIPT_CONTENT_TYPES = [
+    'image/jpeg',
+    'image/png',
+    'image/gif',
+    'image/webp',
+    'application/pdf',
+];
+const INSTAGRAM_MEDIA_CONTENT_TYPES = [
+    'image/jpeg',
+    'image/png',
+    'image/webp',
+    'video/mp4',
+];
+const EXPECTED_FILE_ARGUMENTS = {
+    'chatgpt/image': [{
+            name: 'image',
+            direction: 'input',
+            pathKind: 'file',
+            multiple: true,
+            required: false,
+            separator: ',',
+            contentTypes: IMAGE_CONTENT_TYPES,
+            maxBytes: 25 * MiB,
+        }, {
+            name: 'op',
+            direction: 'output',
+            pathKind: 'directory',
+            multiple: false,
+            required: false,
+            defaultPath: '~/Pictures/chatgpt',
+        }],
+    'chatgpt/project-file-add': [{
+            name: 'file',
+            direction: 'input',
+            pathKind: 'file',
+            multiple: true,
+            required: true,
+            separator: ',',
+            contentTypes: [
+                ...DOCUMENT_CONTENT_TYPES,
+                ...IMAGE_CONTENT_TYPES,
+            ],
+            maxBytes: 25 * MiB,
+        }],
+    'claude/ask': [{
+            name: 'file',
+            direction: 'input',
+            pathKind: 'file',
+            multiple: false,
+            required: false,
+            contentTypes: [
+                ...DOCUMENT_CONTENT_TYPES,
+                ...IMAGE_CONTENT_TYPES,
+            ],
+            maxBytes: 25 * MiB,
+        }],
+    'instagram/post': [{
+            name: 'media',
+            direction: 'input',
+            pathKind: 'file',
+            multiple: true,
+            required: false,
+            separator: ',',
+            contentTypes: INSTAGRAM_MEDIA_CONTENT_TYPES,
+            maxBytes: 250 * MiB,
+        }],
+    'instagram/reel': [{
+            name: 'video',
+            direction: 'input',
+            pathKind: 'file',
+            multiple: false,
+            required: false,
+            contentTypes: ['video/mp4'],
+            maxBytes: 250 * MiB,
+        }],
+    'mercury/reimbursement-draft': [{
+            name: 'receipt',
+            direction: 'input',
+            pathKind: 'file',
+            multiple: false,
+            required: true,
+            contentTypes: MERCURY_RECEIPT_CONTENT_TYPES,
+            maxBytes: 25 * MiB,
+        }],
+    'twitter/download': [{
+            name: 'output',
+            direction: 'output',
+            pathKind: 'directory',
+            multiple: false,
+            required: false,
+        }],
+    'twitter/post': [{
+            name: 'images',
+            direction: 'input',
+            pathKind: 'file',
+            multiple: true,
+            required: false,
+            separator: ',',
+            contentTypes: IMAGE_CONTENT_TYPES,
+            maxBytes: 25 * MiB,
+        }],
+    'twitter/quote': [{
+            name: 'image',
+            direction: 'input',
+            pathKind: 'file',
+            multiple: false,
+            required: false,
+            contentTypes: IMAGE_CONTENT_TYPES,
+            maxBytes: 25 * MiB,
+        }],
+    'twitter/reply': [{
+            name: 'image',
+            direction: 'input',
+            pathKind: 'file',
+            multiple: false,
+            required: false,
+            contentTypes: IMAGE_CONTENT_TYPES,
+            maxBytes: 25 * MiB,
+        }],
+};
+function readJson(name) {
+    return JSON.parse(readFileSync(path.join(packageRoot, name), 'utf8'));
+}
+function manifestCommand(manifest, command) {
+    const entry = manifest.find(item => `${item.site}/${item.name}` === command);
+    if (!entry)
+        throw new Error(`Missing manifest command: ${command}`);
+    return entry;
+}
+function contractCommand(contract, command) {
+    const entry = contract.commands.find(item => item.command === command);
+    if (!entry)
+        throw new Error(`Missing hosted contract command: ${command}`);
+    return entry;
+}
+describe('hosted file argument contract', () => {
+    it('declares every real local path argument in generated artifacts', () => {
+        const manifest = readJson('cli-manifest.json');
+        const contract = readJson('hosted-contract.json');
+        for (const [command, expected] of Object.entries(EXPECTED_FILE_ARGUMENTS)) {
+            expect(contractCommand(contract, command).fileArguments, command).toEqual(expected);
+            const manifestArgs = manifestCommand(manifest, command).args
+                .filter(arg => arg.file)
+                .map(arg => ({ name: arg.name, file: arg.file }));
+            expect(manifestArgs, command).toEqual(expected.map(({ name, required: _required, ...file }) => ({ name, file })));
+        }
+    });
+    it('does not treat Twitter remote image URLs as file arguments', () => {
+        const contract = readJson('hosted-contract.json');
+        expect(contractCommand(contract, 'twitter/quote').fileArguments.map(arg => arg.name))
+            .not.toContain('image-url');
+        expect(contractCommand(contract, 'twitter/reply').fileArguments.map(arg => arg.name))
+            .not.toContain('image-url');
+    });
+});

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

@@ -0,0 +1,29 @@
+import type { HostedClient } from './client.js';
+import type { HostedArtifactReceipt, HostedCommand, HostedExecuteResponse } from './types.js';
+export interface HostedPreparedFiles {
+    executionId: string;
+    args: Record<string, unknown>;
+    outputs: HostedOutputTarget[];
+}
+export interface HostedOutputTarget {
+    argument: string;
+    pathKind: 'file' | 'directory';
+    localPath: string;
+}
+export interface HostedMaterializedOutput {
+    argument: string;
+    artifact: HostedArtifactReceipt;
+    localPath: string;
+}
+export declare function prepareHostedFiles(input: {
+    client: HostedClient;
+    command: HostedCommand;
+    args: Record<string, unknown>;
+    cwd?: string;
+}): Promise<HostedPreparedFiles>;
+export declare function materializeHostedOutputs(input: {
+    client: HostedClient;
+    response: HostedExecuteResponse;
+    outputs: HostedOutputTarget[];
+}): Promise<HostedMaterializedOutput[]>;
+export declare function rewriteHostedOutputResultPaths(value: unknown, materialized: readonly HostedMaterializedOutput[]): unknown;

package/dist/src/hosted/files.js

@@ -0,0 +1,296 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, rename, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { CliError, EXIT_CODES } from '../errors.js';
+export async function prepareHostedFiles(input) {
+    const fileArgs = input.command.args.filter(hasFileMetadata);
+    const cwd = input.cwd ?? process.cwd();
+    const remoteArgs = { ...input.args };
+    const inputs = [];
+    const outputs = [];
+    for (const arg of fileArgs) {
+        if (arg.file.direction === 'input') {
+            const values = valuesForFileArg(arg, input.args[arg.name]);
+            if (arg.required && values.length === 0) {
+                throw new CliError('HOSTED_FILE_INPUT_REQUIRED', `Argument "${arg.name}" requires a local file path.`, `Pass --${arg.name} <path>.`, EXIT_CODES.USAGE_ERROR);
+            }
+            for (const value of values) {
+                const localPath = resolveLocalPath(cwd, value, arg.name);
+                const body = await readLocalFileNoSymlink(localPath, arg.name);
+                assertLocalInputWithinLimit(arg, body);
+                const contentType = contentTypeForPath(localPath);
+                assertContentTypeAllowed(arg, contentType);
+                inputs.push({
+                    argument: arg.name,
+                    multiple: arg.file.multiple === true,
+                    filename: path.basename(localPath),
+                    contentType,
+                    body,
+                });
+            }
+            continue;
+        }
+        const rawValue = input.args[arg.name] ?? arg.default ?? arg.file.defaultPath;
+        if (rawValue === undefined || rawValue === null || rawValue === '')
+            continue;
+        const values = valuesForFileArg(arg, rawValue);
+        const references = [];
+        for (const value of values) {
+            const localPath = resolveOutputPath(cwd, value, arg.name);
+            outputs.push({ argument: arg.name, pathKind: arg.file.pathKind, localPath });
+            references.push({
+                $webcmdArtifact: {
+                    direction: 'output',
+                    filename: path.basename(localPath) || arg.name,
+                    contentType: 'application/octet-stream',
+                },
+            });
+        }
+        if (references.length > 0) {
+            remoteArgs[arg.name] = arg.file.multiple ? references : references[0];
+        }
+    }
+    const prepared = await input.client.prepareExecution({ command: input.command.command });
+    const referencesByArgument = new Map();
+    for (const upload of inputs) {
+        const uploaded = await input.client.uploadExecutionArtifact({
+            executionId: prepared.execution.id,
+            argument: upload.argument,
+            filename: upload.filename,
+            contentType: upload.contentType,
+            body: upload.body,
+        });
+        const references = referencesByArgument.get(upload.argument) ?? [];
+        references.push(uploaded.reference);
+        referencesByArgument.set(upload.argument, references);
+    }
+    for (const [argument, references] of referencesByArgument) {
+        const original = inputs.find(upload => upload.argument === argument);
+        remoteArgs[argument] = original?.multiple ? references : references[0];
+    }
+    return {
+        executionId: prepared.execution.id,
+        args: remoteArgs,
+        outputs,
+    };
+}
+export async function materializeHostedOutputs(input) {
+    if (!input.outputs.length)
+        return [];
+    const receipts = input.response.artifacts ?? [];
+    const receiptsByArgument = new Map();
+    for (const receipt of receipts) {
+        if (receipt.direction !== 'output')
+            continue;
+        const bucket = receiptsByArgument.get(receipt.argument) ?? [];
+        bucket.push(receipt);
+        receiptsByArgument.set(receipt.argument, bucket);
+    }
+    const tempFiles = [];
+    const materialized = [];
+    try {
+        for (const output of input.outputs) {
+            if (output.pathKind === 'directory')
+                await mkdir(output.localPath, { recursive: true, mode: 0o700 });
+            const outputReceipts = receiptsByArgument.get(output.argument) ?? [];
+            const seenRelativePaths = new Set();
+            for (const receipt of outputReceipts) {
+                const target = targetPathForReceipt(output, receipt, seenRelativePaths);
+                const body = await input.client.downloadExecutionArtifact({
+                    executionId: input.response.execution.id,
+                    artifactId: receipt.artifactId,
+                });
+                assertReceiptBody(receipt, body);
+                const tempPath = await writeTempSibling(target, body);
+                tempFiles.push(tempPath);
+                await rename(tempPath, target);
+                tempFiles.splice(tempFiles.indexOf(tempPath), 1);
+                materialized.push({ argument: output.argument, artifact: receipt, localPath: target });
+            }
+        }
+    }
+    catch (error) {
+        await Promise.all(tempFiles.map(temp => rm(temp, { force: true }).catch(() => undefined)));
+        throw error;
+    }
+    return materialized;
+}
+export function rewriteHostedOutputResultPaths(value, materialized) {
+    if (!materialized.length)
+        return value;
+    if (typeof value === 'string')
+        return rewritePathString(value, materialized);
+    if (Array.isArray(value))
+        return value.map(entry => rewriteHostedOutputResultPaths(entry, materialized));
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, rewriteHostedOutputResultPaths(entry, materialized)]));
+}
+function hasFileMetadata(arg) {
+    return !!arg.file;
+}
+function valuesForFileArg(arg, value) {
+    if (value === undefined || value === null || value === '')
+        return [];
+    if (Array.isArray(value)) {
+        if (!value.every(item => typeof item === 'string')) {
+            throw new CliError('HOSTED_FILE_ARGUMENT', `Argument "${arg.name}" must contain file path strings.`, undefined, EXIT_CODES.USAGE_ERROR);
+        }
+        return value;
+    }
+    if (typeof value !== 'string') {
+        throw new CliError('HOSTED_FILE_ARGUMENT', `Argument "${arg.name}" must be a file path string.`, undefined, EXIT_CODES.USAGE_ERROR);
+    }
+    if (arg.file.multiple && arg.file.separator === ',') {
+        return value.split(',').map(item => item.trim()).filter(Boolean);
+    }
+    return [value];
+}
+function resolveLocalPath(cwd, value, argName) {
+    if (!value.trim()) {
+        throw new CliError('HOSTED_FILE_ARGUMENT', `Argument "${argName}" must be a non-empty file path.`, undefined, EXIT_CODES.USAGE_ERROR);
+    }
+    return resolveUserPath(cwd, value);
+}
+function resolveOutputPath(cwd, value, argName) {
+    if (!value.trim()) {
+        throw new CliError('HOSTED_FILE_ARGUMENT', `Argument "${argName}" must be a non-empty output path.`, undefined, EXIT_CODES.USAGE_ERROR);
+    }
+    return resolveUserPath(cwd, value);
+}
+function resolveUserPath(cwd, value) {
+    if (value === '~')
+        return homedir();
+    if (value.startsWith('~/'))
+        return path.join(homedir(), value.slice(2));
+    return path.resolve(cwd, value);
+}
+async function readLocalFileNoSymlink(localPath, argName) {
+    let entry;
+    try {
+        entry = await lstat(localPath);
+    }
+    catch {
+        throw new CliError('HOSTED_FILE_NOT_FOUND', `Input file for "${argName}" was not found.`, `Check the local path and try again.`, EXIT_CODES.USAGE_ERROR);
+    }
+    if (entry.isSymbolicLink() || !entry.isFile()) {
+        throw new CliError('HOSTED_FILE_NOT_FILE', `Input path for "${argName}" must be a regular file.`, undefined, EXIT_CODES.USAGE_ERROR);
+    }
+    const handle = await open(localPath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        return new Uint8Array(await handle.readFile());
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+}
+function contentTypeForPath(localPath) {
+    const extension = path.extname(localPath).toLowerCase();
+    if (extension === '.jpg' || extension === '.jpeg')
+        return 'image/jpeg';
+    if (extension === '.png')
+        return 'image/png';
+    if (extension === '.gif')
+        return 'image/gif';
+    if (extension === '.webp')
+        return 'image/webp';
+    if (extension === '.mp4')
+        return 'video/mp4';
+    if (extension === '.pdf')
+        return 'application/pdf';
+    if (extension === '.json')
+        return 'application/json';
+    if (extension === '.csv')
+        return 'text/csv';
+    if (extension === '.md' || extension === '.markdown')
+        return 'text/markdown';
+    if (extension === '.txt')
+        return 'text/plain';
+    return 'application/octet-stream';
+}
+function assertLocalInputWithinLimit(arg, body) {
+    if (arg.file.maxBytes !== undefined && body.byteLength > arg.file.maxBytes) {
+        throw new CliError('HOSTED_FILE_TOO_LARGE', `Input file for "${arg.name}" exceeds the hosted argument size limit.`, `Maximum size is ${arg.file.maxBytes} bytes.`, EXIT_CODES.USAGE_ERROR);
+    }
+}
+function assertContentTypeAllowed(arg, contentType) {
+    const allowed = arg.file.contentTypes;
+    if (!allowed?.length)
+        return;
+    const normalized = contentType.toLowerCase();
+    const ok = allowed.some((entry) => {
+        const expected = entry.toLowerCase();
+        if (expected === '*/*')
+            return true;
+        if (expected.endsWith('/*'))
+            return normalized.startsWith(`${expected.slice(0, -1)}`);
+        return normalized === expected;
+    });
+    if (!ok) {
+        throw new CliError('HOSTED_FILE_CONTENT_TYPE', `Input file for "${arg.name}" has unsupported content type ${contentType}.`, `Allowed content types: ${allowed.join(', ')}`, EXIT_CODES.USAGE_ERROR);
+    }
+}
+function targetPathForReceipt(output, receipt, seenRelativePaths) {
+    if (output.pathKind === 'file')
+        return output.localPath;
+    const relativePath = receipt.relativePath;
+    if (!relativePath || !isSafeRelativePath(relativePath) || seenRelativePaths.has(relativePath)) {
+        throw new CliError('HOSTED_FILE_OUTPUT_INVALID', 'Webcmd Cloud returned an unsafe output artifact path.', undefined, EXIT_CODES.GENERIC_ERROR);
+    }
+    seenRelativePaths.add(relativePath);
+    return path.resolve(output.localPath, ...relativePath.split('/'));
+}
+function isSafeRelativePath(relativePath) {
+    if (path.posix.isAbsolute(relativePath) || relativePath.includes('\0'))
+        return false;
+    const parts = relativePath.split('/');
+    return parts.length > 0 && parts.every(part => part.length > 0 && part !== '.' && part !== '..');
+}
+function assertReceiptBody(receipt, body) {
+    if (body.byteLength !== receipt.byteSize) {
+        throw new CliError('HOSTED_FILE_HASH_MISMATCH', 'Downloaded artifact size did not match the hosted receipt.');
+    }
+    if (receipt.sha256 && sha256Hex(body) !== receipt.sha256) {
+        throw new CliError('HOSTED_FILE_HASH_MISMATCH', 'Downloaded artifact hash did not match the hosted receipt.');
+    }
+}
+async function writeTempSibling(targetPath, body) {
+    await mkdir(path.dirname(targetPath), { recursive: true, mode: 0o700 });
+    const tempPath = path.join(path.dirname(targetPath), `.${path.basename(targetPath)}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`);
+    const handle = await open(tempPath, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+    try {
+        await handle.writeFile(body);
+        await handle.sync();
+    }
+    finally {
+        await handle.close().catch(() => undefined);
+    }
+    return tempPath;
+}
+function sha256Hex(body) {
+    return createHash('sha256').update(body).digest('hex');
+}
+function rewritePathString(value, materialized) {
+    let next = value;
+    for (const output of materialized) {
+        const displayPath = displayLocalPath(output.localPath);
+        const tokens = [output.artifact.relativePath, output.artifact.filename]
+            .filter((token) => typeof token === 'string' && token.length > 0);
+        for (const token of tokens) {
+            const pattern = new RegExp(`(?:~|/|[A-Za-z]:[\\\\/])[^\\s"'<>|]*${escapeRegExp(token).replaceAll('/', '[\\\\/]')}`, 'g');
+            next = next.replace(pattern, displayPath);
+        }
+    }
+    return next;
+}
+function displayLocalPath(localPath) {
+    const home = homedir();
+    return localPath === home || localPath.startsWith(`${home}${path.sep}`)
+        ? `~${localPath.slice(home.length)}`
+        : localPath;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

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

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