@john523100/vela-mcp 0.6.0

package/dist/index.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { SessionRegistry } from "./session.js";
+import { launchTool } from "./tools/launch.js";
+import { evalTool } from "./tools/eval.js";
+import { screenshotTool } from "./tools/screenshot.js";
+import { targetsTool } from "./tools/targets.js";
+import { ipcListTool, ipcInvokeTool } from "./tools/ipc.js";
+import { mainEvalTool } from "./tools/main.js";
+import { DebugRegistry } from "./debug.js";
+import { debugAttachTool, debugSetBreakpointTool, debugWaitPausedTool, debugEvalFrameTool, debugStepTool, debugResumeTool, debugDetachTool } from "./tools/debug.js";
+import { specSaveTool, specRunTool, specListTool } from "./tools/spec.js";
+import { CaptureRegistry } from "./capture.js";
+import { captureStartTool, captureReadTool, captureStopTool } from "./tools/capture.js";
+const registry = new SessionRegistry();
+const debugReg = new DebugRegistry();
+const capReg = new CaptureRegistry();
+const server = new McpServer({ name: "vela", version: "0.6.0" });
+server.tool("vela_launch", "Start (mode 'launch', default) an Electron app by absolute projectPath, OR attach (mode 'attach') to an already-running CDP endpoint by port (any Chromium/Electron/web app started with --remote-debugging-port). Returns a sessionId and the CDP targets.", {
+    projectPath: z.string().optional().describe("Absolute path to the Electron project (required for mode 'launch')"),
+    mode: z.enum(["launch", "attach"]).optional().describe("'launch' (default) starts the app; 'attach' connects to a running --remote-debugging-port"),
+    port: z.number().optional().describe("CDP remote-debugging port (required for mode 'attach')")
+}, async ({ projectPath, mode, port }) => {
+    const res = await launchTool(registry, { projectPath, mode, port });
+    return { content: [{ type: "text", text: JSON.stringify(res, null, 2) }] };
+});
+server.tool("vela_targets", "List the session's CDP targets with stable logical names (renderer, webview#N, page#N). Use a returned name as the `target` for vela_eval / vela_screenshot.", { sessionId: z.string() }, async ({ sessionId }) => {
+    const res = await targetsTool(registry, { sessionId });
+    return { content: [{ type: "text", text: JSON.stringify(res.targets, null, 2) }] };
+});
+server.tool("vela_eval", "Evaluate a JavaScript expression in the chosen target's main world for a session (default: the renderer). Returns the JSON-serializable result.", {
+    sessionId: z.string(),
+    expression: z.string(),
+    awaitPromise: z.boolean().optional(),
+    target: z.string().optional().describe("Logical target name (e.g. renderer, webview#0, page#0); defaults to renderer")
+}, async ({ sessionId, expression, awaitPromise, target }) => {
+    const res = await evalTool(registry, { sessionId, expression, awaitPromise, target });
+    return { content: [{ type: "text", text: JSON.stringify(res.value) }] };
+});
+server.tool("vela_screenshot", "Capture a PNG screenshot of the chosen target for a session (default: the renderer). Returns the file path on disk.", {
+    sessionId: z.string(),
+    target: z.string().optional().describe("Logical target name (e.g. renderer, webview#0, page#0); defaults to renderer")
+}, async ({ sessionId, target }) => {
+    const res = await screenshotTool(registry, { sessionId, target });
+    return { content: [{ type: "text", text: res.path }] };
+});
+server.tool("vela_ipc_list", "List the app's registered IPC channels (ipcMain.handle/on) with their kind. Requires the vela-agent dev probe in the target app.", { sessionId: z.string() }, async ({ sessionId }) => {
+    const res = await ipcListTool(registry, { sessionId });
+    return { content: [{ type: "text", text: JSON.stringify(res.channels, null, 2) }] };
+});
+server.tool("vela_ipc_invoke", "Invoke an ipcMain.handle channel by name with JSON args and return its result. Requires the vela-agent dev probe.", {
+    sessionId: z.string(),
+    channel: z.string(),
+    args: z.array(z.any()).optional()
+}, async ({ sessionId, channel, args }) => {
+    const res = await ipcInvokeTool(registry, { sessionId, channel, args });
+    return { content: [{ type: "text", text: JSON.stringify(res.result) }] };
+});
+server.tool("vela_main_eval", "Evaluate a JavaScript expression in the app's MAIN process scope and return the result. Requires the vela-agent dev probe.", { sessionId: z.string(), code: z.string() }, async ({ sessionId, code }) => {
+    const res = await mainEvalTool(registry, { sessionId, code });
+    return { content: [{ type: "text", text: JSON.stringify(res.value) }] };
+});
+server.tool("vela_debug_attach", "Attach a debugger to a target ('renderer', 'webview#N', 'page#N', or 'main' for the main process). Required before setting breakpoints.", { sessionId: z.string(), target: z.string() }, async ({ sessionId, target }) => {
+    const res = await debugAttachTool(registry, debugReg, { sessionId, target });
+    return { content: [{ type: "text", text: JSON.stringify(res) }] };
+});
+server.tool("vela_debug_set_breakpoint", "Set a breakpoint by a URL regex (e.g. 'app\\\\.js') and a 1-based line number on an attached target.", { sessionId: z.string(), target: z.string(), urlRegex: z.string(), line: z.number() }, async ({ sessionId, target, urlRegex, line }) => {
+    const res = await debugSetBreakpointTool(debugReg, { sessionId, target, urlRegex, line });
+    return { content: [{ type: "text", text: JSON.stringify(res) }] };
+});
+server.tool("vela_debug_wait_paused", "Block until the target hits a breakpoint (or is already paused); returns the call stack. Trigger the code path in a separate, non-awaited call first.", { sessionId: z.string(), target: z.string(), timeoutMs: z.number().optional() }, async ({ sessionId, target, timeoutMs }) => {
+    const res = await debugWaitPausedTool(debugReg, { sessionId, target, timeoutMs });
+    return { content: [{ type: "text", text: JSON.stringify(res, null, 2) }] };
+});
+server.tool("vela_debug_eval_frame", "Evaluate an expression in a paused call frame (frameIndex 0 = top) to read locals/scope.", { sessionId: z.string(), target: z.string(), frameIndex: z.number().optional(), expression: z.string() }, async ({ sessionId, target, frameIndex, expression }) => {
+    const res = await debugEvalFrameTool(debugReg, { sessionId, target, frameIndex, expression });
+    return { content: [{ type: "text", text: JSON.stringify(res.value) }] };
+});
+server.tool("vela_debug_step", "Step the paused target: kind 'over' (default), 'into', or 'out'. Then call vela_debug_wait_paused again.", { sessionId: z.string(), target: z.string(), kind: z.enum(["over", "into", "out"]).optional() }, async ({ sessionId, target, kind }) => {
+    const res = await debugStepTool(debugReg, { sessionId, target, kind });
+    return { content: [{ type: "text", text: JSON.stringify(res) }] };
+});
+server.tool("vela_debug_resume", "Resume execution of a paused target.", { sessionId: z.string(), target: z.string() }, async ({ sessionId, target }) => {
+    const res = await debugResumeTool(debugReg, { sessionId, target });
+    return { content: [{ type: "text", text: JSON.stringify(res) }] };
+});
+server.tool("vela_debug_detach", "Detach the debugger from a target (resumes if paused, removes breakpoints and the debug connection).", { sessionId: z.string(), target: z.string() }, async ({ sessionId, target }) => {
+    const res = await debugDetachTool(debugReg, { sessionId, target });
+    return { content: [{ type: "text", text: JSON.stringify(res) }] };
+});
+server.tool("vela_spec_save", "Save a verified interaction as a re-runnable spec: a name, the app projectPath, and ordered steps (tool=eval/ipc_invoke/ipc_list/targets/main_eval/screenshot, args, optional expect={equals|truthy|contains|matches}).", {
+    name: z.string(),
+    projectPath: z.string(),
+    steps: z.array(z.object({
+        tool: z.enum(["eval", "ipc_invoke", "ipc_list", "targets", "main_eval", "screenshot"]),
+        args: z.record(z.any()).optional(),
+        expect: z.object({
+            equals: z.any().optional(),
+            truthy: z.boolean().optional(),
+            contains: z.string().optional(),
+            matches: z.string().optional()
+        }).optional(),
+        label: z.string().optional()
+    })),
+    specsDir: z.string().optional()
+}, async (args) => {
+    const res = await specSaveTool(args);
+    return { content: [{ type: "text", text: res.saved }] };
+});
+server.tool("vela_spec_run", "Re-run a saved spec by name: launches its app, runs each step, applies assertions, and returns a pass/fail report.", { name: z.string(), specsDir: z.string().optional() }, async ({ name, specsDir }) => {
+    const report = await specRunTool({ name, specsDir });
+    return { content: [{ type: "text", text: JSON.stringify(report, null, 2) }] };
+});
+server.tool("vela_spec_list", "List saved spec names.", { specsDir: z.string().optional() }, async ({ specsDir }) => {
+    const res = await specListTool({ specsDir });
+    return { content: [{ type: "text", text: JSON.stringify(res.specs) }] };
+});
+server.tool("vela_capture_start", "Start capturing console output and/or network requests for a target (default 'renderer'). Pass console:true and/or network:true (console defaults on if neither given).", { sessionId: z.string(), target: z.string().optional(), console: z.boolean().optional(), network: z.boolean().optional() }, async ({ sessionId, target, console, network }) => {
+    const res = await captureStartTool(registry, capReg, { sessionId, target, console, network });
+    return { content: [{ type: "text", text: JSON.stringify(res) }] };
+});
+server.tool("vela_capture_read", "Read the console lines and network requests (method/url/status/mimeType) captured so far for a target.", { sessionId: z.string(), target: z.string().optional() }, async ({ sessionId, target }) => {
+    const res = await captureReadTool(capReg, { sessionId, target });
+    return { content: [{ type: "text", text: JSON.stringify(res, null, 2) }] };
+});
+server.tool("vela_capture_stop", "Stop capturing for a target and close its capture connection.", { sessionId: z.string(), target: z.string().optional() }, async ({ sessionId, target }) => {
+    const res = await captureStopTool(capReg, { sessionId, target });
+    return { content: [{ type: "text", text: JSON.stringify(res) }] };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const shutdown = async () => {
+        await registry.disposeAll();
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/launcher.d.ts

@@ -0,0 +1,17 @@
+import { type ChildProcess } from "node:child_process";
+export interface LaunchedApp {
+    port: number;
+    inspectPort: number;
+    child: ChildProcess;
+    probe?: {
+        port: number;
+        token: string;
+    };
+}
+/**
+ * Kill a child process and resolve once it has actually exited.
+ * Falls back to SIGKILL if the process does not exit within `forceAfterMs`.
+ */
+export declare function killAndWait(child: ChildProcess, forceAfterMs?: number): Promise<void>;
+/** Launch an Electron app in dev with a CDP debug port and wait until its renderer is reachable. */
+export declare function launchElectron(projectPath: string): Promise<LaunchedApp>;

package/dist/launcher.js

@@ -0,0 +1,128 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { getFreePort } from "./ports.js";
+import { CdpClient } from "./cdp.js";
+import { pickPageTarget } from "./targets.js";
+import { ProbeClient } from "./probe.js";
+/** Resolve the Electron executable path from the target project's own dependency tree. */
+function resolveElectronBinary(projectPath) {
+    const requireFromProject = createRequire(path.join(projectPath, "package.json"));
+    // The `electron` package's main export is the path to the binary.
+    const binary = requireFromProject("electron");
+    if (typeof binary !== "string") {
+        throw new Error(`Could not resolve electron binary from ${projectPath}`);
+    }
+    return binary;
+}
+/** Best-effort wait until the renderer's document has parsed (inline scripts have run). */
+async function waitForDocumentReady(port, timeoutMs = 10_000) {
+    const cdp = new CdpClient(port);
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        try {
+            const { value } = await cdp.evaluate("document.readyState", false);
+            // 'interactive' = DOMContentLoaded (all parser-inserted inline scripts have executed); 'complete' = fully loaded.
+            if (value === "interactive" || value === "complete")
+                return;
+        }
+        catch {
+            // renderer not evaluable yet
+        }
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    // best-effort: don't fail the launch if readiness can't be confirmed in time
+}
+async function waitForPageTarget(port, timeoutMs = 20_000) {
+    const cdp = new CdpClient(port);
+    const start = Date.now();
+    // Poll until a renderer page target is reachable.
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        try {
+            const targets = await cdp.listTargets();
+            if (pickPageTarget(targets))
+                return;
+        }
+        catch {
+            // debug endpoint not up yet
+        }
+        if (Date.now() - start > timeoutMs) {
+            throw new Error(`Timed out waiting for renderer page target on port ${port}`);
+        }
+        await new Promise((r) => setTimeout(r, 250));
+    }
+}
+/**
+ * Kill a child process and resolve once it has actually exited.
+ * Falls back to SIGKILL if the process does not exit within `forceAfterMs`.
+ */
+export function killAndWait(child, forceAfterMs = 5_000) {
+    // Already exited? Nothing to wait for.
+    if (child.exitCode !== null || child.signalCode !== null)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const force = setTimeout(() => child.kill("SIGKILL"), forceAfterMs);
+        child.once("exit", () => {
+            clearTimeout(force);
+            resolve();
+        });
+        child.kill();
+    });
+}
+/**
+ * Poll the probe's /health up to `timeoutMs`; returns true if it ever answers.
+ * 1s is enough: an integrated probe calls attach() at main-process load, well before
+ * the renderer becomes ready (which is what we already awaited), so it answers immediately.
+ * Projects without the probe simply pay this short bounded wait once.
+ */
+async function detectProbe(port, token, timeoutMs = 1_000) {
+    const client = new ProbeClient(port, token);
+    const start = Date.now();
+    while (Date.now() - start < timeoutMs) {
+        if (await client.health())
+            return true;
+        await new Promise((r) => setTimeout(r, 150));
+    }
+    return false;
+}
+/** Launch an Electron app in dev with a CDP debug port and wait until its renderer is reachable. */
+export async function launchElectron(projectPath) {
+    const port = await getFreePort();
+    const probePort = await getFreePort();
+    const inspectPort = await getFreePort();
+    const probeToken = randomUUID();
+    const electron = resolveElectronBinary(projectPath);
+    const child = spawn(electron, [".", `--remote-debugging-port=${port}`, `--inspect=${inspectPort}`], {
+        cwd: projectPath,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: {
+            ...process.env,
+            NODE_ENV: "development",
+            VELA_PROBE_PORT: String(probePort),
+            VELA_PROBE_TOKEN: probeToken
+        }
+    });
+    // Permanent listener so a later 'error' event never throws as an unhandled emitter error.
+    child.on("error", (err) => {
+        console.error(`[vela] electron process error: ${err.message}`);
+    });
+    const spawnFailed = new Promise((_, reject) => {
+        child.once("error", reject);
+    });
+    spawnFailed.catch(() => { });
+    try {
+        await Promise.race([waitForPageTarget(port), spawnFailed]);
+    }
+    catch (err) {
+        await killAndWait(child);
+        throw err;
+    }
+    // Wait until the renderer has parsed so inline-script globals are present before any eval.
+    await waitForDocumentReady(port);
+    // The probe is optional: projects that haven't integrated vela-agent simply won't answer.
+    const hasProbe = await detectProbe(probePort, probeToken);
+    return { port, inspectPort, child, probe: hasProbe ? { port: probePort, token: probeToken } : undefined };
+}
+//# sourceMappingURL=launcher.js.map

