@agentrhq/webcmd 0.3.0 → 0.3.1

package/dist/src/main.js

@@ -16,7 +16,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { getCompletionsFromManifest, hasAllManifests, printCompletionScriptFast } from './completion-fast.js';
+import { getCompletionScriptFast, getCompletionsFromManifest, hasAllManifests } from './completion-fast.js';
 import { findPackageRoot, getCliManifestPath } from './package-paths.js';
 import { PKG_VERSION } from './version.js';
 import { EXIT_CODES } from './errors.js';
@@ -42,44 +42,111 @@ if (typeof globalThis.Bun === 'undefined' && !isSupportedNodeVersion(process.ver
 }
 // Fast path: --version (only when it's the top-level intent, not passed to a subcommand)
 // e.g. `webcmd --version` or `webcmd -V`, but NOT `webcmd gh --version`
+let fastPathHandled = false;
 if (argv[0] === '--version' || argv[0] === '-V') {
     process.stdout.write(PKG_VERSION + '\n');
     process.exit(EXIT_CODES.SUCCESS);
 }
 // Fast path: completion <shell> — print shell script without discovery
-if (argv[0] === 'completion' && argv.length >= 2) {
-    if (printCompletionScriptFast(argv[1])) {
+if (!fastPathHandled && argv[0] === 'completion' && argv.length >= 2) {
+    const script = getCompletionScriptFast(argv[1]);
+    if (script !== undefined) {
+        process.stdout.write(script);
         process.exit(EXIT_CODES.SUCCESS);
     }
     // Unknown shell — fall through to full path for proper error handling
 }
 // Hosted setup and hosted dispatch run before local adapter discovery. This is
 // the mode boundary: hosted mode must not read ~/.webcmd/clis or local site
-// memory just to decide what commands exist.
-if (argv[0] === 'setup') {
-    const { runHostedSetup } = await import('./hosted/setup.js');
-    process.exit(await runHostedSetup());
-}
-const { shouldUseHostedMode } = await import('./hosted/config.js');
-if (shouldUseHostedMode()) {
-    const { runHostedCli } = await import('./hosted/runner.js');
-    const result = await runHostedCli(argv);
-    if (result.handled)
-        process.exit(result.exitCode);
+// memory just to decide what commands exist. Awaiting the selected branch and
+// assigning exitCode lets Node flush pending stdout/stderr before shutdown.
+if (!fastPathHandled) {
+    if (argv[0] === 'setup') {
+        const { runHostedSetup } = await import('./hosted/setup.js');
+        process.exitCode = await runHostedSetup();
+    }
+    else {
+        const { shouldUseHostedMode } = await import('./hosted/config.js');
+        if (shouldUseHostedMode()) {
+            const { runHostedCli } = await import('./hosted/runner.js');
+            const result = await runHostedCli(argv);
+            process.exitCode = result.exitCode;
+        }
+        else {
+            await runLocalMain();
+        }
+    }
 }
-// Fast path: --get-completions — read from manifest, skip discovery
-const getCompIdx = process.argv.indexOf('--get-completions');
-if (getCompIdx !== -1) {
-    // Only include manifests that actually exist on disk.
-    // With sparse override, the user clis dir may exist but have no manifest.
-    const manifestPaths = [getCliManifestPath(BUILTIN_CLIS)];
-    const userManifest = getCliManifestPath(USER_CLIS);
-    try {
-        fs.accessSync(userManifest);
-        manifestPaths.push(userManifest);
+async function runLocalMain() {
+    // Fast path: --get-completions — read from manifest, skip discovery
+    const getCompIdx = process.argv.indexOf('--get-completions');
+    if (getCompIdx !== -1) {
+        // Only include manifests that actually exist on disk.
+        // With sparse override, the user clis dir may exist but have no manifest.
+        const manifestPaths = [getCliManifestPath(BUILTIN_CLIS)];
+        const userManifest = getCliManifestPath(USER_CLIS);
+        try {
+            fs.accessSync(userManifest);
+            manifestPaths.push(userManifest);
+        }
+        catch { /* no user manifest */ }
+        if (hasAllManifests(manifestPaths)) {
+            const rest = process.argv.slice(getCompIdx + 1);
+            let cursor;
+            const words = [];
+            for (let i = 0; i < rest.length; i++) {
+                if (rest[i] === '--cursor' && i + 1 < rest.length) {
+                    cursor = parseInt(rest[i + 1], 10);
+                    i++;
+                }
+                else {
+                    words.push(rest[i]);
+                }
+            }
+            if (cursor === undefined)
+                cursor = words.length;
+            const candidates = getCompletionsFromManifest(words, cursor, manifestPaths);
+            process.stdout.write(candidates.join('\n') + '\n');
+            process.exit(EXIT_CODES.SUCCESS);
+        }
+        // No manifest — fall through to full discovery path below
+    }
+    // ── Full startup path ───────────────────────────────────────────────────
+    // Dynamic imports: these are deferred so the fast path above never pays the cost.
+    const { discoverClis, discoverPlugins, ensureUserCliCompatShims, ensureUserAdapters } = await import('./discovery.js');
+    const { getCompletions } = await import('./completion.js');
+    const { runCli } = await import('./cli.js');
+    const { emitHook } = await import('./hooks.js');
+    const { installNodeNetwork } = await import('./node-network.js');
+    const { registerUpdateNoticeOnExit, checkForUpdateBackground } = await import('./update-check.js');
+    installNodeNetwork();
+    // Parallelise independent startup I/O:
+    //  - Built-in adapter discovery has no dependency on user-dir setup.
+    //  - ensureUserCliCompatShims and ensureUserAdapters operate on different paths
+    //    (~/.webcmd/node_modules/ vs ~/.webcmd/clis/ + adapter-manifest.json).
+    //  - registerCommand() overwrites on name collision (see registry.ts), so
+    //    user-CLI discovery MUST run after built-in discovery to preserve the
+    //    intended override order (user adapters override built-in ones).
+    //  - discoverPlugins runs last: plugins may override both built-in and user CLIs.
+    const skipUserDiscovery = argv[0] === 'convention-audit';
+    if (skipUserDiscovery) {
+        await discoverClis(BUILTIN_CLIS);
+    }
+    else {
+        const [, ,] = await Promise.all([
+            ensureUserCliCompatShims(),
+            ensureUserAdapters(),
+            discoverClis(BUILTIN_CLIS),
+        ]);
+        await discoverClis(USER_CLIS);
+        await discoverPlugins();
     }
-    catch { /* no user manifest */ }
-    if (hasAllManifests(manifestPaths)) {
+    // Register exit hook: notice appears after command output (same as npm/gh/yarn)
+    registerUpdateNoticeOnExit();
+    // Kick off background fetch for next run (non-blocking)
+    checkForUpdateBackground();
+    // ── Fallback completion: manifest unavailable, use full registry ─────────
+    if (getCompIdx !== -1) {
         const rest = process.argv.slice(getCompIdx + 1);
         let cursor;
         const words = [];
@@ -94,93 +161,38 @@ if (getCompIdx !== -1) {
         }
         if (cursor === undefined)
             cursor = words.length;
-        const candidates = getCompletionsFromManifest(words, cursor, manifestPaths);
+        const candidates = getCompletions(words, cursor);
         process.stdout.write(candidates.join('\n') + '\n');
         process.exit(EXIT_CODES.SUCCESS);
     }
-    // No manifest — fall through to full discovery path below
-}
-// ── Full startup path ───────────────────────────────────────────────────
-// Dynamic imports: these are deferred so the fast path above never pays the cost.
-const { discoverClis, discoverPlugins, ensureUserCliCompatShims, ensureUserAdapters } = await import('./discovery.js');
-const { getCompletions } = await import('./completion.js');
-const { runCli } = await import('./cli.js');
-const { emitHook } = await import('./hooks.js');
-const { installNodeNetwork } = await import('./node-network.js');
-const { registerUpdateNoticeOnExit, checkForUpdateBackground } = await import('./update-check.js');
-installNodeNetwork();
-// Parallelise independent startup I/O:
-//  - Built-in adapter discovery has no dependency on user-dir setup.
-//  - ensureUserCliCompatShims and ensureUserAdapters operate on different paths
-//    (~/.webcmd/node_modules/ vs ~/.webcmd/clis/ + adapter-manifest.json).
-//  - registerCommand() overwrites on name collision (see registry.ts), so
-//    user-CLI discovery MUST run after built-in discovery to preserve the
-//    intended override order (user adapters override built-in ones).
-//  - discoverPlugins runs last: plugins may override both built-in and user CLIs.
-const skipUserDiscovery = argv[0] === 'convention-audit';
-if (skipUserDiscovery) {
-    await discoverClis(BUILTIN_CLIS);
-}
-else {
-    const [, ,] = await Promise.all([
-        ensureUserCliCompatShims(),
-        ensureUserAdapters(),
-        discoverClis(BUILTIN_CLIS),
-    ]);
-    await discoverClis(USER_CLIS);
-    await discoverPlugins();
-}
-// Register exit hook: notice appears after command output (same as npm/gh/yarn)
-registerUpdateNoticeOnExit();
-// Kick off background fetch for next run (non-blocking)
-checkForUpdateBackground();
-// ── Fallback completion: manifest unavailable, use full registry ─────────
-if (getCompIdx !== -1) {
-    const rest = process.argv.slice(getCompIdx + 1);
-    let cursor;
-    const words = [];
-    for (let i = 0; i < rest.length; i++) {
-        if (rest[i] === '--cursor' && i + 1 < rest.length) {
-            cursor = parseInt(rest[i + 1], 10);
-            i++;
-        }
-        else {
-            words.push(rest[i]);
-        }
-    }
-    if (cursor === undefined)
-        cursor = words.length;
-    const candidates = getCompletions(words, cursor);
-    process.stdout.write(candidates.join('\n') + '\n');
-    process.exit(EXIT_CODES.SUCCESS);
-}
-// Rewrite `webcmd browser <session> <subcommand> ...` so commander (which
-// can't combine a parent positional with subcommand dispatch) sees the internal
-// `--session <name>` flag form. Also refuses the retired `webcmd browser
-// --session foo ...` user form with a friendly usage error.
-const { rewriteBrowserArgv, BrowserSessionArgvError, escapeLeadingDashPositional } = await import('./cli-argv-preprocess.js');
-try {
-    let rewritten = rewriteBrowserArgv(process.argv.slice(2));
-    // Insert a `--` separator before a required positional whose value starts
-    // with `-` (e.g. opaque securityId tokens; #1160). Skipped when the
-    // manifest is unavailable so the user-cli / dev paths still work.
+    // Rewrite `webcmd browser <session> <subcommand> ...` so commander (which
+    // can't combine a parent positional with subcommand dispatch) sees the internal
+    // `--session <name>` flag form. Also refuses the retired `webcmd browser
+    // --session foo ...` user form with a friendly usage error.
+    const { rewriteBrowserArgv, BrowserSessionArgvError, escapeLeadingDashPositional } = await import('./cli-argv-preprocess.js');
     try {
-        const manifestPath = getCliManifestPath(BUILTIN_CLIS);
-        if (fs.existsSync(manifestPath)) {
-            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
-            if (Array.isArray(manifest))
-                rewritten = escapeLeadingDashPositional(rewritten, manifest);
+        let rewritten = rewriteBrowserArgv(process.argv.slice(2));
+        // Insert a `--` separator before a required positional whose value starts
+        // with `-` (e.g. opaque securityId tokens; #1160). Skipped when the
+        // manifest is unavailable so the user-cli / dev paths still work.
+        try {
+            const manifestPath = getCliManifestPath(BUILTIN_CLIS);
+            if (fs.existsSync(manifestPath)) {
+                const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+                if (Array.isArray(manifest))
+                    rewritten = escapeLeadingDashPositional(rewritten, manifest);
+            }
         }
+        catch { /* manifest unavailable; skip the dash escape */ }
+        process.argv.splice(2, process.argv.length - 2, ...rewritten);
     }
-    catch { /* manifest unavailable; skip the dash escape */ }
-    process.argv.splice(2, process.argv.length - 2, ...rewritten);
-}
-catch (err) {
-    if (err instanceof BrowserSessionArgvError) {
-        process.stderr.write(`error: ${err.message}\n`);
-        process.exit(EXIT_CODES.GENERIC_ERROR);
+    catch (err) {
+        if (err instanceof BrowserSessionArgvError) {
+            process.stderr.write(`error: ${err.message}\n`);
+            process.exit(EXIT_CODES.GENERIC_ERROR);
+        }
+        throw err;
     }
-    throw err;
+    await emitHook('onStartup', { command: '__startup__', args: {} });
+    runCli(BUILTIN_CLIS, USER_CLIS);
 }
-await emitHook('onStartup', { command: '__startup__', args: {} });
-runCli(BUILTIN_CLIS, USER_CLIS);

package/dist/src/manifest-types.d.ts

@@ -6,6 +6,7 @@
  * runtime code needs from build-manifest is the `ManifestEntry` type,
  * and that lives here.
  */
+import type { FileArgumentContract } from './hosted/contract.js';
 export interface ManifestEntry {
     site: string;
     name: string;
@@ -25,6 +26,7 @@ export interface ManifestEntry {
         positional?: boolean;
         help?: string;
         choices?: string[];
+        file?: FileArgumentContract;
     }>;
     columns?: string[];
     pipeline?: Record<string, unknown>[];

package/dist/src/output.d.ts

@@ -1,14 +1,29 @@
 /**
  * Output formatting: table, JSON, Markdown, CSV, YAML.
  */
+import type { ErrorEnvelope } from './errors.js';
 export interface RenderOptions {
     fmt?: string;
-    /** True when the user explicitly passed -f on the command line */
+    /** True when the user explicitly passed -f on the command line. */
     fmtExplicit?: boolean;
+    /** TTY state used by the pure formatter. `render` derives this from stdout. */
+    isTTY?: boolean;
     columns?: string[];
     title?: string;
     elapsed?: number;
     source?: string;
     footerExtra?: string;
 }
-export declare function render(data: unknown, opts?: RenderOptions): void;
+export interface ErrorRenderOptions {
+    cmdName?: string;
+    traceMode?: unknown;
+}
+export interface StreamRenderOptions extends RenderOptions {
+    stdout?: NodeJS.WritableStream;
+}
+/** Format output without writing to process-global streams. */
+export declare function formatOutput(data: unknown, opts?: RenderOptions): string;
+/** Render to an injected stream, with the legacy console path retained for local callers. */
+export declare function render(data: unknown, opts?: StreamRenderOptions): Promise<void>;
+/** Serialize the local error envelope without writing to process-global stderr. */
+export declare function formatErrorEnvelope(envelope: ErrorEnvelope, opts?: ErrorRenderOptions): string;

package/dist/src/output.js

@@ -3,6 +3,7 @@
  */
 import Table from 'cli-table3';
 import yaml from 'js-yaml';
+import { writeToStream } from './stream-write.js';
 function normalizeRows(data) {
     if (Array.isArray(data))
         return data;
@@ -13,140 +14,146 @@ function normalizeRows(data) {
 function resolveColumns(rows, opts) {
     return opts.columns ?? Object.keys(rows[0] ?? {});
 }
-export function render(data, opts = {}) {
+/** Format output without writing to process-global streams. */
+export function formatOutput(data, opts = {}) {
     let fmt = opts.fmt ?? 'table';
-    // Non-TTY auto-downgrade only when format was NOT explicitly passed by user.
-    if (!opts.fmtExplicit) {
-        if (fmt === 'table' && !process.stdout.isTTY)
-            fmt = 'yaml';
-    }
-    if (data === null || data === undefined) {
-        console.log(data);
-        return;
-    }
+    if (!opts.fmtExplicit && fmt === 'table' && !opts.isTTY)
+        fmt = 'yaml';
+    if (data === null || data === undefined)
+        return `${String(data)}\n`;
     switch (fmt) {
-        case 'json':
-            renderJson(data);
-            break;
-        case 'plain':
-            renderPlain(data, opts);
-            break;
+        case 'json': return `${JSON.stringify(data, null, 2)}\n`;
+        case 'plain': return formatPlain(data);
         case 'md':
-        case 'markdown':
-            renderMarkdown(data, opts);
-            break;
-        case 'csv':
-            renderCsv(data, opts);
-            break;
+        case 'markdown': return formatMarkdown(data, opts);
+        case 'csv': return formatCsv(data, opts);
         case 'yaml':
-        case 'yml':
-            renderYaml(data);
-            break;
-        default:
-            renderTable(data, opts);
-            break;
+        case 'yml': return `${yaml.dump(data, { sortKeys: false, lineWidth: 120, noRefs: true })}\n`;
+        default: return formatTable(data, opts);
     }
 }
-function renderTable(data, opts) {
-    const rows = normalizeRows(data);
-    if (!rows.length) {
-        console.log('(no data)');
+/** Render to an injected stream, with the legacy console path retained for local callers. */
+export async function render(data, opts = {}) {
+    const { stdout, ...formatOptions } = opts;
+    const targetIsTTY = formatOptions.isTTY
+        ?? (stdout ? stdout.isTTY === true : process.stdout.isTTY === true);
+    const output = formatOutput(data, { ...formatOptions, isTTY: targetIsTTY });
+    if (!output)
+        return;
+    if (stdout) {
+        await writeToStream(stdout, output);
         return;
     }
+    // Existing local command tests and embedders intercept console.log. Passing
+    // one string preserves the exact bytes console.log historically emitted.
+    console.log(output.endsWith('\n') ? output.slice(0, -1) : output);
+}
+/** Serialize the local error envelope without writing to process-global stderr. */
+export function formatErrorEnvelope(envelope, opts = {}) {
+    let output = yaml.dump(envelope, { sortKeys: false, lineWidth: 120, noRefs: true });
+    const code = envelope.error.code;
+    if (opts.cmdName
+        && opts.traceMode !== 'on'
+        && opts.traceMode !== 'retain-on-failure'
+        && (code === 'SELECTOR' || code === 'EMPTY_RESULT' || code === 'ADAPTER_LOAD' || code === 'UNKNOWN')) {
+        const runnable = opts.cmdName.replace('/', ' ');
+        output += '# AutoFix: re-run with --trace=retain-on-failure for trace artifact\n';
+        output += `# webcmd ${runnable} --trace retain-on-failure\n`;
+    }
+    return output;
+}
+function formatTable(data, opts) {
+    const rows = normalizeRows(data);
+    if (!rows.length)
+        return '(no data)\n';
     const columns = resolveColumns(rows, opts);
-    const header = columns.map(c => capitalize(c));
     const table = new Table({
-        head: header.map(h => h),
+        head: columns.map(capitalize),
         style: { head: [], border: [] },
         wordWrap: true,
         wrapOnWordBoundary: true,
     });
     for (const row of rows) {
-        table.push(columns.map(c => {
-            const v = row[c];
-            return v === null || v === undefined ? '' : String(v);
+        table.push(columns.map((column) => {
+            const value = row[column];
+            return value === null || value === undefined ? '' : String(value);
         }));
     }
-    console.log();
+    const output = [''];
     if (opts.title)
-        console.log(`  ${opts.title}`);
-    console.log(table.toString());
-    const footer = [];
-    footer.push(`${rows.length} items`);
+        output.push(`  ${opts.title}`);
+    output.push(table.toString());
+    const footer = [`${rows.length} items`];
     if (opts.elapsed !== undefined)
         footer.push(`${opts.elapsed.toFixed(1)}s`);
     if (opts.source)
         footer.push(opts.source);
     if (opts.footerExtra)
         footer.push(opts.footerExtra);
-    console.log(footer.join(' | '));
+    output.push(footer.join(' | '));
+    return `${output.join('\n')}\n`;
 }
-function renderJson(data) {
-    console.log(JSON.stringify(data, null, 2));
-}
-function renderPlain(data, opts) {
+function formatPlain(data) {
     const rows = normalizeRows(data);
     if (!rows.length)
-        return;
-    // Single-row single-field shortcuts for chat-style commands.
+        return '';
     if (rows.length === 1) {
-        const row = rows[0];
-        const entries = Object.entries(row);
+        const entries = Object.entries(rows[0]);
         if (entries.length === 1) {
             const [key, value] = entries[0];
             if (key === 'response' || key === 'content' || key === 'markdown' || key === 'text' || key === 'value') {
-                console.log(String(value ?? ''));
-                return;
+                return `${String(value ?? '')}\n`;
             }
         }
     }
+    const output = [];
     rows.forEach((row, index) => {
-        const entries = Object.entries(row).filter(([, value]) => value !== undefined && value !== null && String(value) !== '');
-        entries.forEach(([key, value]) => {
-            console.log(`${key}: ${value}`);
-        });
+        for (const [key, value] of Object.entries(row)) {
+            if (value === undefined || value === null || String(value) === '')
+                continue;
+            output.push(`${key}: ${value}`);
+        }
         if (index < rows.length - 1)
-            console.log('');
+            output.push('');
     });
+    return output.length > 0 ? `${output.join('\n')}\n` : '';
 }
-function renderMarkdown(data, opts) {
+function formatMarkdown(data, opts) {
     const rows = normalizeRows(data);
     if (!rows.length)
-        return;
+        return '';
     if (rows.length === 1) {
         const entries = Object.entries(rows[0]);
         if (entries.length === 1) {
             const [key, value] = entries[0];
             if (key === 'content' || key === 'markdown' || key === 'text' || key === 'value') {
-                console.log(String(value ?? ''));
-                return;
+                return `${String(value ?? '')}\n`;
             }
         }
     }
     const columns = resolveColumns(rows, opts);
-    console.log('| ' + columns.join(' | ') + ' |');
-    console.log('| ' + columns.map(() => '---').join(' | ') + ' |');
-    for (const row of rows) {
-        console.log('| ' + columns.map(c => String(row[c] ?? '')).join(' | ') + ' |');
-    }
+    const output = [
+        `| ${columns.join(' | ')} |`,
+        `| ${columns.map(() => '---').join(' | ')} |`,
+        ...rows.map(row => `| ${columns.map(column => String(row[column] ?? '')).join(' | ')} |`),
+    ];
+    return `${output.join('\n')}\n`;
 }
-function renderCsv(data, opts) {
+function formatCsv(data, opts) {
     const rows = normalizeRows(data);
     if (!rows.length)
-        return;
+        return '';
     const columns = resolveColumns(rows, opts);
-    console.log(columns.join(','));
-    for (const row of rows) {
-        console.log(columns.map(c => {
-            const v = String(row[c] ?? '');
-            return v.includes(',') || v.includes('"') || v.includes('\n') || v.includes('\r')
-                ? `"${v.replace(/"/g, '""')}"` : v;
-        }).join(','));
-    }
+    const output = [
+        columns.join(','),
+        ...rows.map(row => columns.map(column => csvCell(row[column])).join(',')),
+    ];
+    return `${output.join('\n')}\n`;
 }
-function renderYaml(data) {
-    console.log(yaml.dump(data, { sortKeys: false, lineWidth: 120, noRefs: true }));
+function csvCell(value) {
+    const text = String(value ?? '');
+    return /[,"\r\n]/.test(text) ? `"${text.replace(/"/g, '""')}"` : text;
 }
-function capitalize(s) {
-    return s.charAt(0).toUpperCase() + s.slice(1);
+function capitalize(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
 }