memtrace 0.3.37 → 0.3.39

package/bin/memtrace.js

@@ -5,8 +5,11 @@ const os   = require("os");
 const path = require("path");
 const fs   = require("fs");
 const { spawnSync, spawn } = require("child_process");
+const readline = require("readline");
 const { getBinaryPath } = require("../install.js");
 const { platformBinary, spawnOptionsForPlatform } = require("../lib/spawn-helper");
+const { shouldPromptForUpgrade, isPromptDisabled } = require("../lib/update-prompt");
+const { fetchLatestVersion, readCachedVersion } = require("../lib/update-check");
 
 // ── Handle `memtrace uninstall` before delegating to the Rust binary ────────
 // npm v7+ does NOT fire preuninstall hooks for global packages (npm/cli#3042).
@@ -127,58 +130,27 @@ try {
 }
 
 // ── Update checker ────────────────────────────────────────────────────────────
-// Checks registry.npmjs.org at most once every 24 h (cached in ~/.memtrace/).
-// Completely non-blocking: errors are silently swallowed.
-
-const CACHE_FILE    = path.join(os.homedir(), ".memtrace", "update-check.json");
-const CHECK_INTERVAL = 24 * 60 * 60 * 1000; // 24 h in ms
+//
+// Policy (v0.3.39+): always TRY a fresh HTTP fetch first (1.5s timeout —
+// invisible to humans). On any failure (timeout, network, 5xx, parse
+// error), fall back to the on-disk cache. The cache also serves as the
+// Node ↔ Rust IPC handoff for the MCP banner: the Rust binary reads
+// `~/.memtrace/update-check.json` to decide whether to surface an
+// "update available" line in serverInfo.instructions for agents.
+//
+// We dropped the previous 24h TTL because it directly contradicted the
+// visibility goal: a user installing v0.3.36 the hour we shipped v0.3.37
+// would have waited 23 hours before their banner reflected reality.
+//
+// Implementation lives in lib/update-check.js and is unit + property
+// tested with injectable httpGet / cache path.
 