package/dist/launcher.js.map

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

package/dist/ports.d.ts

@@ -0,0 +1,2 @@
+/** Ask the OS for an unused TCP port bound to loopback. */
+export declare function getFreePort(): Promise<number>;

package/dist/ports.js

@@ -0,0 +1,22 @@
+import net from "node:net";
+/** Ask the OS for an unused TCP port bound to loopback. */
+export function getFreePort() {
+    return new Promise((resolve, reject) => {
+        const srv = net.createServer();
+        srv.unref();
+        srv.on("error", reject);
+        srv.listen(0, "127.0.0.1", () => {
+            const addr = srv.address();
+            if (addr && typeof addr === "object") {
+                const port = addr.port;
+                // NOTE: the port is released here and handed to Electron afterwards; there is a
+                // small TOCTOU window where another process could claim it. Accepted for local use.
+                srv.close(() => resolve(port));
+            }
+            else {
+                srv.close(() => reject(new Error("Failed to acquire a free port")));
+            }
+        });
+    });
+}
+//# sourceMappingURL=ports.js.map

package/dist/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,UAAU,CAAC;AAE3B,2DAA2D;AAC3D,MAAM,UAAU,WAAW;IACzB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,GAAG,GAAG,GAAG,CAAC,YAAY,EAAE,CAAC;QAC/B,GAAG,CAAC,KAAK,EAAE,CAAC;QACZ,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACxB,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE;YAC9B,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,EAAE,CAAC;YAC3B,IAAI,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACrC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC;gBACvB,gFAAgF;gBAChF,oFAAoF;gBACpF,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;YACjC,CAAC;iBAAM,CAAC;gBACN,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC,CAAC,CAAC;YACtE,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/probe.d.ts

