@agentrhq/webcmd 0.3.0 → 0.3.1

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

@@ -0,0 +1,361 @@
+import { describe, expect, it } from 'vitest';
+import { Strategy } from '../registry.js';
+import { HOSTED_CONTRACT_SCHEMA_VERSION, buildHostedContract, serializeHostedContract, } from './contract.js';
+describe('buildHostedContract', () => {
+    const commands = [
+        {
+            site: 'web',
+            name: 'profile',
+            aliases: ['me'],
+            description: 'Read a profile',
+            access: 'read',
+            strategy: Strategy.COOKIE,
+            browser: true,
+            domain: 'example.com',
+            args: [
+                {
+                    name: 'user',
+                    type: 'str',
+                    positional: true,
+                    required: true,
+                    help: 'Profile handle',
+                    choices: ['alice', 'bob'],
+                },
+                {
+                    name: 'include-private',
+                    type: 'bool',
+                    default: false,
+                    help: 'Include private fields',
+                },
+            ],
+            columns: ['name', 'bio'],
+            defaultFormat: 'plain',
+            example: 'webcmd web profile alice',
+        },
+        {
+            site: 'local',
+            name: 'cache',
+            description: 'Read local cache',
+            access: 'read',
+            strategy: Strategy.LOCAL,
+            browser: false,
+            args: [],
+        },
+        {
+            site: 'files',
+            name: 'transfer',
+            description: 'Transfer a file',
+            access: 'write',
+            strategy: Strategy.PUBLIC,
+            browser: false,
+            args: [
+                {
+                    name: 'source',
+                    type: 'string',
+                    positional: true,
+                    required: true,
+                    help: 'Source document',
+                    file: {
+                        direction: 'input',
+                        pathKind: 'file',
+                        contentTypes: ['application/pdf'],
+                        maxBytes: 2_000_000,
+                    },
+                },
+                {
+                    name: 'destination',
+                    type: 'string',
+                    help: 'Destination file',
+                    file: { direction: 'output', pathKind: 'directory', multiple: true },
+                },
+                {
+                    name: 'retries',
+                    type: 'int',
+                    default: 2,
+                    help: 'Retry count',
+                },
+            ],
+            defaultFormat: 'markdown',
+        },
+        {
+            site: 'app',
+            name: 'editor',
+            description: 'Control a desktop editor',
+            access: 'write',
+            strategy: Strategy.UI,
+            browser: true,
+            domain: 'localhost',
+            args: [],
+        },
+    ];
+    const browserCatalog = [
+        {
+            command: 'bind',
+            aliases: [],
+            description: 'Bind an existing local tab',
+            positionals: [],
+            options: [],
+            sessionPolicy: 'local-only',
+        },
+        {
+            command: 'open',
+            aliases: ['navigate'],
+            description: 'Open a browser page',
+            positionals: [{
+                    name: 'url',
+                    type: 'string',
+                    description: 'URL to open',
+                    positional: true,
+                    required: true,
+                    variadic: false,
+                }],
+            options: [],
+            sessionPolicy: 'create-or-reuse',
+            action: 'navigate',
+        },
+    ];
+    it('emits the deterministic versioned public contract shape', () => {
+        const contract = buildHostedContract(commands, browserCatalog, '9.8.7');
+        expect(contract).toEqual({
+            schemaVersion: HOSTED_CONTRACT_SCHEMA_VERSION,
+            webcmdVersion: '9.8.7',
+            outputFormats: ['table', 'plain', 'json', 'yaml', 'md', 'csv'],
+            traceModes: ['off', 'on', 'retain-on-failure'],
+            commonOptions: [
+                {
+                    name: 'format',
+                    flags: '-f, --format <fmt>',
+                    type: 'string',
+                    description: 'Output format: table, plain, json, yaml, md, csv',
+                    positional: false,
+                    required: false,
+                    variadic: false,
+                    default: 'table',
+                    choices: ['table', 'plain', 'json', 'yaml', 'md', 'csv'],
+                },
+                {
+                    name: 'trace',
+                    flags: '--trace <mode>',
+                    type: 'string',
+                    description: 'Trace capture: off, on, retain-on-failure',
+                    positional: false,
+                    required: false,
+                    variadic: false,
+                    default: 'off',
+                    choices: ['off', 'on', 'retain-on-failure'],
+                },
+                {
+                    name: 'verbose',
+                    flags: '-v, --verbose',
+                    type: 'boolean',
+                    description: 'Debug output',
+                    positional: false,
+                    required: false,
+                    variadic: false,
+                    default: false,
+                },
+                {
+                    name: 'help',
+                    flags: '-h, --help',
+                    type: 'boolean',
+                    description: 'display help for command',
+                    positional: false,
+                    required: false,
+                    variadic: false,
+                },
+            ],
+            commands: [
+                {
+                    command: 'app/editor',
+                    site: 'app',
+                    name: 'editor',
+                    description: 'Control a desktop editor',
+                    access: 'write',
+                    strategy: 'UI',
+                    browser: true,
+                    domain: 'localhost',
+                    positionals: [],
+                    options: [],
+                    columns: [],
+                    aliases: [],
+                    defaultFormat: 'table',
+                    fileArguments: [],
+                    sessionPolicy: 'local-only',
+                    availability: { mode: 'local-only', reason: 'desktop-app' },
+                },
+                {
+                    command: 'files/transfer',
+                    site: 'files',
+                    name: 'transfer',
+                    description: 'Transfer a file',
+                    access: 'write',
+                    strategy: 'PUBLIC',
+                    browser: false,
+                    positionals: [
+                        {
+                            name: 'source',
+                            type: 'string',
+                            description: 'Source document',
+                            positional: true,
+                            required: true,
+                            variadic: false,
+                        },
+                    ],
+                    options: [
+                        {
+                            name: 'destination',
+                            type: 'string',
+                            description: 'Destination file',
+                            positional: false,
+                            required: false,
+                            variadic: false,
+                        },
+                        {
+                            name: 'retries',
+                            type: 'int',
+                            description: 'Retry count',
+                            positional: false,
+                            required: false,
+                            variadic: false,
+                            default: 2,
+                        },
+                    ],
+                    columns: [],
+                    aliases: [],
+                    defaultFormat: 'md',
+                    fileArguments: [
+                        {
+                            name: 'source',
+                            direction: 'input',
+                            pathKind: 'file',
+                            multiple: false,
+                            required: true,
+                            contentTypes: ['application/pdf'],
+                            maxBytes: 2_000_000,
+                        },
+                        {
+                            name: 'destination',
+                            direction: 'output',
+                            pathKind: 'directory',
+                            multiple: true,
+                            required: false,
+                        },
+                    ],
+                    sessionPolicy: 'create-or-reuse',
+                    availability: { mode: 'hosted' },
+                },
+                {
+                    command: 'local/cache',
+                    site: 'local',
+                    name: 'cache',
+                    description: 'Read local cache',
+                    access: 'read',
+                    strategy: 'LOCAL',
+                    browser: false,
+                    positionals: [],
+                    options: [],
+                    columns: [],
+                    aliases: [],
+                    defaultFormat: 'table',
+                    fileArguments: [],
+                    sessionPolicy: 'local-only',
+                    availability: { mode: 'local-only', reason: 'local-tool' },
+                },
+                {
+                    command: 'web/profile',
+                    site: 'web',
+                    name: 'profile',
+                    aliases: ['me'],
+                    description: 'Read a profile',
+                    access: 'read',
+                    strategy: 'COOKIE',
+                    browser: true,
+                    domain: 'example.com',
+                    positionals: [
+                        {
+                            name: 'user',
+                            type: 'string',
+                            description: 'Profile handle',
+                            positional: true,
+                            required: true,
+                            variadic: false,
+                            choices: ['alice', 'bob'],
+                        },
+                    ],
+                    options: [
+                        {
+                            name: 'include-private',
+                            type: 'boolean',
+                            description: 'Include private fields',
+                            positional: false,
+                            required: false,
+                            variadic: false,
+                            default: false,
+                        },
+                    ],
+                    columns: ['name', 'bio'],
+                    defaultFormat: 'plain',
+                    example: 'webcmd web profile alice',
+                    fileArguments: [],
+                    sessionPolicy: 'create-or-reuse',
+                    availability: { mode: 'hosted' },
+                },
+            ],
+            browserCommands: [browserCatalog[0], browserCatalog[1]],
+        });
+        expect(serializeHostedContract(contract)).toBe(serializeHostedContract(buildHostedContract([...commands].reverse(), [...browserCatalog].reverse(), '9.8.7')));
+    });
+    it('rejects duplicate canonical commands and aliases', () => {
+        const duplicate = { ...commands[0] };
+        expect(() => buildHostedContract([commands[0], duplicate], [], '1.0.0'))
+            .toThrow('Duplicate canonical command: web/profile');
+        const aliasCollision = {
+            ...commands[0],
+            name: 'me',
+            aliases: undefined,
+        };
+        expect(() => buildHostedContract([commands[0], aliasCollision], [], '1.0.0'))
+            .toThrow('Duplicate command alias: web/me');
+    });
+    it('rejects incomplete file and browser session metadata', () => {
+        const missingDirection = {
+            ...commands[2],
+            args: [{
+                    name: 'source',
+                    positional: true,
+                    file: {},
+                }],
+        };
+        expect(() => buildHostedContract([missingDirection], [], '1.0.0'))
+            .toThrow('File argument files/transfer source must declare direction');
+        const missingPathKind = {
+            ...commands[2],
+            args: [{
+                    name: 'source',
+                    positional: true,
+                    file: { direction: 'input' },
+                }],
+        };
+        expect(() => buildHostedContract([missingPathKind], [], '1.0.0'))
+            .toThrow('File argument files/transfer source must declare pathKind');
+        const unsupportedSeparator = {
+            ...commands[2],
+            args: [{
+                    name: 'source',
+                    positional: true,
+                    file: { direction: 'input', pathKind: 'file', separator: ':' },
+                }],
+        };
+        expect(() => buildHostedContract([unsupportedSeparator], [], '1.0.0'))
+            .toThrow('File argument files/transfer source declares unsupported separator');
+        const missingPolicy = [{
+                command: 'open',
+                aliases: [],
+                description: 'Open',
+                positionals: [],
+                options: [],
+            }];
+        expect(() => buildHostedContract([], missingPolicy, '1.0.0'))
+            .toThrow('Browser command open must declare a known session policy');
+    });
+});

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

