@agentrhq/webcmd 0.2.4 → 0.3.0

package/dist/src/hosted/client.js

@@ -0,0 +1,122 @@
+import { CliError, EXIT_CODES } from '../errors.js';
+export class HostedClientError extends CliError {
+    constructor(code, message, help, exitCode = EXIT_CODES.GENERIC_ERROR) {
+        super(code, message, help, exitCode);
+    }
+}
+export class HostedClient {
+    apiBaseUrl;
+    apiKey;
+    fetchImpl;
+    constructor(options) {
+        this.apiBaseUrl = options.apiBaseUrl.replace(/\/+$/, '');
+        this.apiKey = options.apiKey;
+        this.fetchImpl = options.fetchImpl ?? fetch;
+    }
+    async getMe() {
+        return this.request('/v1/me');
+    }
+    async getManifest() {
+        const body = await this.request('/v1/manifest');
+        if (!body.manifest || !Array.isArray(body.manifest.commands)) {
+            throw new HostedClientError('HOSTED_PROTOCOL', 'Webcmd Cloud returned an invalid manifest.');
+        }
+        return body.manifest;
+    }
+    async execute(input) {
+        return this.request('/v1/execute', {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async startBrowserRun(session, input) {
+        return this.request(`/v1/browser/${encodeURIComponent(session)}/runs`, {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async browserAction(session, executionId, input) {
+        return this.request(`/v1/browser/${encodeURIComponent(session)}/runs/${encodeURIComponent(executionId)}/actions`, {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async finishBrowserRun(session, executionId, input) {
+        return this.request(`/v1/browser/${encodeURIComponent(session)}/runs/${encodeURIComponent(executionId)}/finish`, {
+            method: 'POST',
+            body: JSON.stringify(input),
+        });
+    }
+    async runBrowserAction(session, input) {
+        const { command, trace, windowMode, action, profile, args } = input;
+        const run = await this.startBrowserRun(session, {
+            command,
+            args,
+            ...(profile !== undefined ? { profile } : {}),
+            ...(windowMode !== undefined ? { windowMode } : {}),
+            ...(trace !== undefined ? { trace } : {}),
+        });
+        try {
+            const actionResponse = await this.browserAction(session, run.run.executionId, {
+                action,
+                args,
+                ...(profile !== undefined ? { profile } : {}),
+            });
+            const finished = await this.finishBrowserRun(session, run.run.executionId, {
+                status: 'succeeded',
+                ...(profile !== undefined ? { profile } : {}),
+            });
+            return {
+                ...actionResponse,
+                run: run.run,
+                execution: finished.execution,
+            };
+        }
+        catch (error) {
+            await this.finishBrowserRun(session, run.run.executionId, {
+                status: 'failed',
+                errorCode: error instanceof HostedClientError ? error.code : 'HOSTED_BROWSER_ACTION_FAILED',
+                ...(profile !== undefined ? { profile } : {}),
+            }).catch(() => undefined);
+            throw error;
+        }
+    }
+    async request(path, init = {}) {
+        const response = await this.fetchImpl(`${this.apiBaseUrl}${path}`, {
+            ...init,
+            headers: {
+                accept: 'application/json',
+                ...(init.body ? { 'content-type': 'application/json' } : {}),
+                authorization: `Bearer ${this.apiKey}`,
+                ...(init.headers ?? {}),
+            },
+        });
+        const text = await response.text();
+        const body = text ? parseJson(text) : {};
+        if (!response.ok || isHostedError(body)) {
+            const error = isHostedError(body)
+                ? body.error
+                : { code: `HTTP_${response.status}`, message: `Webcmd Cloud request failed with HTTP ${response.status}.` };
+            throw new HostedClientError(error.code || `HTTP_${response.status}`, error.message || `Webcmd Cloud request failed with HTTP ${response.status}.`, error.help ?? error.hint, normalizeExitCode(error.exitCode, response.status === 401 ? EXIT_CODES.NOPERM : EXIT_CODES.GENERIC_ERROR));
+        }
+        return body;
+    }
+}
+function normalizeExitCode(value, fallback) {
+    const allowed = new Set(Object.values(EXIT_CODES));
+    return value !== undefined && allowed.has(value) ? value : fallback;
+}
+function parseJson(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new HostedClientError('HOSTED_PROTOCOL', 'Webcmd Cloud returned non-JSON response.');
+    }
+}
+function isHostedError(value) {
+    return !!value
+        && typeof value === 'object'
+        && value.ok === false
+        && typeof value.error === 'object';
+}

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

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

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

@@ -0,0 +1,119 @@
+import { describe, expect, it } from 'vitest';
+import { HostedClient } from './client.js';
+describe('HostedClient', () => {
+    it('sends bearer auth and parses hosted manifest', async () => {
+        const requests = [];
+        const client = new HostedClient({
+            apiBaseUrl: 'https://api.example.com/',
+            apiKey: 'wcmd_live_test',
+            fetchImpl: async (url, init) => {
+                requests.push({
+                    url: String(url),
+                    authorization: new Headers(init?.headers).get('authorization'),
+                });
+                return new Response(JSON.stringify({
+                    ok: true,
+                    manifest: { userId: 'user_demo', generatedAt: 'now', commands: [] },
+                }), { status: 200 });
+            },
+        });
+        await expect(client.getManifest()).resolves.toEqual({
+            userId: 'user_demo',
+            generatedAt: 'now',
+            commands: [],
+        });
+        expect(requests).toEqual([{ url: 'https://api.example.com/v1/manifest', authorization: 'Bearer wcmd_live_test' }]);
+    });
+    it('maps hosted error envelopes to CliError-compatible errors', async () => {
+        const client = new HostedClient({
+            apiBaseUrl: 'https://api.example.com',
+            apiKey: 'bad',
+            fetchImpl: async () => new Response(JSON.stringify({
+                ok: false,
+                error: {
+                    code: 'UNAUTHORIZED',
+                    message: 'Invalid key',
+                    help: 'Run setup',
+                    exitCode: 77,
+                },
+            }), { status: 401 }),
+        });
+        await expect(client.getManifest()).rejects.toMatchObject({
+            code: 'UNAUTHORIZED',
+            message: 'Invalid key',
+            hint: 'Run setup',
+            exitCode: 77,
+        });
+    });
+    it('runs hosted browser lifecycle calls and finishes the execution', async () => {
+        const requests = [];
+        const client = new HostedClient({
+            apiBaseUrl: 'https://api.example.com',
+            apiKey: 'wcmd_live_test',
+            fetchImpl: async (url, init) => {
+                requests.push({
+                    url: String(url),
+                    body: init?.body ? JSON.parse(String(init.body)) : undefined,
+                });
+                if (String(url).endsWith('/runs')) {
+                    return new Response(JSON.stringify({
+                        ok: true,
+                        run: {
+                            executionId: 'exec_1',
+                            session: 'work',
+                            profile: { id: 'profile_default', displayName: 'default' },
+                        },
+                    }), { status: 201 });
+                }
+                if (String(url).endsWith('/actions')) {
+                    return new Response(JSON.stringify({
+                        ok: true,
+                        result: { url: 'https://example.com' },
+                        columns: ['url'],
+                        trace: null,
+                    }), { status: 200 });
+                }
+                return new Response(JSON.stringify({
+                    ok: true,
+                    execution: { id: 'exec_1', status: 'succeeded' },
+                }), { status: 200 });
+            },
+        });
+        await expect(client.runBrowserAction('work', {
+            command: 'browser/open',
+            action: 'navigate',
+            args: { url: 'https://example.com' },
+            profile: 'default',
+            windowMode: 'background',
+        })).resolves.toMatchObject({
+            result: { url: 'https://example.com' },
+            execution: { id: 'exec_1', status: 'succeeded' },
+        });
+        expect(requests).toEqual([
+            {
+                url: 'https://api.example.com/v1/browser/work/runs',
+                body: {
+                    command: 'browser/open',
+                    args: { url: 'https://example.com' },
+                    profile: 'default',
+                    windowMode: 'background',
+                },
+            },
+            {
+                url: 'https://api.example.com/v1/browser/work/runs/exec_1/actions',
+                body: {
+                    action: 'navigate',
+                    args: { url: 'https://example.com' },
+                    profile: 'default',
+                },
+            },
+            {
+                url: 'https://api.example.com/v1/browser/work/runs/exec_1/finish',
+                body: {
+                    status: 'succeeded',
+                    profile: 'default',
+                },
+            },
+        ]);
+    });
+});

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

@@ -0,0 +1,50 @@
+import * as fs from 'node:fs';
+export interface HostedManifestCache {
+    fetchedAt: string;
+    manifest: unknown;
+}
+export type WebcmdConfig = {
+    mode: 'local';
+    updatedAt: string;
+} | {
+    mode: 'hosted';
+    updatedAt: string;
+    hosted: {
+        apiBaseUrl: string;
+        apiKey: string;
+        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;
+    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,90 @@
+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') {
+        return {
+            mode: 'hosted',
+            updatedAt: parsed.updatedAt,
+            hosted: {
+                apiBaseUrl: parsed.hosted.apiBaseUrl,
+                apiKey: parsed.hosted.apiKey,
+                ...(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(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),
+            apiKey: input.apiKey.trim(),
+            ...(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));
+}

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

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

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

@@ -0,0 +1,48 @@
+import { mkdtemp, rm } 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';
+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('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/manifest.d.ts

@@ -0,0 +1,9 @@
+import type { HostedCommand, HostedManifest } from './types.js';
+export declare function isLocalOnlyHostedCommand(command: HostedCommand): boolean;
+export declare function hostedCommands(manifest: HostedManifest): HostedCommand[];
+export declare function findHostedCommand(manifest: HostedManifest, site: string, name: string): HostedCommand | null;
+export declare function hostedListRows(manifest: HostedManifest, structured: boolean): Record<string, unknown>[];
+export declare function siteNames(manifest: HostedManifest): string[];
+export declare function commandNamesForSite(manifest: HostedManifest, site: string): string[];
+export declare function renderHostedSiteHelp(manifest: HostedManifest, site: string): string;
+export declare function renderHostedCommandHelp(command: HostedCommand): string;

package/dist/src/hosted/manifest.js

@@ -0,0 +1,92 @@
+import { formatArgSummary } from '../serialization.js';
+export function isLocalOnlyHostedCommand(command) {
+    return command.strategy.toUpperCase() === 'LOCAL';
+}
+export function hostedCommands(manifest) {
+    return manifest.commands
+        .filter((command) => !isLocalOnlyHostedCommand(command))
+        .sort((a, b) => a.command.localeCompare(b.command));
+}
+export function findHostedCommand(manifest, site, name) {
+    return manifest.commands.find((command) => {
+        return command.site === site && (command.name === name || command.aliases?.includes(name));
+    }) ?? null;
+}
+export function hostedListRows(manifest, structured) {
+    return hostedCommands(manifest).map((command) => {
+        const row = {
+            command: command.command,
+            site: command.site,
+            name: command.name,
+            aliases: command.aliases ?? [],
+            description: command.description,
+            access: command.access,
+            strategy: command.strategy.toLowerCase(),
+            browser: command.browser,
+            args: command.args,
+            columns: command.columns ?? [],
+            domain: command.domain ?? null,
+        };
+        if (structured)
+            return row;
+        return {
+            ...row,
+            aliases: command.aliases?.join(', ') ?? '',
+            args: formatArgSummary(command.args.map((arg) => ({
+                name: arg.name,
+                type: arg.type,
+                required: arg.required,
+                valueRequired: arg.valueRequired,
+                positional: arg.positional,
+                help: arg.help,
+                choices: arg.choices?.map(String),
+                default: arg.default,
+            }))),
+        };
+    });
+}
+export function siteNames(manifest) {
+    return [...new Set(hostedCommands(manifest).map((command) => command.site))].sort((a, b) => a.localeCompare(b));
+}
+export function commandNamesForSite(manifest, site) {
+    return hostedCommands(manifest)
+        .filter((command) => command.site === site)
+        .flatMap((command) => [command.name, ...(command.aliases ?? [])])
+        .sort((a, b) => a.localeCompare(b));
+}
+export function renderHostedSiteHelp(manifest, site) {
+    const commands = hostedCommands(manifest).filter((command) => command.site === site);
+    if (commands.length === 0)
+        return `Unknown hosted Webcmd site: ${site}\n`;
+    const lines = [`Usage: webcmd ${site} <command> [options]`, '', 'Commands:'];
+    for (const command of commands) {
+        const tag = `[${command.strategy.toLowerCase()}]`;
+        lines.push(`  ${command.name.padEnd(18)} ${tag} ${command.description}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+export function renderHostedCommandHelp(command) {
+    const lines = [
+        `Usage: webcmd ${command.site} ${command.name} ${formatArgSummary(command.args.map((arg) => ({
+            name: arg.name,
+            type: arg.type,
+            required: arg.required,
+            valueRequired: arg.valueRequired,
+            positional: arg.positional,
+            help: arg.help,
+            choices: arg.choices?.map(String),
+            default: arg.default,
+        })))} [options]`,
+        '',
+        command.description,
+        '',
+        `Access: ${command.access}`,
+        `Strategy: ${command.strategy.toLowerCase()}`,
+        `Browser: ${command.browser ? 'yes' : 'no'}`,
+    ];
+    if (command.domain)
+        lines.push(`Domain: ${command.domain}`);
+    if (command.columns?.length)
+        lines.push(`Output columns: ${command.columns.join(', ')}`);
+    return `${lines.join('\n')}\n`;
+}

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

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

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

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest';
+import { commandNamesForSite, findHostedCommand, hostedListRows, renderHostedCommandHelp, renderHostedSiteHelp, siteNames, } from './manifest.js';
+const manifest = {
+    userId: 'user_demo',
+    generatedAt: '2026-07-08T00:00:00.000Z',
+    commands: [
+        {
+            site: 'github',
+            name: 'whoami',
+            aliases: ['me'],
+            command: 'github/whoami',
+            description: 'Show GitHub identity',
+            access: 'read',
+            strategy: 'COOKIE',
+            browser: true,
+            args: [],
+            columns: ['username'],
+            domain: 'github.com',
+        },
+        {
+            site: 'docker',
+            name: 'ps',
+            command: 'docker/ps',
+            description: 'Local Docker containers',
+            access: 'read',
+            strategy: 'LOCAL',
+            browser: false,
+            args: [],
+        },
+    ],
+};
+describe('hosted manifest helpers', () => {
+    it('filters LOCAL commands from hosted list rows', () => {
+        expect(hostedListRows(manifest, true).map((row) => row.command)).toEqual(['github/whoami']);
+    });
+    it('finds canonical commands and aliases', () => {
+        expect(findHostedCommand(manifest, 'github', 'whoami')?.command).toBe('github/whoami');
+        expect(findHostedCommand(manifest, 'github', 'me')?.command).toBe('github/whoami');
+    });
+    it('renders hosted help and completion names from supported commands', () => {
+        expect(siteNames(manifest)).toEqual(['github']);
+        expect(commandNamesForSite(manifest, 'github')).toEqual(['me', 'whoami']);
+        expect(renderHostedSiteHelp(manifest, 'github')).toContain('whoami');
+        expect(renderHostedCommandHelp(manifest.commands[0])).toContain('Output columns: username');
+    });
+});

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

@@ -0,0 +1,12 @@
+import { type WebcmdConfig } from './config.js';
+export interface HostedRunnerOptions {
+    config?: WebcmdConfig;
+    fetchImpl?: typeof fetch;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+}
+export interface HostedRunResult {
+    handled: boolean;
+    exitCode: number;
+}
+export declare function runHostedCli(argv: string[], opts?: HostedRunnerOptions): Promise<HostedRunResult>;