lensmcp 1.18.0 → 1.18.2

package/bundled/dashboard.js

@@ -17435,9 +17435,14 @@ var MAX_ERRORS = 50;
 var STATE_BY_KIND = {
   "service-starting": "starting",
   "service-respawn": "starting",
+  // A lens frontend's vite has been SPAWNED — started, not yet proven to serve.
+  // The gateway's liveness probe emits `service-up` once its port accepts, so
+  // this must claim `starting` and never `up`.
+  "lens-app-up": "starting",
   "service-up": "up",
   "cold-start": "up",
   "service-down": "down",
+  "idle-kill": "idle",
   "service-recycle": "wedged",
   "pod-recycle": "wedged",
   "service-crash-loop": "crash-looping"
@@ -17494,6 +17499,7 @@ var ClusterHealth = class {
       down: byState("down"),
       wedged: byState("wedged"),
       crashLooping: byState("crash-looping"),
+      idle: byState("idle"),
       buildFailed: services.filter((s) => s.buildFailed).map((s) => s.project),
       restarts: services.reduce((n, s) => n + s.restarts, 0),
       errors: this.errors.slice()

package/bundled/main.js

@@ -17437,9 +17437,14 @@ var MAX_ERRORS = 50;
 var STATE_BY_KIND = {
   "service-starting": "starting",
   "service-respawn": "starting",
+  // A lens frontend's vite has been SPAWNED — started, not yet proven to serve.
+  // The gateway's liveness probe emits `service-up` once its port accepts, so
+  // this must claim `starting` and never `up`.
+  "lens-app-up": "starting",
   "service-up": "up",
   "cold-start": "up",
   "service-down": "down",
+  "idle-kill": "idle",
   "service-recycle": "wedged",
   "pod-recycle": "wedged",
   "service-crash-loop": "crash-looping"
@@ -17496,6 +17501,7 @@ var ClusterHealth = class {
       down: byState("down"),
       wedged: byState("wedged"),
       crashLooping: byState("crash-looping"),
+      idle: byState("idle"),
       buildFailed: services.filter((s) => s.buildFailed).map((s) => s.project),
       restarts: services.reduce((n, s) => n + s.restarts, 0),
       errors: this.errors.slice()

package/bundled/shim.js

@@ -8493,6 +8493,9 @@ async function ensureSharedServer(deps) {
   };
   if (await deps.probe())
     return live("already-running");
+  const taken = await deps.foreignPortOwner?.();
+  if (taken)
+    return { outcome: "unavailable", reason: taken, waitedMs: elapsed() };
   let holdsLock = deps.tryCreateLock(JSON.stringify({ pid: process.pid, at: deps.now() }));
   if (!holdsLock) {
     const existing = parseSpawnLock(deps.readLock());
@@ -8624,6 +8627,9 @@ function startSharedServerWatched(opts) {
   }
 }
 
+// servers/lensmcp-mcp/dist/shim/probe.js
+import { connect } from "node:net";
+
 // servers/lensmcp-mcp/dist/shim/workspace.js
 import { existsSync as existsSync2, readFileSync as readFileSync2, realpathSync } from "node:fs";
 import { basename, dirname, join as join2 } from "node:path";
@@ -8779,7 +8785,7 @@ async function probeShared(port, timeoutMs = 2e3) {
     if (res.ok) {
       const identity = parseServerIdentity(await res.json().catch(() => void 0));
       if (identity)
-        return { alive: true, identity };
+        return { alive: true, identity, owner: "lensmcp" };
     } else {
       await res.text().catch(() => void 0);
     }
@@ -8788,8 +8794,22 @@ async function probeShared(port, timeoutMs = 2e3) {
     clearTimeout(timer);
   }
   if (!answered)
-    return { alive: false };
-  return { alive: await probeMcp(sharedMcpUrl(port), timeoutMs) };
+    return { alive: false, owner: "none" };
+  const legacy = await probeMcp(sharedMcpUrl(port), timeoutMs);
+  return { alive: legacy, owner: legacy ? "lensmcp" : "foreign" };
+}
+function tcpAccepts(port, timeoutMs = 750) {
+  return new Promise((resolve2) => {
+    const socket = connect({ port, host: "127.0.0.1" });
+    const settle = (accepted) => {
+      socket.destroy();
+      resolve2(accepted);
+    };
+    socket.setTimeout(timeoutMs);
+    socket.once("connect", () => settle(true));
+    socket.once("timeout", () => settle(false));
+    socket.once("error", () => settle(false));
+  });
 }
 
 // servers/lensmcp-mcp/dist/shim/proxy.js
@@ -8976,9 +8996,9 @@ async function main() {
   const scope = resolveWorkspaceScope(cwd);
   const url2 = sharedMcpUrl(scope.mcpHttpPort);
   log(`[lensmcp] shim \u2192 workspace "${scope.key}" (${scope.root}) \u2192 ${url2}`);
-  let seen = { alive: false };
+  let seen = { alive: false, owner: "none" };
   let warnedUnknown = false;
-  let refused = false;
+  let explained = false;
   const verifyIdentity = () => {
     const mismatch = describeIdentityMismatch(scope, seen.identity);
     if (!mismatch) {
@@ -8989,7 +9009,7 @@ async function main() {
       return void 0;
     }
     const theirs = seen.identity;
-    refused = true;
+    explained = true;
     log("");
     log(`[lensmcp] REFUSING the shared MCP server on 127.0.0.1:${scope.mcpHttpPort} \u2014 ${mismatch}.`);
     log(`[lensmcp]   this session's workspace : "${scope.key}"  ${scope.root}`);
@@ -9002,6 +9022,27 @@ async function main() {
     log("");
     return `the shared MCP port is served by workspace "${theirs?.key}", not "${scope.key}"`;
   };
+  const foreignPortOwner = async () => {
+    const port = scope.mcpHttpPort;
+    const nonHttp = seen.owner === "foreign" ? false : await tcpAccepts(port);
+    if (seen.owner !== "foreign" && !nonHttp)
+      return void 0;
+    explained = true;
+    log("");
+    log(`[lensmcp] the shared MCP port 127.0.0.1:${port} is TAKEN by another process.`);
+    log(`[lensmcp]   It ${nonHttp ? "accepts connections but does not speak HTTP" : "answers HTTP but is not a lensmcp MCP server"}, so this session cannot attach to it.`);
+    log("[lensmcp]   Not starting a server on it: on macOS a second bind SUCCEEDS on the");
+    log("[lensmcp]   wildcard address while the kernel keeps routing 127.0.0.1 to the");
+    log("[lensmcp]   process already there \u2014 the new server would be unreachable, and");
+    log("[lensmcp]   would keep running after this session ends.");
+    log("[lensmcp]   Fix EITHER by freeing the port:");
+    log(`[lensmcp]     lsof -nP -iTCP:${port} -sTCP:LISTEN`);
+    log(`[lensmcp]   OR by pinning a different one in ${join3(scope.root, ".lensmcp", "config.json")}:`);
+    log(`[lensmcp]     { "ports": { "mcpHttp": ${port + 1} } }`);
+    log("[lensmcp]   then restart this session. Any free 4500-4699 port works.");
+    log("");
+    return `the shared MCP port ${port} is held by another process that is not a lensmcp server`;
+  };
   const ensure = () => {
     let watch;
     return ensureSharedServer({
@@ -9010,6 +9051,7 @@ async function main() {
         return seen.alive;
       },
       verifyIdentity,
+      foreignPortOwner,
       startServer: () => {
         const started = startSharedServerWatched({
           serverEntry: serverEntry(),
@@ -9032,7 +9074,7 @@ async function main() {
   };
   const ensured = await ensure();
   if (ensured.outcome === "unavailable") {
-    runEmbedded(cwd, ensured.reason ?? "unknown", !refused);
+    runEmbedded(cwd, ensured.reason ?? "unknown", !explained);
     return;
   }
   log(`[lensmcp] shim: shared server ${ensured.outcome} (${ensured.waitedMs}ms)`);

package/lib/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/lib/cli.ts"],"names":[],"mappings":"AAkBA,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;AA8GD,wBAAsB,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CA4ChE;AAypBD,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEnE;;;;;;;;iFAQiF;AACjF,wBAAgB,oBAAoB,CAAC,CAAC,EAAE;IACtC,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,mBAAmB,CAItB"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/lib/cli.ts"],"names":[],"mappings":"AAmCA,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;AAgID,wBAAsB,MAAM,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAgDhE;AAypBD,MAAM,MAAM,mBAAmB,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEnE;;;;;;;;iFAQiF;AACjF,wBAAgB,oBAAoB,CAAC,CAAC,EAAE;IACtC,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,mBAAmB,CAItB"}

package/lib/cli.js

@@ -8,6 +8,9 @@ import { ensureLensConfig } from './workspace-scope.js';
 import { isMcpMode } from './mcp-mode.js';
 import { effectiveMcpMode, LENS_CONFIG, probeSharedMcp, probeSharedMcpSync, readMcpWiring, wireMcpMode, } from './mcp-wiring.js';
 import { sweepLensRuntimeFiles } from './sweep.js';
+import { candidateSignals, findingLine, formatContext, hookPayload, isHookEvent, select, } from './status-policy.js';
+import { DEFAULT_BUDGET_MS, readStatus } from './status-client.js';
+import { detectSkew, formatSkewContext, readVersions, spawnRunner, syncPlugin, updateCommands, } from './plugin-version.js';
 const HELP = `lensmcp — CLI for LensMCP (FrontMCP-based observability for coding agents)
 
 Usage:
@@ -83,6 +86,24 @@ Commands:
                        cluster host (+ lensmcp.local), flush DNS. Wraps the
                        auto-discovered \`@lensmcp/cluster:trust\` target.
                        Idempotent; sudo prompts inline — run in a terminal.
+  status [--cwd <dir>] [--json] [--quiet] [--hook <event>] [--timeout <ms>]
+                       Workspace health in one line — the hook-callable read of
+                       \`agent://current-status\` from this workspace's SHARED MCP
+                       server (embedded mode has none). Reports ONLY what it can
+                       vouch for: a signal with no producer is unmonitored, not
+                       healthy, and a verdict with no evidence of when it last
+                       ran is unknown, not clean. \`--quiet\` prints NOTHING unless
+                       something actionable is trustworthy — it is meant to run
+                       every turn. \`--hook <Stop|SessionStart|SubagentStop>\`
+                       emits the Claude Code \`additionalContext\` envelope
+                       (advisory only — it never blocks). FAILS OPEN: no server,
+                       no setup, a timeout → silent, exit 0, always.
+  version-check [--cwd <dir>] [--json] [--quiet] [--hook <event>] [--plugin-root <dir>]
+                       Compare the installed Claude Code PLUGIN's version against
+                       the lensmcp this project uses. On a proven mismatch it
+                       names both versions and the exact update command; when
+                       they match, or either version cannot be read, it is
+                       silent. Same fail-open contract as \`status\`.
   doctor [--cwd <dir>] [--json]
                        Diagnose the install: Node, workspace + plugin,
                        .mcp.json server entry, MCP bundle, per-project
@@ -142,6 +163,10 @@ export async function runCli(ctx) {
             return runInstall(ctx, rest, out, err);
         case 'trust':
             return runTrust(ctx, rest, out, err);
+        case 'status':
+            return runStatus(ctx, rest, out);
+        case 'version-check':
+            return runVersionCheck(ctx, rest, out);
         case 'doctor':
             return runDoctor(ctx, rest, out);
         case 'rollout':
@@ -1069,6 +1094,37 @@ async function applyMcpModeStep(cwd, flag, env, out) {
         ? `      \u2713 already up \u2014 ${health.server ?? 'MCP'} (protocol ${health.protocolVersion ?? '?'})`
         : `      \u00b7 not up yet (${health.error ?? 'unknown'}) \u2014 the next session starts it on demand`);
 }
+/**
+ * Bring the installed Claude Code plugin in step with this lensmcp.
+ *
+ * `setup` already reconciles `.mcp.json`, the nx config, the vite/nest wiring
+ * and the pods; the plugin was the one component it walked past, and it drifted
+ * nine minors on the machine this was written for. It is reconciled LAST and
+ * NON-FATALLY: `setup` is the recovery command, so a marketplace/cache/network
+ * problem must degrade to one warning line rather than abort the steps that
+ * actually fix a broken workspace.
+ *
+ * Nothing is written into `~/.claude/plugins` — see `plugin-version.ts` for why
+ * the sanctioned `claude plugin …` commands are the only path taken.
+ */
+function applyPluginSyncStep(cwd, env, out) {
+    const facts = readVersions({ cwd, cliVersion: readCliVersion() });
+    const result = syncPlugin({ run: spawnRunner(env), facts });
+    // Quiet when already current — `setup` is run constantly and must not churn.
+    if (result.outcome === 'current' || result.outcome === 'unknown')
+        return;
+    out('');
+    if (result.outcome === 'updated') {
+        out(`[plugin] ${result.from} → ${result.to}`);
+        out('         restart Claude Code for the new plugin to load.');
+        return;
+    }
+    out(`[plugin] the Claude Code plugin is ${result.from}, this lensmcp is ${result.to}.`);
+    out(`         could not update it automatically (${result.detail ?? 'unknown reason'}). Run:`);
+    for (const c of result.commands ?? [])
+        out(`           ${c}`);
+    out('         …then restart Claude Code.');
+}
 async function runSetup(ctx, args, out, err) {
     const opts = parseFlags(args, { string: ['--cwd', '--mcp'] });
     const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
@@ -1111,6 +1167,14 @@ async function runSetup(ctx, args, out, err) {
     // shared mode, and re-affirms stdio otherwise. Runs AFTER install so it is the
     // last writer of that entry.
     await applyMcpModeStep(cwd, mcpFlag, ctx.env ?? process.env, out);
+    // The plugin ships inside this npm package but updates on Claude Code's
+    // schedule, not ours — so reconcile it here, last, and never fatally.
+    try {
+        applyPluginSyncStep(cwd, { ...process.env, ...(ctx.env ?? {}) }, out);
+    }
+    catch {
+        /* the plugin step can never be the reason `setup` failed */
+    }
     // All steps succeeded → mark the workspace set up for this version (opens the MCP gate).
     writeSetupState(cwd);
     out('');
@@ -1124,6 +1188,175 @@ async function runSetup(ctx, args, out, err) {
     out('  verify: lensmcp doctor');
     return { exitCode: 0 };
 }
+/**
+ * `lensmcp status` — the hook-callable health read.
+ *
+ * THE CONTRACT, and the reason this function looks paranoid: it runs at the end
+ * of every turn, so it must never block one, never error, and never hang. Hence
+ * `exitCode: 0` on every path including the catch, a whole-call budget, and
+ * silence as the default output. A non-zero exit or a stray line here would show
+ * up in the transcript as a hook error on turns where nothing is wrong, which is
+ * the exact noise the feature exists to avoid.
+ */
+async function runStatus(ctx, args, out) {
+    const opts = parseFlags(args, {
+        string: ['--cwd', '--hook', '--timeout'],
+        boolean: ['--json', '--quiet'],
+    });
+    const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
+    const hookRaw = stringFlag(opts.flags['--hook']);
+    const hook = isHookEvent(hookRaw) ? hookRaw : undefined;
+    // A caller that asked for hook output and named an event we do not emit gets
+    // NOTHING, rather than the human text on a channel expecting JSON. Silence is
+    // the honest answer to "I cannot produce what you asked for".
+    if (hookRaw !== undefined && hook === undefined)
+        return { exitCode: 0 };
+    const asJson = opts.flags['--json'] === true;
+    // A hook is a quiet caller by definition: it speaks only when it has news.
+    const quiet = opts.flags['--quiet'] === true || hookRaw !== undefined;
+    const budget = Number(stringFlag(opts.flags['--timeout']) ?? '');
+    const budgetMs = Number.isFinite(budget) && budget > 0 ? budget : DEFAULT_BUDGET_MS;
+    const env = { ...process.env, ...(ctx.env ?? {}) };
+    try {
+        const read = await readStatus({
+            cwd,
+            env,
+            budgetMs,
+            // Only signals we are about to REPORT get a verification read, so the
+            // clean path costs exactly one request.
+            verify: (status) => candidateSignals(status).map((s) => s.resource),
+        });
+        if (!read.available) {
+            if (asJson && !quiet) {
+                out(JSON.stringify({ available: false, workspace: read.source.workspace, mode: read.source.mode, reason: read.reason, elapsedMs: read.elapsedMs }));
+            }
+            else if (!quiet) {
+                out(`lensmcp status — ${read.source.workspace}: unavailable (${read.reason})`);
+            }
+            return { exitCode: 0 };
+        }
+        const selection = select(read.status, read.evidence, Date.now());
+        const context = formatContext(selection, {
+            workspace: read.source.workspace,
+            includeUnmonitored: hook === 'SessionStart' || !quiet,
+        });
+        if (asJson) {
+            if (quiet && context === undefined)
+                return { exitCode: 0 };
+            out(JSON.stringify({
+                available: true,
+                workspace: read.source.workspace,
+                mode: read.source.mode,
+                url: read.source.url,
+                aggregate: read.status.status ?? 'unknown',
+                elapsedMs: read.elapsedMs,
+                findings: selection.findings,
+                suppressed: selection.suppressed,
+                unmonitored: selection.unmonitored,
+            }));
+            return { exitCode: 0 };
+        }
+        if (hook) {
+            if (context !== undefined)
+                out(hookPayload(hook, context));
+            return { exitCode: 0 };
+        }
+        if (quiet) {
+            if (context !== undefined)
+                out(context);
+            return { exitCode: 0 };
+        }
+        // The human view. Unlike the hook it always says something, and it shows the
+        // SUPPRESSED signals too — "why did it stay quiet about the build?" has to be
+        // answerable, or the silence looks like a bug.
+        out(`lensmcp status — ${read.source.workspace} (${read.source.mode}, ${read.source.url})`);
+        out(`  aggregate says: ${read.status.status ?? 'unknown'}   (read in ${read.elapsedMs}ms)`);
+        if (selection.findings.length === 0) {
+            out('  nothing actionable that this command can vouch for.');
+        }
+        else {
+            for (const f of selection.findings)
+                out(`  • ${findingLine(f)}`);
+        }
+        for (const s of selection.suppressed)
+            out(`  · not reported — ${s.kind}: ${s.reason}`);
+        if (selection.unmonitored.length > 0) {
+            out(`  · unmonitored (unknown, NOT clean): ${selection.unmonitored.join(', ')}`);
+        }
+        return { exitCode: 0 };
+    }
+    catch (e) {
+        // Fail open. A status read is never worth a failed turn.
+        if (!quiet)
+            out(`lensmcp status: unavailable (${e instanceof Error ? e.message : String(e)})`);
+        return { exitCode: 0 };
+    }
+}
+/**
+ * `lensmcp version-check` — is the installed plugin the one this lensmcp ships?
+ *
+ * A separate command from `status` because it is a separate question with a
+ * separate cadence: the answer changes only when someone upgrades, so it belongs
+ * at SessionStart, whereas health changes every turn. Same fail-open contract,
+ * and the same advisory-only rule — it names the command, it does not block.
+ */
+function runVersionCheck(ctx, args, out) {
+    const opts = parseFlags(args, {
+        string: ['--cwd', '--hook', '--plugin-root'],
+        boolean: ['--json', '--quiet'],
+    });
+    const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);
+    const hookRaw = stringFlag(opts.flags['--hook']);
+    const hook = isHookEvent(hookRaw) ? hookRaw : undefined;
+    if (hookRaw !== undefined && hook === undefined)
+        return { exitCode: 0 };
+    const asJson = opts.flags['--json'] === true;
+    const quiet = opts.flags['--quiet'] === true || hookRaw !== undefined;
+    const pluginRoot = stringFlag(opts.flags['--plugin-root']);
+    try {
+        const facts = readVersions({
+            cwd,
+            cliVersion: readCliVersion(),
+            ...(pluginRoot ? { pluginRoot } : {}),
+        });
+        const skew = detectSkew(facts);
+        if (asJson) {
+            if (quiet && !skew)
+                return { exitCode: 0 };
+            out(JSON.stringify({ ...facts, skew: skew ?? null }));
+            return { exitCode: 0 };
+        }
+        if (hook) {
+            if (skew)
+                out(hookPayload(hook, formatSkewContext(skew)));
+            return { exitCode: 0 };
+        }
+        if (quiet) {
+            if (skew)
+                out(formatSkewContext(skew));
+            return { exitCode: 0 };
+        }
+        out(`lensmcp version-check — ${facts.pluginId ?? 'lensmcp plugin'}`);
+        out(`  plugin  ${facts.plugin ?? 'unknown'}${facts.pluginSource ? `  (${facts.pluginSource})` : ''}`);
+        out(`  project ${facts.project ?? 'unknown'}   (node_modules/lensmcp)`);
+        out(`  cli     ${facts.cli ?? 'unknown'}   (the binary running now)`);
+        if (!skew) {
+            out(facts.plugin && (facts.project ?? facts.cli)
+                ? '  ✓ in step.'
+                : '  ? cannot compare — one of the versions is unreadable (staying silent).');
+            return { exitCode: 0 };
+        }
+        out(`  ✗ the plugin is ${skew.direction} — update it, then restart Claude Code:`);
+        for (const c of updateCommands(skew))
+            out(`      ${c}`);
+        return { exitCode: 0 };
+    }
+    catch (e) {
+        if (!quiet)
+            out(`lensmcp version-check: unavailable (${e instanceof Error ? e.message : String(e)})`);
+        return { exitCode: 0 };
+    }
+}
 async function runDoctor(ctx, args, out) {
     const opts = parseFlags(args, { string: ['--cwd'], boolean: ['--json'] });
     const cwd = resolve(stringFlag(opts.flags['--cwd']) ?? ctx.cwd);

package/lib/plugin-version.d.ts

@@ -0,0 +1,121 @@
+/** The plugin's id as Claude Code knows it: `<plugin>@<marketplace>`. */
+export declare const PLUGIN_NAME = "lensmcp";
+export interface InstalledPlugin {
+    /** `lensmcp@lensmcp-marketplace`. */
+    id: string;
+    marketplace: string;
+    version: string;
+    scope?: string;
+    projectPath?: string;
+}
+/**
+ * What Claude Code records about the installed plugin.
+ *
+ * Read from `installed_plugins.json` rather than by shelling out to
+ * `claude plugin list --json`: it is the same data, costs no subprocess (~0.26s
+ * measured), and cannot prompt or hang — all three matter on a hook path. The
+ * file is only ever READ.
+ */
+export declare function readInstalledPlugin(cwd: string, home?: string): InstalledPlugin | undefined;
+export interface VersionFacts {
+    /**
+     * The plugin actually loaded, read from `${CLAUDE_PLUGIN_ROOT}` when a hook
+     * passed it — the only fully authoritative source, since it is the manifest
+     * Claude Code parsed. Falls back to the install index.
+     */
+    plugin?: string;
+    pluginSource?: 'plugin-root' | 'install-index';
+    pluginId?: string;
+    pluginMarketplace?: string;
+    /** The `lensmcp` this project depends on — what the plugin should match. */
+    project?: string;
+    /** The CLI binary currently executing (may be a global install). */
+    cli?: string;
+}
+export interface ReadVersionsOptions {
+    cwd: string;
+    /** `${CLAUDE_PLUGIN_ROOT}`, when invoked from a plugin hook. */
+    pluginRoot?: string;
+    /** The running CLI's own version. */
+    cliVersion?: string;
+    home?: string;
+}
+export declare function readVersions(options: ReadVersionsOptions): VersionFacts;
+/** -1 / 0 / 1, or `undefined` when either side is not a comparable version. */
+export declare function compareVersions(a: string, b: string): number | undefined;
+export interface Skew {
+    /** PROVEN: both versions were read and they differ. */
+    mismatch: boolean;
+    plugin: string;
+    expected: string;
+    /** Which version the `expected` side came from. */
+    expectedSource: 'project' | 'cli';
+    direction: 'behind' | 'ahead' | 'differs';
+    /** `<plugin>@<marketplace>`, when the install index named one. */
+    pluginId?: string;
+    marketplace?: string;
+    /** A global CLI that disagrees with the project's dependency, if any. */
+    cliSkew?: {
+        cli: string;
+        project: string;
+    };
+}
+/**
+ * Decide whether there is a skew worth telling anyone about.
+ *
+ * Returns `undefined` for every uncertain case — no plugin found, no reference
+ * version, an unparseable version string. Trust rule: warn only on a PROVEN
+ * mismatch, never a suspected one. A hook that guesses is a hook that gets
+ * muted.
+ */
+export declare function detectSkew(facts: VersionFacts): Skew | undefined;
+/** The exact commands that reconcile the plugin, in order. */
+export declare function updateCommands(skew: Pick<Skew, 'pluginId' | 'marketplace'>): string[];
+/**
+ * The SessionStart context for a proven skew.
+ *
+ * States both versions and names the command, because "something is out of
+ * date" without the fix is a nag. Advisory: it asks the agent to update first,
+ * it does not prevent anything.
+ */
+export declare function formatSkewContext(skew: Skew): string;
+export type SyncOutcome = 
+/** Already at the expected version — nothing done, nothing printed. */
+'current'
+/** Skew found and the update commands succeeded. */
+ | 'updated'
+/** Skew found; the update could not be run or failed. Actionable, non-fatal. */
+ | 'manual'
+/** Nothing installed, or not enough information to say. Silent. */
+ | 'unknown';
+export interface SyncResult {
+    outcome: SyncOutcome;
+    from?: string;
+    to?: string;
+    /** What the user should run when we could not. */
+    commands?: string[];
+    detail?: string;
+}
+export interface SyncDeps {
+    /** Run a command; `undefined` means the binary was not found. */
+    run: (cmd: string, args: string[]) => {
+        code: number;
+        stderr?: string;
+    } | undefined;
+    facts: VersionFacts;
+}
+/**
+ * Reconcile the installed plugin with the lensmcp this workspace uses.
+ *
+ * Quiet when current (the common case — `setup` is run constantly), and NEVER
+ * fatal: every failure path returns `manual` with the command to run, so a
+ * marketplace, cache or network problem cannot abort the rest of setup.
+ */
+export declare function syncPlugin(deps: SyncDeps): SyncResult;
+/** The real runner. Bounded, non-interactive, and never throws. */
+export declare function spawnRunner(env: NodeJS.ProcessEnv, timeoutMs?: number): SyncDeps['run'];
+/** Where a plugin's manifest lives, for callers that already have its root. */
+export declare const pluginManifestPath: (root: string) => string;
+/** True when `root` looks like an unpacked Claude Code plugin. */
+export declare const isPluginRoot: (root: string) => boolean;
+//# sourceMappingURL=plugin-version.d.ts.map

package/lib/plugin-version.d.ts.map

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