npm - lensmcp - Versions diffs - 1.7.0 → 1.8.0 - Mend

lensmcp 1.7.0 → 1.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/bundled/cluster-app.js +6 -6
package/bundled/dashboard.js +49 -24
package/lib/cli.d.ts.map +1 -1
package/lib/cli.js +185 -10
package/lib/workspace-scope.d.ts +54 -0
package/lib/workspace-scope.d.ts.map +1 -0
package/lib/workspace-scope.js +94 -0
package/package.json +1 -1

package/bundled/dashboard.js CHANGED Viewed

@@ -20132,6 +20132,7 @@ function buildFlowDetail(rawEvents) {
 // servers/lensmcp-mcp/dist/dashboard.js
 var { session } = createLensSession();
 var PORT = Number(process.env["LENSMCP_DASHBOARD_PORT"] ?? 4321);
+var DASH_BASE = (process.env["LENSMCP_DASHBOARD_BASE"] ?? "").replace(/\/+$/, "");
 async function snapshot2() {
   const uris = session.resources.list().sort();
   const resources = {};
@@ -20437,19 +20438,29 @@ function clusterView() {
 }
 var server = createServer2((req, res) => {
   const url2 = new URL(req.url ?? "/", "http://localhost");
-  if (url2.pathname === "/api/cluster/stream") {
+  let pathname = url2.pathname;
+  if (DASH_BASE) {
+    if (pathname === DASH_BASE) {
+      res.writeHead(302, { location: DASH_BASE + "/" });
+      res.end();
+      return;
+    }
+    if (pathname.startsWith(DASH_BASE + "/"))
+      pathname = pathname.slice(DASH_BASE.length);
+  }
+  if (pathname === "/api/cluster/stream") {
     res.writeHead(200, { "content-type": "text/event-stream", "cache-control": "no-store", connection: "keep-alive" });
     res.write("event: snapshot\ndata: " + JSON.stringify(clusterView()) + "\n\n");
     sseClients.add(res);
     req.on("close", () => sseClients.delete(res));
     return;
   }
-  if (url2.pathname === "/api/cluster") {
+  if (pathname === "/api/cluster") {
     res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
     res.end(JSON.stringify(clusterView()));
     return;
   }
-  if (url2.pathname === "/api/snapshot") {
+  if (pathname === "/api/snapshot") {
     void snapshot2().then((data) => {
       res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
       res.end(JSON.stringify(data));
@@ -20459,20 +20470,20 @@ var server = createServer2((req, res) => {
     });
     return;
   }
-  if (url2.pathname === "/api/flow") {
+  if (pathname === "/api/flow") {
     const id = url2.searchParams.get("id") ?? "";
     res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
     res.end(JSON.stringify(flowDetail(id)));
     return;
   }
-  if (url2.pathname === "/api/logs") {
+  if (pathname === "/api/logs") {
     const since = Number(url2.searchParams.get("since") ?? "0");
     const events = since > 0 ? logBuffer.filter((l) => l.seq > since) : logBuffer.slice(-2e3);
     res.writeHead(200, { "content-type": "application/json", "cache-control": "no-store" });
     res.end(JSON.stringify({ seq: logSeq, sources: [...logSources].sort(), events }));
     return;
   }
-  const assetMatch = url2.pathname.match(/^\/assets\/((?:cluster|flow)-app\.(?:js|css))$/);
+  const assetMatch = pathname.match(/^\/assets\/((?:cluster|flow)-app\.(?:js|css))$/);
   if (assetMatch) {
     try {
       const name = assetMatch[1];
@@ -20504,6 +20515,7 @@ process.on("SIGTERM", shutdown);
 var PAGE = `<!doctype html>
 <html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
 <title>LensMCP lens</title>
+<script>window.__LENS_BASE__=${JSON.stringify(DASH_BASE)};function U(p){return (window.__LENS_BASE__||'')+p;}</script>
 <style>
   :root { color-scheme: dark; }
   * { box-sizing: border-box; }
@@ -20706,18 +20718,18 @@ var PAGE = `<!doctype html>
   .canvas .react-flow__edge-text { fill: #9fb8d8; font: 600 10px ui-monospace, Menlo, monospace; }
   .grp-urls .url:hover { text-decoration: underline; }
 </style>
-<link rel="stylesheet" href="/assets/cluster-app.css">
-<link rel="stylesheet" href="/assets/flow-app.css">
+<link rel="stylesheet" href="${DASH_BASE}/assets/cluster-app.css">
+<link rel="stylesheet" href="${DASH_BASE}/assets/flow-app.css">
 </head>
 <body>
 <header>
   <span class="dot off" id="dot"></span>
   <strong>LensMCP</strong><span class="muted">lens</span>
   <nav class="tabs" id="tabs">
-    <a href="#/flows" data-view="flows">Flows</a>
-    <a href="#/cluster" data-view="cluster">Cluster</a>
-    <a href="#/logs" data-view="logs">Logs</a>
-    <a href="#/resources" data-view="resources">Resources</a>
+    <a href="${DASH_BASE}/flows" data-view="flows">Flows</a>
+    <a href="${DASH_BASE}/cluster" data-view="cluster">Cluster</a>
+    <a href="${DASH_BASE}/logs" data-view="logs">Logs</a>
+    <a href="${DASH_BASE}/resources" data-view="resources">Resources</a>
   </nav>
   <span class="count" id="count">connecting\u2026</span>
   <span class="updated muted" id="updated"></span>
@@ -21061,7 +21073,7 @@ var PAGE = `<!doctype html>
   function selectFlow(flowId) {
     selectedFlow = flowId;
-    fetch('/api/flow?id=' + encodeURIComponent(flowId))
+    fetch(U('/api/flow?id=' + encodeURIComponent(flowId)))
       .then(function (r) { return r.json(); })
       .then(renderFlowChart)
       .catch(function () { /* next poll retries */ });
@@ -21143,7 +21155,7 @@ var PAGE = `<!doctype html>
   function fmtLogTime(ms) { var d = new Date(ms); return p2(d.getHours()) + ':' + p2(d.getMinutes()) + ':' + p2(d.getSeconds()) + '.' + p2(d.getMilliseconds(), 3); }
   function logRowEl(r) {
     var row = el('div', 'log-row sev-' + r.severity);
-    if (r.flowId) { row.className += ' jump'; row.title = 'open flow ' + r.flowId; row.addEventListener('click', function () { selectedFlow = r.flowId; location.hash = '#/flows'; }); }
+    if (r.flowId) { row.className += ' jump'; row.title = 'open flow ' + r.flowId; row.addEventListener('click', function () { selectedFlow = r.flowId; navTo('flows'); }); }
     row.appendChild(el('span', 'l-time', fmtLogTime(r.at)));
     row.appendChild(el('span', 'l-src', r.source));
     row.appendChild(el('span', 'l-sev', r.severity));
@@ -21175,7 +21187,7 @@ var PAGE = `<!doctype html>
     sel.value = cur;
   }
   function pollLogs() {
-    fetch('/api/logs?since=' + logSeqSeen).then(function (r) { return r.json(); })
+    fetch(U('/api/logs?since=' + logSeqSeen)).then(function (r) { return r.json(); })
       .then(function (d) {
         refreshLogSources(d.sources || []);
         var fresh = d.events || [];
@@ -21200,11 +21212,18 @@ var PAGE = `<!doctype html>
     document.getElementById('logs-clear').addEventListener('click', function () { logRows = []; renderLogs(); });
   })();
-  // ---- navigation (hash router: #/flows | #/cluster | #/logs | #/resources) ----
+  // ---- navigation (history/path router: <base>/flows | /cluster | /logs | /resources) ----
   var VIEWS = ['flows', 'cluster', 'logs', 'resources'];
   function currentView() {
-    var h = (location.hash || '').replace('#/', '');
-    return VIEWS.indexOf(h) >= 0 ? h : 'flows';
+    var base = window.__LENS_BASE__ || '';
+    var p = location.pathname;
+    if (base && p.indexOf(base) === 0) p = p.slice(base.length);
+    var seg = p.split('/').filter(Boolean)[0] || '';
+    return VIEWS.indexOf(seg) >= 0 ? seg : 'flows';
+  }
+  function navTo(v) {
+    history.pushState(null, '', U('/' + v));
+    applyView();
   }
   function applyView() {
     var v = currentView();
@@ -21216,25 +21235,31 @@ var PAGE = `<!doctype html>
     });
     poll();
   }
-  window.addEventListener('hashchange', applyView);
+  window.addEventListener('popstate', applyView);
+  document.getElementById('tabs').addEventListener('click', function (e) {
+    var a = e.target && e.target.closest ? e.target.closest('a[data-view]') : null;
+    if (!a) return;
+    e.preventDefault();
+    navTo(a.getAttribute('data-view'));
+  });
   function poll() {
     var v = currentView();
     if (v === 'logs') { pollLogs(); return; }
     if (v === 'cluster') {
       // the React app renders the canvas; the shell still owns the header dot
-      fetch('/api/cluster').then(function (r) { return r.json(); })
+      fetch(U('/api/cluster')).then(function (r) { return r.json(); })
         .then(function (c) { setStatus(true, c); document.getElementById('count').textContent = (c.decls ? c.decls.length : 0) + ' services \xB7 ' + (c.edges ? c.edges.length : 0) + ' edges'; })
         .catch(function () { setStatus(false); });
       return;
     }
-    fetch('/api/snapshot').then(function (r) { return r.json(); })
+    fetch(U('/api/snapshot')).then(function (r) { return r.json(); })
       .then(function (snap) {
         renderFlowChips(snap);
         if (v === 'resources') renderPanels(snap);
         setStatus(true, snap);
         if (v === 'flows' && selectedFlow) {
-          fetch('/api/flow?id=' + encodeURIComponent(selectedFlow))
+          fetch(U('/api/flow?id=' + encodeURIComponent(selectedFlow)))
             .then(function (r) { return r.json(); })
             .then(renderFlowChart)
             .catch(function () {});
@@ -21244,6 +21269,6 @@ var PAGE = `<!doctype html>
   }
   setInterval(poll, POLL_MS); applyView();
 </script>
-<script defer src="/assets/cluster-app.js"></script>
-<script defer src="/assets/flow-app.js"></script>
+<script defer src="${DASH_BASE}/assets/cluster-app.js"></script>
+<script defer src="${DASH_BASE}/assets/flow-app.js"></script>
 </body></html>`;

package/lib/cli.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/lib/cli.ts"],"names":[],"mappings":"~~AAKA~~,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,UAAU;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,gEAAgE;IAChE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;~~AA0CD~~,wBAAsB,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,~~CAkChE~~"}
1	+ {"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/lib/cli.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,UAAU,UAAU;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,4EAA4E;IAC5E,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,qDAAqD;IACrD,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,gEAAgE;IAChE,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAoDD,wBAAsB,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAoChE"}

package/lib/cli.js CHANGED Viewed

@@ -1,7 +1,8 @@
-import { spawnSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, readdirSync } from 'node:fs';
+import { spawn, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, openSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { ensureLensConfig } from './workspace-scope.js';
 const HELP = `lensmcp — CLI for LensMCP (FrontMCP-based observability for coding agents)
 Usage:
@@ -12,10 +13,20 @@ Commands:
                        Launch the LensMCP MCP server. Default transport is
                        stdio (set LENSMCP_TRANSPORT=http or pass --transport
                        for HTTP on --port, default 3000).
-  dashboard [--cwd <dir>] [--port <n>]
+  dashboard [--cwd <dir>] [--port <n>] [--base <path>]
                        Serve a live web view of the lens (flows, signals,
-                       stories, status) on --port (default 4321). Reads the
-                       same .lensmcp/events.jsonl your agent-dev producers write.
+                       stories, status). Port defaults to the per-workspace
+                       derived port (see \`.lensmcp/config.json\`); --base mounts
+                       it under a path prefix (e.g. /tetros) for its history
+                       router. Reads the same .lensmcp/events.jsonl your
+                       agent-dev producers write.
+  gateway <start|stop|status|restart> [--cwd <dir>] [--project <p>] [--target <t>]
+                       Run the dev cluster gateway (one HTTPS front door that
+                       reads every project.json \`cluster\` decl and launches all
+                       apps/services under their hosts) AND the per-workspace
+                       lens dashboard at https://lensmcp.local/<key>/. \`start\`
+                       spawns it detached (pid+log in .lensmcp/); \`stop\` ends it;
+                       \`status\` reports liveness. Binding :443 needs privilege.
   bridge [--cwd <dir>] [--host <h>] [--port <n>]
                        Run the standalone browser-event bridge for hosts with
                        no LensMCP build plugin (webpack, Next.js, no build).
@@ -58,6 +69,8 @@ export async function runCli(ctx) {
             return runMcp(ctx, rest, out, err);
         case 'dashboard':
             return runDashboard(ctx, rest, out, err);
+        case 'gateway':
+            return runGateway(ctx, rest, out, err);
         case 'bridge':
             return runBridge(ctx, rest, out, err);
         case 'install':
@@ -78,8 +91,9 @@ function runMcp(ctx, args, _out, err) {
         string: ['--cwd', '--transport', '--port'],
     });
     const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
+    const cfg = ensureLensConfig(cwd);
     const transport = stringFlag(opts.flags['--transport']) ?? ctx.env?.['LENSMCP_TRANSPORT'] ?? 'stdio';
-    const port = stringFlag(opts.flags['--port']) ?? ctx.env?.['LENSMCP_PORT'] ?? '3000';
+    const port = stringFlag(opts.flags['--port']) ?? ctx.env?.['LENSMCP_PORT'] ?? String(cfg.ports.mcpHttp);
     const binPath = findMcpBinary(cwd);
     if (!binPath) {
         err('Could not locate the lensmcp-mcp server bundle.\n' +
@@ -111,9 +125,15 @@ function runMcp(ctx, args, _out, err) {
     return { exitCode: result.status ?? 1 };
 }
 function runDashboard(ctx, args, out, err) {
-    const opts = parseFlags(args, { string: ['--cwd', '--port'] });
+    const opts = parseFlags(args, { string: ['--cwd', '--port', '--base'] });
     const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
-    const port = stringFlag(opts.flags['--port']) ?? ctx.env?.['LENSMCP_DASHBOARD_PORT'] ?? '4321';
+    const cfg = ensureLensConfig(cwd);
+    const port = stringFlag(opts.flags['--port']) ??
+        ctx.env?.['LENSMCP_DASHBOARD_PORT'] ??
+        String(cfg.ports.dashboard);
+    // Standalone defaults to root (''); the cluster gateway passes --base /<key> so the
+    // dashboard's history router + same-origin URLs resolve under lensmcp.local/<key>/.
+    const base = stringFlag(opts.flags['--base']) ?? ctx.env?.['LENSMCP_DASHBOARD_BASE'] ?? '';
     const binPath = findServerBundle(cwd, 'dashboard.js');
     if (!binPath) {
         err('Could not locate the lensmcp dashboard bundle.\n' +
@@ -129,7 +149,7 @@ function runDashboard(ctx, args, out, err) {
     const eventFile = ctx.env?.['LENSMCP_EVENT_FILE'] ??
         process.env['LENSMCP_EVENT_FILE'] ??
         join(cwd, '.lensmcp', 'events.jsonl');
-    out(`lensmcp dashboard → http://localhost:${port}  (reading ${eventFile})`);
+    out(`lensmcp dashboard → http://localhost:${port}${base || '/'}  (reading ${eventFile})`);
     const result = spawnSync(process.execPath, [binPath], {
         cwd,
         stdio: 'inherit',
@@ -137,16 +157,171 @@ function runDashboard(ctx, args, out, err) {
             ...process.env,
             ...(ctx.env ?? {}),
             LENSMCP_DASHBOARD_PORT: port,
+            LENSMCP_DASHBOARD_BASE: base,
             LENSMCP_EVENT_FILE: eventFile,
         },
     });
     return { exitCode: result.status ?? 1 };
 }
+/**
+ * `lensmcp gateway <start|stop|status|restart>` — drive the dev cluster gateway as a
+ * detached background process. The gateway (the `@lensmcp/cluster:gateway` executor)
+ * reads every project.json `cluster` decl, launches each app/service under its host on
+ * :443, and serves the per-workspace lens dashboard at https://lensmcp.local/<key>/.
+ * This wraps it so a single command (and the Claude Code plugin) can bring it up/down.
+ */
+function runGateway(ctx, args, out, err) {
+    const opts = parseFlags(args, { string: ['--cwd', '--project', '--target'] });
+    const sub = (opts.positional[0] ?? 'status').toLowerCase();
+    const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
+    const cfg = ensureLensConfig(cwd);
+    const pidFile = join(cwd, '.lensmcp', 'gateway.pid');
+    const logFile = join(cwd, '.lensmcp', 'gateway.log');
+    const dashUrl = `https://lensmcp.local${cfg.dashboardBasePath}/`;
+    const start = () => {
+        const running = readPid(pidFile);
+        if (running && isAlive(running)) {
+            out(`gateway already running (pid ${running}).`);
+            out(`  dashboard → ${dashUrl}`);
+            return { exitCode: 0 };
+        }
+        const target = findGatewayTarget(cwd, stringFlag(opts.flags['--project']), stringFlag(opts.flags['--target']));
+        if (!target) {
+            err('Could not find a gateway target (an executor `@lensmcp/cluster:gateway`) in this workspace.\n' +
+                'Pass --project <p> --target <t>, or add a gateway project (see @lensmcp/cluster).');
+            return { exitCode: 1 };
+        }
+        const nxBin = findNxBinary(cwd);
+        if (!nxBin) {
+            err('Could not find the `nx` binary in the workspace. Install Nx first: `yarn add -D nx`.');
+            return { exitCode: 1 };
+        }
+        const fd = openSync(logFile, 'a');
+        const child = spawn(nxBin, ['run', `${target.project}:${target.target}`], {
+            cwd,
+            detached: true,
+            stdio: ['ignore', fd, fd],
+            env: { ...process.env, ...(ctx.env ?? {}) },
+        });
+        child.unref();
+        if (child.pid)
+            writeFileSync(pidFile, String(child.pid));
+        out(`gateway starting → ${target.project}:${target.target}  (pid ${child.pid ?? '?'})`);
+        out(`  dashboard → ${dashUrl}`);
+        out(`  logs      → ${logFile}`);
+        out('  note: binding :443 needs privilege — if it fails, run the gateway target with sudo,');
+        out('        and run `nx run gateway:trust` once for the *.local hosts + TLS.');
+        return { exitCode: 0 };
+    };
+    const stop = () => {
+        const pid = readPid(pidFile);
+        if (!pid || !isAlive(pid)) {
+            out('gateway not running.');
+            rmFile(pidFile);
+            return { exitCode: 0 };
+        }
+        // Detached child is its own process-group leader → negative pid kills the whole tree.
+        try {
+            process.kill(-pid, 'SIGTERM');
+        }
+        catch {
+            try {
+                process.kill(pid, 'SIGTERM');
+            }
+            catch {
+                /* already gone */
+            }
+        }
+        rmFile(pidFile);
+        out(`gateway stopped (pid ${pid}).`);
+        return { exitCode: 0 };
+    };
+    const status = () => {
+        const pid = readPid(pidFile);
+        const alive = pid !== undefined && isAlive(pid);
+        out(`gateway: ${alive ? `running (pid ${pid})` : 'stopped'}`);
+        out(`  workspace → ${cfg.key}`);
+        out(`  dashboard → ${dashUrl}`);
+        if (alive)
+            out(`  logs      → ${logFile}`);
+        return { exitCode: alive ? 0 : 1 };
+    };
+    switch (sub) {
+        case 'start':
+            return start();
+        case 'stop':
+            return stop();
+        case 'restart':
+            stop();
+            return start();
+        case 'status':
+            return status();
+        default:
+            err(`Unknown gateway subcommand: ${sub} (use start | stop | status | restart)`);
+            return { exitCode: 2 };
+    }
+}
+/** Find a project + target whose executor is `@lensmcp/cluster:gateway`. An explicit
+ *  `project`/`target` short-circuits the scan; otherwise we read each project.json. */
+function findGatewayTarget(cwd, project, target) {
+    if (project && target)
+        return { project, target };
+    const files = walkProjectFiles(cwd, (n) => n === 'project.json');
+    for (const f of files) {
+        let pj;
+        try {
+            pj = JSON.parse(safeRead(f));
+        }
+        catch {
+            continue;
+        }
+        const name = pj.name ?? basename(dirname(f));
+        for (const [t, def] of Object.entries(pj.targets ?? {})) {
+            if (def.executor === '@lensmcp/cluster:gateway') {
+                return { project: project ?? name, target: target ?? t };
+            }
+        }
+    }
+    // Sensible fallback used by most workspaces (tetros: tools/gateway → `gateway:serve`).
+    return project || target ? { project: project ?? 'gateway', target: target ?? 'serve' } : undefined;
+}
+function readPid(pidFile) {
+    try {
+        const n = Number(readFileSync(pidFile, 'utf8').trim());
+        return Number.isInteger(n) && n > 0 ? n : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** `kill(pid, 0)` probes liveness without signalling — throws ESRCH if the pid is gone. */
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM'; // exists but not ours
+    }
+}
+function rmFile(path) {
+    try {
+        if (existsSync(path))
+            writeFileSync(path, '');
+    }
+    catch {
+        /* ignore */
+    }
+}
 function runBridge(ctx, args, out, err) {
     const opts = parseFlags(args, { string: ['--cwd', '--host', '--port'] });
     const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
+    const cfg = ensureLensConfig(cwd);
     const host = stringFlag(opts.flags['--host']) ?? ctx.env?.['LENSMCP_WS_HOST'] ?? process.env['LENSMCP_WS_HOST'];
-    const port = stringFlag(opts.flags['--port']) ?? ctx.env?.['LENSMCP_WS_PORT'] ?? process.env['LENSMCP_WS_PORT'];
+    const port = stringFlag(opts.flags['--port']) ??
+        ctx.env?.['LENSMCP_WS_PORT'] ??
+        process.env['LENSMCP_WS_PORT'] ??
+        String(cfg.ports.bridge);
     const binPath = findBridgeBundle(cwd);
     if (!binPath) {
         err('Could not locate the lensmcp bridge bundle.\n' +

package/lib/workspace-scope.d.ts ADDED Viewed

@@ -0,0 +1,54 @@
+/**
+ * Per-workspace lens scoping — the contract that lets LensMCP run across MANY
+ * projects without collisions.
+ *
+ * A "project" is identified by its workspace ROOT. Everything keys off a stable
+ * `key` (slug) derived from that root, so two checkouts (tetros, foo, …) get:
+ *   • their OWN dashboard / mcp-http / bridge ports (deterministic offset), and
+ *   • their OWN dashboard mount path (`/<key>`) when served behind the gateway,
+ * while the event bus is already isolated by path (`<root>/.lensmcp/events.jsonl`).
+ *
+ * This module is intentionally dependency-free (the published `lensmcp` CLI bundles
+ * no `@lensmcp/*`), so it is the canonical source the CLI reads; the cluster gateway
+ * mirrors the same derivation from `@lensmcp/core`. Keep the two in lock-step — the
+ * `workspace-scope.spec.ts` pins the derived values.
+ */
+export interface LensPorts {
+    /** The human dashboard server port (loopback; the gateway proxies a host→here). */
+    dashboard: number;
+    /** The MCP server HTTP port (only used when transport=http; stdio ignores it). */
+    mcpHttp: number;
+    /** The standalone browser-event bridge WebSocket port. */
+    bridge: number;
+}
+export interface LensConfig {
+    schemaVersion: 1;
+    /** Stable workspace slug, e.g. `tetros`. */
+    key: string;
+    ports: LensPorts;
+    /** Dashboard mount path behind the gateway, e.g. `/tetros`. */
+    dashboardBasePath: string;
+}
+/** Lowercase kebab slug; empty input → `workspace`. */
+export declare function slugify(input: string): string;
+/**
+ * The workspace key = the project's lens identity. Resolution order:
+ *   1. nx.json  `lensmcp.key`            (explicit override)
+ *   2. root package.json `name`          (usually the repo name, e.g. "tetros")
+ *   3. nx.json  `name`
+ *   4. basename(root)
+ */
+export declare function resolveWorkspaceKey(root: string): string;
+export declare function derivePorts(key: string): LensPorts;
+/** The fully-derived config for a workspace (before any on-disk override). */
+export declare function deriveConfig(root: string): LensConfig;
+/**
+ * Read `<root>/.lensmcp/config.json` if present, else the derived defaults. A present
+ * file OVERRIDES derived values field-by-field (so a user can pin a key/port without
+ * losing the rest), and is the seam the gateway + CLI both read so they agree.
+ */
+export declare function readLensConfig(root: string): LensConfig;
+/** Persist the (derived/merged) config so it is visible + overridable. Idempotent;
+ *  only writes when the on-disk content would change. */
+export declare function ensureLensConfig(root: string): LensConfig;
+//# sourceMappingURL=workspace-scope.d.ts.map

package/lib/workspace-scope.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"workspace-scope.d.ts","sourceRoot":"","sources":["../../src/lib/workspace-scope.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,WAAW,SAAS;IACxB,mFAAmF;IACnF,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,CAAC,CAAC;IACjB,4CAA4C;IAC5C,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,SAAS,CAAC;IACjB,+DAA+D;IAC/D,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAaD,uDAAuD;AACvD,wBAAgB,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOxD;AAOD,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAOlD;AAED,8EAA8E;AAC9E,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAGrD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAWvD;AAED;yDACyD;AACzD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAQzD"}

package/lib/workspace-scope.js ADDED Viewed

@@ -0,0 +1,94 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+/** Deterministic 0..(range-1) from a string (FNV-1a). Stable across runs/machines —
+ *  the same workspace always derives the same ports, so restarts never drift. */
+function hashToRange(s, range) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return Math.abs(h | 0) % range;
+}
+/** Lowercase kebab slug; empty input → `workspace`. */
+export function slugify(input) {
+    return (input
+        .toLowerCase()
+        .replace(/^@[^/]+\//, '') // drop an npm scope (@acme/foo → foo)
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/(^-|-$)/g, '') || 'workspace');
+}
+/**
+ * The workspace key = the project's lens identity. Resolution order:
+ *   1. nx.json  `lensmcp.key`            (explicit override)
+ *   2. root package.json `name`          (usually the repo name, e.g. "tetros")
+ *   3. nx.json  `name`
+ *   4. basename(root)
+ */
+export function resolveWorkspaceKey(root) {
+    const nx = readJson(join(root, 'nx.json'));
+    if (nx?.lensmcp?.key)
+        return slugify(nx.lensmcp.key);
+    const pkg = readJson(join(root, 'package.json'));
+    if (pkg?.name)
+        return slugify(pkg.name);
+    if (nx?.name)
+        return slugify(nx.name);
+    return slugify(basename(root));
+}
+/** Lens-infra port bases. Chosen to avoid typical app/service ranges (3000-3999
+ *  for services, 5173+ for Vite); the per-key offset keeps two projects' standalone
+ *  lens processes from clashing. */
+const BASE_PORTS = { dashboard: 4321, mcpHttp: 4500, bridge: 5747 };
+export function derivePorts(key) {
+    const off = hashToRange(key, 200); // 0..199
+    return {
+        dashboard: BASE_PORTS.dashboard + off,
+        mcpHttp: BASE_PORTS.mcpHttp + off,
+        bridge: BASE_PORTS.bridge + off,
+    };
+}
+/** The fully-derived config for a workspace (before any on-disk override). */
+export function deriveConfig(root) {
+    const key = resolveWorkspaceKey(root);
+    return { schemaVersion: 1, key, ports: derivePorts(key), dashboardBasePath: '/' + key };
+}
+/**
+ * Read `<root>/.lensmcp/config.json` if present, else the derived defaults. A present
+ * file OVERRIDES derived values field-by-field (so a user can pin a key/port without
+ * losing the rest), and is the seam the gateway + CLI both read so they agree.
+ */
+export function readLensConfig(root) {
+    const derived = deriveConfig(root);
+    const file = readJson(join(root, '.lensmcp', 'config.json'));
+    if (!file)
+        return derived;
+    const key = file.key ? slugify(file.key) : derived.key;
+    return {
+        schemaVersion: 1,
+        key,
+        ports: { ...derived.ports, ...(file.ports ?? {}) },
+        dashboardBasePath: file.dashboardBasePath ?? '/' + key,
+    };
+}
+/** Persist the (derived/merged) config so it is visible + overridable. Idempotent;
+ *  only writes when the on-disk content would change. */
+export function ensureLensConfig(root) {
+    const cfg = readLensConfig(root);
+    const dir = join(root, '.lensmcp');
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const path = join(dir, 'config.json');
+    const next = JSON.stringify(cfg, null, 2) + '\n';
+    if (!existsSync(path) || readFileSync(path, 'utf8') !== next)
+        writeFileSync(path, next);
+    return cfg;
+}
+function readJson(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "lensmcp",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "type": "module",
   "main": "./index.js",
   "module": "./index.js",