@@ -0,0 +1,15 @@
+export interface IpcChannelInfo {
+    channel: string;
+    kind: "handle" | "on";
+}
+/** Client for a running vela-agent dev probe (localhost HTTP JSON-RPC). */
+export declare class ProbeClient {
+    private readonly port;
+    private readonly token;
+    constructor(port: number, token: string);
+    private rpc;
+    health(): Promise<boolean>;
+    ipcList(): Promise<IpcChannelInfo[]>;
+    ipcInvoke(channel: string, args: unknown[]): Promise<unknown>;
+    mainEval(code: string): Promise<unknown>;
+}

package/dist/probe.js

@@ -0,0 +1,40 @@
+/** Client for a running vela-agent dev probe (localhost HTTP JSON-RPC). */
+export class ProbeClient {
+    port;
+    token;
+    constructor(port, token) {
+        this.port = port;
+        this.token = token;
+    }
+    async rpc(method, params) {
+        const res = await fetch(`http://127.0.0.1:${this.port}/rpc`, {
+            method: "POST",
+            headers: { "content-type": "application/json", "x-vela-token": this.token },
+            body: JSON.stringify({ method, params }),
+            signal: AbortSignal.timeout(10_000)
+        });
+        const j = (await res.json());
+        if (!j.ok)
+            throw new Error(j.error ?? "probe RPC error");
+        return j.result;
+    }
+    async health() {
+        try {
+            const res = await fetch(`http://127.0.0.1:${this.port}/health`);
+            return res.ok;
+        }
+        catch {
+            return false;
+        }
+    }
+    ipcList() {
+        return this.rpc("ipc.list");
+    }
+    ipcInvoke(channel, args) {
+        return this.rpc("ipc.invoke", { channel, args });
+    }
+    mainEval(code) {
+        return this.rpc("main.eval", { code });
+    }
+}
+//# sourceMappingURL=probe.js.map

