@john523100/vela-mcp 0.6.0

package/README.md

@@ -0,0 +1,91 @@
+# vela-mcp
+
+**Vela MCP** is the MCP server engine for AI-driven dynamic testing of Electron apps.
+
+It exposes 20 tools over the [Model Context Protocol](https://modelcontextprotocol.io), letting an AI agent (Claude Code, Codex, etc.) launch and drive an Electron application, inspect IPC channels, evaluate code in any context, capture screenshots, set breakpoints, record console/network traffic, and save/run re-runnable specs — all without modifying the app's production code.
+
+## Installation
+
+```bash
+npm install -g vela-mcp
+# or use npx / a local path
+```
+
+## Registering with Claude Code
+
+Add to `.mcp.json` in your project root (or `~/.claude/mcp.json` globally):
+
+```json
+{
+  "mcpServers": {
+    "vela": {
+      "command": "node",
+      "args": ["<absolute-path-to>/node_modules/vela-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Or if installed globally / via `npx`:
+
+```json
+{
+  "mcpServers": {
+    "vela": {
+      "command": "npx",
+      "args": ["vela-mcp"]
+    }
+  }
+}
+```
+
+## Registering with Codex
+
+Add the same `command`/`args` block under the `tools.mcp` key in your Codex config.
+
+## Tools (20 total)
+
+### Launch & Targets
+| Tool | Description |
+|------|-------------|
+| `vela_launch` | Launch an Electron app and attach CDP |
+| `vela_list_targets` | List open renderer/webview/BrowserView targets |
+| `vela_attach_target` | Attach to a specific target |
+| `vela_screenshot` | Capture a screenshot of the current target |
+
+### Eval & IPC
+| Tool | Description |
+|------|-------------|
+| `vela_eval` | Evaluate JS in the currently attached renderer |
+| `vela_ipc_list` | List registered IPC channels (requires vela-agent) |
+| `vela_ipc_invoke` | Invoke an IPC channel and return the result |
+| `vela_main_eval` | Evaluate JS in the main process (requires vela-agent) |
+
+### Debugger
+| Tool | Description |
+|------|-------------|
+| `vela_debug_attach` | Attach the debugger to a target |
+| `vela_set_breakpoint` | Set a breakpoint by URL + line number |
+| `vela_wait_paused` | Wait until execution hits a breakpoint |
+| `vela_eval_frame` | Evaluate an expression in the paused call frame |
+| `vela_step` | Step over / in / out |
+| `vela_resume` | Resume execution |
+| `vela_debug_detach` | Detach the debugger |
+
+### Specs
+| Tool | Description |
+|------|-------------|
+| `vela_spec_save` | Save a recorded interaction as a re-runnable spec |
+| `vela_spec_run` | Run a saved spec and return results |
+| `vela_spec_list` | List all saved specs |
+
+### Console & Network Capture
+| Tool | Description |
+|------|-------------|
+| `vela_capture_start` | Start capturing console logs and/or network requests |
+| `vela_capture_read` | Read captured events so far |
+| `vela_capture_stop` | Stop capturing and return final buffer |
+
+## More
+
+See the [repo](https://github.com/OWNER/vela) for the full playbook, Claude Code skill, and sample app.

package/dist/adapter.d.ts

@@ -0,0 +1,31 @@
+/** A connection to a launched-or-attached app that the tool layer drives. */
+export interface LaunchHandle {
+    cdpPort: number;
+    inspectPort?: number;
+    probe?: {
+        port: number;
+        token: string;
+    };
+    /** Tear down whatever this adapter started (no-op for attach mode). */
+    dispose: () => Promise<void>;
+}
+export interface AdapterLaunchOptions {
+    projectPath?: string;
+    port?: number;
+}
+/** Abstracts HOW an app is started/connected, so the tool layer is platform-agnostic. */
+export interface TargetAdapter {
+    readonly kind: string;
+    launch(opts: AdapterLaunchOptions): Promise<LaunchHandle>;
+}
+/** Launches an Electron app in dev with CDP + inspector + probe detection. */
+export declare class ElectronAdapter implements TargetAdapter {
+    readonly kind = "electron";
+    launch(opts: AdapterLaunchOptions): Promise<LaunchHandle>;
+}
+/** Attaches to an already-running CDP endpoint (any Chromium/Electron started with
+ *  --remote-debugging-port). Vela did not start it, so dispose does NOT kill it. */
+export declare class AttachAdapter implements TargetAdapter {
+    readonly kind = "attach";
+    launch(opts: AdapterLaunchOptions): Promise<LaunchHandle>;
+}

package/dist/adapter.js

@@ -0,0 +1,32 @@
+import { launchElectron, killAndWait } from "./launcher.js";
+/** Launches an Electron app in dev with CDP + inspector + probe detection. */
+export class ElectronAdapter {
+    kind = "electron";
+    async launch(opts) {
+        if (!opts.projectPath)
+            throw new Error("ElectronAdapter requires a projectPath");
+        const app = await launchElectron(opts.projectPath);
+        return {
+            cdpPort: app.port,
+            inspectPort: app.inspectPort,
+            probe: app.probe,
+            dispose: () => killAndWait(app.child)
+        };
+    }
+}
+/** Attaches to an already-running CDP endpoint (any Chromium/Electron started with
+ *  --remote-debugging-port). Vela did not start it, so dispose does NOT kill it. */
+export class AttachAdapter {
+    kind = "attach";
+    async launch(opts) {
+        if (!opts.port)
+            throw new Error("attach mode requires a port (the target's --remote-debugging-port)");
+        return {
+            cdpPort: opts.port,
+            dispose: async () => {
+                // intentionally a no-op: we don't own this process
+            }
+        };
+    }
+}
+//# sourceMappingURL=adapter.js.map

package/dist/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAsB5D,8EAA8E;AAC9E,MAAM,OAAO,eAAe;IACjB,IAAI,GAAG,UAAU,CAAC;IAC3B,KAAK,CAAC,MAAM,CAAC,IAA0B;QACrC,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,MAAM,IAAI,KAAK,CAAC,wCAAwC,CAAC,CAAC;QACjF,MAAM,GAAG,GAAG,MAAM,cAAc,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QACnD,OAAO;YACL,OAAO,EAAE,GAAG,CAAC,IAAI;YACjB,WAAW,EAAE,GAAG,CAAC,WAAW;YAC5B,KAAK,EAAE,GAAG,CAAC,KAAK;YAChB,OAAO,EAAE,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC;SACtC,CAAC;IACJ,CAAC;CACF;AAED;oFACoF;AACpF,MAAM,OAAO,aAAa;IACf,IAAI,GAAG,QAAQ,CAAC;IACzB,KAAK,CAAC,MAAM,CAAC,IAA0B;QACrC,IAAI,CAAC,IAAI,CAAC,IAAI;YAAE,MAAM,IAAI,KAAK,CAAC,oEAAoE,CAAC,CAAC;QACtG,OAAO;YACL,OAAO,EAAE,IAAI,CAAC,IAAI;YAClB,OAAO,EAAE,KAAK,IAAI,EAAE;gBAClB,mDAAmD;YACrD,CAAC;SACF,CAAC;IACJ,CAAC;CACF"}

package/dist/capture.d.ts

@@ -0,0 +1,41 @@
+export interface ConsoleLine {
+    level: string;
+    text: string;
+}
+export interface NetEntry {
+    requestId: string;
+    method: string;
+    url: string;
+    status?: number;
+    mimeType?: string;
+}
+export interface CaptureSnapshot {
+    console: ConsoleLine[];
+    network: NetEntry[];
+}
+/**
+ * A long-lived CDP connection buffering console + network events for one target.
+ * Buffers are for time-windowed capture; they are capped to avoid unbounded growth.
+ */
+export declare class CaptureSession {
+    private readonly client;
+    private consoleLines;
+    private net;
+    private constructor();
+    private pushConsole;
+    static start(wsUrl: string, opts: {
+        console?: boolean;
+        network?: boolean;
+    }): Promise<CaptureSession>;
+    snapshot(): CaptureSnapshot;
+    stop(): Promise<void>;
+}
+/** Active capture sessions keyed by `${sessionId}:${target}`. */
+export declare class CaptureRegistry {
+    private sessions;
+    has(key: string): boolean;
+    set(key: string, s: CaptureSession): void;
+    get(key: string): CaptureSession;
+    remove(key: string): Promise<void>;
+    removeAll(): Promise<void>;
+}

package/dist/capture.js

@@ -0,0 +1,96 @@
+import CDP from "chrome-remote-interface";
+/**
+ * A long-lived CDP connection buffering console + network events for one target.
+ * Buffers are for time-windowed capture; they are capped to avoid unbounded growth.
+ */
+export class CaptureSession {
+    client;
+    consoleLines = [];
+    net = new Map();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(client) {
+        this.client = client;
+    }
+    pushConsole(line) {
+        this.consoleLines.push(line);
+        // Time-windowed capture; cap to avoid unbounded growth on very chatty pages.
+        if (this.consoleLines.length > 5000)
+            this.consoleLines.shift();
+    }
+    static async start(wsUrl, opts) {
+        const client = await CDP({ target: wsUrl });
+        try {
+            const s = new CaptureSession(client);
+            if (opts.console !== false) {
+                await client.Runtime.enable();
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                client.Runtime.consoleAPICalled((e) => {
+                    const text = (e.args ?? [])
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        .map((a) => (a.value !== undefined ? String(a.value) : a.description ?? ""))
+                        .join(" ");
+                    s.pushConsole({ level: e.type ?? "log", text });
+                });
+                await client.Log.enable();
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                client.Log.entryAdded((e) => {
+                    s.pushConsole({ level: e.entry?.level ?? "log", text: e.entry?.text ?? "" });
+                });
+            }
+            if (opts.network) {
+                await client.Network.enable();
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                client.Network.requestWillBeSent((e) => {
+                    s.net.set(e.requestId, { requestId: e.requestId, method: e.request?.method ?? "GET", url: e.request?.url ?? "" });
+                });
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                client.Network.responseReceived((e) => {
+                    const r = s.net.get(e.requestId);
+                    if (r) {
+                        r.status = e.response?.status;
+                        r.mimeType = e.response?.mimeType;
+                    }
+                });
+            }
+            return s;
+        }
+        catch (e) {
+            await client.close();
+            throw e;
+        }
+    }
+    snapshot() {
+        return { console: [...this.consoleLines], network: [...this.net.values()] };
+    }
+    async stop() {
+        await this.client.close();
+    }
+}
+/** Active capture sessions keyed by `${sessionId}:${target}`. */
+export class CaptureRegistry {
+    sessions = new Map();
+    has(key) {
+        return this.sessions.has(key);
+    }
+    set(key, s) {
+        this.sessions.set(key, s);
+    }
+    get(key) {
+        const s = this.sessions.get(key);
+        if (!s)
+            throw new Error(`No capture for ${key}. Call vela_capture_start first.`);
+        return s;
+    }
+    async remove(key) {
+        const s = this.sessions.get(key);
+        if (s) {
+            await s.stop();
+            this.sessions.delete(key);
+        }
+    }
+    async removeAll() {
+        for (const k of [...this.sessions.keys()])
+            await this.remove(k);
+    }
+}
+//# sourceMappingURL=capture.js.map

package/dist/capture.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture.js","sourceRoot":"","sources":["../src/capture.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,yBAAyB,CAAC;AAkB1C;;;GAGG;AACH,MAAM,OAAO,cAAc;IAKY;IAJ7B,YAAY,GAAkB,EAAE,CAAC;IACjC,GAAG,GAAG,IAAI,GAAG,EAAoB,CAAC;IAE1C,8DAA8D;IAC9D,YAAqC,MAAW;QAAX,WAAM,GAAN,MAAM,CAAK;IAAG,CAAC;IAE5C,WAAW,CAAC,IAAiB;QACnC,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,6EAA6E;QAC7E,IAAI,IAAI,CAAC,YAAY,CAAC,MAAM,GAAG,IAAI;YAAE,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,CAAC;IACjE,CAAC;IAED,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAa,EAAE,IAA8C;QAC9E,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5C,IAAI,CAAC;YACH,MAAM,CAAC,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;YAErC,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;gBAC3B,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;gBAC9B,8DAA8D;gBAC9D,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAM,EAAE,EAAE;oBACzC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC;wBACzB,8DAA8D;yBAC7D,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC;yBAChF,IAAI,CAAC,GAAG,CAAC,CAAC;oBACb,CAAC,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,IAAI,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBAClD,CAAC,CAAC,CAAC;gBACH,MAAM,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC;gBAC1B,8DAA8D;gBAC9D,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAM,EAAE,EAAE;oBAC/B,CAAC,CAAC,WAAW,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,KAAK,IAAI,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,KAAK,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;gBAC/E,CAAC,CAAC,CAAC;YACL,CAAC;YAED,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBACjB,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;gBAC9B,8DAA8D;gBAC9D,MAAM,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAC,CAAM,EAAE,EAAE;oBAC1C,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAE,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,MAAM,IAAI,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,CAAC,CAAC;gBACpH,CAAC,CAAC,CAAC;gBACH,8DAA8D;gBAC9D,MAAM,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAC,CAAM,EAAE,EAAE;oBACzC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;oBACjC,IAAI,CAAC,EAAE,CAAC;wBACN,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,QAAQ,EAAE,MAAM,CAAC;wBAC9B,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,EAAE,QAAQ,CAAC;oBACpC,CAAC;gBACH,CAAC,CAAC,CAAC;YACL,CAAC;YACD,OAAO,CAAC,CAAC;QACX,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC;YACrB,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC;IAED,QAAQ;QACN,OAAO,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;IAC9E,CAAC;IAED,KAAK,CAAC,IAAI;QACR,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;CACF;AAED,iEAAiE;AACjE,MAAM,OAAO,eAAe;IAClB,QAAQ,GAAG,IAAI,GAAG,EAA0B,CAAC;IACrD,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IACD,GAAG,CAAC,GAAW,EAAE,CAAiB;QAChC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC5B,CAAC;IACD,GAAG,CAAC,GAAW;QACb,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,GAAG,kCAAkC,CAAC,CAAC;QACjF,OAAO,CAAC,CAAC;IACX,CAAC;IACD,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,EAAE,CAAC;YACN,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;YACf,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,KAAK,CAAC,SAAS;QACb,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YAAE,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAClE,CAAC;CACF"}

package/dist/cdp.d.ts

@@ -0,0 +1,18 @@
+import { type CdpTarget, type NamedTarget } from "./targets.js";
+export interface EvalResult {
+    value: unknown;
+}
+export declare class CdpClient {
+    private readonly port;
+    constructor(port: number);
+    /** List all CDP targets exposed on the debug port. */
+    listTargets(): Promise<CdpTarget[]>;
+    /** List targets with stable logical names. */
+    listNamed(): Promise<NamedTarget[]>;
+    /** Resolve a logical target name to its descriptor. Defaults to "renderer". */
+    private resolveTarget;
+    /** Evaluate an expression in the chosen target's main world (default: the renderer). */
+    evaluate(expression: string, awaitPromise?: boolean, target?: string): Promise<EvalResult>;
+    /** Capture a PNG screenshot of the chosen target (default: the renderer), as base64. */
+    screenshotBase64(target?: string): Promise<string>;
+}

package/dist/cdp.js

@@ -0,0 +1,60 @@
+import CDP from "chrome-remote-interface";
+import { nameTargets } from "./targets.js";
+export class CdpClient {
+    port;
+    constructor(port) {
+        this.port = port;
+    }
+    /** List all CDP targets exposed on the debug port. */
+    async listTargets() {
+        const raw = await CDP.List({ host: "127.0.0.1", port: this.port });
+        return raw;
+    }
+    /** List targets with stable logical names. */
+    async listNamed() {
+        return nameTargets(await this.listTargets());
+    }
+    /** Resolve a logical target name to its descriptor. Defaults to "renderer". */
+    async resolveTarget(name = "renderer") {
+        const named = await this.listNamed();
+        const found = named.find((t) => t.name === name);
+        if (!found) {
+            const available = named.map((t) => t.name).join(", ") || "(none)";
+            throw new Error(`Unknown target "${name}". Available: ${available}`);
+        }
+        return found;
+    }
+    /** Evaluate an expression in the chosen target's main world (default: the renderer). */
+    async evaluate(expression, awaitPromise = true, target = "renderer") {
+        const t = await this.resolveTarget(target);
+        const client = await CDP({ host: "127.0.0.1", port: this.port, target: t.webSocketDebuggerUrl });
+        try {
+            await client.Runtime.enable();
+            const res = await client.Runtime.evaluate({ expression, awaitPromise, returnByValue: true });
+            if (res.exceptionDetails) {
+                const d = res.exceptionDetails;
+                // exception.description holds the real message; text is usually just "Uncaught".
+                const message = d.exception?.description ?? d.text ?? "Unknown evaluation error";
+                throw new Error(`Eval exception: ${message}`);
+            }
+            return { value: res.result.value };
+        }
+        finally {
+            await client.close();
+        }
+    }
+    /** Capture a PNG screenshot of the chosen target (default: the renderer), as base64. */
+    async screenshotBase64(target = "renderer") {
+        const t = await this.resolveTarget(target);
+        const client = await CDP({ host: "127.0.0.1", port: this.port, target: t.webSocketDebuggerUrl });
+        try {
+            await client.Page.enable();
+            const { data } = await client.Page.captureScreenshot({ format: "png" });
+            return data;
+        }
+        finally {
+            await client.close();
+        }
+    }
+}
+//# sourceMappingURL=cdp.js.map

package/dist/cdp.js.map

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

package/dist/debug.d.ts

@@ -0,0 +1,40 @@
+export interface PausedFrame {
+    index: number;
+    functionName: string;
+    url: string;
+    line: number;
+}
+export interface PausedInfo {
+    reason: string;
+    frames: PausedFrame[];
+}
+/** A long-lived debugger attached to one target, tracking pause state. */
+export declare class DebugSession {
+    private readonly client;
+    private paused;
+    private waiters;
+    private constructor();
+    static attachToWs(wsUrl: string): Promise<DebugSession>;
+    /** Set a breakpoint by a URL regex and a 1-based line number. */
+    setBreakpoint(urlRegex: string, line: number): Promise<{
+        breakpointId: string;
+        locations: number;
+    }>;
+    isPaused(): boolean;
+    /** Resolve when paused (now or on the next pause), or reject on timeout. */
+    waitPaused(timeoutMs?: number): Promise<PausedInfo>;
+    /** Evaluate an expression in a paused call frame (0-based index). */
+    evalOnFrame(frameIndex: number, expression: string): Promise<unknown>;
+    resume(): Promise<void>;
+    step(kind: "over" | "into" | "out"): Promise<void>;
+    detach(): Promise<void>;
+}
+/** Active debug sessions keyed by `${sessionId}:${target}`. */
+export declare class DebugRegistry {
+    private sessions;
+    has(key: string): boolean;
+    set(key: string, s: DebugSession): void;
+    get(key: string): DebugSession;
+    remove(key: string): Promise<void>;
+    removeAll(): Promise<void>;
+}

package/dist/debug.js

@@ -0,0 +1,133 @@
+import CDP from "chrome-remote-interface";
+/** A long-lived debugger attached to one target, tracking pause state. */
+export class DebugSession {
+    client;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    paused = null;
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    waiters = [];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    constructor(client) {
+        this.client = client;
+    }
+    static async attachToWs(wsUrl) {
+        const client = await CDP({ target: wsUrl });
+        const s = new DebugSession(client);
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        client.Debugger.paused((params) => {
+            s.paused = params;
+            const ws = s.waiters;
+            s.waiters = [];
+            for (const w of ws)
+                w(params);
+        });
+        client.Debugger.resumed(() => {
+            s.paused = null;
+        });
+        await client.Debugger.enable();
+        await client.Runtime.enable();
+        return s;
+    }
+    /** Set a breakpoint by a URL regex and a 1-based line number. */
+    async setBreakpoint(urlRegex, line) {
+        const res = await this.client.Debugger.setBreakpointByUrl({ urlRegex, lineNumber: line - 1 });
+        return { breakpointId: res.breakpointId, locations: res.locations.length };
+    }
+    isPaused() {
+        return this.paused !== null;
+    }
+    /** Resolve when paused (now or on the next pause), or reject on timeout. */
+    async waitPaused(timeoutMs = 10_000) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const params = this.paused ??
+            (await new Promise((resolve, reject) => {
+                const t = setTimeout(() => reject(new Error("Timed out waiting for a pause (breakpoint not hit)")), timeoutMs);
+                // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                this.waiters.push((p) => {
+                    clearTimeout(t);
+                    resolve(p);
+                });
+            }));
+        return {
+            reason: params.reason,
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            frames: params.callFrames.map((f, i) => ({
+                index: i,
+                functionName: f.functionName || "(anonymous)",
+                url: f.url,
+                line: (f.location?.lineNumber ?? 0) + 1
+            }))
+        };
+    }
+    /** Evaluate an expression in a paused call frame (0-based index). */
+    async evalOnFrame(frameIndex, expression) {
+        if (!this.paused)
+            throw new Error("Not paused — call vela_debug_wait_paused first");
+        const frame = this.paused.callFrames[frameIndex];
+        if (!frame)
+            throw new Error(`No call frame #${frameIndex}`);
+        const res = await this.client.Debugger.evaluateOnCallFrame({
+            callFrameId: frame.callFrameId,
+            expression,
+            returnByValue: true
+        });
+        if (res.exceptionDetails) {
+            throw new Error(`Frame eval exception: ${res.exceptionDetails.exception?.description ?? res.exceptionDetails.text}`);
+        }
+        return res.result.value;
+    }
+    async resume() {
+        await this.client.Debugger.resume();
+    }
+    async step(kind) {
+        if (kind === "over")
+            await this.client.Debugger.stepOver();
+        else if (kind === "into")
+            await this.client.Debugger.stepInto();
+        else
+            await this.client.Debugger.stepOut();
+    }
+    async detach() {
+        try {
+            await this.client.Debugger.resume();
+        }
+        catch {
+            // already running / not paused
+        }
+        try {
+            await this.client.Debugger.disable();
+        }
+        catch {
+            // ignore
+        }
+        await this.client.close();
+    }
+}
+/** Active debug sessions keyed by `${sessionId}:${target}`. */
+export class DebugRegistry {
+    sessions = new Map();
+    has(key) {
+        return this.sessions.has(key);
+    }
+    set(key, s) {
+        this.sessions.set(key, s);
+    }
+    get(key) {
+        const s = this.sessions.get(key);
+        if (!s)
+            throw new Error(`No debug session for ${key}. Call vela_debug_attach first.`);
+        return s;
+    }
+    async remove(key) {
+        const s = this.sessions.get(key);
+        if (s) {
+            await s.detach();
+            this.sessions.delete(key);
+        }
+    }
+    async removeAll() {
+        for (const k of [...this.sessions.keys()])
+            await this.remove(k);
+    }
+}
+//# sourceMappingURL=debug.js.map

