@lensmcp/cluster 1.0.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) => {
@@ -253,6 +390,7 @@ async function startGateway(options, context) {
             const text = d.toString();
             for (const line of text.split('\n')) {
                 if (/ERROR in |error TS\d+|Found \d+ error|Unhandled 'error' event|EADDRINUSE/.test(line)) {
+                    // eslint-disable-next-line no-control-regex -- strip ANSI color codes from child output
                     svc.lastErrors.push(line.replace(/\x1b\[[0-9;]*m/g, '').trim());
                     if (svc.lastErrors.length > 12)
                         svc.lastErrors.shift();
@@ -785,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/health-check.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Active upstream health-checking — opt-in. Periodically probes every known
+ * upstream URL and tracks healthy/unhealthy per endpoint, so the gateway routes
+ * a pooled service AROUND dead endpoints (instead of only discovering death
+ * passively, one failed request at a time) and the /statusz rollup reflects true
+ * liveness even with zero traffic.
+ *
+ * Liveness, not readiness: a probe is "healthy" when the endpoint ANSWERS with
+ * status < 500 — so a service without the health path still reads up on a 404;
+ * only a 5xx or a connection failure/timeout is down. New endpoints start
+ * optimistically healthy, so a not-yet-probed endpoint is never black-holed.
+ *
+ * Fail-open by design (see providers-prod `pick`): only multi-endpoint POOLS are
+ * health-filtered, and even then the gateway falls back to an unhealthy endpoint
+ * rather than 503 if a whole pool looks down — a checker false-positive must
+ * never take a service fully offline.
+ */
+export interface HealthCheckerOptions {
+    /** Probe path appended to each upstream URL. Default `/healthz`. */
+    path?: string;
+    /** Probe period (ms). Default 5000. */
+    intervalMs?: number;
+    /** Per-probe timeout (ms). Default 2000. */
+    timeoutMs?: number;
+    /** Consecutive failures before an endpoint is marked unhealthy. Default 2. */
+    unhealthyThreshold?: number;
+    /** Consecutive successes before a down endpoint is marked healthy again. Default 1. */
+    healthyThreshold?: number;
+    /** Injectable fetch (tests). Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Notified when an endpoint flips health. */
+    onChange?: (url: string, healthy: boolean) => void;
+}
+export interface EndpointHealth {
+    url: string;
+    healthy: boolean;
+    fails: number;
+    lastCheckedAt: number | null;
+}
+export interface HealthChecker {
+    /** Set the current URL set to monitor (called on every route rebuild). */
+    track(urls: string[]): void;
+    /** Current health (default true for an untracked / not-yet-probed URL). */
+    isHealthy(url: string): boolean;
+    /** Per-endpoint health for the status page. */
+    snapshot(): EndpointHealth[];
+    /** Probe every tracked URL once (used by start()'s loop and by tests). */
+    probeOnce(): Promise<void>;
+    start(): void;
+    stop(): void;
+}
+export declare function createHealthChecker(opts?: HealthCheckerOptions): HealthChecker;
+//# sourceMappingURL=health-check.d.ts.map

package/executors/gateway/health-check.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-check.d.ts","sourceRoot":"","sources":["../../../../../libs/cluster/src/executors/gateway/health-check.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,WAAW,oBAAoB;IACnC,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uCAAuC;IACvC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,uFAAuF;IACvF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0DAA0D;IAC1D,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CACpD;AAED,MAAM,WAAW,cAAc;IAAG,GAAG,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE;AAE9G,MAAM,WAAW,aAAa;IAC5B,0EAA0E;IAC1E,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAC5B,2EAA2E;IAC3E,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,+CAA+C;IAC/C,QAAQ,IAAI,cAAc,EAAE,CAAC;IAC7B,0EAA0E;IAC1E,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,KAAK,IAAI,IAAI,CAAC;IACd,IAAI,IAAI,IAAI,CAAC;CACd;AAID,wBAAgB,mBAAmB,CAAC,IAAI,GAAE,oBAAyB,GAAG,aAAa,CAyClF"}

package/executors/gateway/health-check.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createHealthChecker = createHealthChecker;
+function createHealthChecker(opts = {}) {
+    const path = opts.path ?? '/healthz';
+    const intervalMs = opts.intervalMs ?? 5000;
+    const timeoutMs = opts.timeoutMs ?? 2000;
+    const downAt = Math.max(1, opts.unhealthyThreshold ?? 2);
+    const upAt = Math.max(1, opts.healthyThreshold ?? 1);
+    const doFetch = opts.fetchImpl ?? globalThis.fetch;
+    const state = new Map();
+    let timer;
+    const probeUrl = (url) => url.replace(/\/+$/, '') + (path.startsWith('/') ? path : '/' + path);
+    const probe = async (url) => {
+        const st = state.get(url);
+        if (!st)
+            return;
+        let ok = false;
+        const ctl = new AbortController();
+        const t = setTimeout(() => ctl.abort(), timeoutMs);
+        try {
+            const res = await doFetch(probeUrl(url), { method: 'GET', signal: ctl.signal, redirect: 'manual' });
+            ok = res.status < 500; // answered → up (even 404); only 5xx counts as down
+        }
+        catch { /* network error / timeout → unhealthy (ok stays false) */ }
+        finally {
+            clearTimeout(t);
+        }
+        st.lastCheckedAt = Date.now();
+        if (ok) {
+            st.oks += 1;
+            st.fails = 0;
+            if (!st.healthy && st.oks >= upAt) {
+                st.healthy = true;
+                opts.onChange?.(url, true);
+            }
+        }
+        else {
+            st.fails += 1;
+            st.oks = 0;
+            if (st.healthy && st.fails >= downAt) {
+                st.healthy = false;
+                opts.onChange?.(url, false);
+            }
+        }
+    };
+    const probeOnce = () => Promise.allSettled([...state.keys()].map(probe)).then(() => undefined);
+    return {
+        track(urls) {
+            const next = new Set(urls);
+            for (const u of urls)
+                if (!state.has(u))
+                    state.set(u, { healthy: true, fails: 0, oks: 0, lastCheckedAt: null });
+            for (const u of [...state.keys()])
+                if (!next.has(u))
+                    state.delete(u);
+        },
+        isHealthy: (url) => state.get(url)?.healthy ?? true,
+        snapshot: () => [...state.entries()].map(([url, s]) => ({ url, healthy: s.healthy, fails: s.fails, lastCheckedAt: s.lastCheckedAt })),
+        probeOnce,
+        start() { if (timer)
+            return; timer = setInterval(() => void probeOnce(), intervalMs); timer.unref?.(); void probeOnce(); },
+        stop() { if (timer)
+            clearInterval(timer); timer = undefined; },
+    };
+}