@agentrhq/webcmd 0.1.1 → 0.1.2

package/dist/src/electron-apps.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Electron app registry — maps site names to launch metadata.
+ *
+ * Builtin apps are defined here. User-defined apps are loaded
+ * from ~/.webcmd/apps.yaml (additive only, does not override builtins).
+ */
+export interface ElectronAppEntry {
+    /** CDP debug port (unique per app) */
+    port: number;
+    /** macOS process name for detection via pgrep */
+    processName: string;
+    /** Candidate executable names inside Contents/MacOS/, tried in order */
+    executableNames?: string[];
+    /** macOS bundle ID for path discovery */
+    bundleId?: string;
+    /** Human-readable name for prompts */
+    displayName?: string;
+    /** Additional launch args beyond --remote-debugging-port */
+    extraArgs?: string[];
+}
+export declare const builtinApps: Record<string, ElectronAppEntry>;
+/** Merge builtin + user-defined apps. User entries are additive only. */
+export declare function loadApps(userApps?: Record<string, Omit<ElectronAppEntry, 'displayName'> & {
+    displayName?: string;
+}>): Record<string, ElectronAppEntry>;
+export declare function getElectronApp(site: string): ElectronAppEntry | undefined;
+export declare function isElectronApp(site: string): boolean;
+/** Get all registered apps (builtin + user-defined). */
+export declare function getAllElectronApps(): Record<string, ElectronAppEntry>;
+/** Reset loaded apps (for testing). */
+export declare function _resetRegistry(): void;

package/dist/src/electron-apps.js

@@ -0,0 +1,91 @@
+/**
+ * Electron app registry — maps site names to launch metadata.
+ *
+ * Builtin apps are defined here. User-defined apps are loaded
+ * from ~/.webcmd/apps.yaml (additive only, does not override builtins).
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import yaml from 'js-yaml';
+export const builtinApps = {
+    cursor: { port: 9226, processName: 'Cursor', bundleId: 'com.todesktop.runtime.Cursor', displayName: 'Cursor' },
+    codex: { port: 9238, processName: 'Codex', bundleId: 'com.openai.codex', displayName: 'Codex' },
+    chatwise: { port: 9228, processName: 'ChatWise', bundleId: 'com.chatwise.app', displayName: 'ChatWise' },
+    'discord-app': { port: 9232, processName: 'Discord', bundleId: 'com.discord.app', displayName: 'Discord' },
+    'doubao-app': { port: 9225, processName: 'Doubao', bundleId: 'com.volcengine.doubao', displayName: 'Doubao' },
+    antigravity: {
+        port: 9234,
+        processName: 'Antigravity',
+        executableNames: ['Electron', 'Antigravity'],
+        bundleId: 'dev.antigravity.app',
+        displayName: 'Antigravity',
+    },
+    'chatgpt-app': { port: 9236, processName: 'ChatGPT', bundleId: 'com.openai.chat', displayName: 'ChatGPT' },
+    qoder: {
+        port: 9237,
+        processName: 'Qoder',
+        executableNames: ['Electron'],
+        bundleId: 'com.qoder.ide',
+        displayName: 'Qoder',
+    },
+    'trae-solo': {
+        port: 9235,
+        processName: 'TRAE SOLO',
+        executableNames: ['Electron', 'TRAE SOLO'],
+        bundleId: 'com.trae.solo.app',
+        displayName: 'Trae SOLO',
+    },
+    'trae-cn': {
+        port: 39240,
+        processName: 'Trae CN',
+        executableNames: ['Electron'],
+        bundleId: 'cn.trae.app',
+        displayName: 'Trae CN',
+    },
+};
+/** Merge builtin + user-defined apps. User entries are additive only. */
+export function loadApps(userApps) {
+    const merged = { ...builtinApps };
+    if (userApps) {
+        for (const [name, entry] of Object.entries(userApps)) {
+            if (!(name in merged)) {
+                merged[name] = entry;
+            }
+        }
+    }
+    return merged;
+}
+let _apps = null;
+function ensureLoaded() {
+    if (_apps)
+        return _apps;
+    let userApps;
+    try {
+        const yamlPath = path.join(os.homedir(), '.webcmd', 'apps.yaml');
+        if (fs.existsSync(yamlPath)) {
+            const content = fs.readFileSync(yamlPath, 'utf-8');
+            const parsed = yaml.load(content);
+            userApps = parsed?.apps;
+        }
+    }
+    catch {
+        // Silently ignore malformed user config
+    }
+    _apps = loadApps(userApps);
+    return _apps;
+}
+export function getElectronApp(site) {
+    return ensureLoaded()[site];
+}
+export function isElectronApp(site) {
+    return site in ensureLoaded();
+}
+/** Get all registered apps (builtin + user-defined). */
+export function getAllElectronApps() {
+    return ensureLoaded();
+}
+/** Reset loaded apps (for testing). */
+export function _resetRegistry() {
+    _apps = null;
+}

