@agentrhq/webcmd 0.3.0 → 0.3.2

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

@@ -1,4 +1,5 @@
 import * as fs from 'node:fs';
+import type { HostedCredentialBackend } from './credentials.js';
 export interface HostedManifestCache {
     fetchedAt: string;
     manifest: unknown;
@@ -11,7 +12,9 @@ export type WebcmdConfig = {
     updatedAt: string;
     hosted: {
         apiBaseUrl: string;
-        apiKey: string;
+        apiKey?: string;
+        apiKeyRef?: string;
+        credentialBackend?: HostedCredentialBackend;
         manifestCache?: HostedManifestCache;
     };
 };
@@ -38,7 +41,9 @@ export type HostedWebcmdConfig = Extract<WebcmdConfig, {
 export declare function makeLocalConfig(now?: Date): LocalWebcmdConfig;
 export declare function makeHostedConfig(input: {
     apiBaseUrl: string;
-    apiKey: string;
+    apiKey?: string;
+    apiKeyRef?: string;
+    credentialBackend?: HostedCredentialBackend;
     manifestCache?: HostedManifestCache;
     now?: Date;
 }): HostedWebcmdConfig;

package/dist/src/hosted/config.js

@@ -17,13 +17,16 @@ function parseConfig(raw) {
     if (parsed.mode === 'hosted'
         && typeof parsed.updatedAt === 'string'
         && typeof parsed.hosted?.apiBaseUrl === 'string'
-        && typeof parsed.hosted?.apiKey === '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,
-                apiKey: parsed.hosted.apiKey,
+                ...(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 } : {}),
             },
         };
@@ -45,7 +48,7 @@ export function saveWebcmdConfig(config, io = {}) {
     const chmodSync = io.chmodSync ?? fs.chmodSync;
     const target = getConfigPath(io);
     mkdirSync(path.dirname(target), { recursive: true });
-    writeFileSync(target, `${JSON.stringify(config, null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
+    writeFileSync(target, `${JSON.stringify(persistableConfig(config), null, 2)}\n`, { encoding: 'utf-8', mode: 0o600 });
     try {
         chmodSync(target, 0o600);
     }
@@ -65,7 +68,9 @@ export function makeHostedConfig(input) {
         updatedAt: (input.now ?? new Date()).toISOString(),
         hosted: {
             apiBaseUrl: normalizeApiBaseUrl(input.apiBaseUrl),
-            apiKey: input.apiKey.trim(),
+            ...(input.apiKey !== undefined ? { apiKey: input.apiKey.trim() } : {}),
+            ...(input.apiKeyRef !== undefined ? { apiKeyRef: input.apiKeyRef } : {}),
+            ...(input.credentialBackend !== undefined ? { credentialBackend: input.credentialBackend } : {}),
             ...(input.manifestCache ? { manifestCache: input.manifestCache } : {}),
         },
     };
@@ -88,3 +93,20 @@ export function isHostedConfig(config) {
 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.js

@@ -1,8 +1,9 @@
-import { mkdtemp, rm } from 'node:fs/promises';
+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)
@@ -37,6 +38,38 @@ describe('hosted config', () => {
         });
         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',

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 {};