@lensmcp/cluster 1.1.0 → 1.2.0

package/executors/gateway/gateway.lib.d.ts

@@ -64,6 +64,17 @@ export interface ClusterProjectDecl {
     serveTarget?: string;
     /** Devserver admin endpoint for scaling (default from port: http(s)://localhost:<port>). */
     adminUrl?: string;
+    /**
+     * FRONTEND apps only: run this app UNDER the lens. When true, the gateway
+     * SPAWNS the app's own Vite dev server with `@lensmcp/vite-plugin`
+     * instrumentation + a browser-capture sidecar (via the shared
+     * `spawnLensFrontend` helper) and routes THAT as the upstream — instead of
+     * assuming an external Vite already runs on `port`/`upstream`. The
+     * cluster-wide singletons (dashboard + MCP) are owned by the gateway, so a
+     * `lens:true` app never spawns its own. Absent/false ⇒ today's behavior
+     * (plain TCP upstream; bring-your-own Vite). Ignored for pod (`service`) decls.
+     */
+    lens?: boolean;
 }
 export interface SockPool {
     dir: string;
@@ -81,6 +92,22 @@ export interface Route {
     svc?: ServiceCtl;
     internal?: boolean;
     auth?: AuthPolicy;
+    /** Frontend `lens:true` route: the gateway spawns this app's Vite + lens
+     *  instrumentation as the upstream (see `LensFrontend`). */
+    lens?: LensFrontend;
+}
+/** A frontend app the gateway runs UNDER the lens (`cluster.lens: true`). The
+ *  gateway spawns its Vite + browser capture as the upstream, deterministically
+ *  on `port`, and never spawns the per-app dashboard/MCP (those are singletons
+ *  the gateway owns). */
+export interface LensFrontend {
+    project: string;
+    /** Absolute project root (holds vite.config.*). */
+    projectRoot: string;
+    /** The pinned Vite dev port (also the upstream target's port). */
+    port: number;
+    /** Set once the Vite child has been spawned (idempotency guard). */
+    started?: boolean;
 }
 export interface ServiceCtl {
     project: string;
@@ -113,6 +140,11 @@ export interface GatewayHandle {
     services: ServiceCtl[];
     stop: () => Promise<void>;
 }
+/** The base domain for the lens dashboard host — the longest common dotted
+ *  suffix of the declared cluster hosts (e.g. ['api.tetros.ai.local',
+ *  'tetros.ai.local'] → 'tetros.ai.local'). Falls back to the first host, then
+ *  to 'lens.local' if no host is declared. */
+export declare function baseDomainOf(hosts: string[]): string;
 /** Round-robin over the pool's sockets, rescanning the dir when the cache ages out. */
 export declare function pickSock(pool: SockPool, scanTtlMs?: number): string | undefined;
 /**

package/executors/gateway/gateway.lib.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gateway.lib.d.ts","sourceRoot":"","sources":["../../../../../libs/cluster/src/executors/gateway/gateway.lib.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"gateway.lib.d.ts","sourceRoot":"","sources":["../../../../../libs/cluster/src/executors/gateway/gateway.lib.ts"],"names":[],"mappings":"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"}

package/executors/gateway/gateway.lib.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.hostMatches = void 0;
 exports.verifyDevJwt = verifyDevJwt;
 exports.stampIdentity = stampIdentity;
+exports.baseDomainOf = baseDomainOf;
 exports.pickSock = pickSock;
 exports.discoverRoutes = discoverRoutes;
 exports.startGateway = startGateway;
@@ -19,6 +20,7 @@ const http = tslib_1.__importStar(require("node:http"));
 const os = tslib_1.__importStar(require("node:os"));
 const path = tslib_1.__importStar(require("node:path"));
 const manifest_1 = require("./manifest");
+const lens_frontend_1 = require("@lensmcp/nx-plugin/lens-frontend");
 var manifest_2 = require("./manifest"); // back-compat re-export
 Object.defineProperty(exports, "hostMatches", { enumerable: true, get: function () { return manifest_2.hostMatches; } });
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -71,6 +73,30 @@ const devAttrs = (req, claims) => ({
     path: (req.url ?? '/').split('?')[0],
 });
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Extract the port from an `upstream` URL like `http://localhost:5173`. */
+function lensPortFromUpstream(upstream) {
+    if (!upstream)
+        return undefined;
+    const m = /:(\d+)/.exec(upstream);
+    return m ? Number(m[1]) : undefined;
+}
+/** The base domain for the lens dashboard host — the longest common dotted
+ *  suffix of the declared cluster hosts (e.g. ['api.tetros.ai.local',
+ *  'tetros.ai.local'] → 'tetros.ai.local'). Falls back to the first host, then
+ *  to 'lens.local' if no host is declared. */
+function baseDomainOf(hosts) {
+    const clean = hosts.filter((h) => !!h && !h.startsWith('*.'));
+    if (clean.length === 0)
+        return 'local';
+    // Use the SHORTEST host as the candidate base (most likely the apex), then
+    // require every other host to end with it.
+    const shortest = clean.reduce((a, b) => (b.length < a.length ? b : a));
+    if (clean.every((h) => h === shortest || h.endsWith('.' + shortest)))
+        return shortest;
+    // No clean common apex — derive the trailing 2-3 labels of the shortest host.
+    const parts = shortest.split('.');
+    return parts.slice(-Math.min(parts.length, 3)).join('.');
+}
 /** Round-robin over the pool's sockets, rescanning the dir when the cache ages out. */
 function pickSock(pool, scanTtlMs = 1500) {
     const now = Date.now();
@@ -113,11 +139,24 @@ function discoverRoutes(rootDir, projects, sockBaseDir = os.tmpdir()) {
         let pool;
         let svc;
         let target;
+        let lens;
         if (decl.service) {
+            // `lens` applies to FRONTEND apps only; a pod service is already
+            // instrumented by the serve executor's node-instrumentation graft.
+            if (decl.lens)
+                console.warn(`[gateway] ${name}: cluster.lens is ignored for pod (service) decls — backends are instrumented by serve-hmr.`);
             pool = { dir: path.join(sockBaseDir, `${decl.service}-devserver`), socks: [], idx: -1, scannedAt: 0 };
             svc = { project: name, decl, pool, state: 'down', lastUsed: Date.now(), inflight: 0, lastScaleAt: 0 };
             services.push(svc);
         }
+        else if (decl.lens) {
+            // Lens-mode frontend: the gateway SPAWNS this app's Vite + instrumentation
+            // (deterministically on `port`) and upstreams to it. One LensFrontend per
+            // project is SHARED across its host/default routes (so the spawn fires once).
+            const port = decl.port ?? lensPortFromUpstream(decl.upstream) ?? 5173;
+            target = `http://localhost:${port}`;
+            lens = { project: name, projectRoot: path.join(rootDir, p.root), port };
+        }
         else {
             target = decl.upstream ?? (decl.port ? `http://localhost:${decl.port}` : undefined);
             if (!target) {
@@ -125,7 +164,7 @@ function discoverRoutes(rootDir, projects, sockBaseDir = os.tmpdir()) {
                 continue;
             }
         }
-        const base = { project: name, prependPrefix: decl.prependPrefix, target, pool, svc, prefix: decl.path, auth: decl.auth };
+        const base = { project: name, prependPrefix: decl.prependPrefix, target, pool, svc, prefix: decl.path, auth: decl.auth, lens };
         if (decl.host) {
             routes.push({ ...base, host: decl.host });
             // internal.<host>: east-west traffic, same pods, NO middleware.
@@ -222,6 +261,104 @@ async function startGateway(options, context) {
     if (routes.length === 0) {
         throw new Error('[gateway] no project declares a `cluster` field — nothing to route.');
     }
+    // --- lens-mode children: the dashboard + MCP SINGLETONS, and `lens:true` apps ---
+    // The gateway owns ONE dashboard and ONE MCP server cluster-wide (each
+    // `lens:true` app runs only its Vite + instrumentation, publishing to the
+    // SHARED event bus — never its own dashboard/MCP, which would collide on
+    // :4321 / :3000). These children share the pods' lifecycle: best-effort
+    // (a crash doesn't tear the gateway down) and reaped on stop().
+    const lensChildren = [];
+    const lensRespawn = new Map();
+    // A `SpawnChild` over the gateway's managed-children array — the SAME shape
+    // `agent-dev` passes to `spawnLensFrontend`, so the helper behaves identically.
+    const spawnManagedChild = (label, bin, args, env, optional = false, respawn) => {
+        const child = (0, node_child_process_1.spawn)(bin, args, { cwd: context.root, env: { ...process.env, ...(env ?? {}) }, stdio: 'inherit' });
+        lensChildren.push(child);
+        child.on('exit', (code, sig) => {
+            if (stopped)
+                return;
+            if (optional && respawn) {
+                const used = lensRespawn.get(label) ?? 0;
+                if (used < respawn.max) {
+                    lensRespawn.set(label, used + 1);
+                    console.warn(`[gateway] lens child ${label} exited (code=${code} sig=${sig}); respawning in ${Math.round(respawn.delayMs / 1000)}s (${used + 1}/${respawn.max}).`);
+                    const t = setTimeout(() => { if (!stopped)
+                        spawnManagedChild(label, bin, args, env, optional, respawn); }, respawn.delayMs);
+                    t.unref?.();
+                    return;
+                }
+            }
+            // Singletons (dashboard/MCP) and exhausted-respawn children just log —
+            // a dead dashboard must never kill the cluster.
+            console.warn(`[gateway] lens child ${label} exited (code=${code} sig=${sig}); continuing.`);
+        });
+        return child;
+    };
+    const lensApps = [...new Map(routes.filter((r) => r.lens).map((r) => [r.project, r.lens])).values()];
+    const wantDashboard = options.dashboard !== false;
+    const wantMcp = options.mcp !== false && lensApps.length > 0;
+    if (wantDashboard) {
+        const dashboardBundle = (0, lens_frontend_1.findDashboardBundle)(context.root);
+        if (!dashboardBundle) {
+            console.warn("[gateway] lens dashboard bundle not found — skipping. Install the self-contained CLI: `npm i -D lensmcp` (it ships `bundled/dashboard.js`), or `yarn nx build @lensmcp/lensmcp-mcp` in-repo.");
+        }
+        else {
+            const dashboardPort = options.dashboardPort ?? 4321;
+            const declaredHosts = routes.map((r) => r.host).filter((h) => !!h);
+            const lensHost = options.lensHost ?? `lens.${baseDomainOf(declaredHosts)}`;
+            // Route the dashboard at lens.<baseDomain> (plain TCP upstream — the
+            // dashboard serves HTTP same-origin JSON; the gateway terminates TLS).
+            // Pushed BEFORE the cert SANs are derived (routes.map(r=>r.host)).
+            routes.push({ host: lensHost, project: '(lens-dashboard)', target: `http://localhost:${dashboardPort}` });
+            (0, manifest_1.sortBySpecificity)(routes);
+            console.log(`[gateway] starting lens dashboard → http://localhost:${dashboardPort} (routed at ${lensHost})`);
+            emit('info', `lens dashboard up: ${lensHost} → :${dashboardPort}`, 'cluster-lens-dashboard', { kind: 'lens-dashboard-up', host: lensHost, port: dashboardPort });
+            spawnManagedChild('lens-dashboard', process.execPath, [dashboardBundle], {
+                LENSMCP_EVENT_FILE: eventFile,
+                LENSMCP_DASHBOARD_PORT: String(dashboardPort),
+            });
+        }
+    }
+    if (wantMcp) {
+        const mcpBundle = (0, lens_frontend_1.findMcpBundle)(context.root);
+        if (!mcpBundle) {
+            console.warn("[gateway] MCP server bundle not found — skipping (lens apps will still publish to the bus; an external `lensmcp mcp` can read it). Install: `npm i -D lensmcp`.");
+        }
+        else {
+            console.log(`[gateway] starting lens MCP server (${mcpBundle})`);
+            spawnManagedChild('lens-mcp', process.execPath, [mcpBundle], {
+                LENSMCP_EVENT_FILE: eventFile,
+                LENSMCP_TRANSPORT: process.env['LENSMCP_TRANSPORT'] ?? 'http',
+                LENSMCP_PORT: process.env['LENSMCP_PORT'] ?? '3000',
+            });
+        }
+    }
+    // Spawn each `lens:true` frontend's Vite + browser capture as the upstream,
+    // via the SAME shared helper `agent-dev` uses (singletons excluded — owned above).
+    for (const app of lensApps) {
+        if (app.started)
+            continue;
+        app.started = true;
+        try {
+            (0, lens_frontend_1.spawnLensFrontend)({
+                projectRoot: app.projectRoot,
+                workspaceRoot: context.root,
+                project: app.project,
+                eventFile,
+                port: app.port,
+                chrome: true,
+                headless: true,
+                // Identify this app's events on the shared bus (mirrors the serve
+                // executor's LENSMCP_PROJECT stamp for pods).
+                viteEnv: { LENSMCP_PROJECT: app.project },
+                log: (l) => console.log(l),
+            }, spawnManagedChild);
+            emit('info', `lens app started: ${app.project} (vite :${app.port})`, `cluster-lens-app:${app.project}`, { kind: 'lens-app-up', project: app.project, port: app.port });
+        }
+        catch (e) {
+            console.error(`[gateway] lens app ${app.project}: ${e.message}`);
+        }
+    }
     // --- service lifecycle: scale-from-zero, autoscale, idle kill ----------------
     const scanNow = (pool) => { pool.scannedAt = 0; return pickSock(pool, scanTtlMs) ? pool.socks.length : 0; };
     const spawnService = (svc) => {
@@ -786,6 +923,14 @@ async function startGateway(options, context) {
         emit('info', 'gateway down', 'cluster-gateway', { kind: 'gateway-down' });
         for (const svc of services)
             killSpawned(svc, 'gateway shutdown');
+        // Reap the lens-mode managed children (dashboard + MCP singletons + each
+        // `lens:true` app's Vite/capture) — same teardown as the pod services.
+        for (const c of lensChildren) {
+            try {
+                c.kill('SIGTERM');
+            }
+            catch { /* already gone */ }
+        }
         await Promise.all(servers.map((s) => new Promise((r) => s.close(() => r()))));
         try {
             proxy.close?.();

package/executors/gateway/schema.d.ts

@@ -7,4 +7,12 @@ export interface GatewayExecutorSchema {
   trafficFlushMs?: number;
   /** Workspace-relative path to a per-request middleware module (the JWT seam). */
   middleware?: string;
+  /** Spawn the lens dashboard as a gateway-managed child + route lens.<baseDomain>. Default true. */
+  dashboard?: boolean;
+  /** Spawn the single MCP server as a gateway-managed child when a `lens:true` app exists. Default true. */
+  mcp?: boolean;
+  /** Port the managed dashboard listens on (proxied behind lens.<baseDomain>). Default 4321. */
+  dashboardPort?: number;
+  /** Override the dashboard hostname. Default lens.<baseDomain>. */
+  lensHost?: string;
 }

package/executors/gateway/schema.json

@@ -24,6 +24,25 @@
     "trafficFlushMs": {
       "type": "number",
       "description": "Traffic-edge aggregation window in ms before flushing to the LensMCP bus. Default 5000; lower (e.g. 1000) for near-realtime canvases."
+    },
+    "dashboard": {
+      "type": "boolean",
+      "default": true,
+      "description": "Spawn the LensMCP dashboard (the human web view of the lens) as a gateway-managed child and route it at lens.<baseDomain>. The gateway also owns the single MCP server, so `lens:true` frontend apps run only their Vite + instrumentation. Set false to skip (e.g. when a separate `lensmcp dashboard` is already running)."
+    },
+    "mcp": {
+      "type": "boolean",
+      "default": true,
+      "description": "Spawn the single LensMCP MCP server (the agent surface) as a gateway-managed child when any `lens:true` frontend app is declared. Set false if an external `lensmcp mcp` / agent-dev already owns it."
+    },
+    "dashboardPort": {
+      "type": "number",
+      "default": 4321,
+      "description": "Port the gateway-managed dashboard listens on (proxied behind lens.<baseDomain>). Default 4321."
+    },
+    "lensHost": {
+      "type": "string",
+      "description": "Override the dashboard's dev hostname. Default lens.<baseDomain>, where <baseDomain> is the longest common dotted suffix of the declared cluster hosts (e.g. lens.tetros.ai.local)."
     }
   },
   "additionalProperties": false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lensmcp/cluster",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Run your Nx workspace as a local production cluster: pods on unix sockets with true HMR, one https gateway with per-project domains, scale-from-zero, autoscale, idle-kill, local-CA TLS — observed by the LensMCP lens.",
   "main": "./index.js",
   "types": "./index.d.ts",