package/dist/src/electron-apps.test.d.ts

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

package/dist/src/electron-apps.test.js

@@ -0,0 +1,76 @@
+import { describe, it, expect } from 'vitest';
+import { builtinApps, getElectronApp, isElectronApp, loadApps } from './electron-apps.js';
+describe('electron-apps registry', () => {
+    it('returns builtin app entry for cursor', () => {
+        const app = getElectronApp('cursor');
+        expect(app).toBeDefined();
+        expect(app.port).toBe(9226);
+        expect(app.processName).toBe('Cursor');
+    });
+    it('returns builtin app entry for codex', () => {
+        const app = getElectronApp('codex');
+        expect(app).toBeDefined();
+        expect(app.port).toBe(9238);
+    });
+    it('keeps builtin Electron app CDP ports unique and off the browser-bridge port', () => {
+        const ports = Object.values(builtinApps).map((app) => app.port);
+        expect(new Set(ports).size).toBe(ports.length);
+        expect(ports).not.toContain(9222);
+    });
+    it('returns builtin app entry for Trae CN', () => {
+        const app = getElectronApp('trae-cn');
+        expect(app).toBeDefined();
+        expect(app.port).toBe(39240);
+        expect(app.processName).toBe('Trae CN');
+        expect(app.bundleId).toBe('cn.trae.app');
+        expect(app.executableNames).toEqual(['Electron']);
+    });
+    it('returns undefined for non-Electron sites', () => {
+        expect(getElectronApp('bilibili')).toBeUndefined();
+        expect(getElectronApp('hackernews')).toBeUndefined();
+    });
+    it('isElectronApp returns true for registered apps', () => {
+        expect(isElectronApp('cursor')).toBe(true);
+        expect(isElectronApp('codex')).toBe(true);
+        expect(isElectronApp('chatwise')).toBe(true);
+        expect(isElectronApp('qoder')).toBe(true);
+        expect(isElectronApp('trae-solo')).toBe(true);
+        expect(isElectronApp('trae-cn')).toBe(true);
+    });
+    it('registers Qoder on its own CDP port', () => {
+        const app = getElectronApp('qoder');
+        expect(app).toMatchObject({
+            port: 9237,
+            processName: 'Qoder',
+            bundleId: 'com.qoder.ide',
+            displayName: 'Qoder',
+        });
+    });
+    it('registers Trae SOLO with its own CDP port and process metadata', () => {
+        const app = getElectronApp('trae-solo');
+        expect(app).toBeDefined();
+        expect(app.port).toBe(9235);
+        expect(app.processName).toBe('TRAE SOLO');
+        expect(app.bundleId).toBe('com.trae.solo.app');
+    });
+    it('isElectronApp returns false for non-Electron sites', () => {
+        expect(isElectronApp('bilibili')).toBe(false);
+        expect(isElectronApp('notion')).toBe(false);
+        expect(isElectronApp('unknown-app')).toBe(false);
+    });
+    it('loadApps merges user config additively', () => {
+        const apps = loadApps({
+            myapp: { port: 9234, processName: 'MyApp' },
+        });
+        expect(apps.myapp).toBeDefined();
+        expect(apps.myapp.port).toBe(9234);
+        // Builtins still present
+        expect(apps.cursor).toBeDefined();
+    });
+    it('loadApps does not override builtin entries', () => {
+        const apps = loadApps({
+            cursor: { port: 9999, processName: 'FakeCursor' },
+        });
+        expect(apps.cursor.port).toBe(9226); // Builtin wins
+    });
+});

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

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

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;