craftdriver 0.0.3 → 0.2.0

package/dist/cli/mcp/artifacts.d.ts

@@ -0,0 +1,43 @@
+export interface ArtifactWriteResult {
+    path: string;
+    bytes: number;
+}
+export declare class ArtifactStore {
+    private dir;
+    private ready;
+    private counter;
+    constructor(rootOverride?: string);
+    /** Absolute path to the artifact directory (may not exist yet). */
+    get directory(): string;
+    private ensure;
+    /**
+     * Write a payload to a numbered file. `nameHint` is used to build a
+     * human-readable filename (`0001-<hint>`); pass something like
+     * `screenshot.png` or `eval.json`.
+     */
+    write(nameHint: string, data: Buffer | string): Promise<ArtifactWriteResult>;
+    /**
+     * Allocate a path for an artifact the caller will write itself (e.g.
+     * pass to `browser.screenshot({ path })`). Doesn't touch the disk
+     * beyond `mkdir -p` of the directory.
+     */
+    allocate(nameHint: string): Promise<string>;
+}
+/**
+ * Spill threshold in bytes. Content blocks longer than this are
+ * written to an artifact and replaced inline with a short preview.
+ *
+ * Default 2 KB ≈ 500 tokens — enough room for a typical short
+ * snapshot diff or a small JSON result, but well below the cost of a
+ * full 80-node snapshot or a verbose eval payload.
+ */
+export declare const DEFAULT_SPILL_BYTES = 2048;
+export declare function resolveSpillBytes(): number;
+/**
+ * Build the short inline replacement shown in place of a spilled
+ * payload. Keeps the first ~5 lines (or 240 chars, whichever is
+ * shorter) so the agent still sees the head of the data without
+ * having to read the file for a quick glance.
+ */
+export declare function spillPreview(text: string, written: ArtifactWriteResult): string;
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/cli/mcp/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/artifacts.ts"],"names":[],"mappings":"AA8BA,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,KAAK,CAA8B;IAC3C,OAAO,CAAC,OAAO,CAAK;gBAER,YAAY,CAAC,EAAE,MAAM;IAQjC,mEAAmE;IACnE,IAAI,SAAS,IAAI,MAAM,CAEtB;YAEa,MAAM;IAOpB;;;;OAIG;IACG,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAUlF;;;;OAIG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAMlD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,wBAAgB,iBAAiB,IAAI,MAAM,CAK1C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,MAAM,CAI/E"}

package/dist/cli/mcp/artifacts.js

