@agentrhq/webcmd 0.2.5 → 0.3.1

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

@@ -0,0 +1,55 @@
+import * as fs from 'node:fs';
+import type { HostedCredentialBackend } from './credentials.js';
+export interface HostedManifestCache {
+    fetchedAt: string;
+    manifest: unknown;
+}
+export type WebcmdConfig = {
+    mode: 'local';
+    updatedAt: string;
+} | {
+    mode: 'hosted';
+    updatedAt: string;
+    hosted: {
+        apiBaseUrl: string;
+        apiKey?: string;
+        apiKeyRef?: string;
+        credentialBackend?: HostedCredentialBackend;
+        manifestCache?: HostedManifestCache;
+    };
+};
+export interface ConfigIo {
+    readFileSync?: typeof fs.readFileSync;
+    writeFileSync?: typeof fs.writeFileSync;
+    mkdirSync?: typeof fs.mkdirSync;
+    chmodSync?: typeof fs.chmodSync;
+    existsSync?: typeof fs.existsSync;
+    env?: NodeJS.ProcessEnv;
+    homeDir?: string;
+    now?: () => Date;
+}
+export declare function getConfigDir(io?: Pick<ConfigIo, 'env' | 'homeDir'>): string;
+export declare function getConfigPath(io?: Pick<ConfigIo, 'env' | 'homeDir'>): string;
+export declare function loadWebcmdConfig(io?: ConfigIo): WebcmdConfig;
+export declare function saveWebcmdConfig(config: WebcmdConfig, io?: ConfigIo): void;
+export type LocalWebcmdConfig = Extract<WebcmdConfig, {
+    mode: 'local';
+}>;
+export type HostedWebcmdConfig = Extract<WebcmdConfig, {
+    mode: 'hosted';
+}>;
+export declare function makeLocalConfig(now?: Date): LocalWebcmdConfig;
+export declare function makeHostedConfig(input: {
+    apiBaseUrl: string;
+    apiKey?: string;
+    apiKeyRef?: string;
+    credentialBackend?: HostedCredentialBackend;
+    manifestCache?: HostedManifestCache;
+    now?: Date;
+}): HostedWebcmdConfig;
+export declare function normalizeApiBaseUrl(raw: string): string;
+export declare function defaultHostedApiBaseUrl(env?: NodeJS.ProcessEnv): string;
+export declare function isHostedConfig(config: WebcmdConfig): config is Extract<WebcmdConfig, {
+    mode: 'hosted';
+}>;
+export declare function shouldUseHostedMode(io?: ConfigIo): boolean;

package/dist/src/hosted/config.js