@@ -0,0 +1,38 @@
+import { type ConfigIo, type HostedManifestCache, type HostedWebcmdConfig } from './config.js';
+export type HostedCredentialBackend = 'os' | 'file-fallback';
+export interface HostedCredentialStore {
+    put(reference: string, secret: string): Promise<void>;
+    get(reference: string): Promise<string | null>;
+    delete(reference: string): Promise<void>;
+    backend(): HostedCredentialBackend;
+}
+export interface HostedCredentialIo extends ConfigIo {
+    credentialStore?: HostedCredentialStore;
+    randomUUID?: () => string;
+    platform?: NodeJS.Platform;
+}
+export interface HostedCredentialResolution {
+    apiKey: string;
+    backend?: HostedCredentialBackend;
+    migrated: boolean;
+    migrationError?: Error;
+}
+interface StoredHostedConfigInput {
+    apiBaseUrl: string;
+    apiKeyRef: string;
+    credentialBackend: HostedCredentialBackend;
+    manifestCache?: HostedManifestCache;
+    now?: Date;
+}
+export declare function getHostedCredentialPath(io?: Pick<ConfigIo, 'env' | 'homeDir'>): string;
+export declare function storeHostedApiKey(apiKey: string, io?: HostedCredentialIo): Promise<{
+    apiKeyRef: string;
+    credentialBackend: HostedCredentialBackend;
+}>;
+export declare function resolveHostedApiKey(config: HostedWebcmdConfig, io?: HostedCredentialIo & {
+    migrate?: boolean;
+}): Promise<HostedCredentialResolution>;
+export declare function makeStoredHostedConfig(input: StoredHostedConfigInput): HostedWebcmdConfig;
+declare function isMacOsKeychainAvailable(io: HostedCredentialIo): boolean;
+export declare const _isMacOsKeychainAvailableForTest: typeof isMacOsKeychainAvailable;
+export {};