package/dist/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,yBAAyB,CAAC;AAa1C,0EAA0E;AAC1E,MAAM,OAAO,YAAY;IAOc;IANrC,8DAA8D;IACtD,MAAM,GAAQ,IAAI,CAAC;IAC3B,8DAA8D;IACtD,OAAO,GAA4B,EAAE,CAAC;IAE9C,8DAA8D;IAC9D,YAAqC,MAAW;QAAX,WAAM,GAAN,MAAM,CAAK;IAAG,CAAC;IAEpD,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,KAAa;QACnC,MAAM,MAAM,GAAG,MAAM,GAAG,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QAC5C,MAAM,CAAC,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;QACnC,8DAA8D;QAC9D,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,MAAW,EAAE,EAAE;YACrC,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC;YAClB,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC;YACrB,CAAC,CAAC,OAAO,GAAG,EAAE,CAAC;YACf,KAAK,MAAM,CAAC,IAAI,EAAE;gBAAE,CAAC,CAAC,MAAM,CAAC,CAAC;QAChC,CAAC,CAAC,CAAC;QACH,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE;YAC3B,CAAC,CAAC,MAAM,GAAG,IAAI,CAAC;QAClB,CAAC,CAAC,CAAC;QACH,MAAM,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QAC/B,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC;QAC9B,OAAO,CAAC,CAAC;IACX,CAAC;IAED,iEAAiE;IACjE,KAAK,CAAC,aAAa,CAAC,QAAgB,EAAE,IAAY;QAChD,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,QAAQ,EAAE,UAAU,EAAE,IAAI,GAAG,CAAC,EAAE,CAAC,CAAC;QAC9F,OAAO,EAAE,YAAY,EAAE,GAAG,CAAC,YAAY,EAAE,SAAS,EAAE,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;IAC7E,CAAC;IAED,QAAQ;QACN,OAAO,IAAI,CAAC,MAAM,KAAK,IAAI,CAAC;IAC9B,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,UAAU,CAAC,SAAS,GAAG,MAAM;QACjC,8DAA8D;QAC9D,MAAM,MAAM,GACV,IAAI,CAAC,MAAM;YACX,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACrC,MAAM,CAAC,GAAG,UAAU,CAClB,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC,EAC7E,SAAS,CACV,CAAC;gBACF,8DAA8D;gBAC9D,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAM,EAAE,EAAE;oBAC3B,YAAY,CAAC,CAAC,CAAC,CAAC;oBAChB,OAAO,CAAC,CAAC,CAAC,CAAC;gBACb,CAAC,CAAC,CAAC;YACL,CAAC,CAAC,CAAC,CAAC;QACN,OAAO;YACL,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,8DAA8D;YAC9D,MAAM,EAAE,MAAM,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,CAAS,EAAE,EAAE,CAAC,CAAC;gBACpD,KAAK,EAAE,CAAC;gBACR,YAAY,EAAE,CAAC,CAAC,YAAY,IAAI,aAAa;gBAC7C,GAAG,EAAE,CAAC,CAAC,GAAG;gBACV,IAAI,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,UAAU,IAAI,CAAC,CAAC,GAAG,CAAC;aACxC,CAAC,CAAC;SACJ,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,KAAK,CAAC,WAAW,CAAC,UAAkB,EAAE,UAAkB;QACtD,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;QACpF,MAAM,KAAK,GAAG,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC;QACjD,IAAI,CAAC,KAAK;YAAE,MAAM,IAAI,KAAK,CAAC,kBAAkB,UAAU,EAAE,CAAC,CAAC;QAC5D,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAC;YACzD,WAAW,EAAE,KAAK,CAAC,WAAW;YAC9B,UAAU;YACV,aAAa,EAAE,IAAI;SACpB,CAAC,CAAC;QACH,IAAI,GAAG,CAAC,gBAAgB,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,yBAAyB,GAAG,CAAC,gBAAgB,CAAC,SAAS,EAAE,WAAW,IAAI,GAAG,CAAC,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC;QACvH,CAAC;QACD,OAAO,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC;IAC1B,CAAC;IAED,KAAK,CAAC,MAAM;QACV,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;IACtC,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,IAA6B;QACtC,IAAI,IAAI,KAAK,MAAM;YAAE,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;aACtD,IAAI,IAAI,KAAK,MAAM;YAAE,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;;YAC3D,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;IAC5C,CAAC;IACD,KAAK,CAAC,MAAM;QACV,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,EAAE,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,+BAA+B;QACjC,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;QACvC,CAAC;QAAC,MAAM,CAAC;YACP,SAAS;QACX,CAAC;QACD,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IAC5B,CAAC;CACF;AAED,+DAA+D;AAC/D,MAAM,OAAO,aAAa;IAChB,QAAQ,GAAG,IAAI,GAAG,EAAwB,CAAC;IACnD,GAAG,CAAC,GAAW;QACb,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAChC,CAAC;IACD,GAAG,CAAC,GAAW,EAAE,CAAe;QAC9B,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC5B,CAAC;IACD,GAAG,CAAC,GAAW;QACb,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,GAAG,iCAAiC,CAAC,CAAC;QACtF,OAAO,CAAC,CAAC;IACX,CAAC;IACD,KAAK,CAAC,MAAM,CAAC,GAAW;QACtB,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,EAAE,CAAC;YACN,MAAM,CAAC,CAAC,MAAM,EAAE,CAAC;YACjB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;IACH,CAAC;IACD,KAAK,CAAC,SAAS;QACb,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;YAAE,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAClE,CAAC;CACF"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};