vela-agent 0.2.0

package/README.md

@@ -0,0 +1,33 @@
+# vela-agent
+
+**Vela Agent** is a lightweight dev probe for Electron main processes.
+
+A single `attach()` call in your main process registers IPC introspection and a main-process eval channel, giving the [vela-mcp](https://www.npmjs.com/package/vela-mcp) server the ability to call `vela_ipc_list`, `vela_ipc_invoke`, and `vela_main_eval` tools during development and testing.
+
+## Integration
+
+Add one line at the **top** of your `main.js` / `main.ts`, before any `ipcMain.handle` calls:
+
+```js
+if (process.env.NODE_ENV !== 'production') require('vela-agent').attach();
+```
+
+That is the entire integration. The probe is:
+
+- **Dev-only** — the `NODE_ENV` guard means it is completely inert in production builds.
+- **Environment/token-gated** — the agent only activates when the Vela environment token is present, so it will not interfere with regular `npm start` runs unless a Vela test session is active.
+- **Zero runtime dependencies** — nothing extra is bundled into your production app.
+
+## What it enables
+
+| vela-mcp tool | Requires vela-agent |
+|---------------|-------------------|
+| `vela_ipc_list` | Yes — lists every registered `ipcMain.handle` channel |
+| `vela_ipc_invoke` | Yes — calls a channel as if from a renderer |
+| `vela_main_eval` | Yes — evaluates arbitrary JS in the main process |
+
+All other Vela tools (CDP-based renderer eval, screenshot, debugger, specs, capture) work without vela-agent.
+
+## More
+
+See [vela-mcp](https://www.npmjs.com/package/vela-mcp) and the [repo](https://github.com/OWNER/vela) for the full playbook.

package/dist/attach.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Attach the Vela dev probe. No-op unless launched by Vela (the launcher sets
+ * VELA_PROBE_PORT + VELA_PROBE_TOKEN) and not in production. Call this at the TOP
+ * of the app's main process, BEFORE registering any ipcMain handlers.
+ */
+export declare function attach(): void;

package/dist/attach.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attach = attach;
+const core_1 = require("./core");
+const server_1 = require("./server");
+/**
+ * Attach the Vela dev probe. No-op unless launched by Vela (the launcher sets
+ * VELA_PROBE_PORT + VELA_PROBE_TOKEN) and not in production. Call this at the TOP
+ * of the app's main process, BEFORE registering any ipcMain handlers.
+ */
+function attach() {
+    if (process.env.NODE_ENV === "production")
+        return;
+    const port = Number(process.env.VELA_PROBE_PORT);
+    const token = process.env.VELA_PROBE_TOKEN;
+    if (!port || !token)
+        return; // not launched by Vela — stay completely inert
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const electron = require("electron");
+    const core = (0, core_1.createProbe)(electron.ipcMain);
+    (0, server_1.startProbeServer)(core, { port, token }).catch((e) => {
+        // eslint-disable-next-line no-console
+        console.error("[vela-agent] failed to start probe server:", e);
+    });
+}
+//# sourceMappingURL=attach.js.map

package/dist/attach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.js","sourceRoot":"","sources":["../src/attach.ts"],"names":[],"mappings":";;AAQA,wBAaC;AArBD,iCAAqC;AACrC,qCAA4C;AAE5C;;;;GAIG;AACH,SAAgB,MAAM;IACpB,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY;QAAE,OAAO;IAClD,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACjD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;IAC3C,IAAI,CAAC,IAAI,IAAI,CAAC,KAAK;QAAE,OAAO,CAAC,+CAA+C;IAE5E,8DAA8D;IAC9D,MAAM,QAAQ,GAAG,OAAO,CAAC,UAAU,CAA0C,CAAC;IAC9E,MAAM,IAAI,GAAG,IAAA,kBAAW,EAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAC3C,IAAA,yBAAgB,EAAC,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE;QAClD,sCAAsC;QACtC,OAAO,CAAC,KAAK,CAAC,4CAA4C,EAAE,CAAC,CAAC,CAAC;IACjE,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/core.d.ts

@@ -0,0 +1,19 @@
+export interface IpcLike {
+    handle(channel: string, listener: (...args: any[]) => any): void;
+    on(channel: string, listener: (...args: any[]) => any): void;
+}
+export interface IpcChannelInfo {
+    channel: string;
+    kind: "handle" | "on";
+}
+export interface ProbeCore {
+    list(): IpcChannelInfo[];
+    invoke(channel: string, args: unknown[]): Promise<unknown>;
+    evalMain(code: string): Promise<unknown>;
+}
+/**
+ * Wrap an ipcMain-like object so every `handle`/`on` registration is recorded
+ * (and still forwarded to the original), exposing introspection + invocation.
+ * Must be called BEFORE the app registers its IPC handlers.
+ */
+export declare function createProbe(ipc: IpcLike): ProbeCore;

package/dist/core.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProbe = createProbe;
+/**
+ * Wrap an ipcMain-like object so every `handle`/`on` registration is recorded
+ * (and still forwarded to the original), exposing introspection + invocation.
+ * Must be called BEFORE the app registers its IPC handlers.
+ */
+function createProbe(ipc) {
+    const handleFns = new Map();
+    const onFns = new Map();
+    const origHandle = ipc.handle.bind(ipc);
+    const origOn = ipc.on.bind(ipc);
+    ipc.handle = (channel, listener) => {
+        handleFns.set(channel, listener);
+        return origHandle(channel, listener);
+    };
+    ipc.on = (channel, listener) => {
+        onFns.set(channel, listener);
+        return origOn(channel, listener);
+    };
+    return {
+        list() {
+            return [
+                ...[...handleFns.keys()].map((channel) => ({ channel, kind: "handle" })),
+                ...[...onFns.keys()].map((channel) => ({ channel, kind: "on" }))
+            ];
+        },
+        async invoke(channel, args) {
+            const fn = handleFns.get(channel);
+            if (!fn)
+                throw new Error(`No ipcMain.handle for "${channel}"`);
+            const stubEvent = {};
+            return await fn(stubEvent, ...args);
+        },
+        async evalMain(code) {
+            const result = (0, eval)(code);
+            return await result;
+        }
+    };
+}
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../src/core.ts"],"names":[],"mappings":";;AAqBA,kCAkCC;AAvCD;;;;GAIG;AACH,SAAgB,WAAW,CAAC,GAAY;IACtC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAmC,CAAC;IAC7D,MAAM,KAAK,GAAG,IAAI,GAAG,EAAmC,CAAC;IAEzD,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACxC,MAAM,MAAM,GAAG,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEhC,GAAG,CAAC,MAAM,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE;QACjC,SAAS,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QACjC,OAAO,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACvC,CAAC,CAAC;IACF,GAAG,CAAC,EAAE,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE;QAC7B,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAC7B,OAAO,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IACnC,CAAC,CAAC;IAEF,OAAO;QACL,IAAI;YACF,OAAO;gBACL,GAAG,CAAC,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,QAAiB,EAAE,CAAC,CAAC;gBACjF,GAAG,CAAC,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,IAAa,EAAE,CAAC,CAAC;aAC1E,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI;YACxB,MAAM,EAAE,GAAG,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YAClC,IAAI,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,OAAO,GAAG,CAAC,CAAC;YAC/D,MAAM,SAAS,GAAG,EAAS,CAAC;YAC5B,OAAO,MAAM,EAAE,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,CAAC;QACtC,CAAC;QACD,KAAK,CAAC,QAAQ,CAAC,IAAI;YACjB,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;YAC/B,OAAO,MAAM,MAAM,CAAC;QACtB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { attach } from "./attach";
+export { createProbe } from "./core";
+export type { IpcLike, IpcChannelInfo, ProbeCore } from "./core";

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProbe = exports.attach = void 0;
+var attach_1 = require("./attach");
+Object.defineProperty(exports, "attach", { enumerable: true, get: function () { return attach_1.attach; } });
+var core_1 = require("./core");
+Object.defineProperty(exports, "createProbe", { enumerable: true, get: function () { return core_1.createProbe; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mCAAkC;AAAzB,gGAAA,MAAM,OAAA;AACf,+BAAqC;AAA5B,mGAAA,WAAW,OAAA"}

package/dist/server.d.ts

@@ -0,0 +1,11 @@
+import type { ProbeCore } from "./core";
+export interface ProbeServer {
+    port: number;
+    close: () => Promise<void>;
+}
+/** Start a token-gated localhost JSON-RPC server exposing the probe core.
+ * Pass port 0 to let the OS choose (the chosen port is returned). */
+export declare function startProbeServer(core: ProbeCore, opts: {
+    port: number;
+    token: string;
+}): Promise<ProbeServer>;

package/dist/server.js

@@ -0,0 +1,62 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startProbeServer = startProbeServer;
+const node_http_1 = __importDefault(require("node:http"));
+/** Start a token-gated localhost JSON-RPC server exposing the probe core.
+ * Pass port 0 to let the OS choose (the chosen port is returned). */
+function startProbeServer(core, opts) {
+    const server = node_http_1.default.createServer((req, res) => {
+        if (req.method === "GET" && req.url === "/health") {
+            res.writeHead(200);
+            res.end("ok");
+            return;
+        }
+        if (req.method !== "POST" || req.url !== "/rpc") {
+            res.writeHead(404);
+            res.end();
+            return;
+        }
+        if (req.headers["x-vela-token"] !== opts.token) {
+            res.writeHead(401, { "content-type": "application/json" });
+            res.end(JSON.stringify({ ok: false, error: "bad token" }));
+            return;
+        }
+        let body = "";
+        req.on("data", (c) => (body += c));
+        req.on("end", async () => {
+            try {
+                const { method, params } = JSON.parse(body || "{}");
+                let result;
+                if (method === "ipc.list")
+                    result = core.list();
+                else if (method === "ipc.invoke")
+                    result = await core.invoke(params.channel, params.args ?? []);
+                else if (method === "main.eval")
+                    result = await core.evalMain(params.code);
+                else
+                    throw new Error(`Unknown method: ${method}`);
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end(JSON.stringify({ ok: true, result }));
+            }
+            catch (e) {
+                res.writeHead(200, { "content-type": "application/json" });
+                res.end(JSON.stringify({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+            }
+        });
+    });
+    return new Promise((resolve, reject) => {
+        server.on("error", reject);
+        server.listen(opts.port, "127.0.0.1", () => {
+            const addr = server.address();
+            const port = addr && typeof addr === "object" ? addr.port : opts.port;
+            resolve({
+                port,
+                close: () => new Promise((r) => server.close(() => r()))
+            });
+        });
+    });
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "vela-agent",
+  "version": "0.2.0",
+  "description": "Vela dev probe — a one-line require('vela-agent').attach() in an Electron main process that exposes IPC introspection + main-process eval to the Vela test framework (dev-only).",
+  "license": "MIT",
+  "author": "Vela authors <colleenkantner@gmail.com>",
+  "keywords": [
+    "electron",
+    "testing",
+    "ipc",
+    "vela",
+    "mcp",
+    "dev"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/michael-ltm/vela.git",
+    "directory": "packages/agent"
+  },
+  "homepage": "https://github.com/michael-ltm/vela/tree/main/packages/agent#readme",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "pnpm run build"
+  }
+}