package/dist/src/hosted/credentials.js

@@ -0,0 +1,248 @@
+import { execFile as execFileCallback } from 'node:child_process';
+import * as fs from 'node:fs';
+import { mkdir, readFile, rename, rm, writeFile, chmod } from 'node:fs/promises';
+import * as path from 'node:path';
+import { promisify } from 'node:util';
+import { randomUUID } from 'node:crypto';
+import { ConfigError } from '../errors.js';
+import { getConfigDir, normalizeApiBaseUrl, saveWebcmdConfig, } from './config.js';
+const execFile = promisify(execFileCallback);
+const MACOS_KEYCHAIN_SERVICE = 'dev.webcmd.hosted-api-key';
+const MACOS_KEYCHAIN_TIMEOUT_MS = 5_000;
+export function getHostedCredentialPath(io = {}) {
+    return path.join(getConfigDir(io), 'hosted-credentials.json');
+}
+export async function storeHostedApiKey(apiKey, io = {}) {
+    const apiKeyRef = createHostedCredentialReference(io);
+    const candidates = createCredentialStoreCandidates(io);
+    let lastError;
+    for (const store of candidates) {
+        try {
+            await store.put(apiKeyRef, apiKey);
+            const readBack = await store.get(apiKeyRef);
+            if (readBack !== apiKey) {
+                throw new Error(`Hosted credential store ${store.backend()} did not verify the saved key.`);
+            }
+            return { apiKeyRef, credentialBackend: store.backend() };
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            try {
+                await store.delete(apiKeyRef);
+            }
+            catch {
+                // Best-effort cleanup only; a failed candidate must not hide fallback stores.
+            }
+        }
+    }
+    throw lastError ?? new Error('No hosted credential store is available.');
+}
+export async function resolveHostedApiKey(config, io = {}) {
+    if (config.hosted.apiKeyRef) {
+        const store = createCredentialStoreForBackend(config.hosted.credentialBackend, io);
+        const apiKey = await store.get(config.hosted.apiKeyRef);
+        if (!apiKey) {
+            throw new ConfigError('Webcmd hosted credentials are missing.', 'Run `webcmd setup` again to reconnect hosted mode.');
+        }
+        return {
+            apiKey,
+            backend: store.backend(),
+            migrated: false,
+        };
+    }
+    if (config.hosted.apiKey) {
+        const apiKey = config.hosted.apiKey;
+        if (io.migrate === false)
+            return { apiKey, migrated: false };
+        try {
+            const stored = await storeHostedApiKey(apiKey, io);
+            saveWebcmdConfig(makeStoredHostedConfig({
+                apiBaseUrl: config.hosted.apiBaseUrl,
+                apiKeyRef: stored.apiKeyRef,
+                credentialBackend: stored.credentialBackend,
+                ...(config.hosted.manifestCache ? { manifestCache: config.hosted.manifestCache } : {}),
+                now: new Date(config.updatedAt),
+            }), io);
+            return {
+                apiKey,
+                backend: stored.credentialBackend,
+                migrated: true,
+            };
+        }
+        catch (error) {
+            return {
+                apiKey,
+                migrated: false,
+                migrationError: error instanceof Error ? error : new Error(String(error)),
+            };
+        }
+    }
+    throw new ConfigError('Webcmd hosted mode is missing its API key reference.', 'Run `webcmd setup` again to reconnect hosted mode.');
+}
+export function makeStoredHostedConfig(input) {
+    return {
+        mode: 'hosted',
+        updatedAt: (input.now ?? new Date()).toISOString(),
+        hosted: {
+            apiBaseUrl: normalizeApiBaseUrl(input.apiBaseUrl),
+            apiKeyRef: input.apiKeyRef,
+            credentialBackend: input.credentialBackend,
+            ...(input.manifestCache ? { manifestCache: input.manifestCache } : {}),
+        },
+    };
+}
+function createHostedCredentialReference(io) {
+    const id = (io.randomUUID ?? randomUUID)().replace(/[^A-Za-z0-9_-]/g, '');
+    return `wcmd_cred_${id}`;
+}
+function createCredentialStoreCandidates(io) {
+    if (io.credentialStore)
+        return [io.credentialStore];
+    const stores = [];
+    if (isMacOsKeychainAvailable(io))
+        stores.push(new MacOsKeychainCredentialStore());
+    stores.push(new FileHostedCredentialStore(io));
+    return stores;
+}
+function createCredentialStoreForBackend(backend, io) {
+    if (io.credentialStore)
+        return io.credentialStore;
+    if (backend === 'os' && isMacOsKeychainAvailable(io))
+        return new MacOsKeychainCredentialStore();
+    if (backend === 'os') {
+        throw new ConfigError('The configured OS credential store is not available on this machine.', 'Run `webcmd setup` again to reconnect hosted mode on this machine.');
+    }
+    return new FileHostedCredentialStore(io);
+}
+function isMacOsKeychainAvailable(io) {
+    const env = io.env ?? process.env;
+    if (env.WEBCMD_CREDENTIAL_BACKEND === 'file')
+        return false;
+    const platform = io.platform ?? process.platform;
+    const existsSync = io.existsSync ?? fs.existsSync;
+    return platform === 'darwin' && existsSync('/usr/bin/security');
+}
+class MacOsKeychainCredentialStore {
+    backend() {
+        return 'os';
+    }
+    async put(reference, secret) {
+        validateCredentialReference(reference);
+        await execFile('/usr/bin/security', [
+            'add-generic-password',
+            '-a',
+            reference,
+            '-s',
+            MACOS_KEYCHAIN_SERVICE,
+            '-w',
+            secret,
+            '-U',
+        ], { timeout: MACOS_KEYCHAIN_TIMEOUT_MS });
+    }
+    async get(reference) {
+        validateCredentialReference(reference);
+        try {
+            const { stdout } = await execFile('/usr/bin/security', [
+                'find-generic-password',
+                '-a',
+                reference,
+                '-s',
+                MACOS_KEYCHAIN_SERVICE,
+                '-w',
+            ], { timeout: MACOS_KEYCHAIN_TIMEOUT_MS });
+            return stdout.replace(/\r?\n$/, '');
+        }
+        catch {
+            return null;
+        }
+    }
+    async delete(reference) {
+        validateCredentialReference(reference);
+        try {
+            await execFile('/usr/bin/security', [
+                'delete-generic-password',
+                '-a',
+                reference,
+                '-s',
+                MACOS_KEYCHAIN_SERVICE,
+            ], { timeout: MACOS_KEYCHAIN_TIMEOUT_MS });
+        }
+        catch {
+            // Missing credentials are already deleted for the caller's purposes.
+        }
+    }
+}
+class FileHostedCredentialStore {
+    io;
+    constructor(io = {}) {
+        this.io = io;
+    }
+    backend() {
+        return 'file-fallback';
+    }
+    async put(reference, secret) {
+        validateCredentialReference(reference);
+        const document = await this.readDocument();
+        document.credentials[reference] = secret;
+        document.updatedAt = new Date().toISOString();
+        await this.writeDocument(document);
+    }
+    async get(reference) {
+        validateCredentialReference(reference);
+        const document = await this.readDocument();
+        return document.credentials[reference] ?? null;
+    }
+    async delete(reference) {
+        validateCredentialReference(reference);
+        const document = await this.readDocument();
+        if (!Object.prototype.hasOwnProperty.call(document.credentials, reference))
+            return;
+        delete document.credentials[reference];
+        document.updatedAt = new Date().toISOString();
+        await this.writeDocument(document);
+    }
+    async readDocument() {
+        try {
+            const parsed = JSON.parse(await readFile(getHostedCredentialPath(this.io), 'utf8'));
+            if (parsed.version === 1 && parsed.credentials && typeof parsed.credentials === 'object') {
+                const credentials = {};
+                for (const [key, value] of Object.entries(parsed.credentials)) {
+                    if (typeof value === 'string')
+                        credentials[key] = value;
+                }
+                return {
+                    version: 1,
+                    credentials,
+                    updatedAt: typeof parsed.updatedAt === 'string' ? parsed.updatedAt : new Date(0).toISOString(),
+                };
+            }
+        }
+        catch {
+            // Missing or malformed fallback storage starts empty. The main config still
+            // holds only an opaque reference, so malformed fallback credentials surface
+            // later as a missing credential rather than as config corruption.
+        }
+        return { version: 1, credentials: {}, updatedAt: new Date(0).toISOString() };
+    }
+    async writeDocument(document) {
+        const target = getHostedCredentialPath(this.io);
+        await mkdir(path.dirname(target), { recursive: true });
+        const temp = `${target}.${process.pid}.${Date.now()}.tmp`;
+        try {
+            await writeFile(temp, `${JSON.stringify(document, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+            await chmod(temp, 0o600).catch(() => undefined);
+            await rename(temp, target);
+            await chmod(target, 0o600).catch(() => undefined);
+        }
+        catch (error) {
+            await rm(temp, { force: true }).catch(() => undefined);
+            throw error;
+        }
+    }
+}
+function validateCredentialReference(reference) {
+    if (!/^[A-Za-z0-9_-]{8,160}$/.test(reference)) {
+        throw new Error('Hosted credential reference must be opaque and URL-safe.');
+    }
+}
+export const _isMacOsKeychainAvailableForTest = isMacOsKeychainAvailable;

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

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