lensmcp 1.20.0 → 1.21.0

package/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "lensmcp-marketplace",
+  "interface": {
+    "displayName": "LensMCP Marketplace"
+  },
+  "plugins": [
+    {
+      "name": "lensmcp",
+      "source": {
+        "source": "local",
+        "path": "./plugins/lensmcp"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Developer Tools"
+    }
+  ]
+}

package/README.md

@@ -2,7 +2,7 @@
 
 > The observability lens for coding agents — run the MCP server your agent connects to and watch your apps live.
 
-**LensMCP** gives coding agents (and you) eyes on running applications. It captures traces, flows, and logs from your app and exposes them through an [MCP](https://modelcontextprotocol.io) server, so an agent can ask *"what just happened?"* and get a real answer — request flows, state changes, errors, and browser activity — instead of guessing from source code alone.
+**LensMCP** gives coding agents (and you) eyes on running applications. It captures traces, flows, and logs from your app and exposes them through an [MCP](https://modelcontextprotocol.io) server, so an agent can ask _"what just happened?"_ and get a real answer — request flows, state changes, errors, and browser activity — instead of guessing from source code alone.
 
 `lensmcp` is the CLI. It runs the LensMCP MCP server (over stdio or HTTP) that agents discover and connect to, and it serves a local **dashboard** where you can browse Flows, Cluster, Logs, and Resources captured from your running apps. It also ships helpers to wire LensMCP into your workspace (`install`) and to diagnose your setup (`doctor`).
 
@@ -20,15 +20,17 @@ Requires **Node 18+** (Node 20+ recommended; this workspace pins Node 26 via `.n
 lensmcp <command> [options]
 ```
 
-| Command | Description |
-| --- | --- |
-| `lensmcp mcp` | Launch the LensMCP MCP server that agents connect to. Defaults to **stdio**; set `--transport http` (or `LENSMCP_TRANSPORT=http`) to serve over HTTP on `--port` (default **3000**). |
-| `lensmcp dashboard` | Serve the live web view of the lens — Flows, Cluster, Logs, Resources — on `--port` (default **4321**). |
-| `lensmcp install` | Install LensMCP into the host Nx workspace (delegates to `nx g @lensmcp/nx-plugin:init`). Wires `.mcp.json` so agents auto-discover the server, plus `.gitignore` and config. Idempotent. |
-| `lensmcp doctor` | Diagnose the install: Node version, workspace + plugin registration, `.mcp.json` entry, MCP bundle, per-project Vite/Nest wiring, `agent-dev` targets, and Chrome for browser capture. |
-| `lensmcp rollout` | Edit the gateway rollout config (`@lensmcp/cluster`) — `add-cohort`, `set-weight`, `promote`, `abort`, `add-rule`, `remove-rule`, `status`. |
-| `lensmcp --version` | Print the installed `lensmcp` version. |
-| `lensmcp --help` | Show usage. |
+| Command             | Description                                                                                                                                                                               |
+| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `lensmcp mcp`       | Launch the LensMCP MCP server that agents connect to. Defaults to **stdio**; set `--transport http` (or `LENSMCP_TRANSPORT=http`) to serve over HTTP on `--port` (default **3000**).      |
+| `lensmcp dashboard` | Serve the live web view of the lens — Flows, Cluster, Logs, Resources — on `--port` (default **4321**).                                                                                   |
+| `lensmcp install`   | Install LensMCP into the host Nx workspace (delegates to `nx g @lensmcp/nx-plugin:init`). Wires `.mcp.json` so agents auto-discover the server, plus `.gitignore` and config. Idempotent. |
+| `lensmcp plugin`    | Install the LensMCP plugin into the coding agents on this machine — **Claude Code and Codex** — from the lensmcp package the workspace depends on. `plugin status` compares installed vs packaged versions. Idempotent; the same command upgrades.                     |
+| `lensmcp upgrade`   | Move **every connected workspace** (`~/.lensmcp/workspaces.json` + the current one) onto one lensmcp version: rewrite `lensmcp`/`@lensmcp/*` in each package.json, run each workspace's package manager, refresh a global install + both agent plugins, then restart the gateway daemon and re-register its guests. |
+| `lensmcp doctor`    | Diagnose the install: Node version, workspace + plugin registration, `.mcp.json` entry, MCP bundle, per-project Vite/Nest wiring, `agent-dev` targets, and Chrome for browser capture.    |
+| `lensmcp rollout`   | Edit the gateway rollout config (`@lensmcp/cluster`) — `add-cohort`, `set-weight`, `promote`, `abort`, `add-rule`, `remove-rule`, `status`.                                               |
+| `lensmcp --version` | Print the installed `lensmcp` version.                                                                                                                                                    |
+| `lensmcp --help`    | Show usage.                                                                                                                                                                               |
 
 ### `lensmcp mcp`
 
@@ -36,11 +38,11 @@ lensmcp <command> [options]
 lensmcp mcp [--cwd <dir>] [--transport stdio|http] [--port <n>]
 ```
 
-| Flag | Default | Description |
-| --- | --- | --- |
-| `--cwd <dir>` | current directory | Workspace root the server runs against. |
-| `--transport <stdio\|http>` | `stdio` | Transport agents connect over. `stdio` for local agents (Claude Code, Cursor); `http` to expose an HTTP endpoint. |
-| `--port <n>` | `3000` | HTTP port (used when transport is `http`). |
+| Flag                        | Default           | Description                                                                                                       |
+| --------------------------- | ----------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `--cwd <dir>`               | current directory | Workspace root the server runs against.                                                                           |
+| `--transport <stdio\|http>` | `stdio`           | Transport agents connect over. `stdio` for local agents (Claude Code, Cursor); `http` to expose an HTTP endpoint. |
+| `--port <n>`                | `3000`            | HTTP port (used when transport is `http`).                                                                        |
 
 Reads/writes the cross-process event file at `<cwd>/.lensmcp/events.jsonl` (override with `LENSMCP_EVENT_FILE`) — the same file your instrumented apps write to, so ingest and producers rendezvous with zero extra config.
 
@@ -50,10 +52,10 @@ Reads/writes the cross-process event file at `<cwd>/.lensmcp/events.jsonl` (over
 lensmcp dashboard [--cwd <dir>] [--port <n>]
 ```
 
-| Flag | Default | Description |
-| --- | --- | --- |
-| `--cwd <dir>` | current directory | Workspace root to read events from. |
-| `--port <n>` | `4321` | Port to serve the dashboard on (`http://localhost:<port>`). |
+| Flag          | Default           | Description                                                 |
+| ------------- | ----------------- | ----------------------------------------------------------- |
+| `--cwd <dir>` | current directory | Workspace root to read events from.                         |
+| `--port <n>`  | `4321`            | Port to serve the dashboard on (`http://localhost:<port>`). |
 
 Tails the same `.lensmcp/events.jsonl` the MCP server uses, so the dashboard shows the identical live flows, signals, and resources your agent sees.
 
@@ -65,6 +67,44 @@ lensmcp install [--cwd <dir>] [--skip-format] [--register-host-config <mode>]
 
 Run from inside an Nx workspace (requires `nx.json` and a local `nx` binary). Delegates to `nx g @lensmcp/nx-plugin:init --no-interactive`. Use `--skip-format` to skip post-generation formatting and `--register-host-config <mode>` to control how the host config is registered.
 
+### `lensmcp plugin`
+
+```bash
+lensmcp plugin <install|status> [claude|codex] [--from <dir>] [--scope <user|project|local>] [--cwd <dir>]
+```
+
+Installs the LensMCP plugin into the coding agents on this machine, from the lensmcp
+package the workspace at `--cwd` depends on (walks up to the nearest
+`node_modules/lensmcp`; `--from` overrides). Idempotent, and the **same command
+upgrades**: both agents treat the package directory as a live marketplace source, so a
+re-install re-reads whatever version is installed there. An agent whose CLI is not on
+PATH is skipped. `--scope` (Claude Code only) picks the install scope, defaulting to the
+scope of the existing install.
+
+### `lensmcp upgrade`
+
+```bash
+lensmcp upgrade [version] [--dry-run] [--no-install] [--no-plugins] [--no-global] [--no-restart]
+```
+
+One command that moves the whole machine to one lensmcp version (latest by default), in
+the only order that works:
+
+1. rewrite `lensmcp` + `@lensmcp/*` lines in every connected workspace's package.json
+   (the gateway registry `~/.lensmcp/workspaces.json` plus the workspace you run it in;
+   `^`/`~` operators are kept, `link:`/`workspace:` pins are reported and never touched),
+2. run each workspace's **own** package manager install (`packageManager` field, then lockfile),
+3. move a machine-global `npm i -g lensmcp` when one exists (it shadows every project for a bare `lensmcp`),
+4. re-install the Claude Code + Codex plugins from the fresh package,
+5. restart the gateway daemon and **re-register every workspace it hosted** — the daemon
+   keeps the bundle it loaded at start forever, and an owner restart drops its guests, so
+   both halves are mandatory. A daemon that *reports* a version (1.21+) is restarted even
+   when no package.json moved, if it provably lags the target.
+
+Per-workspace failure posture: one failed install never blocks the others, every failure
+names the command that finishes the job by hand, and re-running converges. `--dry-run`
+prints the full plan without changing anything.
+
 ### `lensmcp doctor`
 
 ```bash
@@ -83,13 +123,13 @@ Edits a gateway rollout config with validated, atomic writes that the production
 
 ## Environment variables
 
-| Variable | Used by | Default |
-| --- | --- | --- |
-| `LENSMCP_TRANSPORT` | `mcp` | `stdio` (overridden by `--transport`) |
-| `LENSMCP_PORT` | `mcp` | `3000` (overridden by `--port`) |
-| `LENSMCP_DASHBOARD_PORT` | `dashboard` | `4321` (overridden by `--port`) |
-| `LENSMCP_EVENT_FILE` | `mcp`, `dashboard` | `<cwd>/.lensmcp/events.jsonl` |
-| `CHROME_PATH` | `doctor` | auto-detected (browser capture only) |
+| Variable                 | Used by            | Default                               |
+| ------------------------ | ------------------ | ------------------------------------- |
+| `LENSMCP_TRANSPORT`      | `mcp`              | `stdio` (overridden by `--transport`) |
+| `LENSMCP_PORT`           | `mcp`              | `3000` (overridden by `--port`)       |
+| `LENSMCP_DASHBOARD_PORT` | `dashboard`        | `4321` (overridden by `--port`)       |
+| `LENSMCP_EVENT_FILE`     | `mcp`, `dashboard` | `<cwd>/.lensmcp/events.jsonl`         |
+| `CHROME_PATH`            | `doctor`           | auto-detected (browser capture only)  |
 
 ## Quick start
 
@@ -113,6 +153,30 @@ lensmcp mcp --transport http --port 3000   # or expose over HTTP
 
 Most local agents (Claude Code, Cursor, VS Code) read `.mcp.json` and launch `lensmcp mcp` over stdio automatically after `lensmcp install` — no manual wiring needed.
 
+### Agent plugins (Claude Code + Codex)
+
+The npm package ships a plugin per agent — Claude Code (`plugin/`) and Codex
+(`plugins/lensmcp/`), each with LensMCP skills and project-scoped MCP wiring. One command
+installs (or upgrades) both, pointing each agent's directory marketplace at this
+workspace's `node_modules/lensmcp` so it moves with the dependency:
+
+```bash
+npx -y lensmcp plugin install          # both agents; a missing CLI is skipped, not an error
+npx -y lensmcp plugin install codex    # just one
+npx -y lensmcp plugin status           # installed vs packaged versions
+```
+
+Under the hood that is the documented marketplace-add + plugin-add pair per agent — run
+them by hand if you prefer:
+
+```bash
+codex plugin marketplace add ./node_modules/lensmcp
+codex plugin add lensmcp@lensmcp-marketplace
+```
+
+Start a new Codex thread after installation. The existing Claude Code plugin remains available
+separately and is unchanged.
+
 ## How it fits
 
 `lensmcp` is the entry point of the LensMCP toolchain. [`@lensmcp/nx-plugin`](https://github.com/kiwiapps-ltd/lensmcp) wires LensMCP into your workspace and projects; the instrumentation libraries (`@lensmcp/vite-plugin`, `@lensmcp/nest-instrumentation`, `@lensmcp/react-instrumentation`, and friends) capture flows, state, and logs from running apps into `.lensmcp/events.jsonl`; and [`@lensmcp/cluster`](https://github.com/kiwiapps-ltd/lensmcp) powers the gateway and targeted rollouts driven by `lensmcp rollout`.

package/bin.js

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-"use strict";import{runCli as e}from"./lib/cli.js";e({cwd:process.cwd(),argv:process.argv.slice(2)}).then(s=>{process.exit(s.exitCode)},s=>{console.error(s instanceof Error?s.stack??s.message:String(s)),process.exit(1)});
+"use strict";import{runCli as r}from"./lib/cli.js";r({cwd:process.cwd(),argv:process.argv.slice(2)}).then(e=>{process.exit(e.exitCode)},e=>{console.error(e instanceof Error?e.stack??e.message:String(e)),process.exit(1)});

package/lib/agent-plugins.d.ts

@@ -0,0 +1,103 @@
+/** The marketplace both manifests declare — one name, so `<plugin>@<marketplace>` is agent-agnostic. */
+export declare const MARKETPLACE = "lensmcp-marketplace";
+export declare const PLUGIN = "lensmcp";
+export declare const PLUGIN_ID = "lensmcp@lensmcp-marketplace";
+export type AgentId = 'claude' | 'codex';
+export interface AgentDefinition {
+    id: AgentId;
+    label: string;
+    /** The agent's CLI binary, as invoked. */
+    bin: string;
+    /** Package-relative marketplace manifest. Its presence PROVES this agent's plugin ships in that version. */
+    manifest: string;
+    /** Package-relative plugin manifest — read for the version we are about to install. */
+    pluginManifest: string;
+    /** The lensmcp version that first shipped this agent's plugin (named when the manifest is missing). */
+    since: string;
+    restartHint: string;
+}
+export declare const AGENTS: readonly AgentDefinition[];
+export declare function agentById(id: string): AgentDefinition | undefined;
+export interface ResolveRootOptions {
+    cwd: string;
+    /** `--from <dir>` — an explicit package root, taken at face value. */
+    from?: string;
+    /** The running CLI's own package root (`cliPackageRoot()`), used when the workspace has no install. */
+    selfRoot?: string;
+    /** Injected for tests. */
+    exists?: (path: string) => boolean;
+}
+export interface ResolvedRoot {
+    root: string;
+    source: 'flag' | 'workspace' | 'self';
+    /** The lensmcp version at that root, when readable. */
+    version?: string;
+}
+/**
+ * The directory an agent's `marketplace add` is pointed at.
+ *
+ * WORKSPACE FIRST, self last, and the order is load-bearing: the marketplace is a
+ * DIRECTORY source, so whatever is on disk there is the version the agent installs
+ * and keeps re-reading. Pointing it at the running CLI (often a global or an `npx`
+ * cache) would pin the agent to a version the project does not use and cannot
+ * upgrade — precisely the plugin/project skew this toolchain already had to grow a
+ * detector for. `node_modules/lensmcp` moves with `lensmcp upgrade`; nothing else does.
+ */
+export declare function resolvePluginRoot(options: ResolveRootOptions): ResolvedRoot | undefined;
+/** The version stamped into an agent's plugin manifest at publish time (`scripts/prepare-dist.mjs`). */
+export declare function readPluginManifestVersion(root: string, agent: AgentDefinition): string | undefined;
+export interface PlanOptions {
+    /** Absolute package root the marketplace points at. */
+    root: string;
+    /** Claude only — `user` (its default) | `project` | `local`. Omitted = the agent's default. */
+    scope?: string;
+}
+/**
+ * The exact commands, in order. Every one of them is idempotent (verified against
+ * both CLIs): re-adding a marketplace at the same path is a no-op that exits 0, and
+ * re-installing an installed plugin re-reads the directory source — which is how an
+ * UPGRADE happens here too. So `plugin install` is the same command whether nothing,
+ * an old version, or the current version is installed, and there is no
+ * install-vs-update branch to get wrong.
+ */
+export declare function planAgentInstall(agent: AgentDefinition, options: PlanOptions): string[][];
+export type AgentInstallOutcome = 
+/** Every command exited 0. */
+'installed'
+/** The agent's CLI is not on PATH — not an error, this machine just has no Codex/Claude. */
+ | 'skipped-no-cli'
+/** This lensmcp version ships no plugin for that agent. Actionable: upgrade lensmcp. */
+ | 'skipped-not-packaged'
+/** A command failed. Actionable, and never fatal to the other agents. */
+ | 'failed';
+export interface AgentInstallResult {
+    agent: AgentId;
+    label: string;
+    outcome: AgentInstallOutcome;
+    /** The version the plugin manifest declares (what the agent ends up with). */
+    version?: string;
+    /** What was run (or what to run, when it could not be). */
+    commands: string[];
+    detail?: string;
+    restartHint?: string;
+}
+export interface InstallDeps {
+    /** Run a command; `undefined` means the binary was not found (ENOENT). */
+    run: (bin: string, args: string[]) => {
+        code: number;
+        stdout?: string;
+        stderr?: string;
+    } | undefined;
+    exists?: (path: string) => boolean;
+}
+export declare function installAgentPlugin(agent: AgentDefinition, options: PlanOptions, deps: InstallDeps): AgentInstallResult;
+/** The real runner — bounded, non-interactive, never throws. */
+export declare function spawnAgentRunner(env: NodeJS.ProcessEnv, timeoutMs?: number): InstallDeps['run'];
+/**
+ * The version Codex has installed, from `codex plugin list --json`.
+ *
+ * Unlike Claude Code there is no index file contract to read (its state lives in
+ * `~/.codex` with no documented layout), so this one IS a subprocess — acceptable
+ * for an explicit `plugin status`, which is not on a hook path.
+ */
+export declare function codexInstalledVersion(run: InstallDeps['run']): string | undefined;

package/lib/agent-plugins.js

@@ -0,0 +1,2 @@
+"use strict";var k=Object.defineProperty;var l=(t,e)=>k(t,"name",{value:e,configurable:!0});var y=Object.defineProperty,c=l((t,e)=>y(t,"name",{value:e,configurable:!0}),"d");import{spawnSync as j}from"node:child_process";import{existsSync as m,readFileSync as v}from"node:fs";import{dirname as A,isAbsolute as P,join as d,resolve as x}from"node:path";export const MARKETPLACE="lensmcp-marketplace",PLUGIN="lensmcp",PLUGIN_ID=`${PLUGIN}@${MARKETPLACE}`,AGENTS=[{id:"claude",label:"Claude Code",bin:"claude",manifest:".claude-plugin/marketplace.json",pluginManifest:"plugin/.claude-plugin/plugin.json",since:"1.9.0",restartHint:"restart Claude Code (or run /plugin) for the new version to load"},{id:"codex",label:"Codex",bin:"codex",manifest:".agents/plugins/marketplace.json",pluginManifest:"plugins/lensmcp/.codex-plugin/plugin.json",since:"1.20.0",restartHint:"start a new Codex thread for the plugin to load"}];export function agentById(t){return AGENTS.find(e=>e.id===t)}l(agentById,"agentById"),c(agentById,"agentById");export function resolvePluginRoot(t){const e=t.exists??m,o=c(r=>{try{const s=JSON.parse(v(d(r,"package.json"),"utf8"));return typeof s.version=="string"?s.version:void 0}catch{return}},"readVersion"),i=c((r,s)=>{const a=o(r);return{root:r,source:s,...a?{version:a}:{}}},"decorate");if(t.from){const r=P(t.from)?t.from:x(t.cwd,t.from);return e(d(r,"package.json"))?i(r,"flag"):void 0}let n=x(t.cwd);for(let r=0;r<8;r++){const s=d(n,"node_modules","lensmcp");if(e(d(s,"package.json")))return i(s,"workspace");const a=A(n);if(a===n)break;n=a}if(t.selfRoot&&e(d(t.selfRoot,"package.json")))return i(t.selfRoot,"self")}l(resolvePluginRoot,"resolvePluginRoot"),c(resolvePluginRoot,"resolvePluginRoot");export function readPluginManifestVersion(t,e){try{const o=JSON.parse(v(d(t,e.pluginManifest),"utf8"));return typeof o.version=="string"?o.version:void 0}catch{return}}l(readPluginManifestVersion,"readPluginManifestVersion"),c(readPluginManifestVersion,"readPluginManifestVersion");export function planAgentInstall(t,e){if(t.id==="codex")return[[t.bin,"plugin","marketplace","add",e.root],[t.bin,"plugin","add",PLUGIN_ID]];const o=e.scope?["--scope",e.scope]:[];return[[t.bin,"plugin","marketplace","add",e.root],[t.bin,"plugin","marketplace","update",MARKETPLACE],[t.bin,"plugin","install",PLUGIN_ID,...o,"--yes"]]}l(planAgentInstall,"planAgentInstall"),c(planAgentInstall,"planAgentInstall");export function installAgentPlugin(t,e,o){const i=o.exists??m,n=planAgentInstall(t,e),r=n.map(p=>p.join(" ")),s=readPluginManifestVersion(e.root,t),a={agent:t.id,label:t.label,commands:r,...s?{version:s}:{}};if(!i(d(e.root,t.manifest)))return{...a,outcome:"skipped-not-packaged",detail:`${e.root} ships no ${t.manifest} \u2014 the ${t.label} plugin arrived in lensmcp ${t.since}. Upgrade first: \`lensmcp upgrade\`.`};for(const p of n){const[g,...b]=p,u=g===void 0?void 0:o.run(g,b);if(!u)return{...a,outcome:"skipped-no-cli",detail:`\`${t.bin}\` is not on PATH`};if(u.code!==0){const f=(u.stderr??u.stdout??"").trim().split(`
+`).filter(Boolean).pop();return{...a,outcome:"failed",detail:f&&f.length>0?f:`\`${p.join(" ")}\` exited ${u.code}`}}}return{...a,outcome:"installed",restartHint:t.restartHint}}l(installAgentPlugin,"installAgentPlugin"),c(installAgentPlugin,"installAgentPlugin");export function spawnAgentRunner(t,e=12e4){return(o,i)=>{try{const n=j(o,i,{encoding:"utf8",timeout:e,env:t,stdio:["ignore","pipe","pipe"]});return n.error&&n.error.code==="ENOENT"?void 0:{code:n.status??1,...n.stdout?{stdout:n.stdout}:{},...n.stderr?{stderr:n.stderr}:{}}}catch{return}}}l(spawnAgentRunner,"spawnAgentRunner"),c(spawnAgentRunner,"spawnAgentRunner");export function codexInstalledVersion(t){const e=t("codex",["plugin","list","--json"]);if(!(!e||e.code!==0||!e.stdout))try{const o=(JSON.parse(e.stdout).installed??[]).find(i=>i.pluginId===PLUGIN_ID||i.name===PLUGIN&&i.marketplaceName===MARKETPLACE)?.version;return typeof o=="string"?o:void 0}catch{return}}l(codexInstalledVersion,"codexInstalledVersion"),c(codexInstalledVersion,"codexInstalledVersion");