-function readUpdateCache() {
-  try {
-    return JSON.parse(fs.readFileSync(CACHE_FILE, "utf-8"));
-  } catch {
-    return null;
-  }
-}
-
-function writeUpdateCache(data) {
-  try {
-    fs.mkdirSync(path.dirname(CACHE_FILE), { recursive: true });
-    fs.writeFileSync(CACHE_FILE, JSON.stringify(data), "utf-8");
-  } catch {
-    // non-fatal
-  }
-}
+const CACHE_FILE = path.join(os.homedir(), ".memtrace", "update-check.json");
 
 function checkForUpdate(currentVersion) {
-  return new Promise((resolve) => {
-    // Return cached result if it's fresh enough
-    const cache = readUpdateCache();
-    if (cache && Date.now() - cache.checkedAt < CHECK_INTERVAL) {
-      resolve(cache.latestVersion !== currentVersion ? cache.latestVersion : null);
-      return;
-    }
-
-    const https = require("https");
-    const req = https.get(
-      "https://registry.npmjs.org/memtrace/latest",
-      { headers: { Accept: "application/json" }, timeout: 3000 },
-      (res) => {
-        let body = "";
-        res.on("data", (chunk) => (body += chunk));
-        res.on("end", () => {
-          try {
-            const latest = JSON.parse(body).version;
-            writeUpdateCache({ checkedAt: Date.now(), latestVersion: latest });
-            resolve(latest !== currentVersion ? latest : null);
-          } catch {
-            resolve(null);
-          }
-        });
-      }
-    );
-    req.on("error",   () => resolve(null));
-    req.on("timeout", () => { req.destroy(); resolve(null); });
+  return fetchLatestVersion({ cachePath: CACHE_FILE }).then((latest) => {
+    if (!latest) return null;
+    return latest !== currentVersion ? latest : null;
   });
 }
 
@@ -199,6 +171,91 @@ const updateCheckPromise = checkForUpdate(currentVersion).then((latest) => {
   }
 });
 
+// ── Interactive upgrade prompt for `memtrace start` / `memtrace index` ───
+//
+// `memtrace mcp` is non-interactive (agents would hang) so we never
+// prompt there — that path is handled by the Rust binary's banner in
+// serverInfo.instructions. For interactive long-running commands, if
+// our cached check found a newer version on npm, ask once before
+// delegating to the binary. ENTER defaults to "no" to keep automation
+// scripts unblocked. Set MEMTRACE_NO_UPDATE_PROMPT=1 to opt out.
+async function maybePromptForUpgrade(command) {
+  // Wait briefly for the in-flight check to populate the cache, but
+  // don't hold the user up if the network is slow. 1.5s budget — if
+  // the check hasn't completed, fall back to whatever was cached.
+  await Promise.race([
+    updateCheckPromise,
+    new Promise((r) => setTimeout(r, 1500)),
+  ]);
+
+  // After awaiting the in-flight check, the cache file holds whatever
+  // the fresh fetch produced (or last-known-good if it failed). Use
+  // readCachedVersion as the single source of truth here.
+  const cachedLatest = readCachedVersion(CACHE_FILE);
+
+  const decision = shouldPromptForUpgrade({
+    command,
+    isTty: Boolean(process.stdin.isTTY && process.stdout.isTTY),
+    cachedLatestVersion: cachedLatest,
+    currentVersion,
+    suppressEnv: isPromptDisabled(process.env),
+  });
+  if (!decision) return false;
+
+  // Ask. Default = no.
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+  const answer = await new Promise((resolve) => {
+    rl.question(
+      `\n[memtrace] Update available: ${currentVersion} → ${cachedLatest}\n` +
+      `           Upgrade now? [y/N] `,
+      resolve,
+    );
+  });
+  rl.close();
+
+  if (!/^y(es)?$/i.test(answer.trim())) {
+    process.stdout.write(
+      `[memtrace] Continuing with ${currentVersion}. ` +
+      `Run \x1b[1mmemtrace install\x1b[0m anytime to upgrade.\n\n`,
+    );
+    return false;
+  }
+
+  // Run npm install -g memtrace@latest, then re-exec the user's
+  // original command via the new binary on PATH.
+  process.stdout.write("[memtrace] Upgrading…\n");
+  const npmCmd = platformBinary("npm", process.platform);
+  const installResult = spawnSync(
+    npmCmd,
+    ["install", "-g", "memtrace@latest"],
+    spawnOptionsForPlatform(process.platform, {
+      stdio: "inherit",
+      env: process.env,
+    }),
+  );
+  if (installResult.status !== 0) {
+    process.stderr.write(
+      "[memtrace] Upgrade failed; continuing with current version.\n\n",
+    );
+    return false;
+  }
+
+  // Chain into the new binary.
+  const memtraceCmd = platformBinary("memtrace", process.platform);
+  const runResult = spawnSync(
+    memtraceCmd,
+    args,
+    spawnOptionsForPlatform(process.platform, {
+      stdio: "inherit",
+      env: process.env,
+    }),
+  );
+  process.exit(runResult.status ?? 0);
+}
+
 if (args[0] === "mcp") {
   // MCP mode: async spawn so Node's event loop keeps running long enough
   // for the update check to print its notice to the agent's stderr.
@@ -216,19 +273,29 @@ if (args[0] === "mcp") {
   });
 
 } else {
-  // All other commands: synchronous pass-through. The update check
-  // already fired above; cache write happens in the background and we
-  // don't block on it (the http GET timeout is 3 s, well under any
-  // reasonable user-visible startup budget).
-  const result = spawnSync(binaryPath, args, {
-    stdio: "inherit",
-    env:   process.env,
-  });
-
-  if (result.error) {
-    console.error(`Failed to run memtrace: ${result.error.message}`);
-    process.exit(1);
-  }
-
-  process.exit(result.status ?? 0);
+  // All other commands: synchronous pass-through, but FIRST give the
+  // user a chance to upgrade if cached check found a newer version.
+  // The prompt is gated on TTY + start/index command + cache says newer
+  // (see lib/update-prompt.js for the gating logic). When the user
+  // accepts, maybePromptForUpgrade calls process.exit() and we never
+  // reach the spawn below.
+  (async () => {
+    try {
+      await maybePromptForUpgrade(args[0]);
+    } catch (e) {
+      // Prompting must never block the user's command. Eat any error.
+      process.stderr.write(
+        `[memtrace] Update prompt failed (continuing): ${e.message}\n`,
+      );
+    }
+    const result = spawnSync(binaryPath, args, {
+      stdio: "inherit",
+      env:   process.env,
+    });
+    if (result.error) {
+      console.error(`Failed to run memtrace: ${result.error.message}`);
+      process.exit(1);
+    }
+    process.exit(result.status ?? 0);
+  })();
 }

