@agentrhq/webcmd 0.2.5 → 0.3.1

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

@@ -0,0 +1,10 @@
+import { type ConfigIo } from './config.js';
+import { type HostedCredentialIo } from './credentials.js';
+export interface SetupIo extends ConfigIo, HostedCredentialIo {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    fetchImpl?: typeof fetch;
+    question?: (prompt: string) => Promise<string>;
+    write?: (message: string) => void | Promise<void>;
+}
+export declare function runHostedSetup(io?: SetupIo): Promise<number>;

package/dist/src/hosted/setup.js

@@ -0,0 +1,79 @@
+import { createInterface } from 'node:readline/promises';
+import { stdin as defaultInput, stdout as defaultOutput } from 'node:process';
+import { writeToStream } from '../stream-write.js';
+import { HostedClient } from './client.js';
+import { defaultHostedApiBaseUrl, makeLocalConfig, saveWebcmdConfig, } from './config.js';
+import { makeStoredHostedConfig, storeHostedApiKey, } from './credentials.js';
+export async function runHostedSetup(io = {}) {
+    const write = io.write
+        ? async (message) => { await io.write(message); }
+        : async (message) => writeToStream(io.output ?? defaultOutput, message);
+    const ownedReadline = io.question ? undefined : createInterface({
+        input: io.input ?? defaultInput,
+        output: io.output ?? defaultOutput,
+    });
+    const ask = io.question ?? ((prompt) => ownedReadline.question(prompt));
+    try {
+        await write('Webcmd setup\n');
+        const mode = await ask('Use hosted Webcmd Cloud or local Webcmd? [hosted/local] ');
+        if (mode.trim().toLowerCase().startsWith('l')) {
+            saveWebcmdConfig(makeLocalConfig(io.now?.() ?? new Date()), io);
+            await write('Webcmd is now configured for local mode.\n');
+            return 0;
+        }
+        const apiBaseUrl = defaultHostedApiBaseUrl(io.env ?? process.env);
+        const apiKey = (await ask('Webcmd API key: ')).trim();
+        if (!apiKey) {
+            await write('A Webcmd API key is required for hosted mode.\n');
+            return 2;
+        }
+        let accountLabel;
+        try {
+            const me = await new HostedClient({
+                apiBaseUrl,
+                apiKey,
+                fetchImpl: io.fetchImpl,
+            }).getMe();
+            accountLabel = hostedAccountLabel(me);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            await write(`Warning: could not verify API key yet: ${message}\n`);
+        }
+        const credential = await storeHostedApiKey(apiKey, io);
+        const config = makeStoredHostedConfig({
+            apiBaseUrl,
+            apiKeyRef: credential.apiKeyRef,
+            credentialBackend: credential.credentialBackend,
+            now: io.now?.() ?? new Date(),
+        });
+        saveWebcmdConfig(config, io);
+        if (accountLabel)
+            await write(`Verified Webcmd Cloud account: ${accountLabel}\n`);
+        if (credential.credentialBackend === 'file-fallback') {
+            await write('Warning: OS credential storage was unavailable; API key stored in a protected Webcmd credentials file.\n');
+        }
+        await write(`Credential backend: ${credentialBackendLabel(credential.credentialBackend)}.\n`);
+        await write('Webcmd is now configured for hosted mode.\n');
+        return 0;
+    }
+    finally {
+        ownedReadline?.close();
+    }
+}
+function hostedAccountLabel(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return undefined;
+    const user = body.user;
+    if (!user || typeof user !== 'object' || Array.isArray(user))
+        return undefined;
+    const record = user;
+    if (typeof record.email === 'string' && record.email.trim())
+        return record.email.trim();
+    if (typeof record.id === 'string' && record.id.trim())
+        return record.id.trim();
+    return undefined;
+}
+function credentialBackendLabel(backend) {
+    return backend === 'os' ? 'OS credential store' : 'protected file fallback';
+}

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

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

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

