@agentrhq/webcmd 0.1.1 → 0.2.0

package/dist/src/engine.test.js

@@ -0,0 +1,312 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { discoverClis, discoverPlugins, ensureUserCliCompatShims, ensureUserAdapters, PLUGINS_DIR } from './discovery.js';
+import { executeCommand } from './execution.js';
+import { getRegistry, cli, Strategy } from './registry.js';
+import { clearAllHooks, onAfterExecute } from './hooks.js';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { pathToFileURL } from 'node:url';
+describe('discoverClis', () => {
+    it('handles non-existent directories gracefully', async () => {
+        // Should not throw for missing directories
+        await expect(discoverClis(path.join(os.tmpdir(), 'nonexistent-webcmd-test-dir'))).resolves.not.toThrow();
+    });
+    it('imports only CLI command modules during filesystem discovery', async () => {
+        const tempRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-discovery-'));
+        const siteDir = path.join(tempRoot, 'temp-site');
+        const helperPath = path.join(siteDir, 'helper.js');
+        const commandPath = path.join(siteDir, 'hello.js');
+        try {
+            await fs.promises.mkdir(siteDir, { recursive: true });
+            await fs.promises.writeFile(helperPath, `
+globalThis.__webcmd_helper_loaded__ = true;
+export const helper = true;
+`);
+            await fs.promises.writeFile(commandPath, `
+import { cli, Strategy } from '${pathToFileURL(path.join(process.cwd(), 'src', 'registry.ts')).href}';
+cli({
+  site: 'temp-site',
+  name: 'hello', access: 'read',
+  description: 'hello command',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  func: async () => [{ ok: true }],
+});
+`);
+            delete globalThis.__webcmd_helper_loaded__;
+            await discoverClis(tempRoot);
+            expect(globalThis.__webcmd_helper_loaded__).toBeUndefined();
+            expect(getRegistry().get('temp-site/hello')).toBeDefined();
+        }
+        finally {
+            delete globalThis.__webcmd_helper_loaded__;
+            await fs.promises.rm(tempRoot, { recursive: true, force: true });
+        }
+    });
+    it('falls back to filesystem discovery when the manifest is invalid', async () => {
+        const tempBuildRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-manifest-fallback-'));
+        const distDir = path.join(tempBuildRoot, 'dist');
+        const siteDir = path.join(distDir, 'fallback-site');
+        const commandPath = path.join(siteDir, 'hello.js');
+        const manifestPath = path.join(tempBuildRoot, 'cli-manifest.json');
+        try {
+            await fs.promises.mkdir(siteDir, { recursive: true });
+            await fs.promises.writeFile(manifestPath, '{ invalid json');
+            await fs.promises.writeFile(commandPath, `
+import { cli, Strategy } from '${pathToFileURL(path.join(process.cwd(), 'src', 'registry.ts')).href}';
+cli({
+  site: 'fallback-site',
+  name: 'hello', access: 'read',
+  description: 'hello command',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  func: async () => [{ ok: true }],
+});
+`);
+            await discoverClis(distDir);
+            expect(getRegistry().get('fallback-site/hello')).toBeDefined();
+        }
+        finally {
+            await fs.promises.rm(tempBuildRoot, { recursive: true, force: true });
+        }
+    });
+    it('loads user CLI modules via package exports symlink', async () => {
+        const tempWebcmdRoot = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-user-clis-'));
+        const userClisDir = path.join(tempWebcmdRoot, 'clis');
+        const siteDir = path.join(userClisDir, 'legacy-site');
+        const commandPath = path.join(siteDir, 'hello.js');
+        try {
+            await ensureUserCliCompatShims(tempWebcmdRoot);
+            await fs.promises.mkdir(siteDir, { recursive: true });
+            await fs.promises.writeFile(commandPath, `
+import { cli, Strategy } from '@agentrhq/webcmd/registry';
+import { CommandExecutionError } from '@agentrhq/webcmd/errors';
+import { htmlToMarkdown } from '@agentrhq/webcmd/utils';
+
+cli({
+  site: 'legacy-site',
+  name: 'hello', access: 'read',
+  description: 'hello command',
+  strategy: Strategy.PUBLIC,
+  browser: false,
+  func: async () => [{ ok: true, errorName: new CommandExecutionError('boom').name, markdown: htmlToMarkdown('<p>hello</p>') }],
+});
+`);
+            await discoverClis(userClisDir);
+            const cmd = getRegistry().get('legacy-site/hello');
+            expect(cmd).toBeDefined();
+            await expect(executeCommand(cmd, {})).resolves.toEqual([{ ok: true, errorName: 'CommandExecutionError', markdown: 'hello' }]);
+        }
+        finally {
+            await fs.promises.rm(tempWebcmdRoot, { recursive: true, force: true });
+        }
+    });
+});
+describe('ensureUserAdapters', () => {
+    it('creates user clis directory without triggering full copy', async () => {
+        const tempDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-ensure-'));
+        const clisDir = path.join(tempDir, 'clis');
+        try {
+            // Patch USER_CLIS_DIR is not easy, so we test the function behavior indirectly:
+            // ensureUserAdapters should not throw and should be very fast (no fetch script)
+            const start = Date.now();
+            await ensureUserAdapters();
+            const elapsed = Date.now() - start;
+            // Should complete quickly (< 1s) since it only creates a directory
+            expect(elapsed).toBeLessThan(1000);
+        }
+        finally {
+            await fs.promises.rm(tempDir, { recursive: true, force: true });
+        }
+    });
+    it('discoverClis handles empty user directory gracefully', async () => {
+        const emptyDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), 'webcmd-empty-'));
+        try {
+            // Should not throw for an empty directory (no adapters to discover)
+            await expect(discoverClis(emptyDir)).resolves.not.toThrow();
+        }
+        finally {
+            await fs.promises.rm(emptyDir, { recursive: true, force: true });
+        }
+    });
+});
+describe('discoverPlugins', () => {
+    const testPluginDir = path.join(PLUGINS_DIR, '__test-plugin__');
+    const yamlPath = path.join(testPluginDir, 'greeting.yaml');
+    const symlinkTargetDir = path.join(os.tmpdir(), '__test-plugin-symlink-target__');
+    const symlinkPluginDir = path.join(PLUGINS_DIR, '__test-plugin-symlink__');
+    const brokenSymlinkDir = path.join(PLUGINS_DIR, '__test-plugin-broken__');
+    const dirSymlinkType = process.platform === 'win32' ? 'junction' : 'dir';
+    afterEach(async () => {
+        try {
+            await fs.promises.rm(testPluginDir, { recursive: true });
+        }
+        catch { }
+        try {
+            await fs.promises.rm(symlinkPluginDir, { recursive: true, force: true });
+        }
+        catch { }
+        try {
+            await fs.promises.rm(symlinkTargetDir, { recursive: true, force: true });
+        }
+        catch { }
+        try {
+            await fs.promises.rm(brokenSymlinkDir, { recursive: true, force: true });
+        }
+        catch { }
+    });
+    it('ignores YAML files in plugin directories (YAML format removed)', async () => {
+        await fs.promises.mkdir(testPluginDir, { recursive: true });
+        await fs.promises.writeFile(yamlPath, `
+site: __test-plugin__
+name: greeting
+description: Test plugin greeting
+strategy: public
+browser: false
+`);
+        await discoverPlugins();
+        const registry = getRegistry();
+        const cmd = registry.get('__test-plugin__/greeting');
+        expect(cmd).toBeUndefined();
+    });
+    it('handles non-existent plugins directory gracefully', async () => {
+        // discoverPlugins should not throw if ~/.webcmd/plugins/ does not exist
+        await expect(discoverPlugins()).resolves.not.toThrow();
+    });
+    it('ignores YAML files in symlinked plugin directories (YAML format removed)', async () => {
+        await fs.promises.mkdir(PLUGINS_DIR, { recursive: true });
+        await fs.promises.mkdir(symlinkTargetDir, { recursive: true });
+        await fs.promises.writeFile(path.join(symlinkTargetDir, 'hello.yaml'), `
+site: __test-plugin-symlink__
+name: hello
+description: Test plugin greeting via symlink
+strategy: public
+browser: false
+`);
+        await fs.promises.symlink(symlinkTargetDir, symlinkPluginDir, dirSymlinkType);
+        await discoverPlugins();
+        const cmd = getRegistry().get('__test-plugin-symlink__/hello');
+        expect(cmd).toBeUndefined();
+    });
+    it('skips broken plugin symlinks without throwing', async () => {
+        await fs.promises.mkdir(PLUGINS_DIR, { recursive: true });
+        await fs.promises.symlink(path.join(os.tmpdir(), '__missing-plugin-target__'), brokenSymlinkDir, dirSymlinkType);
+        await expect(discoverPlugins()).resolves.not.toThrow();
+        expect(getRegistry().get('__test-plugin-broken__/hello')).toBeUndefined();
+    });
+});
+describe('executeCommand', () => {
+    beforeEach(() => {
+        clearAllHooks();
+        vi.unstubAllEnvs();
+    });
+    it('accepts kebab-case option names after Commander camelCases them', async () => {
+        const cmd = cli({
+            site: 'test-engine',
+            name: 'kebab-arg-test', access: 'read',
+            description: 'test command with kebab-case arg',
+            browser: false,
+            strategy: Strategy.PUBLIC,
+            args: [
+                { name: 'note-id', required: true, help: 'Note ID' },
+            ],
+            func: async (kwargs) => [{ noteId: kwargs['note-id'] }],
+        });
+        const result = await executeCommand(cmd, { 'note-id': 'abc123' });
+        expect(result).toEqual([{ noteId: 'abc123' }]);
+    });
+    it('executes a command with func', async () => {
+        const cmd = cli({
+            site: 'test-engine',
+            name: 'func-test', access: 'read',
+            description: 'test command with func',
+            browser: false,
+            strategy: Strategy.PUBLIC,
+            func: async (kwargs) => {
+                return [{ title: kwargs.query ?? 'default' }];
+            },
+        });
+        const result = await executeCommand(cmd, { query: 'hello' });
+        expect(result).toEqual([{ title: 'hello' }]);
+    });
+    it('executes a command with pipeline', async () => {
+        const cmd = cli({
+            site: 'test-engine',
+            name: 'pipe-test', access: 'read',
+            description: 'test command with pipeline',
+            browser: false,
+            strategy: Strategy.PUBLIC,
+            pipeline: [
+                { evaluate: '() => [{ n: 1 }, { n: 2 }, { n: 3 }]' },
+                { limit: '2' },
+            ],
+        });
+        // Pipeline commands require page for evaluate step, so we'll test the error path
+        await expect(executeCommand(cmd, {})).rejects.toThrow();
+    });
+    it('throws for command with no func or pipeline', async () => {
+        const cmd = cli({
+            site: 'test-engine',
+            name: 'empty-test', access: 'read',
+            description: 'empty command',
+            browser: false,
+        });
+        await expect(executeCommand(cmd, {})).rejects.toThrow('has no func or pipeline');
+    });
+    it('passes debug flag to func', async () => {
+        let receivedDebug = false;
+        const cmd = cli({
+            site: 'test-engine',
+            name: 'debug-test', access: 'read',
+            description: 'debug test',
+            browser: false,
+            func: async (_kwargs, debug) => {
+                receivedDebug = debug ?? false;
+                return [];
+            },
+        });
+        await executeCommand(cmd, {}, true);
+        expect(receivedDebug).toBe(true);
+    });
+    it('fires onAfterExecute even when command execution throws', async () => {
+        const seen = [];
+        onAfterExecute((ctx) => {
+            seen.push({ error: ctx.error, finishedAt: ctx.finishedAt });
+        });
+        const cmd = cli({
+            site: 'test-engine',
+            name: 'failing-test', access: 'read',
+            description: 'failing command',
+            browser: false,
+            strategy: Strategy.PUBLIC,
+            func: async () => {
+                throw new Error('boom');
+            },
+        });
+        await expect(executeCommand(cmd, {})).rejects.toThrow('boom');
+        expect(seen).toHaveLength(1);
+        expect(seen[0].error).toBeInstanceOf(Error);
+        expect(seen[0].error.message).toBe('boom');
+        expect(typeof seen[0].finishedAt).toBe('number');
+    });
+    it('uses launcher for registered Electron apps (chatwise)', async () => {
+        // Mock the launcher to return a fake endpoint (avoids real HTTP/process calls)
+        const launcher = await import('./launcher.js');
+        const spy = vi.spyOn(launcher, 'resolveElectronEndpoint')
+            .mockResolvedValue('http://127.0.0.1:9228');
+        const cmd = cli({
+            site: 'chatwise',
+            name: 'status', access: 'read',
+            description: 'chatwise status',
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            func: async () => [{ ok: true }],
+        });
+        // CDPBridge.connect() will fail (no actual CDP server), but the launcher
+        // should have been called with 'chatwise'.
+        await expect(executeCommand(cmd, {})).rejects.toThrow();
+        expect(spy).toHaveBeenCalledWith('chatwise');
+        spy.mockRestore();
+    });
+});

