@bridge_gpt/mcp-server 0.2.68 → 0.2.70

package/build/update-check.js

@@ -1,7 +1,10 @@
 /**
  * Update check logic — extracted for testability.
- * The main index.ts imports and calls checkForUpdate().
+ * `update-status.ts` (the background manager) and `doctor.ts` call checkForUpdate();
+ * the synchronous notice paths use `readCachedLatestVersion` and never touch the
+ * network.
  */
+import { readFileSync } from "fs";
 import { writeFile, mkdir, readFile } from "fs/promises";
 import path from "path";
 import os from "os";
@@ -10,13 +13,51 @@ import { MCP_PACKAGE_NAME } from "./mcp-identity.js";
 const CACHE_TTL = 86400000; // 24 hours
 const FETCH_TIMEOUT = 3000;
 const REGISTRY_URL = `https://registry.npmjs.org/${MCP_PACKAGE_NAME}/latest`;
+/** Manual-only override of the latest version, for exercising the notice paths. */
+export const FAKE_LATEST_ENV = "BAPI_MCP_UPDATE_CHECK_FAKE_LATEST";
+const PLAIN_RELEASE_RE = /^\d+\.\d+\.\d+$/;
 export function getCachePath() {
     return path.join(os.homedir(), ".config", ...MCP_PACKAGE_NAME.split("/"), "update-check.json");
 }
