@scottwalker/claude-connector 0.1.0

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/errors/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,eAAe,EACf,UAAU,EACV,eAAe,GAChB,MAAM,aAAa,CAAC"}

package/dist/executor/cli-executor.d.ts

@@ -0,0 +1,35 @@
+import type { QueryResult, StreamEvent } from '../types/index.js';
+import type { IExecutor, ExecuteOptions } from './interface.js';
+/**
+ * Executor implementation that spawns the Claude Code CLI as a child process.
+ *
+ * ## How it works
+ *
+ * - `execute()` spawns `claude -p <prompt> --output-format json` and collects stdout.
+ * - `stream()` spawns `claude -p <prompt> --output-format stream-json` and parses
+ *   newline-delimited JSON (NDJSON) from stdout in real time.
+ *
+ * ## Error handling
+ *
+ * - Non-zero exit code → {@link CliExecutionError}
+ * - `ENOENT` (binary not found) → {@link CliNotFoundError}
+ * - Timeout → {@link CliTimeoutError}
+ *
+ * ## Lifecycle
+ *
+ * Each call to `execute()` or `stream()` spawns a fresh process.
+ * The executor is stateless — safe to use concurrently from multiple queries.
+ */
+export declare class CliExecutor implements IExecutor {
+    private readonly executable;
+    private readonly timeoutMs;
+    private activeProcess;
+    constructor(executable?: string, timeoutMs?: number);
+    execute(args: readonly string[], options: ExecuteOptions): Promise<QueryResult>;
+    stream(args: readonly string[], options: ExecuteOptions): AsyncIterable<StreamEvent>;
+    abort(): void;
+    private spawnProcess;
+    private spawn;
+    private readStream;
+}
+//# sourceMappingURL=cli-executor.d.ts.map

package/dist/executor/cli-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-executor.d.ts","sourceRoot":"","sources":["../../src/executor/cli-executor.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAQhE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,WAAY,YAAW,SAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,aAAa,CAA6B;gBAEtC,UAAU,GAAE,MAAiB,EAAE,SAAS,GAAE,MAA2B;IAK3E,OAAO,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC;IAc9E,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,aAAa,CAAC,WAAW,CAAC;IAW3F,KAAK,IAAI,IAAI;IASb,OAAO,CAAC,YAAY;IAwBpB,OAAO,CAAC,KAAK;YA2CE,UAAU;CAsC1B"}

package/dist/executor/cli-executor.js