@@ -0,0 +1,112 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { CONFIG_DIR_NAME, ENV_PREFIX } from '../brand.js';
+export function getConfigDir(io = {}) {
+    const env = io.env ?? process.env;
+    return env[`${ENV_PREFIX}_CONFIG_DIR`] || path.join(io.homeDir ?? os.homedir(), CONFIG_DIR_NAME);
+}
+export function getConfigPath(io = {}) {
+    return path.join(getConfigDir(io), 'config.json');
+}
+function parseConfig(raw) {
+    const parsed = JSON.parse(raw);
+    if (parsed.mode === 'local' && typeof parsed.updatedAt === 'string') {
+        return { mode: 'local', updatedAt: parsed.updatedAt };
+    }
+    if (parsed.mode === 'hosted'
+        && typeof parsed.updatedAt === 'string'
+        && typeof parsed.hosted?.apiBaseUrl === 'string'
+        && (typeof parsed.hosted?.apiKey === 'string' || typeof parsed.hosted?.apiKeyRef === 'string')) {
+        const credentialBackend = readCredentialBackend(parsed.hosted.credentialBackend);
+        return {
+            mode: 'hosted',
+            updatedAt: parsed.updatedAt,
+            hosted: {
+                apiBaseUrl: parsed.hosted.apiBaseUrl,
+                ...(typeof parsed.hosted.apiKey === 'string' ? { apiKey: parsed.hosted.apiKey } : {}),
+                ...(typeof parsed.hosted.apiKeyRef === 'string' ? { apiKeyRef: parsed.hosted.apiKeyRef } : {}),
+                ...(credentialBackend ? { credentialBackend } : {}),
+                ...(parsed.hosted.manifestCache ? { manifestCache: parsed.hosted.manifestCache } : {}),
+            },
+        };
+    }
+    return { mode: 'local', updatedAt: new Date(0).toISOString() };
+}
+export function loadWebcmdConfig(io = {}) {
+    const readFileSync = io.readFileSync ?? fs.readFileSync;
+    try {
+        return parseConfig(readFileSync(getConfigPath(io), 'utf-8'));
+    }
+    catch {
+        return { mode: 'local', updatedAt: new Date(0).toISOString() };
+    }
+}
+export function saveWebcmdConfig(config, io = {}) {
+    const writeFileSync = io.writeFileSync ?? fs.writeFileSync;
+    const mkdirSync = io.mkdirSync ?? fs.mkdirSync;
+    const chmodSync = io.chmodSync ?? fs.chmodSync;
+    const target = getConfigPath(io);
+    mkdirSync(path.dirname(target), { recursive: true });
+    writeFileSync(target, `${JSON.stringify(persistableConfig(config), null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+    try {
+        chmodSync(target, 0o600);
+    }
+    catch {
+        // Windows and unusual filesystems may not support POSIX modes.
+    }
+}
+export function makeLocalConfig(now = new Date()) {
+    return {
+        mode: 'local',
+        updatedAt: now.toISOString(),
+    };
+}
+export function makeHostedConfig(input) {
+    return {
+        mode: 'hosted',
+        updatedAt: (input.now ?? new Date()).toISOString(),
+        hosted: {
+            apiBaseUrl: normalizeApiBaseUrl(input.apiBaseUrl),
+            ...(input.apiKey !== undefined ? { apiKey: input.apiKey.trim() } : {}),
+            ...(input.apiKeyRef !== undefined ? { apiKeyRef: input.apiKeyRef } : {}),
+            ...(input.credentialBackend !== undefined ? { credentialBackend: input.credentialBackend } : {}),
+            ...(input.manifestCache ? { manifestCache: input.manifestCache } : {}),
+        },
+    };
+}
+export function normalizeApiBaseUrl(raw) {
+    const value = raw.trim().replace(/\/+$/, '');
+    return value || defaultHostedApiBaseUrl();
+}
+export function defaultHostedApiBaseUrl(env = process.env) {
+    return normalizeConfiguredUrl(env.WEBCMD_CLOUD_API_URL) ?? 'https://api.webcmd.dev';
+}
+function normalizeConfiguredUrl(raw) {
+    if (!raw?.trim())
+        return undefined;
+    return raw.trim().replace(/\/+$/, '');
+}
+export function isHostedConfig(config) {
+    return config.mode === 'hosted';
+}
+export function shouldUseHostedMode(io = {}) {
+    return isHostedConfig(loadWebcmdConfig(io));
+}
+function readCredentialBackend(value) {
+    return value === 'os' || value === 'file-fallback' ? value : undefined;
+}
+function persistableConfig(config) {
+    if (config.mode !== 'hosted' || !config.hosted.apiKeyRef)
+        return config;
+    return {
+        mode: 'hosted',
+        updatedAt: config.updatedAt,
+        hosted: {
+            apiBaseUrl: config.hosted.apiBaseUrl,
+            apiKeyRef: config.hosted.apiKeyRef,
+            ...(config.hosted.credentialBackend ? { credentialBackend: config.hosted.credentialBackend } : {}),
+            ...(config.hosted.manifestCache ? { manifestCache: config.hosted.manifestCache } : {}),
+        },
+    };
+}

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

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

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

@@ -0,0 +1,81 @@
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { defaultHostedApiBaseUrl, getConfigPath, isHostedConfig, loadWebcmdConfig, makeHostedConfig, makeLocalConfig, saveWebcmdConfig, } from './config.js';
+import { resolveHostedApiKey } from './credentials.js';
+let tempDir;
+afterEach(async () => {
+    if (tempDir)
+        await rm(tempDir, { recursive: true, force: true });
+    tempDir = undefined;
+});
+describe('hosted config', () => {
+    it('defaults to local mode when config is absent', () => {
+        tempDir = join(tmpdir(), `webcmd-config-missing-${Date.now()}`);
+        expect(loadWebcmdConfig({ env: { WEBCMD_CONFIG_DIR: tempDir } })).toEqual({
+            mode: 'local',
+            updatedAt: '1970-01-01T00:00:00.000Z',
+        });
+    });
+    it('writes and reads hosted config', async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'webcmd-config-'));
+        const env = { WEBCMD_CONFIG_DIR: tempDir };
+        const config = makeHostedConfig({
+            apiBaseUrl: 'https://api.example.com/',
+            apiKey: 'wcmd_live_test',
+            now: new Date('2026-07-08T00:00:00.000Z'),
+        });
+        saveWebcmdConfig(config, { env });
+        expect(getConfigPath({ env })).toBe(join(tempDir, 'config.json'));
+        expect(loadWebcmdConfig({ env })).toEqual({
+            mode: 'hosted',
+            updatedAt: '2026-07-08T00:00:00.000Z',
+            hosted: {
+                apiBaseUrl: 'https://api.example.com',
+                apiKey: 'wcmd_live_test',
+            },
+        });
+        expect(isHostedConfig(loadWebcmdConfig({ env }))).toBe(true);
+    });
+    it('migrates a legacy inline API key without losing manifest cache', async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'webcmd-config-migrate-'));
+        const env = {
+            WEBCMD_CONFIG_DIR: tempDir,
+            WEBCMD_CREDENTIAL_BACKEND: 'file',
+        };
+        await writeFile(getConfigPath({ env }), JSON.stringify({
+            mode: 'hosted',
+            updatedAt: '2026-07-08T00:00:00.000Z',
+            hosted: {
+                apiBaseUrl: 'https://api.example.com',
+                apiKey: 'wcmd_legacy_secret',
+                manifestCache: {
+                    fetchedAt: '2026-07-08T00:01:00.000Z',
+                    manifest: { ok: true },
+                },
+            },
+        }, null, 2));
+        const loaded = loadWebcmdConfig({ env });
+        if (!isHostedConfig(loaded))
+            throw new Error('Expected hosted config');
+        const credential = await resolveHostedApiKey(loaded, { env, platform: 'linux' });
+        const persisted = await readFile(getConfigPath({ env }), 'utf8');
+        expect(credential).toMatchObject({
+            apiKey: 'wcmd_legacy_secret',
+            backend: 'file-fallback',
+            migrated: true,
+        });
+        expect(persisted).not.toContain('wcmd_legacy_secret');
+        expect(persisted).toContain('apiKeyRef');
+        expect(persisted).toContain('manifestCache');
+    });
+    it('writes local config and resolves default API URL from env', () => {
+        expect(makeLocalConfig(new Date('2026-07-08T00:00:00.000Z'))).toEqual({
+            mode: 'local',
+            updatedAt: '2026-07-08T00:00:00.000Z',
+        });
+        expect(defaultHostedApiBaseUrl({ WEBCMD_CLOUD_API_URL: 'https://cloud.example.com/' }))
+            .toBe('https://cloud.example.com');
+    });
+});

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

@@ -0,0 +1,94 @@
+import type { Arg, CliCommand } from '../registry.js';
+import { type HostedAvailability } from './availability.js';
+export declare const HOSTED_CONTRACT_SCHEMA_VERSION: 1;
+export type { HostedAvailability } from './availability.js';
+export interface FileArgumentContract {
+    direction: 'input' | 'output';
+    pathKind: 'file' | 'directory';
+    multiple?: boolean;
+    separator?: ',';
+    contentTypes?: string[];
+    maxBytes?: number;
+    /** Local destination used when the adapter itself supplies an implicit path. */
+    defaultPath?: string;
+}
+export interface HostedFileArgumentContract {
+    name: string;
+    direction: 'input' | 'output';
+    pathKind: 'file' | 'directory';
+    multiple: boolean;
+    required: boolean;
+    separator?: ',';
+    contentTypes?: string[];
+    maxBytes?: number;
+    defaultPath?: string;
+}
+export interface HostedArgumentContract {
+    name: string;
+    type: 'string' | 'int' | 'number' | 'boolean';
+    description: string;
+    positional: boolean;
+    required: boolean;
+    variadic: boolean;
+    default?: unknown;
+    choices?: string[];
+}
+export interface HostedOptionContract extends HostedArgumentContract {
+    name: string;
+    flags: string;
+    positional: false;
+}
+export type HostedSessionPolicy = 'create-or-reuse' | 'require-existing' | 'close-existing' | 'local-only';
+export interface HostedBrowserCommandContract {
+    command: string;
+    aliases: string[];
+    description: string;
+    positionals: HostedArgumentContract[];
+    options: HostedArgumentContract[];
+    sessionPolicy: HostedSessionPolicy;
+    action?: string;
+}
+export interface HostedContractCommand {
+    command: string;
+    site: string;
+    name: string;
+    description: string;
+    access: 'read' | 'write';
+    strategy: 'PUBLIC' | 'COOKIE' | 'INTERCEPT' | 'UI' | 'LOCAL';
+    browser: boolean;
+    domain?: string;
+    positionals: HostedArgumentContract[];
+    options: HostedArgumentContract[];
+    columns: string[];
+    aliases: string[];
+    defaultFormat: string;
+    example?: string;
+    fileArguments: HostedFileArgumentContract[];
+    sessionPolicy: HostedSessionPolicy;
+    availability: HostedAvailability;
+}
+export interface HostedContract {
+    schemaVersion: typeof HOSTED_CONTRACT_SCHEMA_VERSION;
+    webcmdVersion: string;
+    outputFormats: Array<'table' | 'plain' | 'json' | 'yaml' | 'md' | 'csv'>;
+    traceModes: Array<'off' | 'on' | 'retain-on-failure'>;
+    commonOptions: HostedOptionContract[];
+    commands: HostedContractCommand[];
+    browserCommands: HostedBrowserCommandContract[];
+}
+export interface HostedContractCommandInput {
+    site: string;
+    name: string;
+    aliases?: string[];
+    description: string;
+    access: 'read' | 'write';
+    example?: string;
+    domain?: string;
+    strategy?: string;
+    browser?: boolean;
+    args: Arg[];
+    columns?: string[];
+    defaultFormat?: CliCommand['defaultFormat'];
+}
+export declare function buildHostedContract(commands: readonly HostedContractCommandInput[], browserCatalogInput: readonly HostedBrowserCommandContract[], packageVersion: string): HostedContract;
+export declare function serializeHostedContract(contract: HostedContract): string;

package/dist/src/hosted/contract.js

@@ -0,0 +1,208 @@
+import { commandHelpData } from '../help.js';
+import { browserCommandCatalog } from '../browser/command-catalog.js';
+import { deriveBrowserAvailability, deriveHostedAvailability, } from './availability.js';
+export const HOSTED_CONTRACT_SCHEMA_VERSION = 1;
+const KNOWN_SESSION_POLICIES = new Set([
+    'create-or-reuse',
+    'require-existing',
+    'close-existing',
+    'local-only',
+]);
+function sharedContractOptions() {
+    const metadata = commandHelpData({
+        site: '__contract__',
+        name: '__contract__',
+        description: '',
+        access: 'read',
+        strategy: 'public',
+        browser: false,
+        args: [],
+    });
+    const common = metadata.common_options;
+    const format = common.find(option => option.name === 'format');
+    const trace = common.find(option => option.name === 'trace');
+    if (!format?.choices || !trace?.choices) {
+        throw new Error('Shared format and trace option choices are required');
+    }
+    return {
+        outputFormats: [...format.choices],
+        traceModes: [...trace.choices],
+        commonOptions: common.map(option => ({
+            name: option.name,
+            flags: option.flags,
+            type: option.flags.includes('<') || option.flags.includes('[') ? 'string' : 'boolean',
+            description: option.help ?? '',
+            positional: false,
+            required: false,
+            variadic: false,
+            ...(option.default !== undefined ? { default: option.default } : {}),
+            ...(option.choices?.length ? { choices: [...option.choices] } : {}),
+        })),
+    };
+}
+function normalizeArgumentType(type) {
+    switch ((type ?? 'string').toLowerCase()) {
+        case 'str':
+        case 'string':
+            return 'string';
+        case 'bool':
+        case 'boolean':
+            return 'boolean';
+        case 'int':
+        case 'integer':
+            return 'int';
+        case 'number':
+        case 'float':
+            return 'number';
+        default:
+            throw new Error(`Unsupported hosted argument type: ${type}`);
+    }
+}
+function normalizeArgument(arg) {
+    return {
+        name: arg.name,
+        type: normalizeArgumentType(arg.type),
+        description: arg.help ?? '',
+        positional: arg.positional === true,
+        required: arg.required === true,
+        variadic: false,
+        ...(arg.default !== undefined ? { default: arg.default } : {}),
+        ...(arg.choices?.length ? { choices: [...arg.choices] } : {}),
+    };
+}
+function normalizeStrategy(command) {
+    const raw = command.strategy ?? (command.browser === false ? 'public' : 'cookie');
+    const strategy = raw.toUpperCase();
+    if (strategy === 'PUBLIC' || strategy === 'COOKIE' || strategy === 'INTERCEPT'
+        || strategy === 'UI' || strategy === 'LOCAL') {
+        return strategy;
+    }
+    throw new Error(`Unsupported hosted strategy for ${command.site}/${command.name}: ${raw}`);
+}
+function normalizeDefaultFormat(format) {
+    if (format === 'yml')
+        return 'yaml';
+    if (format === 'markdown')
+        return 'md';
+    return format ?? 'table';
+}
+function normalizeFileArguments(command) {
+    return command.args.flatMap((arg) => {
+        if (!arg.file)
+            return [];
+        if (arg.file.direction !== 'input' && arg.file.direction !== 'output') {
+            throw new Error(`File argument ${command.site}/${command.name} ${arg.name} must declare direction`);
+        }
+        if (arg.file.pathKind !== 'file' && arg.file.pathKind !== 'directory') {
+            throw new Error(`File argument ${command.site}/${command.name} ${arg.name} must declare pathKind`);
+        }
+        if (arg.file.separator !== undefined && arg.file.separator !== ',') {
+            throw new Error(`File argument ${command.site}/${command.name} ${arg.name} declares unsupported separator`);
+        }
+        return [{
+                name: arg.name,
+                direction: arg.file.direction,
+                pathKind: arg.file.pathKind,
+                multiple: arg.file.multiple === true,
+                required: arg.required === true,
+                ...(arg.file.separator !== undefined ? { separator: arg.file.separator } : {}),
+                ...(arg.file.contentTypes?.length ? { contentTypes: [...arg.file.contentTypes] } : {}),
+                ...(arg.file.maxBytes !== undefined ? { maxBytes: arg.file.maxBytes } : {}),
+                ...(arg.file.defaultPath !== undefined ? { defaultPath: arg.file.defaultPath } : {}),
+            }];
+    });
+}
+function assertUniqueAdapterCommands(commands) {
+    const canonical = new Set();
+    for (const command of commands) {
+        const key = `${command.site}/${command.name}`;
+        if (canonical.has(key))
+            throw new Error(`Duplicate canonical command: ${key}`);
+        canonical.add(key);
+    }
+    const invocations = new Set(canonical);
+    for (const command of commands) {
+        for (const alias of command.aliases ?? []) {
+            const key = `${command.site}/${alias}`;
+            if (invocations.has(key))
+                throw new Error(`Duplicate command alias: ${key}`);
+            invocations.add(key);
+        }
+    }
+}
+function normalizeBrowserCatalog(browserCatalog) {
+    const canonical = new Set();
+    for (const browserCommand of browserCatalog) {
+        if (canonical.has(browserCommand.command)) {
+            throw new Error(`Duplicate canonical browser command: ${browserCommand.command}`);
+        }
+        canonical.add(browserCommand.command);
+        if (!KNOWN_SESSION_POLICIES.has(browserCommand.sessionPolicy)) {
+            throw new Error(`Browser command ${browserCommand.command} must declare a known session policy`);
+        }
+        const availability = deriveBrowserAvailability(browserCommand.command);
+        if (availability.mode === 'local-only' && browserCommand.sessionPolicy !== 'local-only') {
+            throw new Error(`Browser command ${browserCommand.command} must use local-only session policy`);
+        }
+    }
+    const invocations = new Set(canonical);
+    for (const browserCommand of browserCatalog) {
+        for (const alias of browserCommand.aliases ?? []) {
+            if (invocations.has(alias))
+                throw new Error(`Duplicate browser command alias: ${alias}`);
+            invocations.add(alias);
+        }
+    }
+    return browserCatalog
+        .map(browserCommand => ({
+        command: browserCommand.command,
+        aliases: [...(browserCommand.aliases ?? [])],
+        description: browserCommand.description,
+        positionals: browserCommand.positionals.map(arg => ({ ...arg })),
+        options: browserCommand.options.map(arg => ({ ...arg })),
+        sessionPolicy: browserCommand.sessionPolicy,
+        ...(browserCommand.action !== undefined ? { action: browserCommand.action } : {}),
+    }))
+        .sort((a, b) => a.command.localeCompare(b.command));
+}
+export function buildHostedContract(commands, browserCatalogInput, packageVersion) {
+    assertUniqueAdapterCommands(commands);
+    const browserCatalog = browserCatalogInput.length > 0
+        ? browserCatalogInput
+        : browserCommandCatalog;
+    const shared = sharedContractOptions();
+    const contractCommands = commands.map((command) => {
+        const availability = deriveHostedAvailability(command);
+        return {
+            command: `${command.site}/${command.name}`,
+            site: command.site,
+            name: command.name,
+            description: command.description,
+            access: command.access,
+            strategy: normalizeStrategy(command),
+            browser: command.browser !== false,
+            ...(command.domain !== undefined ? { domain: command.domain } : {}),
+            positionals: command.args.filter(arg => arg.positional).map(normalizeArgument),
+            options: command.args.filter(arg => !arg.positional).map(normalizeArgument),
+            columns: [...(command.columns ?? [])],
+            aliases: [...(command.aliases ?? [])],
+            defaultFormat: normalizeDefaultFormat(command.defaultFormat),
+            ...(command.example !== undefined ? { example: command.example } : {}),
+            fileArguments: normalizeFileArguments(command),
+            sessionPolicy: availability.mode === 'hosted' ? 'create-or-reuse' : 'local-only',
+            availability,
+        };
+    }).sort((a, b) => a.command.localeCompare(b.command));
+    return {
+        schemaVersion: HOSTED_CONTRACT_SCHEMA_VERSION,
+        webcmdVersion: packageVersion,
+        outputFormats: shared.outputFormats,
+        traceModes: shared.traceModes,
+        commonOptions: shared.commonOptions,
+        commands: contractCommands,
+        browserCommands: normalizeBrowserCatalog(browserCatalog),
+    };
+}
+export function serializeHostedContract(contract) {
+    return `${JSON.stringify(contract, null, 2)}\n`;
+}

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

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