package/dist/src/errors.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Unified error types for webcmd.
+ *
+ * All errors thrown by the framework should extend CliError so that
+ * the top-level handler in commanderAdapter.ts can render consistent,
+ * helpful output with emoji-coded severity and actionable hints.
+ *
+ * ## Exit codes
+ *
+ * webcmd follows Unix conventions (sysexits.h) for process exit codes:
+ *
+ *   0   Success
+ *   1   Generic / unexpected error
+ *   2   Argument / usage error          (ArgumentError)
+ *  66   No input / empty result         (EmptyResultError)
+ *  69   Service unavailable             (BrowserConnectError, adapter load failures)
+ *  75   Temporary failure, retry later  (TimeoutError)   EX_TEMPFAIL
+ *  77   Permission denied / auth needed (AuthRequiredError)
+ *  78   Configuration error             (ConfigError)
+ * 130   Interrupted by Ctrl-C           (set by tui.ts SIGINT handler)
+ */
+import type { ObservationTraceReceipt } from './observation/events.js';
+export declare const EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly GENERIC_ERROR: 1;
+    readonly USAGE_ERROR: 2;
+    readonly EMPTY_RESULT: 66;
+    readonly SERVICE_UNAVAIL: 69;
+    readonly TEMPFAIL: 75;
+    readonly NOPERM: 77;
+    readonly CONFIG_ERROR: 78;
+    readonly INTERRUPTED: 130;
+};
+export type ExitCode = typeof EXIT_CODES[keyof typeof EXIT_CODES];
+export declare class CliError extends Error {
+    /** Machine-readable error code (e.g. 'BROWSER_CONNECT', 'AUTH_REQUIRED') */
+    readonly code: string;
+    /** Human-readable hint on how to fix the problem */
+    readonly hint?: string;
+    /** Unix process exit code — defaults to 1 (generic error) */
+    readonly exitCode: ExitCode;
+    constructor(code: string, message: string, hint?: string, exitCode?: ExitCode);
+}
+export declare function attachTraceReceipt(err: unknown, receipt: ObservationTraceReceipt): void;
+export declare function getTraceReceipt(err: unknown): ObservationTraceReceipt | undefined;
+export type BrowserConnectKind = 'daemon-not-running' | 'runtime-not-ready' | 'extension-not-connected' | 'profile-required' | 'profile-disconnected' | 'command-failed' | 'unknown';
+export declare class BrowserConnectError extends CliError {
+    readonly kind: BrowserConnectKind;
+    constructor(message: string, hint?: string, kind?: BrowserConnectKind);
+}
+export declare class CommandExecutionError extends CliError {
+    constructor(message: string, hint?: string);
+}
+export declare class ConfigError extends CliError {
+    constructor(message: string, hint?: string);
+}
+export declare class AuthRequiredError extends CliError {
+    readonly domain: string;
+    constructor(domain: string, message?: string);
+}
+export declare class TimeoutError extends CliError {
+    constructor(label: string, seconds: number, hint?: string);
+}
+export declare class ArgumentError extends CliError {
+    constructor(message: string, hint?: string);
+}
+export declare class EmptyResultError extends CliError {
+    constructor(command: string, hint?: string);
+}
+export declare function adapterLoadError(message: string, hint?: string): CliError;
+export declare function selectorError(selector: string, hint?: string): CliError;
+export declare class PluginError extends CliError {
+    constructor(message: string, hint?: string);
+}
+/**
+ * Thrown when a JSON endpoint returns HTML instead of JSON — typically a login
+ * wall, rate-limit page, or WAF challenge. Surfaced as a structured error so
+ * callers can show "re-login or wait out the rate limit" guidance instead of
+ * the cryptic `SyntaxError: Unexpected token '<', "<!DOCTYPE "...` that a naive
+ * JSON.parse on an HTML body produces.
+ *
+ * `bodyPreview` is the first 100 chars of the response body (after trimming
+ * leading whitespace) — useful for logs / debugging without dumping the full
+ * page.
+ */
+export declare class LoginWallError extends CliError {
+    readonly status: number;
+    readonly url: string;
+    readonly bodyPreview: string;
+    constructor(message: string, status: number, url: string, bodyPreview: string, hint?: string);
+}
+/** Structured error output — unified contract for all consumers (AI agents, scripts, humans). */
+export interface ErrorEnvelope {
+    ok: false;
+    error: {
+        code: string;
+        message: string;
+        help?: string;
+        exitCode: number;
+        stack?: string;
+        cause?: string;
+    };
+    trace?: {
+        traceId: string;
+        dir: string;
+        summaryPath: string;
+        receiptPath: string;
+        status: ObservationTraceReceipt['status'];
+    };
+}
+/** Extract a human-readable message from an unknown caught value. */
+export declare function getErrorMessage(error: unknown): string;
+/** Build an ErrorEnvelope from any caught value. */
+export declare function toEnvelope(err: unknown): ErrorEnvelope;

