@lensmcp/nx-plugin 1.1.0 → 1.4.0

package/executors/agent-build/agent-build.js

@@ -58,7 +58,7 @@ async function agentBuildExecutor(options, context) {
                 buildOutDir: (0, node_path_1.join)(projectRoot, 'dist'),
                 timestamp: new Date().toISOString(),
                 note: 'Phase 2 baseline marker. Per-chunk JSON is materialised by the running ' +
-                    'lensmcp-mcp session via @lensmcp/bundle once the supervisor wires the plugin bus.',
+                    'lensmcp-mcp session (the self-contained bundle) once the supervisor wires the plugin bus.',
             }, null, 2) + '\n');
             console.log(`[agent-build] baseline written: ${baselinePath}`);
         }

package/executors/agent-dev/agent-dev.d.ts

@@ -12,9 +12,12 @@ interface ExecutorResult {
  *      collectors see what the user sees.
  *   3. The LensMCP MCP server, so an agent can connect.
  *
- * Phase 1 keeps this minimal: spawn-and-supervise, no clever
- * inter-process correlation. The real session-supervisor coordinator
- * lands in Phase 2/3 as `@lensmcp/session` extensions.
+ * The MCP server and the browser-capture runner are both spawned from the
+ * self-contained `lensmcp` CLI bundle (`bundled/main.js` +
+ * `bundled/capture-runner.js`), which inlines every internal `@lensmcp/*`
+ * lib — so the executor itself imports NONE of them and a host needs only
+ * `npm i @lensmcp/nx-plugin lensmcp` (no unpublished workspace libs, no
+ * symlink bridging).
  *
  * Streams everyone's stdio to this terminal so the developer can see
  * what's happening. Ctrl-C triggers a clean teardown.

package/executors/agent-dev/agent-dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-dev.d.ts","sourceRoot":"","sources":["../../../src/executors/agent-dev/agent-dev.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAEvD,UAAU,cAAc;IACtB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAA8B,gBAAgB,CAC5C,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CAiNzB"}
+{"version":3,"file":"agent-dev.d.ts","sourceRoot":"","sources":["../../../src/executors/agent-dev/agent-dev.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAOlD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,UAAU,CAAC;AAEvD,UAAU,cAAc;IACtB,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAA8B,gBAAgB,CAC5C,OAAO,EAAE,sBAAsB,EAC/B,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,cAAc,CAAC,CA+MzB"}

package/executors/agent-dev/agent-dev.js

@@ -4,6 +4,7 @@ exports.default = agentDevExecutor;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const lens_frontend_1 = require("../../lens-frontend");
 /**
  * `agent-dev` — long-running executor that spawns:
  *
@@ -13,9 +14,12 @@ const node_path_1 = require("node:path");
  *      collectors see what the user sees.
  *   3. The LensMCP MCP server, so an agent can connect.
  *
- * Phase 1 keeps this minimal: spawn-and-supervise, no clever
- * inter-process correlation. The real session-supervisor coordinator
- * lands in Phase 2/3 as `@lensmcp/session` extensions.
+ * The MCP server and the browser-capture runner are both spawned from the
+ * self-contained `lensmcp` CLI bundle (`bundled/main.js` +
+ * `bundled/capture-runner.js`), which inlines every internal `@lensmcp/*`
+ * lib — so the executor itself imports NONE of them and a host needs only
+ * `npm i @lensmcp/nx-plugin lensmcp` (no unpublished workspace libs, no
+ * symlink bridging).
  *
  * Streams everyone's stdio to this terminal so the developer can see
  * what's happening. Ctrl-C triggers a clean teardown.
@@ -25,13 +29,16 @@ async function agentDevExecutor(options, context) {
         kind: options.kind ?? 'vite-react',
         chrome: options.chrome ?? true,
         headless: options.headless ?? true,
+        node: options.node ?? true,
         devTarget: options.devTarget,
         projectRoot: options.projectRoot,
         port: options.port,
         openUrl: options.openUrl,
+        devCommand: options.devCommand,
+        wsPort: options.wsPort,
     };
-    if (opts.kind !== 'vite-react' && opts.kind !== 'nestjs') {
-        console.error(`[agent-dev] Phase 3 supports kind="vite-react" or "nestjs" (got "${opts.kind}").`);
+    if (opts.kind !== 'vite-react' && opts.kind !== 'nestjs' && opts.kind !== 'imported') {
+        console.error(`[agent-dev] supported kinds are "vite-react", "nestjs", "imported" (got "${opts.kind}").`);
         return { success: false };
     }
     const project = context.projectName;
@@ -44,31 +51,30 @@ async function agentDevExecutor(options, context) {
     if (opts.kind === 'nestjs') {
         return runNestjs(projectRoot, context);
     }
-    // ---- Vite/React branch (Phase 1) ----
-    const viteBin = locateBin('vite', [projectRoot, context.root]);
-    if (!viteBin) {
-        console.error('[agent-dev] Could not find vite binary in node_modules/.bin.');
-        return { success: false };
-    }
-    // Pin the dev port so the browser-capture driver knows the URL. When
-    // Chrome capture is on we always fix it (strictPort) so the attach
-    // target is deterministic.
-    const devPort = opts.port ?? (opts.chrome ? 5173 : undefined);
-    const viteArgs = [
-        '--config',
-        resolveFirstExisting(['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs', 'vite.config.cts', 'vite.config.cjs'], projectRoot) ?? (0, node_path_1.join)(projectRoot, 'vite.config.ts'),
-        projectRoot,
-    ];
-    if (devPort !== undefined) {
-        viteArgs.push('--port', String(devPort), '--strictPort');
+    // ---- Imported / bring-your-own-build branch ----
+    //   (webpack, Next.js, custom builder, or no build at all)
+    if (opts.kind === 'imported') {
+        return runImported(projectRoot, context, {
+            devCommand: opts.devCommand,
+            chrome: opts.chrome,
+            headless: opts.headless,
+            openUrl: opts.openUrl,
+            wsPort: opts.wsPort ?? 5747,
+            node: opts.node,
+        });
     }
+    // ---- Vite/React branch (Phase 1) ----
+    // The per-app half (Vite + browser capture) is the SHARED helper
+    // `spawnLensFrontend`, which the cluster gateway also calls for `lens:true`
+    // apps. agent-dev additionally owns the cluster-wide SINGLETONS (the MCP
+    // server below) since, standalone, nothing else does.
     // 2. LensMCP MCP — prebuilt bundle from `apps/lensmcp-mcp/dist/main.js`.
     //    In a host workspace post-`lensmcp install`, this is the bundled
     //    CLI binary that ships with `lensmcp`. For dev in-repo we
     //    locate the workspace's own build artefact.
-    const mcpBundle = findMcpBundle(context.root);
+    const mcpBundle = (0, lens_frontend_1.findMcpBundle)(context.root);
     if (!mcpBundle) {
-        console.warn('[agent-dev] No lensmcp-mcp bundle found — skipping MCP server.');
+        console.warn("[agent-dev] No lensmcp-mcp bundle found — skipping MCP server. Install the self-contained CLI: `npm i -D lensmcp` (it ships `bundled/main.js`).");
     }
     const children = [];
     const respawnCounts = new Map();
@@ -144,8 +150,28 @@ async function agentDevExecutor(options, context) {
     }
     const bridgeEnv = { LENSMCP_EVENT_FILE: eventFile };
     console.log(`[agent-dev] event bridge → ${eventFile}`);
-    console.log(`[agent-dev] starting Vite for ${project ?? projectRoot}`);
-    spawnChild('vite', viteBin, viteArgs, bridgeEnv);
+    // The per-app half — Vite + browser capture — via the SHARED helper (the
+    // cluster gateway calls the identical function for its `lens:true` apps).
+    try {
+        (0, lens_frontend_1.spawnLensFrontend)({
+            projectRoot,
+            workspaceRoot: context.root,
+            ...(project ? { project } : {}),
+            eventFile,
+            ...(opts.port !== undefined ? { port: opts.port } : {}),
+            chrome: opts.chrome,
+            headless: opts.headless,
+            ...(opts.openUrl ? { openUrl: opts.openUrl } : {}),
+            log: (l) => console.log(l),
+        }, spawnChild);
+    }
+    catch (e) {
+        console.error(e.message);
+        shutdown();
+        return { success: false };
+    }
+    // The SINGLETON half — standalone, agent-dev owns the MCP server (in cluster
+    // mode the gateway owns it instead; a `lens:true` app must NOT spawn its own).
     if (mcpBundle) {
         console.log(`[agent-dev] starting LensMCP MCP server (${mcpBundle})`);
         spawnChild('lensmcp-mcp', process.execPath, [mcpBundle], {
@@ -154,32 +180,6 @@ async function agentDevExecutor(options, context) {
             LENSMCP_PORT: process.env['LENSMCP_PORT'] ?? '3000',
         });
     }
-    if (opts.chrome) {
-        // Live browser capture: launch a headless Chrome against the dev
-        // URL, forward real console/network/exception events + DOMSnapshot
-        // visual frames into the shared event file (best-effort — skips
-        // cleanly if no Chrome). Spawned as an optional child so its exit
-        // never tears down Vite/MCP.
-        const captureRunner = findCaptureRunner(context.root);
-        const devUrl = opts.openUrl ?? (devPort ? `http://localhost:${devPort}/` : undefined);
-        if (!captureRunner) {
-            console.warn('[agent-dev] browser-capture runner not built — skipping live capture.');
-        }
-        else if (!devUrl) {
-            console.warn('[agent-dev] no dev URL/port resolved — skipping live capture.');
-        }
-        else {
-            console.log(`[agent-dev] starting browser capture → ${devUrl}`);
-            spawnChild('browser-capture', process.execPath, [captureRunner], {
-                ...bridgeEnv,
-                LENSMCP_DEV_URL: devUrl,
-                LENSMCP_TOKENS_FILE: (0, node_path_1.join)(context.root, 'lensmcp.tokens.json'),
-                LENSMCP_RULES_FILE: (0, node_path_1.join)(context.root, 'lensmcp.rules.json'),
-                LENSMCP_HEADLESS: opts.headless === false ? 'false' : 'true',
-            }, true, // optional
-            { delayMs: 10_000, max: 5 });
-        }
-    }
     // Wait until any child exits.
     return new Promise((res) => {
         const tick = () => {
@@ -248,80 +248,178 @@ async function runNestjs(projectRoot, context) {
         });
     });
 }
-// ---------- helpers ----------
-function locateBin(name, roots) {
-    for (const root of roots) {
-        const candidate = (0, node_path_1.join)(root, 'node_modules', '.bin', name);
-        if ((0, node_fs_1.existsSync)(candidate))
-            return candidate;
-    }
-    return undefined;
-}
-function resolveFirstExisting(names, root) {
-    for (const n of names) {
-        const p = (0, node_path_1.join)(root, n);
-        if ((0, node_fs_1.existsSync)(p))
-            return p;
-    }
-    return undefined;
-}
+// ---------- imported / bring-your-own-build branch ----------
 /**
- * The global npm root — the recommended `npm i -g lensmcp` puts the bundled
- * artefacts there, not in the host workspace. Fast path derives it from the
- * running node binary (nvm/standard unix layout); `npm root -g` is the
- * fallback. Cached for the executor's lifetime.
+ * `kind: "imported"` — for hosts LensMCP does NOT build: webpack, Next.js, a
+ * custom builder, or no build at all. Instead of owning the dev server, we run
+ * the host's OWN dev command and wrap it with the build-agnostic seams:
+ *
+ *   1. the standalone bridge sidecar (`@lensmcp/bridge`) on a FIXED ws port,
+ *      so the injected `@lensmcp/client-runtime` finds it by a known URL;
+ *   2. the LensMCP MCP server (tails the shared event file);
+ *   3. the host's `devCommand`, with `LENSMCP_EVENT_FILE` + `LENSMCP_WS_PORT`
+ *      exported and (when installed) `NODE_OPTIONS=--import
+ *      @lensmcp/node-instrumentation/register` for zero-touch backend taps;
+ *   4. an optional Chrome capture sidecar against `openUrl`.
+ *
+ * The frontend seam is the user's responsibility (one line —
+ * `import '@lensmcp/client-runtime/auto'`), since we don't control their build.
  */
-let cachedGlobalRoot;
-function globalNodeModules() {
-    if (cachedGlobalRoot !== undefined)
-        return cachedGlobalRoot ?? undefined;
-    const guess = (0, node_path_1.resolve)((0, node_path_1.dirname)(process.execPath), '..', 'lib', 'node_modules');
-    if ((0, node_fs_1.existsSync)(guess)) {
-        cachedGlobalRoot = guess;
-        return guess;
+async function runImported(projectRoot, context, opts) {
+    if (!opts.devCommand) {
+        console.error('[agent-dev] kind="imported" needs a `devCommand` (your dev-server command, e.g. "npm run dev").\n' +
+            '  Add it to the agent-dev target options, or pass `--devCommand "npm run dev"`.');
+        return { success: false };
+    }
+    const bridgeBundle = (0, lens_frontend_1.findBridgeBundle)(context.root);
+    if (!bridgeBundle) {
+        console.error("[agent-dev] No lensmcp bridge bundle found. Install the self-contained CLI: `npm i -D lensmcp` (it ships `bundled/bridge.js`).");
+        return { success: false };
+    }
+    const mcpBundle = (0, lens_frontend_1.findMcpBundle)(context.root);
+    if (!mcpBundle) {
+        console.warn("[agent-dev] No lensmcp-mcp bundle found — skipping MCP server. Install the self-contained CLI: `npm i -D lensmcp`.");
+    }
+    const children = [];
+    const respawnCounts = new Map();
+    let exitRequested = false;
+    function spawnChild(label, bin, args, env, optional = false, respawn, useShell = false) {
+        const child = (0, node_child_process_1.spawn)(bin, args, {
+            cwd: projectRoot,
+            env: { ...process.env, ...(env ?? {}) },
+            stdio: 'inherit',
+            shell: useShell,
+        });
+        children.push(child);
+        child.on('exit', (code, sig) => {
+            if (exitRequested)
+                return;
+            if (optional) {
+                const used = respawnCounts.get(label) ?? 0;
+                if (respawn && used < respawn.max) {
+                    respawnCounts.set(label, used + 1);
+                    console.warn(`[agent-dev] ${label} exited (code=${code} sig=${sig}); respawning in ${Math.round(respawn.delayMs / 1000)}s (${used + 1}/${respawn.max}).`);
+                    const t = setTimeout(() => {
+                        if (!exitRequested)
+                            spawnChild(label, bin, args, env, optional, respawn, useShell);
+                    }, respawn.delayMs);
+                    t.unref?.();
+                    return;
+                }
+                console.warn(`[agent-dev] ${label} exited (code=${code} sig=${sig}); continuing.`);
+                return;
+            }
+            console.warn(`[agent-dev] ${label} exited unexpectedly (code=${code} sig=${sig}); shutting down others.`);
+            shutdown();
+        });
+        return child;
+    }
+    function shutdown() {
+        if (exitRequested)
+            return;
+        exitRequested = true;
+        for (const c of children) {
+            try {
+                c.kill('SIGTERM');
+            }
+            catch { /* swallow */ }
+        }
     }
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    // Shared event bridge file (same contract as the Vite branch).
+    const eventFile = process.env['LENSMCP_EVENT_FILE'] ?? (0, node_path_1.join)(context.root, '.lensmcp', 'events.jsonl');
     try {
-        const out = (0, node_child_process_1.execSync)('npm root -g', { encoding: 'utf8', timeout: 5000 }).trim();
-        cachedGlobalRoot = out && (0, node_fs_1.existsSync)(out) ? out : null;
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(eventFile), { recursive: true });
+        const st = (0, node_fs_1.statSync)(eventFile, { throwIfNoEntry: false });
+        if (!st || Date.now() - st.mtimeMs > 60_000) {
+            (0, node_fs_1.writeFileSync)(eventFile, '');
+        }
+        else {
+            console.log('[agent-dev] event bridge is active (written <60s ago) — appending, not truncating.');
+        }
     }
     catch {
-        cachedGlobalRoot = null;
+        /* non-fatal — ingest tolerates a missing file */
     }
-    return cachedGlobalRoot ?? undefined;
-}
-function findMcpBundle(workspaceRoot) {
-    const globalRoot = globalNodeModules();
-    const candidates = [
-        // Published host install: the bundled server inside the `lensmcp` package.
-        (0, node_path_1.join)(workspaceRoot, 'node_modules', 'lensmcp', 'bundled', 'main.js'),
-        // Global CLI install (`npm i -g lensmcp`).
-        ...(globalRoot ? [(0, node_path_1.join)(globalRoot, 'lensmcp', 'bundled', 'main.js')] : []),
-        // Pre-rename layout (kept for old installs).
-        (0, node_path_1.join)(workspaceRoot, 'node_modules', '@lensmcp', 'cli', 'bundled', 'main.js'),
-        // In-repo dev build (four-bucket layout).
-        (0, node_path_1.join)(workspaceRoot, 'servers', 'lensmcp-mcp', 'dist', 'main.js'),
-    ];
-    for (const c of candidates) {
-        if ((0, node_fs_1.existsSync)(c))
-            return c;
+    const bridgeEnv = { LENSMCP_EVENT_FILE: eventFile };
+    console.log(`[agent-dev] event bridge → ${eventFile}`);
+    // 1. Standalone browser-event bridge on a fixed port.
+    console.log(`[agent-dev] starting bridge → ws://127.0.0.1:${opts.wsPort}`);
+    spawnChild('bridge', process.execPath, [bridgeBundle], {
+        ...bridgeEnv,
+        LENSMCP_WS_HOST: process.env['LENSMCP_WS_HOST'] ?? '127.0.0.1',
+        LENSMCP_WS_PORT: String(opts.wsPort),
+    });
+    // 2. MCP server.
+    if (mcpBundle) {
+        console.log(`[agent-dev] starting LensMCP MCP server (${mcpBundle})`);
+        spawnChild('lensmcp-mcp', process.execPath, [mcpBundle], {
+            ...bridgeEnv,
+            LENSMCP_TRANSPORT: process.env['LENSMCP_TRANSPORT'] ?? 'http',
+            LENSMCP_PORT: process.env['LENSMCP_PORT'] ?? '3000',
+        });
     }
-    return undefined;
-}
-function findCaptureRunner(workspaceRoot) {
-    const globalRoot = globalNodeModules();
-    const candidates = [
-        // Published host install: bundled inside the `lensmcp` package (ship step).
-        (0, node_path_1.join)(workspaceRoot, 'node_modules', 'lensmcp', 'bundled', 'capture-runner.js'),
-        // Global CLI install (`npm i -g lensmcp`).
-        ...(globalRoot ? [(0, node_path_1.join)(globalRoot, 'lensmcp', 'bundled', 'capture-runner.js')] : []),
-        // Pre-bundling layout (kept for old installs).
-        (0, node_path_1.join)(workspaceRoot, 'node_modules', '@lensmcp', 'browser-capture', 'dist', 'capture-runner.js'),
-        // In-repo dev build.
-        (0, node_path_1.join)(workspaceRoot, 'libs', 'browser-capture', 'dist', 'capture-runner.js'),
-    ];
-    for (const c of candidates) {
-        if ((0, node_fs_1.existsSync)(c))
-            return c;
+    // 3. The host's own dev command, wrapped with the event bridge + ws port,
+    //    plus zero-touch backend taps when @lensmcp/node-instrumentation is
+    //    installed (it's a no-op import otherwise, so we gate on presence).
+    const devEnv = { ...bridgeEnv, LENSMCP_WS_PORT: String(opts.wsPort) };
+    if (opts.node) {
+        const hasNodeInstr = [projectRoot, context.root].some((r) => (0, node_fs_1.existsSync)((0, node_path_1.join)(r, 'node_modules', '@lensmcp', 'node-instrumentation')));
+        if (hasNodeInstr) {
+            const register = '--import @lensmcp/node-instrumentation/register';
+            devEnv.NODE_OPTIONS = process.env['NODE_OPTIONS']
+                ? `${process.env['NODE_OPTIONS']} ${register}`
+                : register;
+            console.log('[agent-dev] backend taps: NODE_OPTIONS += --import @lensmcp/node-instrumentation/register');
+        }
+        else {
+            console.warn('[agent-dev] @lensmcp/node-instrumentation not installed — skipping backend taps. Add it: `npm i -D @lensmcp/node-instrumentation`.');
+        }
+    }
+    console.log(`[agent-dev] front-end seam: add \`import '@lensmcp/client-runtime/auto'\` to your app entry (connects to ws://127.0.0.1:${opts.wsPort}).`);
+    console.log(`[agent-dev] starting dev command: ${opts.devCommand}`);
+    spawnChild('dev', opts.devCommand, [], devEnv, false, undefined, true /* shell */);
+    // 4. Optional Chrome capture (needs a known URL — we don't infer the port).
+    if (opts.chrome) {
+        const captureRunner = (0, lens_frontend_1.findCaptureRunner)(context.root);
+        const devUrl = opts.openUrl;
+        if (!captureRunner) {
+            console.warn("[agent-dev] browser-capture runner not found — skipping live capture. Install the self-contained CLI: `npm i -D lensmcp`.");
+        }
+        else if (!devUrl) {
+            console.warn('[agent-dev] no `openUrl` provided — skipping Chrome capture (set openUrl to your dev URL).');
+        }
+        else {
+            console.log(`[agent-dev] starting browser capture → ${devUrl}`);
+            spawnChild('browser-capture', process.execPath, [captureRunner], {
+                ...bridgeEnv,
+                LENSMCP_DEV_URL: devUrl,
+                LENSMCP_TOKENS_FILE: (0, node_path_1.join)(context.root, 'lensmcp.tokens.json'),
+                LENSMCP_RULES_FILE: (0, node_path_1.join)(context.root, 'lensmcp.rules.json'),
+                LENSMCP_HEADLESS: opts.headless === false ? 'false' : 'true',
+            }, true, { delayMs: 10_000, max: 5 });
+        }
     }
-    return undefined;
+    // Wait until any non-optional child exits.
+    return new Promise((res) => {
+        const tick = () => {
+            if (exitRequested) {
+                Promise.allSettled(children.map((c) => new Promise((r) => {
+                    if (c.exitCode !== null)
+                        r();
+                    else
+                        c.on('exit', () => r());
+                }))).then(() => res({ success: true }));
+            }
+            else {
+                setTimeout(tick, 500);
+            }
+        };
+        tick();
+    });
 }
+// ---------- helpers ----------
+// The bundle/bin resolvers (locateBin, findMcpBundle, findCaptureRunner,
+// findBridgeBundle, …) now live in the shared `../../lens-frontend` module so
+// the cluster gateway reuses the EXACT same resolution. Imported at the top.

package/executors/agent-dev/schema.d.ts

@@ -1,9 +1,15 @@
 export interface AgentDevExecutorSchema {
-  kind?: 'vite-react' | 'nestjs' | 'nextjs';
+  kind?: 'vite-react' | 'nestjs' | 'nextjs' | 'imported';
   devTarget?: string;
+  /** For kind "imported": the host's own dev-server shell command. */
+  devCommand?: string;
   projectRoot?: string;
   chrome?: boolean;
   headless?: boolean;
   port?: number;
   openUrl?: string;
+  /** For kind "imported": fixed bridge WS port the client runtime connects to. */
+  wsPort?: number;
+  /** For kind "imported": inject the node-instrumentation --import. Default true. */
+  node?: boolean;
 }

package/executors/agent-dev/schema.json

@@ -8,13 +8,27 @@
   "properties": {
     "kind": {
       "type": "string",
-      "enum": ["vite-react", "nestjs", "nextjs"],
+      "enum": ["vite-react", "nestjs", "nextjs", "imported"],
       "default": "vite-react"
     },
     "devTarget": {
       "type": "string",
       "description": "Nx target that starts the host's dev server (e.g. \"web:serve\"). If omitted, the executor runs `vite` on the current project."
     },
+    "devCommand": {
+      "type": "string",
+      "description": "For kind \"imported\": the shell command that starts the host's own dev server (e.g. \"npm run dev\" or \"webpack serve\"). Run with LENSMCP_EVENT_FILE + LENSMCP_WS_PORT exported and (when @lensmcp/node-instrumentation is installed) NODE_OPTIONS=--import for backend taps."
+    },
+    "wsPort": {
+      "type": "number",
+      "default": 5747,
+      "description": "For kind \"imported\": fixed port the standalone bridge listens on. The injected @lensmcp/client-runtime connects here (default 5747)."
+    },
+    "node": {
+      "type": "boolean",
+      "default": true,
+      "description": "For kind \"imported\": inject NODE_OPTIONS=--import @lensmcp/node-instrumentation/register into the dev command so backend taps install with no code change. Skipped automatically if the package isn't installed."
+    },
     "projectRoot": {
       "type": "string",
       "description": "Override the project root passed to Vite. Defaults to the running project's root."

package/lens-frontend.d.ts

@@ -0,0 +1,72 @@
+import type { ChildProcess } from 'node:child_process';
+/** A caller-supplied process spawner so spawned children join the caller's
+ *  lifecycle (teardown, respawn policy, stdio). Mirrors the `spawnChild`
+ *  closures inside `agent-dev` and the gateway. */
+export type SpawnChild = (label: string, bin: string, args: string[], env?: NodeJS.ProcessEnv, optional?: boolean, respawn?: {
+    delayMs: number;
+    max: number;
+}) => ChildProcess;
+export interface LensFrontendOptions {
+    /** Absolute path to the frontend project root (holds vite.config.*). */
+    projectRoot: string;
+    /** Workspace root — used to resolve bundles + the default event file. */
+    workspaceRoot: string;
+    /** Label for logs (the nx project name). */
+    project?: string;
+    /** Shared JSONL event bus the vite plugin + capture runner append to. */
+    eventFile: string;
+    /** Pin the Vite dev port (so the gateway upstream + capture URL are
+     *  deterministic). Default 5173 when chrome capture is on, else Vite's own. */
+    port?: number;
+    /** Launch the headless browser-capture sidecar against the dev URL. */
+    chrome?: boolean;
+    /** Headless Chrome (default true). */
+    headless?: boolean;
+    /** Override the URL Chrome navigates to (default http://localhost:<port>/). */
+    openUrl?: string;
+    /** Override the vite binary path (else resolved from node_modules/.bin). */
+    viteBin?: string;
+    /** Extra env merged into the Vite child (e.g. cluster identity). */
+    viteEnv?: NodeJS.ProcessEnv;
+    /** Logger (default console.log). */
+    log?: (line: string) => void;
+}
+export interface LensFrontendResult {
+    /** The pinned Vite dev port (undefined when unpinned). */
+    devPort?: number;
+    /** The dev URL the gateway should upstream to / Chrome captures. */
+    devUrl?: string;
+    /** The spawned Vite child. */
+    vite: ChildProcess;
+}
+/**
+ * Spawn ONE frontend project under the lens: its Vite dev server (lens plugin
+ * already wired by `setup-vite`) + an optional browser-capture sidecar, both
+ * publishing to the shared event bus. Does NOT spawn the dashboard or MCP
+ * server — those are singletons the CALLER owns.
+ *
+ * Returns the resolved dev port/URL so the gateway can route its TCP upstream
+ * at it. Throws only if Vite can't be located; capture is best-effort.
+ */
+export declare function spawnLensFrontend(options: LensFrontendOptions, spawnChild: SpawnChild): LensFrontendResult;
+export declare function locateBin(name: string, roots: string[]): string | undefined;
+export declare function resolveFirstExisting(names: string[], root: string): string | undefined;
+export declare function globalNodeModules(): string | undefined;
+/**
+ * Resolve the LensMCP MCP server bundle — the self-contained `lensmcp` CLI
+ * bundle (`bundled/main.js`), else the in-repo dev build. See the doc on
+ * `findCaptureRunner` for why we never reach into an unpublished `@lensmcp/*`.
+ */
+export declare function findMcpBundle(workspaceRoot: string): string | undefined;
+/**
+ * Resolve the lens DASHBOARD bundle — the human web view (`bundled/dashboard.js`,
+ * default :4321). Same shipping story as the MCP bundle.
+ */
+export declare function findDashboardBundle(workspaceRoot: string): string | undefined;
+export declare function findCaptureRunner(workspaceRoot: string): string | undefined;
+/**
+ * Resolve the standalone browser-event bridge runner — the self-contained
+ * `lensmcp` package's `bundled/bridge.js`, else the in-repo dev build.
+ */
+export declare function findBridgeBundle(workspaceRoot: string): string | undefined;
+//# sourceMappingURL=lens-frontend.d.ts.map

package/lens-frontend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lens-frontend.d.ts","sourceRoot":"","sources":["../src/lens-frontend.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAEvD;;mDAEmD;AACnD,MAAM,MAAM,UAAU,GAAG,CACvB,KAAK,EAAE,MAAM,EACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,EACvB,QAAQ,CAAC,EAAE,OAAO,EAClB,OAAO,CAAC,EAAE;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,KACvC,YAAY,CAAC;AAElB,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,4CAA4C;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB;mFAC+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uEAAuE;IACvE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAC5B,oCAAoC;IACpC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,0DAA0D;IAC1D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8BAA8B;IAC9B,IAAI,EAAE,YAAY,CAAC;CACpB;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,mBAAmB,EAC5B,UAAU,EAAE,UAAU,GACrB,kBAAkB,CAiEpB;AAID,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAM3E;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMtF;AASD,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,SAAS,CActD;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQvE;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQ7E;AAED,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQ3E;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAQ1E"}

package/lens-frontend.js

@@ -0,0 +1,193 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnLensFrontend = spawnLensFrontend;
+exports.locateBin = locateBin;
+exports.resolveFirstExisting = resolveFirstExisting;
+exports.globalNodeModules = globalNodeModules;
+exports.findMcpBundle = findMcpBundle;
+exports.findDashboardBundle = findDashboardBundle;
+exports.findCaptureRunner = findCaptureRunner;
+exports.findBridgeBundle = findBridgeBundle;
+/**
+ * Shared "run ONE frontend project under the lens" machinery.
+ *
+ * The SAME logic is needed in two places:
+ *
+ *   1. `agent-dev` (standalone, per-app) — `nx run web:agent-dev`. There it ALSO
+ *      spawns the cluster-wide singletons (the MCP server + the dashboard), since
+ *      nothing else owns them.
+ *   2. `@lensmcp/cluster`'s gateway (`nx run gateway:serve`, `lens: true` apps).
+ *      There the gateway owns the singletons (ONE dashboard + ONE MCP server
+ *      cluster-wide), so a `lens:true` app must run ONLY its Vite + the lens
+ *      instrumentation + browser capture — never its own dashboard/MCP (they'd
+ *      collide on :4321 / :3000).
+ *
+ * This module factors out the per-app half — Vite (with `@lensmcp/vite-plugin`
+ * already wired in the host's vite.config) + the optional browser-capture
+ * runner — plus the bundle/bin resolvers both callers share. The singleton half
+ * (dashboard + MCP) stays with each caller, because WHO owns the singletons is
+ * exactly what differs between the two.
+ *
+ * No `@nx/devkit` import here on purpose: the cluster gateway calls this from a
+ * plain runtime context, so the helper takes only POJOs + a `spawnChild`
+ * callback the caller supplies (so children join the caller's lifecycle/teardown).
+ */
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+/**
+ * Spawn ONE frontend project under the lens: its Vite dev server (lens plugin
+ * already wired by `setup-vite`) + an optional browser-capture sidecar, both
+ * publishing to the shared event bus. Does NOT spawn the dashboard or MCP
+ * server — those are singletons the CALLER owns.
+ *
+ * Returns the resolved dev port/URL so the gateway can route its TCP upstream
+ * at it. Throws only if Vite can't be located; capture is best-effort.
+ */
+function spawnLensFrontend(options, spawnChild) {
+    const log = options.log ?? ((l) => console.log(l));
+    const { projectRoot, workspaceRoot, eventFile } = options;
+    const chrome = options.chrome !== false;
+    const headless = options.headless !== false;
+    const viteBin = options.viteBin ?? locateBin('vite', [projectRoot, workspaceRoot]);
+    if (!viteBin) {
+        throw new Error('[lens] Could not find the vite binary in node_modules/.bin.');
+    }
+    // Pin the dev port so the gateway upstream + the capture target are
+    // deterministic. When chrome capture is on we always fix it (strictPort).
+    const devPort = options.port ?? (chrome ? 5173 : undefined);
+    const viteArgs = [
+        '--config',
+        resolveFirstExisting(['vite.config.ts', 'vite.config.mts', 'vite.config.js', 'vite.config.mjs', 'vite.config.cts', 'vite.config.cjs'], projectRoot) ?? (0, node_path_1.join)(projectRoot, 'vite.config.ts'),
+        projectRoot,
+    ];
+    if (devPort !== undefined) {
+        viteArgs.push('--port', String(devPort), '--strictPort');
+    }
+    const bridgeEnv = { LENSMCP_EVENT_FILE: eventFile, ...(options.viteEnv ?? {}) };
+    log(`[lens] starting Vite for ${options.project ?? projectRoot}${devPort ? ` on :${devPort}` : ''}`);
+    const vite = spawnChild('vite', viteBin, viteArgs, bridgeEnv);
+    const devUrl = options.openUrl ?? (devPort ? `http://localhost:${devPort}/` : undefined);
+    if (chrome) {
+        const captureRunner = findCaptureRunner(workspaceRoot);
+        if (!captureRunner) {
+            log("[lens] browser-capture runner not found — skipping live capture. Install the self-contained CLI: `npm i -D lensmcp` (it ships `bundled/capture-runner.js`).");
+        }
+        else if (!devUrl) {
+            log('[lens] no dev URL/port resolved — skipping live capture.');
+        }
+        else {
+            log(`[lens] starting browser capture → ${devUrl}`);
+            spawnChild('browser-capture', process.execPath, [captureRunner], {
+                ...bridgeEnv,
+                LENSMCP_DEV_URL: devUrl,
+                LENSMCP_TOKENS_FILE: (0, node_path_1.join)(workspaceRoot, 'lensmcp.tokens.json'),
+                LENSMCP_RULES_FILE: (0, node_path_1.join)(workspaceRoot, 'lensmcp.rules.json'),
+                LENSMCP_HEADLESS: headless === false ? 'false' : 'true',
+            }, true, // optional — its exit never tears down the session
+            { delayMs: 10_000, max: 5 });
+        }
+    }
+    return {
+        ...(devPort !== undefined ? { devPort } : {}),
+        ...(devUrl ? { devUrl } : {}),
+        vite,
+    };
+}
+// ---------- bundle / bin resolvers (shared by both callers) ----------
+function locateBin(name, roots) {
+    for (const root of roots) {
+        const candidate = (0, node_path_1.join)(root, 'node_modules', '.bin', name);
+        if ((0, node_fs_1.existsSync)(candidate))
+            return candidate;
+    }
+    return undefined;
+}
+function resolveFirstExisting(names, root) {
+    for (const n of names) {
+        const p = (0, node_path_1.join)(root, n);
+        if ((0, node_fs_1.existsSync)(p))
+            return p;
+    }
+    return undefined;
+}
+/**
+ * The global npm root — `npm i -g lensmcp` puts the bundled artefacts there,
+ * not in the host workspace. Fast path derives it from the running node binary
+ * (nvm/standard unix layout); `npm root -g` is the fallback. Cached for the
+ * process lifetime.
+ */
+let cachedGlobalRoot;
+function globalNodeModules() {
+    if (cachedGlobalRoot !== undefined)
+        return cachedGlobalRoot ?? undefined;
+    const guess = (0, node_path_1.resolve)((0, node_path_1.dirname)(process.execPath), '..', 'lib', 'node_modules');
+    if ((0, node_fs_1.existsSync)(guess)) {
+        cachedGlobalRoot = guess;
+        return guess;
+    }
+    try {
+        const out = (0, node_child_process_1.execSync)('npm root -g', { encoding: 'utf8', timeout: 5000 }).trim();
+        cachedGlobalRoot = out && (0, node_fs_1.existsSync)(out) ? out : null;
+    }
+    catch {
+        cachedGlobalRoot = null;
+    }
+    return cachedGlobalRoot ?? undefined;
+}
+/**
+ * Resolve the LensMCP MCP server bundle — the self-contained `lensmcp` CLI
+ * bundle (`bundled/main.js`), else the in-repo dev build. See the doc on
+ * `findCaptureRunner` for why we never reach into an unpublished `@lensmcp/*`.
+ */
+function findMcpBundle(workspaceRoot) {
+    const globalRoot = globalNodeModules();
+    return firstExisting([
+        (0, node_path_1.join)(workspaceRoot, 'node_modules', 'lensmcp', 'bundled', 'main.js'),
+        ...(globalRoot ? [(0, node_path_1.join)(globalRoot, 'lensmcp', 'bundled', 'main.js')] : []),
+        // In-repo dev build (four-bucket layout) — never in a host's node_modules.
+        (0, node_path_1.join)(workspaceRoot, 'servers', 'lensmcp-mcp', 'dist', 'main.js'),
+    ]);
+}
+/**
+ * Resolve the lens DASHBOARD bundle — the human web view (`bundled/dashboard.js`,
+ * default :4321). Same shipping story as the MCP bundle.
+ */
+function findDashboardBundle(workspaceRoot) {
+    const globalRoot = globalNodeModules();
+    return firstExisting([
+        (0, node_path_1.join)(workspaceRoot, 'node_modules', 'lensmcp', 'bundled', 'dashboard.js'),
+        ...(globalRoot ? [(0, node_path_1.join)(globalRoot, 'lensmcp', 'bundled', 'dashboard.js')] : []),
+        // In-repo dev build — never in a host's node_modules.
+        (0, node_path_1.join)(workspaceRoot, 'servers', 'lensmcp-mcp', 'dist', 'dashboard.js'),
+    ]);
+}
+function findCaptureRunner(workspaceRoot) {
+    const globalRoot = globalNodeModules();
+    return firstExisting([
+        (0, node_path_1.join)(workspaceRoot, 'node_modules', 'lensmcp', 'bundled', 'capture-runner.js'),
+        ...(globalRoot ? [(0, node_path_1.join)(globalRoot, 'lensmcp', 'bundled', 'capture-runner.js')] : []),
+        // In-repo dev build — never in a host's node_modules.
+        (0, node_path_1.join)(workspaceRoot, 'libs', 'browser-capture', 'dist', 'capture-runner.js'),
+    ]);
+}
+/**
+ * Resolve the standalone browser-event bridge runner — the self-contained
+ * `lensmcp` package's `bundled/bridge.js`, else the in-repo dev build.
+ */
+function findBridgeBundle(workspaceRoot) {
+    const globalRoot = globalNodeModules();
+    return firstExisting([
+        (0, node_path_1.join)(workspaceRoot, 'node_modules', 'lensmcp', 'bundled', 'bridge.js'),
+        ...(globalRoot ? [(0, node_path_1.join)(globalRoot, 'lensmcp', 'bundled', 'bridge.js')] : []),
+        // In-repo dev build — never in a host's node_modules.
+        (0, node_path_1.join)(workspaceRoot, 'libs', 'bridge', 'dist', 'main.js'),
+    ]);
+}
+function firstExisting(candidates) {
+    for (const c of candidates) {
+        if ((0, node_fs_1.existsSync)(c))
+            return c;
+    }
+    return undefined;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensmcp/nx-plugin",
-  "version": "1.1.0",
+  "version": "1.4.0",
   "main": "./index.js",
   "module": "./index.js",
   "types": "./index.d.ts",
@@ -10,6 +10,11 @@
       "types": "./index.d.ts",
       "import": "./index.js",
       "default": "./index.js"
+    },
+    "./lens-frontend": {
+      "types": "./lens-frontend.d.ts",
+      "import": "./lens-frontend.js",
+      "default": "./lens-frontend.js"
     }
   },
   "dependencies": {