package/dist/probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"probe.js","sourceRoot":"","sources":["../src/probe.ts"],"names":[],"mappings":"AAKA,2EAA2E;AAC3E,MAAM,OAAO,WAAW;IACO;IAA+B;IAA5D,YAA6B,IAAY,EAAmB,KAAa;QAA5C,SAAI,GAAJ,IAAI,CAAQ;QAAmB,UAAK,GAAL,KAAK,CAAQ;IAAG,CAAC;IAErE,KAAK,CAAC,GAAG,CAAI,MAAc,EAAE,MAAgB;QACnD,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,oBAAoB,IAAI,CAAC,IAAI,MAAM,EAAE;YAC3D,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,cAAc,EAAE,IAAI,CAAC,KAAK,EAAE;YAC3E,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;YACxC,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,MAAM,CAAC;SACpC,CAAC,CAAC;QACH,MAAM,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAgD,CAAC;QAC5E,IAAI,CAAC,CAAC,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,iBAAiB,CAAC,CAAC;QACzD,OAAO,CAAC,CAAC,MAAW,CAAC;IACvB,CAAC;IAED,KAAK,CAAC,MAAM;QACV,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,oBAAoB,IAAI,CAAC,IAAI,SAAS,CAAC,CAAC;YAChE,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,GAAG,CAAmB,UAAU,CAAC,CAAC;IAChD,CAAC;IAED,SAAS,CAAC,OAAe,EAAE,IAAe;QACxC,OAAO,IAAI,CAAC,GAAG,CAAU,YAAY,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;IAED,QAAQ,CAAC,IAAY;QACnB,OAAO,IAAI,CAAC,GAAG,CAAU,WAAW,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAClD,CAAC;CACF"}