@@ -0,0 +1,104 @@
+/**
+ * Per-session artifact store for the MCP server.
+ *
+ * Why this exists: MCP content blocks count against the model's
+ * context window. A 100 KB screenshot or a 4 KB full a11y snapshot
+ * costs the agent real tokens on every turn. We'd rather spill the
+ * payload to disk and hand back a short preview + absolute path.
+ * Hosts that can read files (Claude Code, Cursor, Windsurf, Zed,
+ * Goose, Gemini CLI, …) just open it; hosts that can't can still
+ * fetch via MCP resources once we expose them.
+ *
+ * Directory layout:
+ *   <root>/craftdriver-mcp-<pid>-<ts>/
+ *     0001-screenshot.png
+ *     0002-snapshot.txt
+ *     0003-eval.json
+ *
+ * Root resolution order:
+ *   1. $CRAFTDRIVER_MCP_ARTIFACTS_DIR if set
+ *   2. os.tmpdir()
+ *
+ * Lifetime: the directory is **not** deleted on shutdown. Agents may
+ * still be holding paths to past artifacts; OS-level temp cleanup
+ * reclaims them eventually. Override the root if you need a custom
+ * cleanup policy.
+ */
+import { mkdir, writeFile } from 'fs/promises';
+import { join, resolve } from 'path';
+import { tmpdir } from 'os';
+export class ArtifactStore {
+    dir;
+    ready = null;
+    counter = 0;
+    constructor(rootOverride) {
+        const root = rootOverride
+            ?? process.env.CRAFTDRIVER_MCP_ARTIFACTS_DIR
+            ?? tmpdir();
+        const stamp = `${process.pid}-${Date.now().toString(36)}`;
+        this.dir = resolve(root, `craftdriver-mcp-${stamp}`);
+    }
+    /** Absolute path to the artifact directory (may not exist yet). */
+    get directory() {
+        return this.dir;
+    }
+    async ensure() {
+        if (!this.ready) {
+            this.ready = mkdir(this.dir, { recursive: true }).then(() => undefined);
+        }
+        await this.ready;
+    }
+    /**
+     * Write a payload to a numbered file. `nameHint` is used to build a
+     * human-readable filename (`0001-<hint>`); pass something like
+     * `screenshot.png` or `eval.json`.
+     */
+    async write(nameHint, data) {
+        await this.ensure();
+        this.counter += 1;
+        const seq = this.counter.toString().padStart(4, '0');
+        const path = join(this.dir, `${seq}-${nameHint}`);
+        const buf = typeof data === 'string' ? Buffer.from(data, 'utf8') : data;
+        await writeFile(path, buf);
+        return { path, bytes: buf.length };
+    }
+    /**
+     * Allocate a path for an artifact the caller will write itself (e.g.
+     * pass to `browser.screenshot({ path })`). Doesn't touch the disk
+     * beyond `mkdir -p` of the directory.
+     */
+    async allocate(nameHint) {
+        await this.ensure();
+        this.counter += 1;
+        const seq = this.counter.toString().padStart(4, '0');
+        return join(this.dir, `${seq}-${nameHint}`);
+    }
+}
+/**
+ * Spill threshold in bytes. Content blocks longer than this are
+ * written to an artifact and replaced inline with a short preview.
+ *
+ * Default 2 KB ≈ 500 tokens — enough room for a typical short
+ * snapshot diff or a small JSON result, but well below the cost of a
+ * full 80-node snapshot or a verbose eval payload.
+ */
+export const DEFAULT_SPILL_BYTES = 2048;
+export function resolveSpillBytes() {
+    const env = process.env.CRAFTDRIVER_MCP_SPILL_BYTES;
+    if (!env)
+        return DEFAULT_SPILL_BYTES;
+    const n = Number.parseInt(env, 10);
+    return Number.isFinite(n) && n > 0 ? n : DEFAULT_SPILL_BYTES;
+}
+/**
+ * Build the short inline replacement shown in place of a spilled
+ * payload. Keeps the first ~5 lines (or 240 chars, whichever is
+ * shorter) so the agent still sees the head of the data without
+ * having to read the file for a quick glance.
+ */
+export function spillPreview(text, written) {
+    const head = text.split('\n').slice(0, 5).join('\n');
+    const trimmed = head.length > 240 ? head.slice(0, 237) + '…' : head;
+    return `${trimmed}\n…\n(full output: ${written.path}, ${written.bytes} bytes)`;
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/cli/mcp/artifacts.js.map

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

package/dist/cli/mcp/server.d.ts

@@ -0,0 +1,34 @@
+/**
+ * MCP server — JSON-RPC 2.0 over stdio.
+ *
+ * Hand-rolled because the spec we use (initialize / tools/list /
+ * tools/call) is ~6 methods, and pulling `@modelcontextprotocol/sdk`
+ * would multiply our runtime-dep footprint. If the spec grows we can
+ * swap in the SDK without changing tool definitions in `tools.ts`.
+ *
+ * Protocol version we advertise: 2024-11-05. If the client offers a
+ * newer one we just echo theirs back — the methods we implement are
+ * stable across versions to date.
+ *
+ * Lifecycle:
+ *   client → initialize         → server returns capabilities + info
+ *   client → notifications/initialized   (no response)
+ *   client ⇆ tools/list, tools/call, ...
+ *   stdin EOF (or SIGINT/SIGTERM)        → close browser, exit 0
+ */
+import { type LaunchOptions } from '../../lib/browser.js';
+export interface McpServerOptions {
+    launch: LaunchOptions;
+    /** Stream for incoming messages; defaults to process.stdin. */
+    input?: NodeJS.ReadableStream;
+    /** Stream for outgoing messages; defaults to process.stdout. */
+    output?: NodeJS.WritableStream;
+    /** Disable snapshots for tests that want a deterministic payload. */
+    snapshot?: 'auto' | 'none';
+    /** Override the artifact directory root (defaults to $CRAFTDRIVER_MCP_ARTIFACTS_DIR or os.tmpdir()). */
+    artifactsDir?: string;
+    /** Override the spill threshold in bytes (default 2048; env: $CRAFTDRIVER_MCP_SPILL_BYTES). */
+    spillBytes?: number;
+}
+export declare function runMcpServer(opts: McpServerOptions): Promise<void>;
+//# sourceMappingURL=server.d.ts.map

package/dist/cli/mcp/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAW,KAAK,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAiDnE,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,aAAa,CAAC;IACtB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,gEAAgE;IAChE,MAAM,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC/B,qEAAqE;IACrE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC3B,wGAAwG;IACxG,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+FAA+F;IAC/F,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAoHxE"}

package/dist/cli/mcp/server.js

@@ -0,0 +1,214 @@
+/**
+ * MCP server — JSON-RPC 2.0 over stdio.
+ *
+ * Hand-rolled because the spec we use (initialize / tools/list /
+ * tools/call) is ~6 methods, and pulling `@modelcontextprotocol/sdk`
+ * would multiply our runtime-dep footprint. If the spec grows we can
+ * swap in the SDK without changing tool definitions in `tools.ts`.
+ *
+ * Protocol version we advertise: 2024-11-05. If the client offers a
+ * newer one we just echo theirs back — the methods we implement are
+ * stable across versions to date.
+ *
+ * Lifecycle:
+ *   client → initialize         → server returns capabilities + info
+ *   client → notifications/initialized   (no response)
+ *   client ⇆ tools/list, tools/call, ...
+ *   stdin EOF (or SIGINT/SIGTERM)        → close browser, exit 0
+ */
+import { Browser } from '../../lib/browser.js';
+import { CraftdriverError, ErrorCode } from '../../lib/errors.js';
+import { createBrowserHandle } from '../dispatcher.js';
+import { TOOLS, getTool, runTool } from './tools.js';
+import { renderDelta, renderFull, takeSnapshot } from '../snapshot.js';
+import { ArtifactStore, resolveSpillBytes, spillPreview, } from './artifacts.js';
+const PROTOCOL_VERSION = '2024-11-05';
+const SERVER_NAME = 'craftdriver';
+const SERVER_VERSION = '0.1.0';
+export async function runMcpServer(opts) {
+    const input = opts.input ?? process.stdin;
+    const output = opts.output ?? process.stdout;
+    const handle = createBrowserHandle(() => Browser.launch(opts.launch));
+    const ctx = { handle, launchOptions: opts.launch };
+    // Snapshot state: one most-recent snapshot per session for diffing.
+    let lastSnapshot = null;
+    const snapshotsOn = opts.snapshot !== 'none';
+    // Artifact store: large content blocks spill here so they don't burn
+    // context tokens on every turn.
+    const artifacts = new ArtifactStore(opts.artifactsDir);
+    const spillBytes = opts.spillBytes ?? resolveSpillBytes();
+    function send(msg) {
+        output.write(JSON.stringify(msg) + '\n');
+    }
+    async function handleRequest(req) {
+        const id = req.id ?? null;
+        try {
+            switch (req.method) {
+                case 'initialize':
+                    return ok(id, {
+                        protocolVersion: req.params?.protocolVersion ?? PROTOCOL_VERSION,
+                        capabilities: { tools: {} },
+                        serverInfo: { name: SERVER_NAME, version: SERVER_VERSION },
+                        instructions: 'craftdriver browser automation. Probe selectors with browser_exists ' +
+                            'before acting; errors carry a stable `code` field; the post-action ' +
+                            'a11y snapshot diff tells you what changed.',
+                    });
+                case 'notifications/initialized':
+                    return null; // notification — no response
+                case 'ping':
+                    return ok(id, {});
+                case 'tools/list':
+                    return ok(id, {
+                        tools: TOOLS.map((t) => ({
+                            name: t.name,
+                            description: t.description,
+                            inputSchema: t.inputSchema,
+                        })),
+                    });
+                case 'tools/call': {
+                    const name = req.params?.name;
+                    const args = req.params?.arguments ?? {};
+                    if (!name)
+                        return rpcError(id, -32602, 'tools/call: missing "name"');
+                    const tool = getTool(name);
+                    if (!tool) {
+                        return ok(id, toolError(`unknown tool: ${name}`, ErrorCode.INVALID_ARGUMENT));
+                    }
+                    const result = await callTool(ctx, tool, args, {
+                        snapshotsOn,
+                        getPrev: () => lastSnapshot,
+                        setLast: (s) => {
+                            lastSnapshot = s;
+                        },
+                        artifacts,
+                        spillBytes,
+                    });
+                    return ok(id, result);
+                }
+                case 'resources/list':
+                    // Resources land with Item 7 (trace summaries). Empty list now
+                    // keeps clients that probe for resource capability happy.
+                    return ok(id, { resources: [] });
+                default:
+                    return rpcError(id, -32601, `method not found: ${req.method}`);
+            }
+        }
+        catch (e) {
+            return rpcError(id, -32000, e.message ?? String(e));
+        }
+    }
+    // Line-delimited JSON over stdin. Tolerate \r\n and trailing whitespace.
+    let buf = '';
+    input.setEncoding?.('utf8');
+    input.on('data', (chunk) => {
+        buf += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+        let nl;
+        while ((nl = buf.indexOf('\n')) !== -1) {
+            const line = buf.slice(0, nl).trim();
+            buf = buf.slice(nl + 1);
+            if (!line)
+                continue;
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } });
+                continue;
+            }
+            // Run async; responses may interleave but each carries its own id.
+            void handleRequest(parsed).then((resp) => {
+                if (resp)
+                    send(resp);
+            });
+        }
+    });
+    await new Promise((resolve) => {
+        const done = () => resolve();
+        input.once('end', done);
+        input.once('close', done);
+        process.once('SIGINT', done);
+        process.once('SIGTERM', done);
+    });
+    await handle.close();
+}
+async function callTool(ctx, tool, args, snap) {
+    // Screenshot path allocation: if the caller didn't supply a path,
+    // give them one inside the artifact directory so the PNG bytes are
+    // actually persisted somewhere they can read.
+    if (tool.name === 'browser_screenshot' && !args.path) {
+        args = { ...args, path: await snap.artifacts.allocate('screenshot.png') };
+    }
+    let value;
+    try {
+        value = await runTool(ctx, tool, args);
+    }
+    catch (e) {
+        if (e instanceof CraftdriverError) {
+            return toolError(e.message, e.code, e.hint);
+        }
+        return toolError(e.message ?? String(e), ErrorCode.DRIVER_ERROR);
+    }
+    const content = [];
+    // Render result. The snapshot tool returns a structured shape we
+    // know how to print compactly; everything else falls through to
+    // the generic summariser. Both paths run through `maybeSpill` so
+    // large payloads land on disk instead of in the context window.
+    let primaryText;
+    if (tool.name === 'browser_snapshot' && value && typeof value === 'object' && 'lines' in value) {
+        primaryText = await maybeSpill(renderFull(value), 'snapshot.txt', snap.artifacts, snap.spillBytes);
+    }
+    else {
+        primaryText = await summariseValue(tool.name, value, snap.artifacts, snap.spillBytes);
+    }
+    content.push({ type: 'text', text: primaryText });
+    // Post-action a11y diff, when this tool changed page state.
+    if (tool.mutating && snap.snapshotsOn) {
+        const next = await takeSnapshot(await ctx.handle.get()).catch(() => null);
+        const delta = renderDelta(snap.getPrev(), next);
+        if (delta) {
+            const block = await maybeSpill(delta, 'snapshot.txt', snap.artifacts, snap.spillBytes);
+            content.push({ type: 'text', text: block });
+        }
+        snap.setLast(next);
+    }
+    return { content, structuredContent: { result: value } };
+}
+async function summariseValue(toolName, value, artifacts, spillBytes) {
+    if (value === null || value === undefined)
+        return `${toolName}: ok`;
+    const text = typeof value === 'string' ? value : safeJson(value);
+    return maybeSpill(text, `${toolName}.txt`, artifacts, spillBytes);
+}
+async function maybeSpill(text, nameHint, artifacts, spillBytes) {
+    const size = Buffer.byteLength(text, 'utf8');
+    if (size <= spillBytes)
+        return text;
+    const written = await artifacts.write(nameHint, text);
+    return spillPreview(text, written);
+}
+function safeJson(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function toolError(message, code, hint) {
+    const lines = [`error: ${message}`, `code:  ${code}`];
+    if (hint)
+        lines.push(`hint:  ${hint}`);
+    return {
+        isError: true,
+        content: [{ type: 'text', text: lines.join('\n') }],
+        structuredContent: { error: { code, message, hint } },
+    };
+}
+function ok(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+function rpcError(id, code, message) {
+    return { jsonrpc: '2.0', id, error: { code, message } };
+}
+//# sourceMappingURL=server.js.map

package/dist/cli/mcp/server.js.map

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

package/dist/cli/mcp/tools.d.ts

@@ -0,0 +1,34 @@
+/**
+ * MCP tool registry.
+ *
+ * Each tool: a JSON Schema for the model + a thin handler that maps
+ * the arguments onto the existing dispatcher. The dispatcher already
+ * speaks `{ cmd, args }` and throws `CraftdriverError` with stable
+ * codes — we reuse it untouched so library, CLI, and MCP all behave
+ * identically when given the same selector.
+ *
+ * Compact set per §6 of the AI-productivity plan: ~12 tools, one-line
+ * descriptions, merged variants behind options. `browser_trace` is
+ * intentionally absent in v1 — it ships with Item 7 (trace summaries).
+ */
+import type { DispatchContext } from '../dispatcher.js';
+export interface ToolDef {
+    name: string;
+    description: string;
+    /** JSON Schema, restricted to types MCP clients reliably support. */
+    inputSchema: Record<string, unknown>;
+    /** Map MCP args → dispatcher args. Defaults to identity. */
+    toDispatch: (args: Record<string, unknown>) => {
+        cmd: string;
+        args: Record<string, unknown>;
+    };
+    /** When true, this action mutates page state — caller should take a snapshot. */
+    mutating: boolean;
+    /** When true, the result includes binary content (image bytes). */
+    returnsImage?: boolean;
+}
+export declare const TOOLS: ToolDef[];
+export declare function getTool(name: string): ToolDef | undefined;
+/** Run a tool against the dispatcher. Throws CraftdriverError on failure. */
+export declare function runTool(ctx: DispatchContext, tool: ToolDef, args: Record<string, unknown>): Promise<unknown>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/cli/mcp/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../../../src/cli/mcp/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAGxD,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,4DAA4D;IAC5D,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAC9F,iFAAiF;IACjF,QAAQ,EAAE,OAAO,CAAC;IAClB,mEAAmE;IACnE,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAUD,eAAO,MAAM,KAAK,EAAE,OAAO,EAkO1B,CAAC;AAIF,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAEzD;AAED,6EAA6E;AAC7E,wBAAsB,OAAO,CAC3B,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,OAAO,EACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,OAAO,CAAC,OAAO,CAAC,CAGlB"}