@agentrhq/webcmd 0.1.1 → 0.1.2

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 {};

package/dist/src/errors.test.js

@@ -0,0 +1,109 @@
+import { describe, it, expect } from 'vitest';
+import { CliError, BrowserConnectError, adapterLoadError, CommandExecutionError, ConfigError, AuthRequiredError, TimeoutError, ArgumentError, EmptyResultError, selectorError, toEnvelope, } from './errors.js';
+describe('Error type hierarchy', () => {
+    it('all error types extend CliError', () => {
+        const errors = [
+            new BrowserConnectError('test'),
+            adapterLoadError('test'),
+            new CommandExecutionError('test'),
+            new ConfigError('test'),
+            new AuthRequiredError('example.com'),
+            new TimeoutError('test', 30),
+            new ArgumentError('test'),
+            new EmptyResultError('test/cmd'),
+            selectorError('.btn'),
+        ];
+        for (const err of errors) {
+            expect(err).toBeInstanceOf(CliError);
+            expect(err).toBeInstanceOf(Error);
+        }
+    });
+    it('AuthRequiredError has correct code, domain, and auto-generated hint', () => {
+        const err = new AuthRequiredError('bilibili.com');
+        expect(err.code).toBe('AUTH_REQUIRED');
+        expect(err.domain).toBe('bilibili.com');
+        expect(err.message).toBe('Not logged in to bilibili.com');
+        expect(err.hint).toContain('https://bilibili.com');
+    });
+    it('AuthRequiredError accepts custom message', () => {
+        const err = new AuthRequiredError('x.com', 'No ct0 cookie found');
+        expect(err.message).toBe('No ct0 cookie found');
+        expect(err.hint).toContain('https://x.com');
+    });
+    it('TimeoutError has correct code and hint', () => {
+        const err = new TimeoutError('bilibili/hot', 60);
+        expect(err.code).toBe('TIMEOUT');
+        expect(err.message).toBe('bilibili/hot timed out after 60s');
+        expect(err.hint).toContain('timeout');
+    });
+    it('ArgumentError has correct code', () => {
+        const err = new ArgumentError('Argument "limit" must be a valid number');
+        expect(err.code).toBe('ARGUMENT');
+    });
+    it('EmptyResultError has default hint', () => {
+        const err = new EmptyResultError('hackernews/top');
+        expect(err.code).toBe('EMPTY_RESULT');
+        expect(err.message).toBe('hackernews/top returned no data');
+        expect(err.hint).toBeTruthy();
+    });
+    it('selectorError has default hint about page changes', () => {
+        const err = selectorError('.submit-btn');
+        expect(err.code).toBe('SELECTOR');
+        expect(err.message).toContain('.submit-btn');
+        expect(err.hint).toContain('report');
+    });
+    it('BrowserConnectError has correct code', () => {
+        const err = new BrowserConnectError('Cannot connect');
+        expect(err.code).toBe('BROWSER_CONNECT');
+    });
+});
+describe('toEnvelope', () => {
+    it('converts CliError to structured envelope', () => {
+        const err = new AuthRequiredError('bilibili.com');
+        const envelope = toEnvelope(err);
+        expect(envelope).toEqual({
+            ok: false,
+            error: {
+                code: 'AUTH_REQUIRED',
+                message: 'Not logged in to bilibili.com',
+                help: expect.stringContaining('https://bilibili.com'),
+                exitCode: 77,
+            },
+        });
+    });
+    it('converts CliError without hint (omits help field)', () => {
+        const err = new CommandExecutionError('Something broke');
+        const envelope = toEnvelope(err);
+        expect(envelope.error.code).toBe('COMMAND_EXEC');
+        expect(envelope.error).not.toHaveProperty('help');
+    });
+    it('converts unknown Error to UNKNOWN envelope', () => {
+        const envelope = toEnvelope(new Error('random failure'));
+        expect(envelope).toEqual({
+            ok: false,
+            error: {
+                code: 'UNKNOWN',
+                message: 'random failure',
+                exitCode: 1,
+            },
+        });
+    });
+    it('converts non-Error values to UNKNOWN envelope', () => {
+        const envelope = toEnvelope('string error');
+        expect(envelope.error.code).toBe('UNKNOWN');
+        expect(envelope.error.message).toBe('string error');
+    });
+    it('serializes deep cause chains without stack overflow', () => {
+        // Build a 20-level deep cause chain — should truncate at depth 10
+        let deepErr = new Error('root');
+        for (let i = 0; i < 20; i++) {
+            deepErr = new Error(`level-${i}`, { cause: deepErr });
+        }
+        const topErr = new CommandExecutionError('top');
+        topErr.cause = deepErr;
+        const envelope = toEnvelope(topErr);
+        const causeStr = envelope.error.cause ?? '';
+        expect(causeStr).toContain('(cause chain truncated)');
+        expect(causeStr).not.toContain('root'); // root is beyond depth 10
+    });
+});

package/dist/src/execution.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Command execution: validates args, manages browser sessions, runs commands.
+ *
+ * This is the single entry point for executing any CLI command. It handles:
+ * 1. Argument validation and coercion
+ * 2. Browser session lifecycle (if needed)
+ * 3. Domain pre-navigation for cookie strategies
+ * 4. Timeout enforcement
+ * 5. Lazy-loading of TS modules from manifest
+ * 6. Lifecycle hooks (onBeforeExecute / onAfterExecute)
+ */
+import { type CliCommand, type Arg, type CommandArgs } from './registry.js';
+import { type ObservationExportResult } from './observation/index.js';
+export declare function coerceAndValidateArgs(cmdArgs: Arg[], kwargs: CommandArgs): CommandArgs;
+export declare function executeCommand(cmd: CliCommand, rawKwargs: CommandArgs, debug?: boolean, opts?: {
+    prepared?: boolean;
+    profile?: string;
+    trace?: string;
+    keepTab?: string;
+    windowMode?: string;
+    siteSession?: string;
+    onTraceExport?: (trace: ObservationExportResult) => void;
+}): Promise<unknown>;
+export declare function prepareCommandArgs(cmd: CliCommand, rawKwargs: CommandArgs): CommandArgs;