package/dist/session.d.ts

@@ -0,0 +1,26 @@
+export interface Session {
+    projectPath: string;
+    port: number;
+    /** Set when a vela-agent dev probe was detected for this launch. */
+    probe?: {
+        port: number;
+        token: string;
+    };
+    /** Main-process Node inspector port (for vela_debug_attach target "main"). */
+    inspectPort?: number;
+    /** Tears down the Electron process and any CDP connections. */
+    dispose: () => Promise<void>;
+}
+export declare class SessionRegistry {
+    private sessions;
+    private counter;
+    register(session: Session): string;
+    get(id: string): Session;
+    list(): Array<{
+        sessionId: string;
+        projectPath: string;
+        port: number;
+    }>;
+    dispose(id: string): Promise<void>;
+    disposeAll(): Promise<void>;
+}

package/dist/session.js

@@ -0,0 +1,31 @@
+export class SessionRegistry {
+    sessions = new Map();
+    counter = 0;
+    register(session) {
+        const id = `s${++this.counter}-${session.port}`;
+        this.sessions.set(id, session);
+        return id;
+    }
+    get(id) {
+        const s = this.sessions.get(id);
+        if (!s)
+            throw new Error(`Unknown session: ${id}`);
+        return s;
+    }
+    list() {
+        return [...this.sessions.entries()].map(([sessionId, s]) => ({
+            sessionId,
+            projectPath: s.projectPath,
+            port: s.port
+        }));
+    }
+    async dispose(id) {
+        const s = this.get(id);
+        await s.dispose();
+        this.sessions.delete(id);
+    }
+    async disposeAll() {
+        await Promise.all([...this.sessions.keys()].map((id) => this.dispose(id)));
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,eAAe;IAClB,QAAQ,GAAG,IAAI,GAAG,EAAmB,CAAC;IACtC,OAAO,GAAG,CAAC,CAAC;IAEpB,QAAQ,CAAC,OAAgB;QACvB,MAAM,EAAE,GAAG,IAAI,EAAE,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC;QAChD,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;QAC/B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,GAAG,CAAC,EAAU;QACZ,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QAChC,IAAI,CAAC,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,oBAAoB,EAAE,EAAE,CAAC,CAAC;QAClD,OAAO,CAAC,CAAC;IACX,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC3D,SAAS;YACT,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,IAAI,EAAE,CAAC,CAAC,IAAI;SACb,CAAC,CAAC,CAAC;IACN,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,EAAU;QACtB,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvB,MAAM,CAAC,CAAC,OAAO,EAAE,CAAC;QAClB,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC3B,CAAC;IAED,KAAK,CAAC,UAAU;QACd,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC7E,CAAC;CACF"}

package/dist/spec.d.ts

@@ -0,0 +1,39 @@
+export interface Expectation {
+    equals?: unknown;
+    truthy?: boolean;
+    contains?: string;
+    matches?: string;
+}
+export interface SpecStep {
+    tool: "eval" | "ipc_invoke" | "ipc_list" | "targets" | "main_eval" | "screenshot";
+    args?: Record<string, unknown>;
+    expect?: Expectation;
+    label?: string;
+}
+export interface Spec {
+    name: string;
+    projectPath: string;
+    steps: SpecStep[];
+}
+export interface SpecStepResult {
+    label: string;
+    ok: boolean;
+    actual?: unknown;
+    error?: string;
+}
+export interface SpecReport {
+    name: string;
+    passed: boolean;
+    steps: SpecStepResult[];
+}
+/** Evaluate an assertion against an observed value. Pure. */
+export declare function checkExpect(actual: unknown, exp?: Expectation): {
+    ok: boolean;
+    reason?: string;
+};
+/** Persist a spec as JSON; returns the file path. */
+export declare function saveSpec(spec: Spec, root?: string): Promise<string>;
+export declare function loadSpec(name: string, root?: string): Promise<Spec>;
+export declare function listSpecs(root?: string): Promise<string[]>;
+/** Launch the spec's app, run each step, assert, dispose, and report. */
+export declare function runSpec(spec: Spec): Promise<SpecReport>;

package/dist/spec.js

@@ -0,0 +1,116 @@
+import { SessionRegistry } from "./session.js";
+import { launchTool } from "./tools/launch.js";
+import { evalTool } from "./tools/eval.js";
+import { ipcInvokeTool, ipcListTool } from "./tools/ipc.js";
+import { mainEvalTool } from "./tools/main.js";
+import { targetsTool } from "./tools/targets.js";
+import { screenshotTool } from "./tools/screenshot.js";
+import os from "node:os";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+/** Evaluate an assertion against an observed value. Pure. */
+export function checkExpect(actual, exp) {
+    if (!exp)
+        return { ok: true };
+    if ("equals" in exp) {
+        const ok = JSON.stringify(actual) === JSON.stringify(exp.equals);
+        return ok ? { ok } : { ok, reason: `expected ${JSON.stringify(exp.equals)}, got ${JSON.stringify(actual)}` };
+    }
+    if ("truthy" in exp) {
+        const ok = Boolean(actual) === exp.truthy;
+        return ok ? { ok } : { ok, reason: `expected truthy=${exp.truthy}, got ${JSON.stringify(actual)}` };
+    }
+    if ("contains" in exp) {
+        const s = JSON.stringify(actual) ?? "";
+        const ok = s.includes(exp.contains);
+        return ok ? { ok } : { ok, reason: `expected to contain "${exp.contains}", got ${s}` };
+    }
+    if ("matches" in exp) {
+        const ok = new RegExp(exp.matches).test(String(actual));
+        return ok ? { ok } : { ok, reason: `expected to match /${exp.matches}/, got ${String(actual)}` };
+    }
+    return { ok: true };
+}
+/** Reject spec names that could escape the specs directory. */
+function assertSafeName(name) {
+    if (!name || /[/\\]/.test(name) || name === "." || name === "..") {
+        throw new Error(`Invalid spec name: "${name}" (no slashes or dot segments)`);
+    }
+}
+function specsRoot(root) {
+    return root ?? path.join(os.homedir(), ".vela", "specs");
+}
+/** Persist a spec as JSON; returns the file path. */
+export async function saveSpec(spec, root) {
+    assertSafeName(spec.name);
+    const dir = specsRoot(root);
+    await fs.mkdir(dir, { recursive: true });
+    const file = path.join(dir, `${spec.name}.json`);
+    await fs.writeFile(file, JSON.stringify(spec, null, 2));
+    return file;
+}
+export async function loadSpec(name, root) {
+    assertSafeName(name);
+    const file = path.join(specsRoot(root), `${name}.json`);
+    try {
+        return JSON.parse(await fs.readFile(file, "utf8"));
+    }
+    catch {
+        throw new Error(`No spec named "${name}" in ${specsRoot(root)}`);
+    }
+}
+export async function listSpecs(root) {
+    const dir = specsRoot(root);
+    try {
+        return (await fs.readdir(dir)).filter((f) => f.endsWith(".json")).map((f) => f.replace(/\.json$/, ""));
+    }
+    catch {
+        return [];
+    }
+}
+// NOTE: the Parameters<> casts are intentionally unsound — spec steps are external JSON, so a
+// malformed `args` shape surfaces as a thrown step error at run time rather than a compile error.
+const STEP_RUNNERS = {
+    eval: (r, sessionId, a) => evalTool(r, { sessionId, ...a }).then((x) => x.value),
+    ipc_invoke: (r, sessionId, a) => ipcInvokeTool(r, { sessionId, ...a }).then((x) => x.result),
+    ipc_list: (r, sessionId) => ipcListTool(r, { sessionId }).then((x) => x.channels),
+    targets: (r, sessionId) => targetsTool(r, { sessionId }).then((x) => x.targets),
+    main_eval: (r, sessionId, a) => mainEvalTool(r, { sessionId, ...a }).then((x) => x.value),
+    screenshot: (r, sessionId, a) => screenshotTool(r, { sessionId, ...a }).then((x) => x.path)
+};
+/** Launch the spec's app, run each step, assert, dispose, and report. */
+export async function runSpec(spec) {
+    const registry = new SessionRegistry();
+    const steps = [];
+    try {
+        let sessionId;
+        try {
+            ({ sessionId } = await launchTool(registry, { projectPath: spec.projectPath }));
+        }
+        catch (e) {
+            steps.push({ label: "launch", ok: false, error: e instanceof Error ? e.message : String(e) });
+            return { name: spec.name, passed: false, steps };
+        }
+        for (const step of spec.steps) {
+            const label = step.label ?? step.tool;
+            const runner = STEP_RUNNERS[step.tool];
+            if (!runner) {
+                steps.push({ label, ok: false, error: `Unknown step tool "${step.tool}"` });
+                continue;
+            }
+            try {
+                const actual = await runner(registry, sessionId, step.args ?? {});
+                const c = checkExpect(actual, step.expect);
+                steps.push({ label, ok: c.ok, actual, error: c.reason });
+            }
+            catch (e) {
+                steps.push({ label, ok: false, error: e instanceof Error ? e.message : String(e) });
+            }
+        }
+    }
+    finally {
+        await registry.disposeAll();
+    }
+    return { name: spec.name, passed: steps.every((s) => s.ok), steps };
+}
+//# sourceMappingURL=spec.js.map