@@ -0,0 +1,195 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, readFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path, { join } from 'node:path';
+import { Writable } from 'node:stream';
+import { fileURLToPath } from 'node:url';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { getConfigPath } from './config.js';
+import { getHostedCredentialPath } from './credentials.js';
+import { runHostedSetup } from './setup.js';
+let tempDir;
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+afterEach(async () => {
+    if (tempDir)
+        await rm(tempDir, { recursive: true, force: true });
+    tempDir = undefined;
+});
+describe('webcmd setup', () => {
+    it('writes local mode from interactive answer', async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'webcmd-setup-'));
+        const answers = ['local'];
+        const messages = [];
+        const env = { WEBCMD_CONFIG_DIR: tempDir };
+        const code = await runHostedSetup({
+            env,
+            platform: 'linux',
+            now: () => new Date('2026-07-08T00:00:00.000Z'),
+            question: async () => answers.shift() ?? '',
+            write: (message) => { messages.push(message); },
+        });
+        expect(code).toBe(0);
+        expect(JSON.parse(await readFile(getConfigPath({ env }), 'utf8'))).toEqual({
+            mode: 'local',
+            updatedAt: '2026-07-08T00:00:00.000Z',
+        });
+        expect(messages.join('')).toContain('local mode');
+    });
+    it('writes hosted mode and validates with /v1/me', async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'webcmd-setup-'));
+        const answers = ['hosted', 'wcmd_live_test'];
+        const env = {
+            WEBCMD_CONFIG_DIR: tempDir,
+            WEBCMD_CREDENTIAL_BACKEND: 'file',
+        };
+        const requests = [];
+        const prompts = [];
+        const messages = [];
+        const code = await runHostedSetup({
+            env,
+            platform: 'linux',
+            now: () => new Date('2026-07-08T00:00:00.000Z'),
+            question: async (prompt) => {
+                prompts.push(prompt);
+                return answers.shift() ?? '';
+            },
+            fetchImpl: async (url, init) => {
+                requests.push({
+                    url: String(url),
+                    authorization: new Headers(init?.headers).get('authorization'),
+                });
+                return new Response(JSON.stringify({ ok: true, user: { id: 'user_demo' } }), { status: 200 });
+            },
+            write: (message) => { messages.push(message); },
+        });
+        expect(code).toBe(0);
+        expect(prompts).toEqual([
+            'Use hosted Webcmd Cloud or local Webcmd? [hosted/local] ',
+            'Webcmd API key: ',
+        ]);
+        expect(requests).toEqual([{ url: 'https://api.webcmd.dev/v1/me', authorization: 'Bearer wcmd_live_test' }]);
+        expect(JSON.parse(await readFile(getConfigPath({ env }), 'utf8'))).toMatchObject({
+            mode: 'hosted',
+            hosted: {
+                apiBaseUrl: 'https://api.webcmd.dev',
+                apiKeyRef: expect.stringMatching(/^wcmd_cred_/),
+                credentialBackend: 'file-fallback',
+            },
+        });
+        expect(await readFile(getConfigPath({ env }), 'utf8')).not.toContain('wcmd_live_test');
+        expect(await readFile(getHostedCredentialPath({ env }), 'utf8')).toContain('wcmd_live_test');
+        expect(messages.join('')).toContain('Verified Webcmd Cloud account: user_demo');
+        expect(messages.join('')).toContain('Credential backend: protected file fallback.');
+    });
+    it('persists interactive local setup before the real CLI process completes', async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'webcmd-setup-process-'));
+        const child = spawn(process.execPath, ['--import', 'tsx', 'src/main.ts', 'setup'], {
+            cwd: packageRoot,
+            env: { ...process.env, WEBCMD_CONFIG_DIR: tempDir, WEBCMD_NO_UPDATE_CHECK: '1' },
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on('data', chunk => stdout.push(Buffer.from(chunk)));
+        child.stderr.on('data', chunk => stderr.push(Buffer.from(chunk)));
+        child.stdin.end('local\n');
+        const status = await new Promise((resolve, reject) => {
+            child.once('error', reject);
+            child.once('close', resolve);
+        });
+        expect(status).toBe(0);
+        expect(Buffer.concat(stderr).toString('utf8')).toBe('');
+        expect(Buffer.concat(stdout).toString('utf8')).toContain('Webcmd is now configured for local mode.');
+        expect(JSON.parse(await readFile(getConfigPath({ env: { WEBCMD_CONFIG_DIR: tempDir } }), 'utf8')))
+            .toMatchObject({ mode: 'local' });
+    }, 20_000);
+    it('does not resolve until all caller-owned output writes complete', async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'webcmd-setup-slow-output-'));
+        const output = new SetupControlledWritable();
+        let settled = false;
+        const run = runHostedSetup({
+            env: { WEBCMD_CONFIG_DIR: tempDir },
+            output,
+            question: async () => 'local',
+        }).then(code => {
+            settled = true;
+            return code;
+        });
+        await Promise.resolve();
+        expect(settled).toBe(false);
+        expect(output.pendingCount()).toBe(1);
+        output.release();
+        await new Promise(resolve => setImmediate(resolve));
+        expect(settled).toBe(false);
+        expect(output.pendingCount()).toBe(1);
+        output.release();
+        await expect(run).resolves.toBe(0);
+        expect(output.text()).toBe('Webcmd setup\nWebcmd is now configured for local mode.\n');
+    });
+    it('rejects caller-owned stream errors without ending the stream', async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'webcmd-setup-output-error-'));
+        const output = new Writable({
+            write(_chunk, _encoding, callback) {
+                callback(new Error('setup output failed'));
+            },
+        });
+        const end = vi.spyOn(output, 'end');
+        await expect(runHostedSetup({
+            env: { WEBCMD_CONFIG_DIR: tempDir },
+            output,
+            question: async () => 'local',
+        })).rejects.toThrow('setup output failed');
+        expect(end).not.toHaveBeenCalled();
+    });
+    it('rejects within a bound when caller-owned output closes before its callback', async () => {
+        tempDir = await mkdtemp(join(tmpdir(), 'webcmd-setup-output-close-'));
+        const output = new SetupCloseBeforeCallbackWritable();
+        const end = vi.spyOn(output, 'end');
+        await expect(within(runHostedSetup({
+            env: { WEBCMD_CONFIG_DIR: tempDir },
+            output,
+            question: async () => 'local',
+        }))).rejects.toThrow('closed before the write completed');
+        expect(end).not.toHaveBeenCalled();
+    });
+});
+async function within(promise, milliseconds = 500) {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error(`promise did not settle within ${milliseconds}ms`)), milliseconds);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+class SetupCloseBeforeCallbackWritable extends Writable {
+    _write(_chunk, _encoding, _callback) {
+        this.destroy();
+    }
+}
+class SetupControlledWritable extends Writable {
+    chunks = [];
+    releases = [];
+    _write(chunk, _encoding, callback) {
+        this.chunks.push(Buffer.from(chunk));
+        this.releases.push(callback);
+    }
+    pendingCount() {
+        return this.releases.length;
+    }
+    release() {
+        const callback = this.releases.shift();
+        if (!callback)
+            throw new Error('No setup write is pending');
+        callback();
+    }
+    text() {
+        return Buffer.concat(this.chunks).toString('utf8');
+    }
+}

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

