@bridge_gpt/mcp-server 0.2.34 → 0.2.37

package/build/update-status.js

@@ -0,0 +1,102 @@
+/**
+ * Process-wide cached update status (BAPI-728).
+ *
+ * The staleness signal already existed — `checkForUpdate()` ran on every server
+ * start and computed the right answer. It was emitted through
+ * `sendLoggingMessage({ level: "notice", ... })`, an MCP log sink that no user
+ * or model surface reads. The published 0.2.16 tarball shipped that code, so a
+ * stale server correctly computed `updateAvailable: true` and announced it to
+ * nobody, on every session, for twenty releases.
+ *
+ * This manager gives that value two readers instead of zero: one stderr warning
+ * per process (humans), and a `tools/list` advisory (models). It is:
+ *
+ *   - **single-flight** — one `checkForUpdate()` per process, cached forever;
+ *   - **non-blocking** — started at boot, never awaited before `connect`;
+ *   - **fail-open** — a null, malformed, rejected, or not-newer result yields
+ *     no advisory and no warning, and never throws.
+ */
+import { checkForUpdate } from "./update-check.js";
+import { formatUpdateAdvice, formatToolSurfaceUpdateAdvisory } from "./upgrade-advice.js";
+/** The not-stale conclusion, used for every fail-open branch. */
+const NOT_STALE = { stale: false };
+/**
+ * Build the manager. Nothing runs until `start()` is called, so importing this
+ * module never performs I/O.
+ */
+export function createUpdateStatusManager(options = {}) {
+    const check = options.check ?? checkForUpdate;
+    const warn = options.warn ?? ((message) => console.error(message));
+    let started = false;
+    let settled = null;
+    let settledPromise = null;
+    let warned = false;
+    let listServed = false;
+    let lateNotified = false;
+    function conclude(result) {
+        // Every uncertain shape is fail-open. A malformed payload must never produce
+        // an advisory telling a user to upgrade to a version that may not exist.
+        if (!result || typeof result !== "object")
+            return NOT_STALE;
+        if (result.updateAvailable !== true)
+            return NOT_STALE;
+        const { currentVersion, latestVersion } = result;
+        if (typeof currentVersion !== "string" || currentVersion.length === 0)
+            return NOT_STALE;
+        if (typeof latestVersion !== "string" || latestVersion.length === 0)
+            return NOT_STALE;
+        return { stale: true, currentVersion, latestVersion };
+    }
+    function start() {
+        if (started)
+            return;
+        started = true;
+        settledPromise = (async () => {
+            let status;
+            try {
+                status = conclude(await check());
+            }
+            catch {
+                status = NOT_STALE; // `checkForUpdate` is contracted not to reject; belt and braces.
+            }
+            settled = status;
+            if (status.stale && !warned) {
+                warned = true;
+                // stderr, never stdout: stdout is the JSON-RPC frame channel and any
+                // stray write there corrupts the protocol stream.
+                warn(formatUpdateAdvice(status.currentVersion, status.latestVersion));
+                if (listServed && !lateNotified) {
+                    lateNotified = true;
+                    try {
+                        options.onLateStale?.();
+                    }
+                    catch {
+                        // A notification failure must never affect server operation.
+                    }
+                }
+            }
+            return status;
+        })();
+    }
+    return {
+        start,
+        getStatus: () => settled ?? NOT_STALE,
+        whenSettled: async () => {
+            if (!started)
+                start();
+            return (await settledPromise) ?? NOT_STALE;
+        },
+        markListServed: () => {
+            listServed = true;
+        },
+    };
+}
+/**
+ * Produce the model-visible advisory for a settled status, or null when the
+ * status is not (yet) known-stale. Pure — safe to call on every list request.
+ */
+export function updateAdvisoryFor(status) {
+    if (!status.stale || !status.currentVersion || !status.latestVersion)
+        return null;
+    return formatToolSurfaceUpdateAdvisory(status.currentVersion, status.latestVersion);
+}

package/build/upgrade-advice.js

@@ -0,0 +1,47 @@
+/**
+ * The one canonical upgrade command and its advice formatter (BAPI-728).
+ *
+ * Before this module the command literal was duplicated in three places — ping's
+ * advice, the startup update notice, and the backend release constant — and the
+ * copies had already drifted onto opposite conventions (`@latest` in the MCP
+ * server, unpinned in the backend). An unpinned `npx -y @bridge_gpt/mcp-server`
+ * is exactly what lets npx reuse a cached stale copy, which is the trap BAPI-430
+ * was written to close, so the pinned form is the canonical one.
+ *
+ * The formatter accepts ONLY version strings and validates their shape, so no
+ * caller can interpolate arbitrary (possibly secret-bearing) text into advice
+ * that is surfaced to users and models.
+ */
+/**
+ * The canonical, always-fresh upgrade invocation.
+ *
+ * `@latest` here refers to the UPGRADER — the short-lived CLI process that does
+ * the repinning. It is deliberately different from the exact `@MAJOR.MINOR.PATCH`
+ * pin that upgrader then writes into each host config: the upgrader must be the
+ * newest published code, while a project launcher must be reproducible.
+ */
+export const CANONICAL_UPGRADE_COMMAND = "npx -y @bridge_gpt/mcp-server@latest --upgrade";
+/** Accept only plain release strings into user-facing advice. */
+const SAFE_VERSION_RE = /^[0-9A-Za-z.\-+]{1,64}$/;
+/** Replace anything that is not a plausible version string with a fixed marker. */
+function sanitizeVersion(value) {
+    return typeof value === "string" && SAFE_VERSION_RE.test(value) ? value : "unknown";
+}
+/**
+ * Format the one-line staleness advisory shown to humans (stderr) and models
+ * (tool discovery). Only the two version values vary; the command is constant.
+ */
+export function formatUpdateAdvice(currentVersion, latestVersion) {
+    return (`Bridge API MCP server update available: running ${sanitizeVersion(currentVersion)}, ` +
+        `latest ${sanitizeVersion(latestVersion)} — run ${CANONICAL_UPGRADE_COMMAND}`);
+}
+/**
+ * The compact form attached to `tools/list`, so a model can see that the tool
+ * surface it is looking at may be missing or misnaming tools that exist in a
+ * newer release (the BAPI-645 `council` rename is the canonical example).
+ */
+export function formatToolSurfaceUpdateAdvisory(currentVersion, latestVersion) {
+    return (`NOTE: this Bridge API MCP server is running ${sanitizeVersion(currentVersion)}, ` +
+        `but ${sanitizeVersion(latestVersion)} is published. Some tools may be missing or ` +
+        `renamed in this older build. To update, run: ${CANONICAL_UPGRADE_COMMAND}`);
+}