lensmcp 1.9.0 → 1.11.0

package/bundled/main.js

@@ -11,6 +11,9 @@ function __decorate(decorators, target, key, desc) {
   else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
   return c > 3 && r && Object.defineProperty(target, key, r), r;
 }
+function __metadata(metadataKey, metadataValue) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(metadataKey, metadataValue);
+}
 
 // servers/lensmcp-mcp/dist/main.js
 import "reflect-metadata";
@@ -20232,10 +20235,145 @@ RenderApp = __decorate([
   })
 ], RenderApp);
 
+// servers/lensmcp-mcp/dist/setup-gate/setup.app.js
+import { App as App21 } from "@frontmcp/sdk";
+
+// servers/lensmcp-mcp/dist/setup-gate/setup-status.tool.js
+import { Tool as Tool24, ToolContext as ToolContext24 } from "@frontmcp/sdk";
+
+// servers/lensmcp-mcp/dist/setup-gate/state.js
+import { existsSync as existsSync5, readFileSync as readFileSync3 } from "node:fs";
+import { dirname as dirname3, join as join3 } from "node:path";
+import { fileURLToPath } from "node:url";
+function lensmcpDir() {
+  const eventFile = process.env["LENSMCP_EVENT_FILE"];
+  if (eventFile)
+    return dirname3(eventFile);
+  return join3(process.cwd(), ".lensmcp");
+}
+function readSetupState() {
+  try {
+    const raw = readFileSync3(join3(lensmcpDir(), "setup-state.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    return typeof parsed?.version === "string" ? parsed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function installedVersion() {
+  let dir = dirname3(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    const pkg = join3(dir, "package.json");
+    if (existsSync5(pkg)) {
+      try {
+        const version2 = JSON.parse(readFileSync3(pkg, "utf8")).version;
+        if (version2)
+          return version2;
+      } catch {
+      }
+    }
+    const parent = dirname3(dir);
+    if (parent === dir)
+      break;
+    dir = parent;
+  }
+  return "0.0.0";
+}
+function checkReadiness() {
+  const installed = installedVersion();
+  const state2 = readSetupState();
+  if (!state2)
+    return { ready: false, installedVersion: installed, reason: "never-setup" };
+  if (state2.version !== installed) {
+    return { ready: false, installedVersion: installed, setupVersion: state2.version, reason: "version-mismatch" };
+  }
+  return { ready: true, installedVersion: installed, setupVersion: state2.version };
+}
+function gateDisabled() {
+  const flag = process.env["LENSMCP_NO_SETUP_GATE"];
+  return flag === "1" || flag === "true";
+}
+function setupRequiredMessage(r) {
+  const last = r.reason === "version-mismatch" && r.setupVersion ? `last set up for v${r.setupVersion}` : "not set up on this machine yet";
+  return `LensMCP is not ready: ${last}, but v${r.installedVersion} is installed. Ask the user to run \`lensmcp setup\` once in their terminal \u2014 it installs the plugin wiring and trusts the dev CA + /etc/hosts (sudo prompts inline; idempotent) \u2014 then retry. Call the \`setup.status\` tool any time to re-check.`;
+}
+
+// servers/lensmcp-mcp/dist/setup-gate/setup-status.tool.js
+var SetupStatusTool = class SetupStatusTool2 extends ToolContext24 {
+  async execute() {
+    const readiness = checkReadiness();
+    return {
+      ready: readiness.ready,
+      installedVersion: readiness.installedVersion,
+      setupVersion: readiness.setupVersion ?? null,
+      reason: readiness.reason ?? null,
+      gateDisabled: gateDisabled(),
+      message: readiness.ready ? `LensMCP is set up for v${readiness.installedVersion}. The lens is open.` : setupRequiredMessage(readiness),
+      fix: readiness.ready ? null : "lensmcp setup"
+    };
+  }
+};
+SetupStatusTool = __decorate([
+  Tool24({
+    name: "setup.status",
+    description: "Report whether LensMCP is set up for the installed version on this machine. Always available (exempt from the setup-gate) so the agent can diagnose. If `ready` is false, ask the user to run `lensmcp setup`.",
+    inputSchema: {}
+  })
+], SetupStatusTool);
+var setup_status_tool_default = SetupStatusTool;
+
+// servers/lensmcp-mcp/dist/setup-gate/gate.plugin.js
+import { Plugin, ToolHook } from "@frontmcp/sdk";
+var { Will } = ToolHook;
+var EXEMPT_TOOLS = /* @__PURE__ */ new Set(["setup.status", "lensmcp.session"]);
+var SetupGatePlugin = class SetupGatePlugin2 {
+  enforceSetup(ctx) {
+    if (gateDisabled())
+      return;
+    let readiness;
+    try {
+      readiness = checkReadiness();
+    } catch {
+      return;
+    }
+    if (!readiness.ready)
+      ctx.fail(new Error(setupRequiredMessage(readiness)));
+  }
+};
+__decorate([
+  Will("execute", {
+    priority: 1e4,
+    filter: (ctx) => !EXEMPT_TOOLS.has(ctx.toolName ?? "")
+  }),
+  __metadata("design:type", Function),
+  __metadata("design:paramtypes", [Object]),
+  __metadata("design:returntype", void 0)
+], SetupGatePlugin.prototype, "enforceSetup", null);
+SetupGatePlugin = __decorate([
+  Plugin({
+    name: "lensmcp-setup-gate",
+    description: "Blocks lens tools until the workspace has run `lensmcp setup` for the installed lensmcp version (after install or upgrade). Fails open on error."
+  })
+], SetupGatePlugin);
+
+// servers/lensmcp-mcp/dist/setup-gate/setup.app.js
+var SetupApp = class SetupApp2 {
+};
+SetupApp = __decorate([
+  App21({
+    id: "lensmcp-setup",
+    name: "LensMCP Setup Gate",
+    description: "Readiness gate: blocks lens tools until the workspace has run `lensmcp setup`, plus the always-open `setup.status` diagnostic.",
+    tools: [setup_status_tool_default],
+    plugins: [SetupGatePlugin]
+  })
+], SetupApp);
+
 // servers/lensmcp-mcp/dist/main.js
 var { session, providers } = createLensSession();
 var transport = process.env["LENSMCP_TRANSPORT"] ?? "stdio";
 var apps = [
+  SetupApp,
   MetaApp,
   AgentApp,
   EventsApp,

package/lib/cli.d.ts.map

@@ -1 +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"}
+{"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;AAiED,wBAAsB,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAwChE"}

package/lib/cli.js

@@ -9,6 +9,13 @@ Usage:
   lensmcp <command> [options]
 
 Commands:
+  setup [--cwd <dir>] [--skip-format] [--register-host-config <mode>]
+                       First-time bootstrap — runs \`install\` then \`trust\` in
+                       one idempotent pass: plugin + .mcp.json + nx config +
+                       vite/nest wiring, then the dev CA (System keychain),
+                       /etc/hosts (both families) + DNS flush. sudo self-prompts
+                       only for the steps that need it — run in a real terminal.
+                       Then \`lensmcp gateway start\`.
   mcp [--cwd <dir>] [--transport stdio|http] [--port <n>]
                        Launch the LensMCP MCP server. Default transport is
                        stdio (set LENSMCP_TRANSPORT=http or pass --transport
@@ -38,6 +45,12 @@ Commands:
                        Install LensMCP into the host Nx workspace at --cwd
                        (current directory by default). Delegates to
                        \`nx g @lensmcp/nx-plugin:init\`. Idempotent.
+  trust [--cwd <dir>] [--project <p>] [--target <t>]
+                       Make the HTTPS dev gateway trusted: mint + trust the local
+                       dev CA, write /etc/hosts (127.0.0.1 + ::1) for every
+                       cluster host (+ lensmcp.local), flush DNS. Wraps the
+                       auto-discovered \`@lensmcp/cluster:trust\` target.
+                       Idempotent; sudo prompts inline — run in a terminal.
   doctor [--cwd <dir>] [--json]
                        Diagnose the install: Node, workspace + plugin,
                        .mcp.json server entry, MCP bundle, per-project
@@ -65,6 +78,8 @@ export async function runCli(ctx) {
         return { exitCode: 0 };
     }
     switch (command) {
+        case 'setup':
+            return runSetup(ctx, rest, out, err);
         case 'mcp':
             return runMcp(ctx, rest, out, err);
         case 'dashboard':
@@ -75,6 +90,8 @@ export async function runCli(ctx) {
             return runBridge(ctx, rest, out, err);
         case 'install':
             return runInstall(ctx, rest, out, err);
+        case 'trust':
+            return runTrust(ctx, rest, out, err);
         case 'doctor':
             return runDoctor(ctx, rest, out);
         case 'rollout':
@@ -261,9 +278,10 @@ function runGateway(ctx, args, out, err) {
             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) {
+/** Scan every project.json for the first project carrying a target whose executor
+ *  is `executor`. An explicit project+target short-circuits the scan; a partial
+ *  override fills the missing half from the match. */
+function scanExecutorTarget(cwd, executor, project, target) {
     if (project && target)
         return { project, target };
     const files = walkProjectFiles(cwd, (n) => n === 'project.json');
@@ -277,14 +295,30 @@ function findGatewayTarget(cwd, project, target) {
         }
         const name = pj.name ?? basename(dirname(f));
         for (const [t, def] of Object.entries(pj.targets ?? {})) {
-            if (def.executor === '@lensmcp/cluster:gateway') {
+            if (def.executor === executor) {
                 return { project: project ?? name, target: target ?? t };
             }
         }
     }
+    return undefined;
+}
+/** Find a project + target whose executor is `@lensmcp/cluster:gateway`. */
+function findGatewayTarget(cwd, project, target) {
+    const found = scanExecutorTarget(cwd, '@lensmcp/cluster:gateway', project, target);
+    if (found)
+        return found;
     // Sensible fallback used by most workspaces (tetros: tools/gateway → `gateway:serve`).
     return project || target ? { project: project ?? 'gateway', target: target ?? 'serve' } : undefined;
 }
+/** Find a project + target whose executor is `@lensmcp/cluster:trust`. Falls back
+ *  unconditionally to `gateway:trust` — the conventional home the init generator
+ *  scaffolds — since trust is idempotent and safe to attempt anywhere. */
+function findTrustTarget(cwd, project, target) {
+    return (scanExecutorTarget(cwd, '@lensmcp/cluster:trust', project, target) ?? {
+        project: project ?? 'gateway',
+        target: target ?? 'trust',
+    });
+}
 function readPid(pidFile) {
     try {
         const n = Number(readFileSync(pidFile, 'utf8').trim());
@@ -384,6 +418,96 @@ function runInstall(ctx, args, out, err) {
     });
     return { exitCode: result.status ?? 1 };
 }
+/**
+ * `lensmcp trust` — make the HTTPS dev gateway trusted in real browsers: mint +
+ * trust the local dev CA, write `/etc/hosts` (both `127.0.0.1` and `::1`) for
+ * every cluster host plus `lensmcp.local`, and flush DNS. Delegates to the
+ * auto-discovered `@lensmcp/cluster:trust` target. The executor self-escalates
+ * with `sudo` per privileged step and skips each when already satisfied, so this
+ * is idempotent — but it needs a real terminal so sudo can prompt.
+ */
+function runTrust(ctx, args, out, err) {
+    const opts = parseFlags(args, { string: ['--cwd', '--project', '--target'] });
+    const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
+    if (!existsSync(join(cwd, 'nx.json'))) {
+        err(`No nx.json found at ${cwd}.`);
+        err('Run `lensmcp trust` from inside a Nx workspace (after `lensmcp install`).');
+        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 target = findTrustTarget(cwd, stringFlag(opts.flags['--project']), stringFlag(opts.flags['--target']));
+    if (!isInteractive()) {
+        out('  note: trust runs `sudo` for the CA + /etc/hosts — run it in a real terminal if a step is needed.');
+    }
+    out(`> ${nxBin} run ${target.project}:${target.target}   (sudo prompts inline for the CA + /etc/hosts)`);
+    const result = spawnSync(nxBin, ['run', `${target.project}:${target.target}`], {
+        cwd,
+        stdio: 'inherit',
+        env: { ...process.env, ...(ctx.env ?? {}) },
+    });
+    return { exitCode: result.status ?? 1 };
+}
+/**
+ * Write the setup-state marker the MCP setup-gate reads to decide readiness.
+ * The shape MUST match `servers/lensmcp-mcp/src/setup-gate/state.ts`
+ * (`SetupState`). Machine-local (`.lensmcp/` is gitignored): it records the
+ * lensmcp version setup completed for, so an upgrade re-arms the gate until
+ * `setup` runs again.
+ */
+function writeSetupState(cwd) {
+    ensureLensmcpDir(cwd);
+    const state = {
+        version: readCliVersion(),
+        completedAt: new Date().toISOString(),
+        steps: { install: true, trust: true },
+    };
+    try {
+        writeFileSync(join(cwd, '.lensmcp', 'setup-state.json'), `${JSON.stringify(state, null, 2)}\n`);
+    }
+    catch {
+        /* non-fatal: the gate just treats the workspace as not-yet-set-up */
+    }
+}
+/**
+ * `lensmcp setup` — first-time bootstrap. Runs `install` (plugin + .mcp.json +
+ * nx config + vite/nest wiring, no sudo) then `trust` (dev CA → keychain,
+ * /etc/hosts, DNS flush, sudo). Both steps are idempotent, so re-running is safe.
+ * Flags are forwarded to whichever sub-command understands them (`--skip-format`,
+ * `--register-host-config` → install; `--project`/`--target` → trust).
+ */
+function runSetup(ctx, args, out, err) {
+    const opts = parseFlags(args, { string: ['--cwd'] });
+    const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
+    const subCtx = { ...ctx, cwd };
+    out('lensmcp setup — first-time bootstrap (install → trust)');
+    out('');
+    out('[1/2] install — plugin, .mcp.json, nx config, vite/nest wiring');
+    const installRes = runInstall(subCtx, args, out, err);
+    if (installRes.exitCode !== 0) {
+        err('');
+        err('setup: the install step failed — fix the above and re-run `lensmcp setup`.');
+        return installRes;
+    }
+    out('');
+    out('[2/2] trust — dev CA → System keychain, /etc/hosts, DNS flush (sudo)');
+    const trustRes = runTrust(subCtx, args, out, err);
+    if (trustRes.exitCode !== 0) {
+        err('');
+        err('setup: the trust step failed — run `lensmcp setup` directly in a terminal so sudo can prompt.');
+        return trustRes;
+    }
+    // Both steps succeeded → mark the workspace set up for this version (opens the MCP gate).
+    writeSetupState(cwd);
+    out('');
+    out('✓ setup complete.');
+    out('  next:   lensmcp gateway start      (the :443 front door — needs sudo)');
+    out('  verify: lensmcp doctor');
+    return { exitCode: 0 };
+}
 function runDoctor(ctx, args, out) {
     const opts = parseFlags(args, { string: ['--cwd'], boolean: ['--json'] });
     const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
@@ -697,6 +821,11 @@ function ensureLensmcpDir(cwd) {
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true });
 }
+/** `sudo` can only prompt for a password when both stdin and stdout are TTYs.
+ *  Used to warn (not block) before the trust step's privileged sub-commands. */
+function isInteractive() {
+    return Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
 /** Narrow a flag value to string-or-undefined, treating booleans as absent. */
 function stringFlag(v) {
     if (v === undefined)

package/package.json

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

package/plugin/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "lensmcp",
   "displayName": "LensMCP",
   "description": "The observability lens for coding agents. One command brings up the dev cluster gateway (every project.json `cluster` decl → its host on :443), the per-project lens dashboard at https://lensmcp.local/<project>/, and the MCP server your agent connects to — scoped automatically to whatever project you opened Claude Code in.",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "author": {
     "name": "David Antoon",
     "email": "davidmantoon@gmail.com"

package/plugin/skills/start/SKILL.md

@@ -25,9 +25,11 @@ After running it:
 1. Report the dashboard URL the script printed.
 2. **Binding :443 needs privilege.** If the log shows `EACCES`/permission denied, tell
    the user to either run the gateway target with `sudo`, or that ports <1024 require
-   elevation on macOS — and that `nx run gateway:trust` must be run once (sudo) to set up
-   the `*.local` hosts + TLS CA. Check `.lensmcp/gateway.log` for the real error.
-3. If the user has not run `gateway:trust` yet, mention it (one-time per machine).
+   elevation on macOS — and that `lensmcp setup` (install + trust) or `lensmcp trust`
+   must be run once (sudo) to set up the `*.local` hosts + TLS CA. Check
+   `.lensmcp/gateway.log` for the real error.
+3. If the user has not run `lensmcp setup` / `lensmcp trust` yet, mention it (one-time
+   per machine).
 
 Do **not** run a service's `serve`/`serve-hmr` manually — the gateway owns each service's
 lifecycle. This one command is the entry point.

package/plugin/skills/using-lensmcp/SKILL.md

@@ -10,6 +10,15 @@ server and the dashboard both read that file. **Project isolation is automatic**
 server is launched with `--cwd ${CLAUDE_PROJECT_DIR}`, so it always reads the flows of the
 project Claude Code is open in. Different project → different event file → different flows.
 
+## First: is the lens set up?
+
+LensMCP gates its tools until the workspace has been set up **once per machine** (and again
+after a lensmcp upgrade). If a tool fails with a **"LensMCP is not ready — run `lensmcp setup`"**
+message — or if `setup.status` reports `ready: false` — do **not** keep retrying. Tell the user
+to run **`lensmcp setup`** in their terminal (it wires the plugin + trusts the dev CA/hosts;
+sudo prompts inline; idempotent), then continue. The `setup.status` tool and the session
+bootstrap stay available even while the gate is closed.
+
 ## The loop
 
 1. **Start** the cluster + lens: `/lensmcp:start` (gateway up, all hosts routed, dashboard