+/** True only for a plain `MAJOR.MINOR.PATCH` release string. */
+export function isPlainReleaseVersion(value) {
+    return typeof value === "string" && PLAIN_RELEASE_RE.test(value);
+}
+/**
+ * Read the manual fake-latest override. Returns the value only when it is a plain
+ * release string; anything else (absent, blank, a prerelease, shell text) is
+ * ignored and never echoed.
+ */
+export function readFakeLatestOverride(env = process.env) {
+    const value = env[FAKE_LATEST_ENV];
+    return isPlainReleaseVersion(value) ? value : null;
+}
+/** Compare two digit strings numerically without converting them to Numbers. */
+function compareDigitStrings(a, b) {
+    const x = a.replace(/^0+(?=\d)/, "");
+    const y = b.replace(/^0+(?=\d)/, "");
+    if (x.length !== y.length)
+        return x.length > y.length ? 1 : -1;
+    if (x === y)
+        return 0;
+    return x > y ? 1 : -1;
+}
 /**
  * Compare two semver strings. Returns true if `latest` is strictly greater.
+ * Valid release strings are compared segment by segment as digit strings, so a
+ * segment beyond the safe-integer range keeps its ordering.
  */
 export function isNewerVersion(current, latest) {
+    if (isPlainReleaseVersion(current) && isPlainReleaseVersion(latest)) {
+        const c = current.split(".");
+        const l = latest.split(".");
+        for (let i = 0; i < 3; i++) {
+            const order = compareDigitStrings(l[i], c[i]);
+            if (order !== 0)
+                return order > 0;
+        }
+        return false;
+    }
     const c = current.split(".").map(Number);
     const l = latest.split(".").map(Number);
     for (let i = 0; i < 3; i++) {
@@ -27,28 +68,66 @@ export function isNewerVersion(current, latest) {
     }
     return false;
 }
+/**
+ * Read the latest version the server last cached, synchronously and offline.
+ *
+ * A valid override wins before the cache is opened. The cache's age is ignored on
+ * purpose: a cached latest can only be older than the real latest, so it is a
+ * lower bound. It may under-claim an update, but it never claims one that does
+ * not exist. Any missing, corrupt, malformed, or unreadable cache returns null.
+ */
+export function readCachedLatestVersion(env = process.env) {
+    try {
+        const override = readFakeLatestOverride(env);
+        if (override)
+            return override;
+        const cache = JSON.parse(readFileSync(getCachePath(), "utf-8"));
+        if (cache === null || typeof cache !== "object" || Array.isArray(cache))
+            return null;
+        const { lastCheck, latestVersion } = cache;
+        if (typeof lastCheck !== "number" || !Number.isFinite(lastCheck))
+            return null;
+        return isPlainReleaseVersion(latestVersion) ? latestVersion : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Checks the npm registry for a newer version of @bridge_gpt/mcp-server.
  * Results are cached for 24 hours. Returns null if the check fails.
  */
-export async function checkForUpdate() {
+export async function checkForUpdate(options = {}) {
     try {
+        const override = readFakeLatestOverride(options.env ?? process.env);
+        if (override) {
+            // An override is never cached, so it cannot outlive the manual test.
+            return {
+                updateAvailable: isNewerVersion(VERSION, override),
+                currentVersion: VERSION,
+                latestVersion: override,
+            };
+        }
+        const useCache = options.readCache !== false;
+        const saveCache = options.writeCache !== false;
         const cachePath = getCachePath();
         const cacheDir = path.dirname(cachePath);
         let latestVersion = null;
         // Try reading cache
-        try {
-            const raw = await readFile(cachePath, "utf-8");
-            const cache = JSON.parse(raw);
-            if (cache &&
-                typeof cache.lastCheck === "number" &&
-                typeof cache.latestVersion === "string" &&
-                Date.now() - cache.lastCheck < CACHE_TTL) {
-                latestVersion = cache.latestVersion;
+        if (useCache) {
+            try {
+                const raw = await readFile(cachePath, "utf-8");
+                const cache = JSON.parse(raw);
+                if (cache &&
+                    typeof cache.lastCheck === "number" &&
+                    isPlainReleaseVersion(cache.latestVersion) &&
+                    Date.now() - cache.lastCheck < CACHE_TTL) {
+                    latestVersion = cache.latestVersion;
+                }
+            }
+            catch {
+                // Cache missing, corrupt, or stale — will fetch fresh
             }
-        }
-        catch {
-            // Cache missing, corrupt, or stale — will fetch fresh
         }
         // Fetch from registry if no valid cache
         if (!latestVersion) {
@@ -57,10 +136,12 @@ export async function checkForUpdate() {
             try {
                 const res = await fetch(REGISTRY_URL, { signal: controller.signal });
                 const data = await res.json();
-                if (data.version) {
+                if (isPlainReleaseVersion(data.version)) {
                     latestVersion = data.version;
-                    await mkdir(cacheDir, { recursive: true });
-                    await writeFile(cachePath, JSON.stringify({ lastCheck: Date.now(), latestVersion }), "utf-8");
+                    if (saveCache) {
+                        await mkdir(cacheDir, { recursive: true });
+                        await writeFile(cachePath, JSON.stringify({ lastCheck: Date.now(), latestVersion }), "utf-8");
+                    }
                 }
             }
             finally {

package/build/update-status.js

@@ -1,69 +1,86 @@
 /**
- * Process-wide cached update status (BAPI-728).
+ * Process-wide settled update status (BAPI-728, reshaped by BAPI-1446).
  *
- * 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.
+ * The staleness signal already existed: `checkForUpdate()` ran on every server
+ * start and computed the right answer, then announced it to a log sink nobody
+ * reads. BAPI-1446 moved delivery to surfaces a session actually reads (startup
+ * instructions, the first completed tool result, the SessionStart hook). This
+ * manager is now only the source of one fact for those surfaces: what the live
+ * check concluded, once it has settled.
  *
- * This manager gives that value two readers instead of zero: one stderr warning
- * per process (humans), and a `tools/list` advisory (models). It is:
+ * The settled-status contract:
  *
  *   - **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.
+ *   - **non-blocking** — `start()` returns at once and is never awaited before
+ *     `connect`; `getStatus()` is synchronous and never waits for the lookup;
+ *   - **known versus unknown** — `known: true` means a reliable live result
+ *     settled, including "you are current". Initial, in-flight, disabled,
+ *     rejected, null, and malformed outcomes are `known: false` and not stale, so
+ *     the tool-result channel never mistakes "unknown" for "confirmed current"
+ *     and can fall back to the local cache;
+ *   - **fail-open** — nothing here throws, and `whenSettled()` never rejects.
  *
- * The manager is default-on. Passing `enabled: false` (BAPI-917) makes it
- * permanently `NOT_STALE` from the moment `start()` returns, without ever
- * invoking the checker, touching the update cache, or making a registry
- * request — used so a hermetic measurement capture cannot be perturbed by
- * runtime update state.
+ * `stale` is kept for existing production consumers and is only ever true for a
+ * reliable newer result.
+ *
+ * Passing `enabled: false` (BAPI-917) makes the manager permanently unknown from
+ * the moment `start()` returns, without invoking the checker, touching the update
+ * cache, or making a registry request — used so a hermetic measurement capture
+ * cannot be perturbed by runtime update state.
  */
-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 };
+import { checkForUpdate, isNewerVersion, isPlainReleaseVersion, readFakeLatestOverride, } from "./update-check.js";
+import { VERSION } from "./version.generated.js";
+/** The unknown conclusion, used for every fail-open branch. */
+const UNKNOWN = { stale: false, known: 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));
+    const env = options.env ?? process.env;
+    const check = options.check ?? (() => checkForUpdate({ env }));
     const enabled = options.enabled !== false;
+    const runningVersion = options.currentVersion ?? VERSION;
     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.
+        // Every uncertain shape is unknown. A malformed payload must never produce a
+        // claim about a version that may not exist.
         if (!result || typeof result !== "object")
-            return NOT_STALE;
-        if (result.updateAvailable !== true)
-            return NOT_STALE;
+            return UNKNOWN;
+        if (typeof result.updateAvailable !== "boolean")
+            return UNKNOWN;
         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 };
+        if (!isPlainReleaseVersion(currentVersion))
+            return UNKNOWN;
+        if (!isPlainReleaseVersion(latestVersion))
+            return UNKNOWN;
+        return { stale: result.updateAvailable, known: true, currentVersion, latestVersion };
     }
     function start() {
         if (started)
             return;
         started = true;
         if (!enabled) {
-            // Disabled: settle immediately, without ever invoking `check`, warning,
-            // or scheduling a checker operation. `whenSettled()` stays usable — it
-            // just resolves to the same already-known conclusion.
-            settled = NOT_STALE;
-            settledPromise = Promise.resolve(NOT_STALE);
+            // Disabled: settle immediately, without ever invoking `check`. `whenSettled()`
+            // stays usable — it just resolves to the same already-known conclusion.
+            settled = UNKNOWN;
+            settledPromise = Promise.resolve(UNKNOWN);
+            return;
+        }
+        // A valid fake-latest override settles at once, before any filesystem or
+        // registry work, exactly as `checkForUpdate` honors it.
+        const override = readFakeLatestOverride(env);
+        if (override && isPlainReleaseVersion(runningVersion)) {
+            const status = {
+                stale: isNewerVersion(runningVersion, override),
+                known: true,
+                currentVersion: runningVersion,
+                latestVersion: override,
+            };
+            settled = status;
+            settledPromise = Promise.resolve(status);
             return;
         }
         settledPromise = (async () => {
@@ -72,46 +89,19 @@ export function createUpdateStatusManager(options = {}) {
                 status = conclude(await check());
             }
             catch {
-                status = NOT_STALE; // `checkForUpdate` is contracted not to reject; belt and braces.
+                status = UNKNOWN; // `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,
+        getStatus: () => settled ?? UNKNOWN,
         whenSettled: async () => {
             if (!started)
                 start();
-            return (await settledPromise) ?? NOT_STALE;
-        },
-        markListServed: () => {
-            listServed = true;
+            return (await settledPromise) ?? UNKNOWN;
         },
     };
 }
-/**
- * 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

@@ -29,20 +29,24 @@ 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.
+ * Format the human-facing staleness line (stderr, terminal, `doctor`, and the
+ * `ping` advice item). It names both versions and the slash command, and carries
+ * no instruction for a model; the model-directed text is
+ * {@link formatSessionUpgradeNotice}.
  */
 export function formatUpdateAdvice(currentVersion, latestVersion) {
-    return (`Bridge API MCP server update available: running ${sanitizeVersion(currentVersion)}, ` +
-        `latest ${sanitizeVersion(latestVersion)} — run ${CANONICAL_UPGRADE_COMMAND}`);
+    return (`Bridge MCP: installed ${sanitizeVersion(currentVersion)}, ` +
+        `latest ${sanitizeVersion(latestVersion)} — upgrade available — run /upgrade-bridge`);
 }
 /**
- * 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).
+ * Format the one-line, plain-text notice delivered to a model session (startup
+ * instructions, the first completed tool result, the SessionStart hook). It tells
+ * the model to inform the user, offer the upgrade, and run `/upgrade-bridge`
+ * only if they say yes. Both versions go through `sanitizeVersion`, so no
+ * caller can interpolate arbitrary text.
  */
-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}`);
+export function formatSessionUpgradeNotice(current, latest) {
+    return (`Bridge MCP upgrade available: this session is running ${sanitizeVersion(current)} ` +
+        `and ${sanitizeVersion(latest)} is published. Tell the user an upgrade is available, ` +
+        "offer to run /upgrade-bridge, and run it only if they say yes.");
 }