@@ -0,0 +1,175 @@
+import type { CommandSurfaceMetadata } from '../command-surface.js';
+import type { Arg } from '../registry.js';
+export type HostedCommandStrategy = 'PUBLIC' | 'COOKIE' | 'INTERCEPT' | 'UI' | 'LOCAL' | string;
+export interface HostedCommandArg extends Arg {
+}
+export interface HostedFileArgument {
+    name: string;
+    direction: 'input' | 'output';
+    pathKind: 'file' | 'directory';
+    multiple: boolean;
+    required: boolean;
+    separator?: ',';
+    contentTypes?: string[];
+    contentType?: string;
+    maxBytes?: number;
+    defaultPath?: string;
+}
+export interface HostedCommand extends CommandSurfaceMetadata {
+    site: string;
+    name: string;
+    aliases?: string[];
+    command: string;
+    description: string;
+    access: 'read' | 'write' | string;
+    strategy: HostedCommandStrategy;
+    browser: boolean;
+    args: HostedCommandArg[];
+    columns: string[];
+    domain?: string | null;
+    defaultFormat?: string | null;
+}
+export interface HostedManifest {
+    userId: string;
+    metadata: {
+        contractSchemaVersion: number;
+        webcmdPackageVersion: string;
+        generatedAt: string;
+    };
+    commands: HostedCommand[];
+}
+export interface HostedPublicProfile {
+    name: string;
+    default: boolean;
+    status: 'available';
+    createdAt: string;
+    lastUsedAt: string;
+}
+export interface HostedProfilesResponse {
+    ok: true;
+    profiles: HostedPublicProfile[];
+}
+export interface HostedExecution {
+    id: string;
+    command: string;
+    status: 'succeeded' | 'failed' | 'timed_out';
+}
+export interface HostedTraceReceipt {
+    receipt: string;
+    executionId: string;
+    artifactsUrl?: string;
+    liveViewUrl?: string;
+    replayUrl?: string;
+}
+export interface HostedExecuteResponse {
+    ok: true;
+    result: unknown;
+    columns?: string[];
+    footerExtra?: string;
+    execution: HostedExecution;
+    trace?: HostedTraceReceipt;
+    artifacts?: HostedArtifactReceipt[];
+}
+export interface HostedPreparedExecution {
+    id: string;
+    command: string;
+    status: 'queued';
+}
+export interface HostedPrepareExecutionResponse {
+    ok: true;
+    execution: HostedPreparedExecution;
+    fileArguments: HostedFileArgument[];
+}
+export interface HostedArtifactReceipt {
+    artifactId: string;
+    argument: string;
+    direction: 'input' | 'output';
+    pathKind: 'file' | 'directory';
+    filename: string;
+    contentType: string;
+    byteSize: number;
+    sha256?: string;
+    relativePath?: string;
+    expiresAt: string;
+}
+export interface HostedArtifactReference {
+    $webcmdArtifact: {
+        id?: string;
+        direction?: 'input' | 'output';
+        filename?: string;
+        contentType?: string;
+    };
+}
+export interface HostedUploadArtifactResponse {
+    ok: true;
+    artifact: HostedArtifactReceipt;
+    reference: HostedArtifactReference;
+}
+export type HostedBrowserActionName = 'analyze' | 'back' | 'check' | 'click' | 'close-window' | 'console' | 'dblclick' | 'dialog-accept' | 'dialog-dismiss' | 'drag' | 'exec' | 'extract' | 'fill' | 'find' | 'focus' | 'frames' | 'get-attributes' | 'get-html' | 'get-text' | 'get-title' | 'get-url' | 'get-value' | 'hover' | 'init' | 'insert-text' | 'navigate' | 'network' | 'press-key' | 'screenshot' | 'scroll' | 'select' | 'set-file-input' | 'snapshot' | 'tabs' | 'type' | 'uncheck' | 'verify' | 'wait';
+export interface HostedBrowserRunRequest {
+    command: string;
+    args: Record<string, unknown>;
+    profile?: string;
+    windowMode?: 'foreground' | 'background';
+    trace?: string;
+}
+export interface HostedBrowserRunResponse {
+    ok: true;
+    run: {
+        executionId: string;
+        session: string;
+        profile: {
+            id: string;
+            displayName: string;
+        };
+        liveViewUrl?: string;
+    };
+}
+export interface HostedBrowserActionRequest {
+    action: HostedBrowserActionName;
+    args: Record<string, unknown>;
+    profile?: string;
+}
+export interface HostedBrowserActionResponse {
+    ok: true;
+    result: unknown;
+    columns: string[];
+    trace: HostedBrowserActionTrace | null;
+}
+export interface HostedBrowserActionTrace {
+    id: string;
+    receipt: string;
+    kind: string;
+    contentType?: string;
+    byteSize?: number;
+    storagePath?: string;
+}
+export interface HostedBrowserFinishRequest {
+    status: 'succeeded' | 'failed' | 'timed_out';
+    errorCode?: string;
+    profile?: string;
+}
+export interface HostedBrowserFinishResponse {
+    ok: true;
+    execution: {
+        id: string;
+        status: 'succeeded' | 'failed' | 'timed_out';
+    };
+}
+export interface HostedBrowserRunActionInput extends HostedBrowserRunRequest, HostedBrowserActionRequest {
+}
+export interface HostedBrowserRunActionResponse extends HostedBrowserActionResponse {
+    run: HostedBrowserRunResponse['run'];
+    execution: HostedBrowserFinishResponse['execution'];
+}
+export interface HostedErrorResponse {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        help?: string;
+        exitCode?: number;
+    };
+    execution?: HostedExecution;
+    trace?: HostedTraceReceipt;
+}

package/dist/src/hosted/types.js

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