package/lib/update-check.js

@@ -0,0 +1,161 @@
+"use strict";
+
+// Update-check with cache-as-fallback semantics.
+//
+// Pre-v0.3.39 we cached the npm-registry result for 24h to avoid
+// hammering the registry. The downside: a user installing v0.3.36 the
+// hour we shipped v0.3.37 wouldn't see the upgrade banner for 23 more
+// hours. That defeats the entire visibility goal.
+//
+// New policy:
+//   1. Always TRY a fresh HTTP fetch (1.5s timeout — invisible to humans).
+//   2. On success, overwrite the cache and return fresh value.
+//   3. On any failure (timeout, network error, non-2xx, parse error),
+//      fall back to whatever the cache last contained.
+//   4. The cache still serves as the Node ↔ Rust IPC handoff: the Rust
+//      MCP banner reads `~/.memtrace/update-check.json` to decide
+//      whether to surface "update available" in `serverInfo.instructions`.
+//
+// All IO is dependency-injected so tests can drive arbitrary network
+// failure modes deterministically.
+
+const fs = require("fs");
+const path = require("path");
+const https = require("https");
+
+const NPM_LATEST_URL = "https://registry.npmjs.org/memtrace/latest";
+const DEFAULT_TIMEOUT_MS = 1500;
+
+/**
+ * Read the JSON cache file. Returns the parsed object, or null on any
+ * IO/parse error. Pure (only file IO at the path you give it).
+ */
+function readUpdateCache(cachePath) {
+    try {
+        return JSON.parse(fs.readFileSync(cachePath, "utf-8"));
+    } catch {
+        return null;
+    }
+}
+
+/**
+ * Write the cache atomically-ish (mkdir + writeFile). Errors are
+ * swallowed — the cache is opportunistic; failing to write must not
+ * break the user's command. Returns true if write succeeded, false on
+ * any error.
+ */
+function writeUpdateCache(cachePath, data) {
+    try {
+        fs.mkdirSync(path.dirname(cachePath), { recursive: true });
+        fs.writeFileSync(cachePath, JSON.stringify(data), "utf-8");
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Resolve the latest memtrace version on npm with cache fallback.
+ *
+ * @param {object} opts
+ * @param {string} opts.cachePath              absolute path to cache file
+ * @param {function(string): Promise<{body: string}>} [opts.httpGet]  injectable for tests
+ * @param {number} [opts.timeoutMs]            fetch timeout (default 1500)
+ * @param {function(): number} [opts.now]      time source (default Date.now)
+ * @returns {Promise<string|null>}             latest version string, or null when
+ *                                              fresh failed AND cache is empty/missing
+ */
+function fetchLatestVersion(opts = {}) {
+    if (!opts.cachePath) {
+        return Promise.reject(new Error("fetchLatestVersion: opts.cachePath is required"));
+    }
+    const httpGet = opts.httpGet || defaultHttpGet;
+    const timeoutMs = opts.timeoutMs || DEFAULT_TIMEOUT_MS;
+    const now = opts.now || Date.now;
+    const cachePath = opts.cachePath;
+
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = (value) => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(value);
+        };
+        const fallback = () => finish(readCachedVersion(cachePath));
+
+        const timer = setTimeout(fallback, timeoutMs);
+
+        Promise.resolve()
+            .then(() => httpGet(NPM_LATEST_URL))
+            .then((result) => {
+                if (!result || typeof result.body !== "string") {
+                    fallback();
+                    return;
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(result.body);
+                } catch {
+                    fallback();
+                    return;
+                }
+                if (!parsed || typeof parsed.version !== "string" || !parsed.version) {
+                    fallback();
+                    return;
+                }
+                writeUpdateCache(cachePath, {
+                    checkedAt: now(),
+                    latestVersion: parsed.version,
+                });
+                finish(parsed.version);
+            })
+            .catch(fallback);
+    });
+}
+
+/**
+ * Read the cached version string only (returns null if cache absent
+ * or shape is wrong). Useful when callers want to read the IPC handoff
+ * without triggering a network fetch.
+ */
+function readCachedVersion(cachePath) {
+    const cache = readUpdateCache(cachePath);
+    if (!cache || typeof cache.latestVersion !== "string" || !cache.latestVersion) {
+        return null;
+    }
+    return cache.latestVersion;
+}
+
+/**
+ * Default HTTP fetcher used in production. Resolves with `{body}` on
+ * 2xx, rejects on any other status, network error, or socket close.
+ */
+function defaultHttpGet(url) {
+    return new Promise((resolve, reject) => {
+        const req = https.get(
+            url,
+            { headers: { Accept: "application/json" } },
+            (res) => {
+                if (res.statusCode < 200 || res.statusCode >= 300) {
+                    res.resume();
+                    reject(new Error(`HTTP ${res.statusCode}`));
+                    return;
+                }
+                let body = "";
+                res.on("data", (chunk) => (body += chunk));
+                res.on("end", () => resolve({ body }));
+            },
+        );
+        req.on("error", reject);
+    });
+}
+
+module.exports = {
+    NPM_LATEST_URL,
+    DEFAULT_TIMEOUT_MS,
+    fetchLatestVersion,
+    readUpdateCache,
+    writeUpdateCache,
+    readCachedVersion,
+};

