@agentrhq/webcmd 0.3.0 → 0.3.1

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

@@ -1,9 +1,10 @@
 import { type ConfigIo } from './config.js';
-export interface SetupIo extends ConfigIo {
+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;
+    write?: (message: string) => void | Promise<void>;
 }
 export declare function runHostedSetup(io?: SetupIo): Promise<number>;

package/dist/src/hosted/setup.js

@@ -1,49 +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, makeHostedConfig, makeLocalConfig, saveWebcmdConfig, } from './config.js';
+import { defaultHostedApiBaseUrl, makeLocalConfig, saveWebcmdConfig, } from './config.js';
+import { makeStoredHostedConfig, storeHostedApiKey, } from './credentials.js';
 export async function runHostedSetup(io = {}) {
-    const write = io.write ?? ((message) => (io.output ?? defaultOutput).write(message));
+    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 {
-        write('Webcmd setup\n');
+        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);
-            write('Webcmd is now configured for local mode.\n');
+            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) {
-            write('A Webcmd API key is required for hosted mode.\n');
+            await write('A Webcmd API key is required for hosted mode.\n');
             return 2;
         }
-        const config = makeHostedConfig({
-            apiBaseUrl,
-            apiKey,
-            now: io.now?.() ?? new Date(),
-        });
+        let accountLabel;
         try {
-            await new HostedClient({
-                apiBaseUrl: config.hosted.apiBaseUrl,
-                apiKey: config.hosted.apiKey,
+            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);
-            write(`Warning: could not verify API key yet: ${message}\n`);
+            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);
-        write('Webcmd is now configured for hosted mode.\n');
+        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.js

@@ -1,10 +1,15 @@
+import { spawn } from 'node:child_process';
 import { mkdtemp, readFile, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { afterEach, describe, expect, it } from 'vitest';
+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 });
@@ -18,9 +23,10 @@ describe('webcmd setup', () => {
         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),
+            write: (message) => { messages.push(message); },
         });
         expect(code).toBe(0);
         expect(JSON.parse(await readFile(getConfigPath({ env }), 'utf8'))).toEqual({
@@ -32,11 +38,16 @@ describe('webcmd setup', () => {
     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 };
+        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);
@@ -49,7 +60,7 @@ describe('webcmd setup', () => {
                 });
                 return new Response(JSON.stringify({ ok: true, user: { id: 'user_demo' } }), { status: 200 });
             },
-            write: () => undefined,
+            write: (message) => { messages.push(message); },
         });
         expect(code).toBe(0);
         expect(prompts).toEqual([
@@ -61,8 +72,124 @@ describe('webcmd setup', () => {
             mode: 'hosted',
             hosted: {
                 apiBaseUrl: 'https://api.webcmd.dev',
-                apiKey: 'wcmd_live_test',
+                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

@@ -1,15 +1,21 @@
+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 {
+export interface HostedCommandArg extends Arg {
+}
+export interface HostedFileArgument {
     name: string;
-    type?: string;
-    required?: boolean;
-    valueRequired?: boolean;
-    positional?: boolean;
-    default?: unknown;
-    help?: string;
-    choices?: unknown[];
-}
-export interface HostedCommand {
+    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[];
@@ -19,24 +25,87 @@ export interface HostedCommand {
     strategy: HostedCommandStrategy;
     browser: boolean;
     args: HostedCommandArg[];
-    columns?: string[];
+    columns: string[];
     domain?: string | null;
     defaultFormat?: string | null;
 }
 export interface HostedManifest {
     userId: string;
-    generatedAt: 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;
-    data?: unknown;
-    rows?: unknown;
+    result: unknown;
     columns?: string[];
-    trace?: unknown;
+    footerExtra?: string;
+    execution: HostedExecution;
+    trace?: HostedTraceReceipt;
+    artifacts?: HostedArtifactReceipt[];
 }
-export type HostedBrowserActionName = 'back' | 'click' | 'close-window' | 'console' | 'exec' | 'fill' | 'frames' | 'insert-text' | 'navigate' | 'network' | 'press-key' | 'screenshot' | 'scroll' | 'set-file-input' | 'snapshot' | 'tabs' | 'type' | 'wait';
+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>;
@@ -63,9 +132,17 @@ export interface HostedBrowserActionRequest {
 }
 export interface HostedBrowserActionResponse {
     ok: true;
-    result?: unknown;
-    columns?: string[];
-    trace?: unknown;
+    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';
@@ -88,10 +165,11 @@ export interface HostedBrowserRunActionResponse extends HostedBrowserActionRespo
 export interface HostedErrorResponse {
     ok: false;
     error: {
-        code?: string;
-        message?: string;
+        code: string;
+        message: string;
         help?: string;
-        hint?: string;
         exitCode?: number;
     };
+    execution?: HostedExecution;
+    trace?: HostedTraceReceipt;
 }