@@ -0,0 +1,223 @@
+import { spawn } from 'node:child_process';
+import { parseJsonResult } from '../parser/json-parser.js';
+import { parseStreamLine } from '../parser/stream-parser.js';
+import { CliExecutionError, CliNotFoundError, CliTimeoutError } from '../errors/errors.js';
+/**
+ * Default timeout for CLI execution (10 minutes).
+ * Long-running agentic tasks can exceed typical HTTP timeouts.
+ */
+const DEFAULT_TIMEOUT_MS = 600_000;
+/**
+ * Executor implementation that spawns the Claude Code CLI as a child process.
+ *
+ * ## How it works
+ *
+ * - `execute()` spawns `claude -p <prompt> --output-format json` and collects stdout.
+ * - `stream()` spawns `claude -p <prompt> --output-format stream-json` and parses
+ *   newline-delimited JSON (NDJSON) from stdout in real time.
+ *
+ * ## Error handling
+ *
+ * - Non-zero exit code → {@link CliExecutionError}
+ * - `ENOENT` (binary not found) → {@link CliNotFoundError}
+ * - Timeout → {@link CliTimeoutError}
+ *
+ * ## Lifecycle
+ *
+ * Each call to `execute()` or `stream()` spawns a fresh process.
+ * The executor is stateless — safe to use concurrently from multiple queries.
+ */
+export class CliExecutor {
+    executable;
+    timeoutMs;
+    activeProcess = null;
+    constructor(executable = 'claude', timeoutMs = DEFAULT_TIMEOUT_MS) {
+        this.executable = executable;
+        this.timeoutMs = timeoutMs;
+    }
+    async execute(args, options) {
+        const { stdout, stderr, exitCode } = await this.spawn(args, options);
+        if (exitCode !== 0) {
+            throw new CliExecutionError(`CLI exited with code ${exitCode}: ${stderr}`, exitCode, stderr);
+        }
+        return parseJsonResult(stdout);
+    }
+    async *stream(args, options) {
+        const child = this.spawnProcess(args, options);
+        this.activeProcess = child;
+        try {
+            yield* this.readStream(child);
+        }
+        finally {
+            this.activeProcess = null;
+        }
+    }
+    abort() {
+        if (this.activeProcess && !this.activeProcess.killed) {
+            this.activeProcess.kill('SIGTERM');
+            this.activeProcess = null;
+        }
+    }
+    // ── Private helpers ───────────────────────────────────────────────
+    spawnProcess(args, options) {
+        try {
+            const child = spawn(this.executable, args, {
+                cwd: options.cwd,
+                env: { ...process.env, ...options.env },
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            if (options.input && child.stdin) {
+                child.stdin.write(options.input);
+                child.stdin.end();
+            }
+            else if (child.stdin) {
+                child.stdin.end();
+            }
+            return child;
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === 'ENOENT') {
+                throw new CliNotFoundError(this.executable);
+            }
+            throw error;
+        }
+    }
+    spawn(args, options) {
+        return new Promise((resolve, reject) => {
+            const child = this.spawnProcess(args, options);
+            this.activeProcess = child;
+            const chunks = [];
+            const errChunks = [];
+            child.stdout.on('data', (chunk) => chunks.push(chunk));
+            child.stderr.on('data', (chunk) => errChunks.push(chunk));
+            const timer = setTimeout(() => {
+                child.kill('SIGTERM');
+                reject(new CliTimeoutError(this.timeoutMs));
+            }, this.timeoutMs);
+            child.on('error', (err) => {
+                clearTimeout(timer);
+                this.activeProcess = null;
+                if (err.code === 'ENOENT') {
+                    reject(new CliNotFoundError(this.executable));
+                }
+                else {
+                    reject(err);
+                }
+            });
+            child.on('close', (exitCode) => {
+                clearTimeout(timer);
+                this.activeProcess = null;
+                resolve({
+                    stdout: Buffer.concat(chunks).toString('utf-8'),
+                    stderr: Buffer.concat(errChunks).toString('utf-8'),
+                    exitCode: exitCode ?? 1,
+                });
+            });
+        });
+    }
+    async *readStream(child) {
+        // Buffer for incomplete lines (NDJSON may arrive in partial chunks)
+        let buffer = '';
+        const iterator = createAsyncIterator(child, (chunk, push) => {
+            buffer += chunk.toString('utf-8');
+            const lines = buffer.split('\n');
+            // Keep the last (possibly incomplete) line in the buffer
+            buffer = lines.pop() ?? '';
+            for (const line of lines) {
+                const trimmed = line.trim();
+                if (!trimmed)
+                    continue;
+                const event = parseStreamLine(trimmed);
+                if (event)
+                    push(event);
+            }
+        }, () => {
+            // Flush remaining buffer on stream end
+            const trimmed = buffer.trim();
+            if (trimmed) {
+                const event = parseStreamLine(trimmed);
+                if (event)
+                    return event;
+            }
+            return null;
+        });
+        for await (const event of iterator) {
+            if (event !== null) {
+                yield event;
+            }
+        }
+    }
+}
+// ── Utility ───────────────────────────────────────────────────────
+function isNodeError(err) {
+    return err instanceof Error && 'code' in err;
+}
+/**
+ * Creates an async iterator from a child process stdout.
+ * Handles backpressure, errors, and process exit.
+ */
+function createAsyncIterator(child, onData, onEnd) {
+    return {
+        [Symbol.asyncIterator]() {
+            const queue = [];
+            let resolve = null;
+            let done = false;
+            let error = null;
+            const push = (item) => {
+                if (resolve) {
+                    const r = resolve;
+                    resolve = null;
+                    r({ value: item, done: false });
+                }
+                else {
+                    queue.push(item);
+                }
+            };
+            child.stdout.on('data', (chunk) => {
+                onData(chunk, push);
+            });
+            child.stderr.on('data', (chunk) => {
+                // Capture stderr but don't fail — CLI may log warnings there
+                const text = chunk.toString('utf-8').trim();
+                if (text) {
+                    push({ type: 'system', subtype: 'stderr', data: { text } });
+                }
+            });
+            const finish = () => {
+                if (done)
+                    return;
+                done = true;
+                const final = onEnd();
+                if (final !== null)
+                    push(final);
+                if (resolve) {
+                    const r = resolve;
+                    resolve = null;
+                    r({ value: undefined, done: true });
+                }
+            };
+            child.on('close', finish);
+            child.on('error', (err) => {
+                error = err;
+                finish();
+            });
+            return {
+                next() {
+                    if (queue.length > 0) {
+                        return Promise.resolve({ value: queue.shift(), done: false });
+                    }
+                    if (done) {
+                        return Promise.resolve({ value: undefined, done: true });
+                    }
+                    if (error) {
+                        return Promise.reject(error);
+                    }
+                    return new Promise((r) => {
+                        resolve = r;
+                    });
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=cli-executor.js.map

package/dist/executor/cli-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-executor.js","sourceRoot":"","sources":["../../src/executor/cli-executor.ts"],"names":[],"mappings":"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"}

package/dist/executor/index.d.ts

@@ -0,0 +1,4 @@
+export type { IExecutor, ExecuteOptions } from './interface.js';
+export { CliExecutor } from './cli-executor.js';
+export { SdkExecutor, type SdkExecutorOptions, type SdkExecutorEvents, type InitStage } from './sdk-executor.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/executor/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/executor/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/executor/index.js

@@ -0,0 +1,3 @@
+export { CliExecutor } from './cli-executor.js';
+export { SdkExecutor } from './sdk-executor.js';
+//# sourceMappingURL=index.js.map

package/dist/executor/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/executor/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAmE,MAAM,mBAAmB,CAAC"}

package/dist/executor/interface.d.ts

@@ -0,0 +1,65 @@
+import type { QueryResult, StreamEvent } from '../types/index.js';
+/**
+ * Abstract execution interface — the core abstraction of claude-connector.
+ *
+ * All interaction with Claude Code goes through an executor. This decouples
+ * the public API ({@link Claude}, {@link Session}) from the underlying
+ * transport mechanism.
+ *
+ * ## Why this abstraction exists
+ *
+ * Today the only executor is {@link CliExecutor} (spawns `claude -p`).
+ * Tomorrow Anthropic may ship a native Node.js SDK, an HTTP API,
+ * or a Unix socket interface. By coding against `IExecutor`, the entire
+ * public surface remains stable — only a new executor implementation is needed.
+ *
+ * ## Contract
+ *
+ * - `execute()` runs a query to completion and returns a structured result.
+ * - `stream()` runs a query and yields incremental events as an async iterator.
+ * - Both methods receive a fully resolved argument list (no option merging here).
+ * - Executors must NOT hold mutable state between calls (stateless per invocation).
+ * - Error conditions must throw {@link ClaudeConnectorError} subclasses.
+ */
+export interface IExecutor {
+    /**
+     * Execute a query and return the complete result.
+     *
+     * @param args  - Resolved CLI arguments (produced by ArgsBuilder).
+     * @param options - Execution-level options (cwd, env, input).
+     * @returns Parsed query result.
+     */
+    execute(args: readonly string[], options: ExecuteOptions): Promise<QueryResult>;
+    /**
+     * Execute a query and stream incremental events.
+     *
+     * The returned async iterable yields events as they arrive.
+     * The final event is always of type `'result'` or `'error'`.
+     *
+     * @param args  - Resolved CLI arguments (produced by ArgsBuilder).
+     * @param options - Execution-level options (cwd, env, input).
+     * @returns Async iterable of stream events.
+     */
+    stream(args: readonly string[], options: ExecuteOptions): AsyncIterable<StreamEvent>;
+    /**
+     * Abort a running execution.
+     * Implementations should kill the underlying process gracefully.
+     */
+    abort?(): void;
+}
+/**
+ * Low-level options passed directly to the executor.
+ * These are resolved from ClientOptions + QueryOptions by the client layer.
+ */
+export interface ExecuteOptions {
+    /** Working directory for the CLI process. */
+    readonly cwd: string;
+    /** Environment variables merged with process.env. */
+    readonly env: Readonly<Record<string, string>>;
+    /**
+     * Data piped to the CLI's stdin.
+     * Equivalent to `echo "data" | claude -p "prompt"`.
+     */
+    readonly input?: string;
+}
+//# sourceMappingURL=interface.d.ts.map

package/dist/executor/interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.d.ts","sourceRoot":"","sources":["../../src/executor/interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,WAAW,SAAS;IACxB;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAEhF;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IAErF;;;OAGG;IACH,KAAK,CAAC,IAAI,IAAI,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAErB,qDAAqD;IACrD,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAE/C;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/dist/executor/interface.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=interface.js.map

package/dist/executor/interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interface.js","sourceRoot":"","sources":["../../src/executor/interface.ts"],"names":[],"mappings":""}

package/dist/executor/sdk-executor.d.ts

@@ -0,0 +1,102 @@
+import { EventEmitter } from 'node:events';
+import type { QueryResult, StreamEvent } from '../types/index.js';
+import type { IExecutor, ExecuteOptions } from './interface.js';
+/**
+ * Initialization stages emitted during SDK warm-up.
+ */
+export type InitStage = 'importing' | 'creating' | 'connecting' | 'ready';
+/**
+ * Events emitted by SdkExecutor.
+ */
+export interface SdkExecutorEvents {
+    /** Emitted as initialization progresses through stages. */
+    'init:stage': [InitStage, string];
+    /** Emitted once the session is fully warmed up. */
+    'init:ready': [];
+    /** Emitted if initialization fails. */
+    'init:error': [Error];
+}
+/**
+ * Executor implementation using the Claude Agent SDK (V2 API).
+ *
+ * ## Why this exists
+ *
+ * The CLI executor (`CliExecutor`) spawns a new `claude` process for every query.
+ * Each spawn has a cold-start cost: loading the CLI, authenticating, initializing
+ * tools and MCP servers. For interactive use this delay is noticeable (5-15s).
+ *
+ * `SdkExecutor` solves this by creating a **persistent SDK session** via
+ * `unstable_v2_createSession()`. The session stays warm — subsequent queries
+ * use `session.send()` + `session.stream()` with near-zero overhead.
+ *
+ * ## Lifecycle
+ *
+ * ```
+ * const executor = new SdkExecutor({ model: 'sonnet' })
+ * await executor.init()          // warm up (emits stage events)
+ * executor.execute(args, opts)   // fast — session already running
+ * executor.execute(args, opts)   // fast
+ * executor.close()               // cleanup
+ * ```
+ *
+ * ## Initialization events
+ *
+ * Subscribe to stage events for UI feedback:
+ * ```
+ * executor.on('init:stage', (stage, message) => {
+ *   console.log(`[${stage}] ${message}`)
+ * })
+ * executor.on('init:ready', () => console.log('Ready!'))
+ * ```
+ */
+export declare class SdkExecutor extends EventEmitter<SdkExecutorEvents> implements IExecutor {
+    private sdkModule;
+    private session;
+    private _ready;
+    private initPromise;
+    private readonly sdkOptions;
+    constructor(options: SdkExecutorOptions);
+    /** Whether the session is initialized and ready for queries. */
+    get ready(): boolean;
+    /**
+     * Initialize the SDK session (warm up).
+     *
+     * This imports the SDK, creates a persistent session, and waits for
+     * the `system/init` message confirming Claude Code is ready.
+     *
+     * Call this once at startup. Subsequent queries will be fast.
+     * Safe to call multiple times — only initializes once.
+     */
+    init(): Promise<void>;
+    execute(args: readonly string[], options: ExecuteOptions): Promise<QueryResult>;
+    stream(args: readonly string[], options: ExecuteOptions): AsyncIterable<StreamEvent>;
+    abort(): void;
+    /**
+     * Close the SDK session and free resources.
+     */
+    close(): void;
+    private doInit;
+    private ensureReady;
+    /**
+     * Map an SDK message to our StreamEvent type.
+     */
+    private mapMessage;
+}
+/**
+ * Options for SdkExecutor.
+ */
+export interface SdkExecutorOptions {
+    /** Model to use. Default: 'sonnet'. */
+    readonly model?: string;
+    /** Path to Claude Code executable (for SDK internal use). */
+    readonly pathToClaudeCodeExecutable?: string;
+    /** Permission mode. */
+    readonly permissionMode?: string;
+    /** Auto-approved tools. */
+    readonly allowedTools?: readonly string[];
+    /** Denied tools. */
+    readonly disallowedTools?: readonly string[];
+    /** Extra environment variables. */
+    readonly env?: Readonly<Record<string, string>>;
+}
+//# sourceMappingURL=sdk-executor.d.ts.map

package/dist/executor/sdk-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sdk-executor.d.ts","sourceRoot":"","sources":["../../src/executor/sdk-executor.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAc,MAAM,mBAAmB,CAAC;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAShE;;GAEG;AACH,MAAM,MAAM,SAAS,GACjB,WAAW,GACX,UAAU,GACV,YAAY,GACZ,OAAO,CAAC;AAEZ;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,2DAA2D;IAC3D,YAAY,EAAE,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IAClC,mDAAmD;IACnD,YAAY,EAAE,EAAE,CAAC;IACjB,uCAAuC;IACvC,YAAY,EAAE,CAAC,KAAK,CAAC,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,WAAY,SAAQ,YAAY,CAAC,iBAAiB,CAAE,YAAW,SAAS;IACnF,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,OAAO,CAA2B;IAC1C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAA8B;IACjD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;gBAEpC,OAAO,EAAE,kBAAkB;IAKvC,gEAAgE;IAChE,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED;;;;;;;;OAQG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQrB,OAAO,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,WAAW,CAAC;IAwC9E,MAAM,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,OAAO,EAAE,cAAc,GAAG,aAAa,CAAC,WAAW,CAAC;IAY3F,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,KAAK,IAAI,IAAI;YAWC,MAAM;YAuDN,WAAW;IAMzB;;OAEG;IACH,OAAO,CAAC,UAAU;CA0CnB;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,uCAAuC;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAExB,6DAA6D;IAC7D,QAAQ,CAAC,0BAA0B,CAAC,EAAE,MAAM,CAAC;IAE7C,uBAAuB;IACvB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAEjC,2BAA2B;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE1C,oBAAoB;IACpB,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAE7C,mCAAmC;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACjD"}