package/lib/update-prompt.js

@@ -0,0 +1,102 @@
+"use strict";
+
+// Interactive upgrade-prompt logic for `memtrace start` / `memtrace
+// index`. Pure helpers here; the side-effecting prompt + npm install
+// path lives in `bin/memtrace.js`.
+//
+// Why:
+//   `memtrace start` is the most-typed entrypoint for memtrace users.
+//   Pre-v0.3.38, our update detection was a stderr line that users
+//   easily missed — and ZERO of the MCP-spawned `memtrace mcp` users
+//   ever saw it because their stderr was captured by their agent.
+//
+//   So users would sit on stale binaries indefinitely. Even after we
+//   shipped v0.3.37 (the portable-MCP-runtime fix), users on v0.3.34
+//   would never know to upgrade because the only place they'd see
+//   the notice was in the agent's MCP log file.
+//
+//   v0.3.38 splits the problem in two:
+//     1. MCP startup banner — the Rust binary now injects an "update
+//        available" line into `serverInfo.instructions`, so agents
+//        read it as ambient context and surface it to users.
+//     2. Interactive prompt for `memtrace start` (this module) — when
+//        a user runs `memtrace start` in a TTY, if the cache shows a
+//        newer version on npm we prompt for one-keystroke upgrade.
+//
+// We don't auto-upgrade. We always ask. Surprise package upgrades on
+// "memtrace start" would be hostile to users who pin versions.
+
+const COMMANDS_WITH_PROMPT = new Set(["start", "index"]);
+
+/**
+ * Decide whether `memtrace start` (or another long-running command)
+ * should pause for an interactive upgrade prompt before delegating
+ * to the Rust binary. Pure: no IO, no prompting.
+ *
+ * @param {object} input
+ * @param {string} input.command          first positional arg, e.g. "start"
+ * @param {boolean} input.isTty           true iff stdin AND stdout are TTYs
+ * @param {string|null} input.cachedLatestVersion  from update-check.json
+ * @param {string} input.currentVersion   running shim's version
+ * @param {boolean} [input.suppressEnv]   true to honor MEMTRACE_NO_UPDATE_PROMPT
+ * @returns {boolean}
+ */
+function shouldPromptForUpgrade(input) {
+    if (!input || typeof input !== "object") return false;
+    if (input.suppressEnv) return false;
+    if (!input.isTty) return false;
+    if (!COMMANDS_WITH_PROMPT.has(input.command)) return false;
+    if (typeof input.cachedLatestVersion !== "string") return false;
+    if (input.cachedLatestVersion.trim() === "") return false;
+    if (input.cachedLatestVersion === input.currentVersion) return false;
+    if (!isNewerSemver(input.cachedLatestVersion, input.currentVersion)) return false;
+    return true;
+}
+
+/**
+ * Compare two semver strings. Returns true iff `a > b`. Tolerates
+ * pre-release suffixes ("0.3.38-rc1") by treating any pre-release as
+ * lower than the same-numbered release. Returns false on parse error.
+ */
+function isNewerSemver(a, b) {
+    const pa = parseSemver(a);
+    const pb = parseSemver(b);
+    if (!pa || !pb) return false;
+    if (pa.major !== pb.major) return pa.major > pb.major;
+    if (pa.minor !== pb.minor) return pa.minor > pb.minor;
+    if (pa.patch !== pb.patch) return pa.patch > pb.patch;
+    // a.pre absent + b.pre present -> a is newer (release > prerelease)
+    if (!pa.pre && pb.pre) return true;
+    if (pa.pre && !pb.pre) return false;
+    if (pa.pre && pb.pre) return pa.pre > pb.pre;
+    return false; // equal
+}
+
+function parseSemver(s) {
+    if (typeof s !== "string") return null;
+    const m = s.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-(.+))?$/);
+    if (!m) return null;
+    return {
+        major: parseInt(m[1], 10),
+        minor: parseInt(m[2], 10),
+        patch: parseInt(m[3], 10),
+        pre: m[4] || null,
+    };
+}
+
+/**
+ * Check whether MEMTRACE_NO_UPDATE_PROMPT is set to a truthy value.
+ * Pure (takes the env object as input for testability).
+ */
+function isPromptDisabled(env) {
+    const v = (env && env.MEMTRACE_NO_UPDATE_PROMPT) || "";
+    return ["1", "true", "yes", "on"].includes(String(v).toLowerCase());
+}
+
+module.exports = {
+    COMMANDS_WITH_PROMPT,
+    shouldPromptForUpgrade,
+    isNewerSemver,
+    parseSemver,
+    isPromptDisabled,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memtrace",
-  "version": "0.3.37",
+  "version": "0.3.39",
   "description": "Code intelligence graph — MCP server + AI agent skills + visualization UI",
   "keywords": [
     "mcp",
@@ -39,9 +39,9 @@
     "fs-extra": "^11.0.0"
   },
   "optionalDependencies": {
-    "@memtrace/darwin-arm64": "0.3.37",
-    "@memtrace/linux-x64": "0.3.37",
-    "@memtrace/win32-x64": "0.3.37"
+    "@memtrace/darwin-arm64": "0.3.39",
+    "@memtrace/linux-x64": "0.3.39",
+    "@memtrace/win32-x64": "0.3.39"
   },
   "engines": {
     "node": ">=18"