package/dist/src/errors.js

@@ -0,0 +1,174 @@
+// ── Exit code table ──────────────────────────────────────────────────────────
+export const EXIT_CODES = {
+    SUCCESS: 0,
+    GENERIC_ERROR: 1,
+    USAGE_ERROR: 2, // Bad arguments / command misuse
+    EMPTY_RESULT: 66, // No data / not found           (EX_NOINPUT)
+    SERVICE_UNAVAIL: 69, // Daemon / browser unavailable  (EX_UNAVAILABLE)
+    TEMPFAIL: 75, // Timeout — try again later     (EX_TEMPFAIL)
+    NOPERM: 77, // Auth required / permission    (EX_NOPERM)
+    CONFIG_ERROR: 78, // Missing / invalid config      (EX_CONFIG)
+    INTERRUPTED: 130, // Ctrl-C / SIGINT
+};
+// ── Base class ───────────────────────────────────────────────────────────────
+export class CliError extends Error {
+    /** Machine-readable error code (e.g. 'BROWSER_CONNECT', 'AUTH_REQUIRED') */
+    code;
+    /** Human-readable hint on how to fix the problem */
+    hint;
+    /** Unix process exit code — defaults to 1 (generic error) */
+    exitCode;
+    constructor(code, message, hint, exitCode = EXIT_CODES.GENERIC_ERROR) {
+        super(message);
+        this.name = new.target.name;
+        this.code = code;
+        this.hint = hint;
+        this.exitCode = exitCode;
+    }
+}
+const TRACE_RECEIPT_SYMBOL = Symbol.for('webcmd.traceReceipt');
+export function attachTraceReceipt(err, receipt) {
+    if (!err || (typeof err !== 'object' && typeof err !== 'function'))
+        return;
+    try {
+        Object.defineProperty(err, TRACE_RECEIPT_SYMBOL, {
+            value: receipt,
+            enumerable: false,
+            configurable: true,
+        });
+    }
+    catch {
+        // Non-extensible thrown objects are rare; trace export should never mask the
+        // original adapter error just because metadata attachment failed.
+    }
+}
+export function getTraceReceipt(err) {
+    if (!err || (typeof err !== 'object' && typeof err !== 'function'))
+        return undefined;
+    return err[TRACE_RECEIPT_SYMBOL];
+}
+export class BrowserConnectError extends CliError {
+    kind;
+    constructor(message, hint, kind = 'unknown') {
+        super('BROWSER_CONNECT', message, hint, EXIT_CODES.SERVICE_UNAVAIL);
+        this.kind = kind;
+    }
+}
+export class CommandExecutionError extends CliError {
+    constructor(message, hint) {
+        super('COMMAND_EXEC', message, hint, EXIT_CODES.GENERIC_ERROR);
+    }
+}
+export class ConfigError extends CliError {
+    constructor(message, hint) {
+        super('CONFIG', message, hint, EXIT_CODES.CONFIG_ERROR);
+    }
+}
+export class AuthRequiredError extends CliError {
+    domain;
+    constructor(domain, message) {
+        super('AUTH_REQUIRED', message ?? `Not logged in to ${domain}`, `Please open Chrome or Chromium and log in to https://${domain}`, EXIT_CODES.NOPERM);
+        this.domain = domain;
+    }
+}
+export class TimeoutError extends CliError {
+    constructor(label, seconds, hint) {
+        super('TIMEOUT', `${label} timed out after ${seconds}s`, hint ?? 'Try again, or increase timeout with --timeout <seconds> (or WEBCMD_BROWSER_COMMAND_TIMEOUT for the global default)', EXIT_CODES.TEMPFAIL);
+    }
+}
+export class ArgumentError extends CliError {
+    constructor(message, hint) {
+        super('ARGUMENT', message, hint, EXIT_CODES.USAGE_ERROR);
+    }
+}
+export class EmptyResultError extends CliError {
+    constructor(command, hint) {
+        super('EMPTY_RESULT', `${command} returned no data`, hint ?? 'The page structure may have changed, or you may need to log in', EXIT_CODES.EMPTY_RESULT);
+    }
+}
+export function adapterLoadError(message, hint) {
+    return new CliError('ADAPTER_LOAD', message, hint, EXIT_CODES.SERVICE_UNAVAIL);
+}
+export function selectorError(selector, hint) {
+    return new CliError('SELECTOR', `Could not find element: ${selector}`, hint ?? 'The page UI may have changed. Please report this issue.', EXIT_CODES.GENERIC_ERROR);
+}
+export class PluginError extends CliError {
+    constructor(message, hint) {
+        super('PLUGIN', message, hint, EXIT_CODES.GENERIC_ERROR);
+    }
+}
+/**
+ * Thrown when a JSON endpoint returns HTML instead of JSON — typically a login
+ * wall, rate-limit page, or WAF challenge. Surfaced as a structured error so
+ * callers can show "re-login or wait out the rate limit" guidance instead of
+ * the cryptic `SyntaxError: Unexpected token '<', "<!DOCTYPE "...` that a naive
+ * JSON.parse on an HTML body produces.
+ *
+ * `bodyPreview` is the first 100 chars of the response body (after trimming
+ * leading whitespace) — useful for logs / debugging without dumping the full
+ * page.
+ */
+export class LoginWallError extends CliError {
+    status;
+    url;
+    bodyPreview;
+    constructor(message, status, url, bodyPreview, hint) {
+        super('LOGIN_WALL', message, hint ?? 'The server returned an HTML page instead of JSON — likely a login wall, rate limit, or WAF challenge. Try re-logging in via your browser, or wait a few minutes before retrying.', EXIT_CODES.NOPERM);
+        this.status = status;
+        this.url = url;
+        this.bodyPreview = bodyPreview;
+    }
+}
+// ── Utilities ───────────────────────────────────────────────────────────────
+/** Extract a human-readable message from an unknown caught value. */
+export function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/** Serialize an error cause chain into a readable string. */
+function serializeCause(cause, depth = 0) {
+    if (depth > 10)
+        return '(cause chain truncated)';
+    if (cause instanceof Error) {
+        const parts = [cause.message];
+        if (cause.cause)
+            parts.push(`  caused by: ${serializeCause(cause.cause, depth + 1)}`);
+        return parts.join('\n');
+    }
+    return String(cause);
+}
+/** Build an ErrorEnvelope from any caught value. */
+export function toEnvelope(err) {
+    const cause = err instanceof Error && err.cause ? serializeCause(err.cause) : undefined;
+    const traceReceipt = getTraceReceipt(err);
+    const trace = traceReceipt ? {
+        traceId: traceReceipt.traceId,
+        dir: traceReceipt.traceDir,
+        summaryPath: traceReceipt.summaryPath,
+        receiptPath: traceReceipt.receiptPath,
+        status: traceReceipt.status,
+    } : undefined;
+    if (err instanceof CliError) {
+        return {
+            ok: false,
+            error: {
+                code: err.code,
+                message: err.message,
+                ...(err.hint ? { help: err.hint } : {}),
+                exitCode: err.exitCode,
+                ...(cause ? { cause } : {}),
+            },
+            ...(trace ? { trace } : {}),
+        };
+    }
+    const msg = getErrorMessage(err);
+    return {
+        ok: false,
+        error: {
+            code: 'UNKNOWN',
+            message: msg,
+            exitCode: EXIT_CODES.GENERIC_ERROR,
+            ...(cause ? { cause } : {}),
+        },
+        ...(trace ? { trace } : {}),
+    };
+}

package/dist/src/errors.test.d.ts

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