sentinel-ir-mcp 0.5.3 → 0.5.5

package/README.md

@@ -28,6 +28,21 @@ of safety. Other languages are not supported yet. What is detected in Python
 and Rust (and what is not) is listed in the
 [sentinel-ir README](https://gitlab.com/jakubrojicek11/sentinel-ir#python).
 
+**0.5.5** fixes the update check in `doctor`: it goes through the proxy npm
+would use (`npm_config_https_proxy`/`npm_config_proxy`, `HTTPS_PROXY`/`HTTP_PROXY`,
+`NO_PROXY`), follows up to 3 registry redirects (never from https to http), and
+says what it found: "newer than npm's stable-0.5 (0.5.3)" when this copy is
+ahead of npm, and "points to ..., not a release version" for a pre-release
+or broken tag instead of "npm has no tag".
+
+**0.5.4** makes `doctor` notice an old copy of itself: it asks npm for the
+newest release on its `stable-X.Y` tag (3 s timeout, skipped offline) and,
+when that is newer, warns and says where the old copy runs from (npx cache,
+global install or another folder) and how to replace it. Before, `npx
+sentinel-ir-mcp doctor` without a version could run an old copy and report
+`[ok]`. The last line now counts warnings (`All checks passed, 1 warning
+above.`).
+
 **0.5.3** splits each tool description into short lines (what it returns,
 parameters, risk scale, when to use another tool) and names the sibling tools
 in all three; `analyze_code` no longer repeats the language rule its schema
@@ -257,7 +272,8 @@ without a shell failed with `ENOENT` on a real Windows runner. For VS Code and
 Claude Code, `setup` prints a PowerShell and a Command Prompt version of the
 command. What was measured on which system: [COMPATIBILITY.md](COMPATIBILITY.md).
 
-`doctor` checks Node.js, the package version, the client config (valid JSON, a
+`doctor` checks Node.js, the package version (and asks the npm registry, or
+`npm_config_registry`, through npm's proxy settings, whether its `stable-X.Y` tag has a newer release), the client config (valid JSON, a
 `"sentinel-ir"` entry that starts `sentinel-ir-mcp`, existing folders), then
 starts **its own** server with the same folders, performs a real MCP
 handshake, expects exactly the three tools and calls `analyze_directory` with

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sentinel-ir-mcp",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "mcpName": "io.github.jakcmencz/sentinel-ir-mcp",
   "description": "MCP server for sentinel-ir: lets AI agents (Claude Desktop, Cursor, Windsurf, ...) read a compact structural IR of JavaScript, TypeScript, Python and Rust files instead of the raw source. Read-only, sandboxed to allowed folders.",
   "main": "src/server.js",

package/src/cli.js

@@ -2,7 +2,7 @@
 
 const readline = require("readline");
 const { runSetup } = require("./setup");
-const { runDoctor } = require("./doctor");
+const { runDoctor, fetchDistTagsIsolated } = require("./doctor");
 const { GUIDE } = require("./guide");
 const { runLog } = require("./logView");
 const { CLIENT_NAMES, PACKAGE_SPEC } = require("./clients");
@@ -103,6 +103,7 @@ function defaultIo() {
         env: process.env,
         platform: process.platform,
         cwd: process.cwd(),
+        fetchDistTags: fetchDistTagsIsolated,
         isTTY,
         prompt: isTTY ? (question) => new Promise((resolve) => {
             const rl = readline.createInterface({ input: process.stdin, output: process.stdout });

package/src/doctor.js

@@ -1,6 +1,9 @@
 "use strict";
 
 const fs = require("fs");
+const http = require("http");
+const https = require("https");
+const net = require("net");
 const path = require("path");
 const { Client } = require("@modelcontextprotocol/sdk/client/index.js");
 const { StdioClientTransport } = require("@modelcontextprotocol/sdk/client/stdio.js");
@@ -44,12 +47,255 @@ function readVersion(file) {
     }
 }
 
-// The _npx/<key> folder this copy was started from, or null.
-function npxCopyDir() {
-    const m = new RegExp(`^(.*\\${path.sep}_npx\\${path.sep}[^\\${path.sep}]+)\\${path.sep}`).exec(__dirname);
+const PACKAGE_DIR = path.join(__dirname, "..");
+
+// The _npx/<key> folder the package in dir was started from, or null.
+function npxCopyDir(dir = PACKAGE_DIR) {
+    const m = /^(.*[\\/]_npx[\\/][^\\/]+)[\\/]/.exec(dir);
     return m ? m[1] : null;
 }
 
+// The prefix line of an npmrc file (npm's ${VAR} and ~/ expanded), or null.
+function npmrcPrefix(file, env, home) {
+    let text;
+    try { text = fs.readFileSync(file, "utf8"); } catch { return null; }
+    const m = /^[ \t]*prefix[ \t]*=[ \t]*(.*?)[ \t]*$/m.exec(text);
+    if (!m || !m[1]) return null;
+    // as npm's ini: a quoted value is literal, an unquoted one ends at an unescaped ; or #
+    const q = /^(["'])(.*)\1$/.exec(m[1]);
+    let v = (q ? q[2] : m[1].replace(/(^|[^\\])[;#].*$/, "$1").trim().replace(/\\([;#\\])/g, "$1")).replace(/\$\{([^}]+)\}/g, (_, k) => env[k] || "");
+    if (/^~[\\/]/.test(v) && home) v = path.join(home, v.slice(2));
+    return v;
+}
+
+// Where npm installs a global sentinel-ir-mcp: the first entry is npm's prefix now; the rest are other
+// places a global install may sit (also %APPDATA%\\npm).
+function globalDirs(env, platform, execPath) {
+    const p = platform === "win32" ? path.win32 : path.posix;
+    const nodePrefix = platform === "win32" ? p.dirname(execPath) : p.dirname(p.dirname(execPath));
+    const home = env.HOME || env.USERPROFILE;
+    const cfg = (k) => env[`npm_config_${k}`] || env[`NPM_CONFIG_${k.toUpperCase()}`];
+    // npm's prefix: environment, then user, global and builtin npmrc (Homebrew sets it there), then the default
+    const builtinPrefix = npmrcPrefix(p.join(nodePrefix, ...(platform === "win32" ? [] : ["lib"]), "node_modules", "npm", "npmrc"), env, home);
+    const prefixes = [cfg("prefix"),
+        npmrcPrefix(cfg("userconfig") || (home ? p.join(home, ".npmrc") : ""), env, home),
+        npmrcPrefix(cfg("globalconfig") || p.join(builtinPrefix || nodePrefix, "etc", "npmrc"), env, home),
+        builtinPrefix,
+        nodePrefix,
+        platform === "win32" && env.APPDATA ? p.join(env.APPDATA, "npm") : null];
+    const dirs = prefixes.filter(Boolean).map((x) => p.join(x, ...(platform === "win32" ? [] : ["lib"]), "node_modules", "sentinel-ir-mcp"));
+    return [...new Set(dirs)];
+}
+
+const realDir = (d) => { try { return fs.realpathSync(d); } catch { return d; } };
+const sameDir = (a, b) => a.replace(/[\\/]+$/, "").toLowerCase() === b.replace(/[\\/]+$/, "").toLowerCase();
+
+// Where the package in dir is installed: an npx cache copy, a global install or elsewhere.
+function installKind(dir, globals = []) {
+    const npx = npxCopyDir(dir);
+    if (npx) return { kind: "npx", dir: npx, key: /[^\\/]+$/.exec(npx)[0] };
+    if (/[\\/](lib|npm)[\\/]node_modules[\\/]sentinel-ir-mcp[\\/]?$/i.test(dir) || globals.some((g) => sameDir(g, dir))) return { kind: "global", dir };
+    return { kind: "other", dir };
+}
+
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+
+const unescapeLogin = (s) => { try { return decodeURIComponent(s); } catch { return s; } };
+
+// The proxy npm would use for url (npm's https-proxy and proxy settings, then HTTPS_PROXY/HTTP_PROXY), null for none,
+// false for a proxy setting doctor cannot use (it then skips instead of going direct).
+function proxyFor(url, env) {
+    const noProxy = env.npm_config_noproxy || env.NO_PROXY || env.no_proxy || "";
+    const host = url.hostname.replace(/^\[|\]$/g, "").replace(/\.$/, "").toLowerCase();
+    for (const rule of noProxy.split(/[\s,]+/).filter(Boolean)) {
+        const bare = /^\[(.*)\](:\d+)?$/.exec(rule)?.[1] ?? (rule.split(":").length === 2 ? rule.replace(/:\d+$/, "") : rule);
+        const r = bare.replace(/^\*?\.?/, "").replace(/\.$/, "").toLowerCase();
+        if (rule === "*" || host === r || host.endsWith("." + r)) return null;
+    }
+    // npm: its https-proxy, then proxy setting, for http registries too; then the environment.
+    const raw = env.npm_config_https_proxy || env.npm_config_proxy || env.HTTPS_PROXY || env.https_proxy || env.HTTP_PROXY || env.http_proxy;
+    if (!raw) return null;
+    try {
+        const p = new URL(/^[a-z][a-z0-9+.-]*:\/\//i.test(raw) ? raw : `http://${raw}`);
+        return p.protocol === "http:" || p.protocol === "https:" ? p : false;
+    } catch { return false; }
+}
+
+// GET url directly or through proxy; calls back with the response. Adds every request it opens to open.
+function openGet(url, env, tls, open, onResponse, onFail) {
+    try { openGetOrThrow(url, env, tls, open, onResponse, onFail); } catch { onFail(); }
+}
+
+function openGetOrThrow(url, env, tls, open, onResponse, onFail) {
+    // The registry login goes in a header we build: Node throws on a malformed % in URL credentials.
+    const bare = new URL(url.href);
+    bare.username = bare.password = "";
+    const headers = { accept: "application/json",
+        ...(url.username || url.password ? { authorization: "Basic " + Buffer.from(`${unescapeLogin(url.username)}:${unescapeLogin(url.password)}`).toString("base64") } : {}) };
+    const proxy = proxyFor(url, env);
+    if (proxy === false) { onFail(); return; }
+    if (!proxy) {
+        const req = (url.protocol === "https:" ? https : http).get(bare, { headers, ...tls }, onResponse);
+        req.on("error", onFail);
+        open.push(req);
+        return;
+    }
+    const proxyLib = proxy.protocol === "https:" ? https : http;
+    const auth = proxy.username
+        ? { "proxy-authorization": "Basic " + Buffer.from(`${unescapeLogin(proxy.username)}:${unescapeLogin(proxy.password)}`).toString("base64") }
+        : {};
+    const target = { host: proxy.hostname.replace(/^\[|\]$/g, ""), port: proxy.port || (proxy.protocol === "https:" ? 443 : 80) };
+    if (url.protocol === "http:") {
+        const req = proxyLib.get({ ...target, path: bare.href, headers: { ...headers, ...auth, host: bare.host } }, onResponse);
+        req.on("error", onFail);
+        open.push(req);
+        return;
+    }
+    const connect = proxyLib.request({ ...target, method: "CONNECT", path: `${url.hostname}:${url.port || 443}`, headers: { ...auth, host: `${url.hostname}:${url.port || 443}` } });
+    connect.on("connect", (res, socket) => {
+        if (res.statusCode !== 200) { socket.destroy(); onFail(); return; }
+        const req = https.get(bare, {
+            headers, ...tls,
+            createConnection: () => require("tls").connect({ socket, host: url.hostname.replace(/^\[|\]$/g, ""), servername: net.isIP(url.hostname.replace(/^\[|\]$/g, "")) ? undefined : url.hostname, ...tls })
+        }, onResponse);
+        req.on("error", onFail);
+        open.push(req);
+    });
+    connect.on("error", onFail);
+    connect.end();
+    open.push(connect);
+}
+
+// npm's strict-ssl and cafile settings as TLS options; null when the cafile is unreadable (npm fails then too).
+function npmTls(env) {
+    const t = {};
+    if (/^false$/i.test(env.npm_config_strict_ssl || "")) t.rejectUnauthorized = false;
+    if (env.npm_config_cafile) {
+        try { t.ca = [...require("tls").rootCertificates, fs.readFileSync(env.npm_config_cafile, "utf8")]; } catch { return null; }
+    }
+    return t;
+}
+
+// npm dist-tags of sentinel-ir-mcp, or null when the registry does not answer in time.
+// Uses npm_config_registry and the proxy npm would use; follows up to 3 redirects.
+function fetchDistTags(env, timeoutMs = 3000, tls = npmTls(env)) {
+    return new Promise((resolve) => {
+        if (tls === null) { resolve(null); return; }
+        let open = [];
+        let done = false;
+        const finish = (v) => {
+            if (done) return;
+            done = true;
+            clearTimeout(timer);
+            for (const r of open) r.destroy();
+            resolve(v);
+        };
+        const timer = setTimeout(() => finish(null), timeoutMs);
+        const get = (url, hops) => {
+            if (url.protocol !== "http:" && url.protocol !== "https:") { finish(null); return; }
+            openGet(url, env, tls, open, (res) => {
+                if (REDIRECTS.has(res.statusCode) && res.headers.location && hops < 3) {
+                    res.destroy();
+                    let next;
+                    try { next = new URL(res.headers.location, url); } catch { finish(null); return; }
+                    if (url.protocol === "https:" && next.protocol !== "https:") { finish(null); return; }
+                    get(next, hops + 1);
+                    return;
+                }
+                if (res.statusCode !== 200) { res.resume(); finish(null); return; }
+                const chunks = [];
+                let size = 0;
+                res.on("data", (d) => { chunks.push(d); size += d.length; if (size > 65536) finish(null); });
+                res.on("end", () => {
+                    try {
+                        const tags = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+                        finish(tags && typeof tags === "object" && !Array.isArray(tags) ? tags : null);
+                    } catch { finish(null); }
+                });
+                res.on("error", () => finish(null));
+                res.on("aborted", () => finish(null));
+            }, () => finish(null));
+        };
+        let url;
+        try {
+            url = new URL("-/package/sentinel-ir-mcp/dist-tags", (env.npm_config_registry || "https://registry.npmjs.org/").replace(/\/?$/, "/"));
+        } catch { finish(null); return; }
+        get(url, 0);
+    });
+}
+
+// fetchDistTags in a child process that is killed on timeout: a DNS lookup that never answers
+// cannot be cancelled and would keep doctor's own process alive for up to 30 s.
+function fetchDistTagsIsolated(env, timeoutMs = 3000) {
+    return new Promise((resolve) => {
+        let out = "";
+        let child;
+        let done = false;
+        const finish = (v) => {
+            if (done) return;
+            done = true;
+            clearTimeout(timer);
+            if (child) child.kill();
+            resolve(v);
+        };
+        const timer = setTimeout(() => finish(null), timeoutMs + 1000);
+        try {
+            child = require("child_process").spawn(process.execPath,
+                ["-e", `require(process.argv[1]).fetchDistTags(process.env, ${Number(timeoutMs)}).then((t) => process.stdout.write(JSON.stringify(t) + "\\n"))`, __filename],
+                { env, stdio: ["ignore", "pipe", "ignore"], windowsHide: true });
+        } catch { finish(null); return; }
+        child.on("error", () => finish(null));
+        child.on("close", () => finish(null));
+        child.stdout.on("data", (d) => {
+            out += d;
+            if (!out.includes("\n")) return;
+            let tags = null;
+            try { tags = JSON.parse(out); } catch { /* unusable */ }
+            finish(tags && typeof tags === "object" && !Array.isArray(tags) ? tags : null);
+        });
+    });
+}
+
+// Warns when npm has a newer release on this version's stable-X.Y tag; says where this copy runs from.
+async function checkUpdate(io, add) {
+    if (typeof io.fetchDistTags !== "function") return;
+    const m = /^(\d+)\.(\d+)\./.exec(version);
+    const tag = m ? `stable-${m[1]}.${m[2]}` : "latest";
+    const tags = await io.fetchDistTags(io.env);
+    if (!tags) {
+        add("skip", "package.update", "No usable answer from the npm registry about a newer sentinel-ir-mcp (offline, blocked or an unexpected reply)");
+        return;
+    }
+    const newest = Object.prototype.hasOwnProperty.call(tags, tag) ? tags[tag] : undefined;
+    if (newest === undefined) {
+        add("skip", "package.update", `npm has no ${tag} tag for sentinel-ir-mcp`);
+        return;
+    }
+    if (typeof newest !== "string" || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/.test(newest)) {
+        const shown = JSON.stringify(newest) ?? String(newest);
+        add("skip", "package.update", `npm's ${tag} tag points to ${shown.length > 40 ? shown.slice(0, 40) + "..." : shown}, not a release version; no update check`);
+        return;
+    }
+    if (newest === version) {
+        add("ok", "package.update", `sentinel-ir-mcp ${version} is the newest ${tag} on npm`);
+        return;
+    }
+    if (!olderThan(version, newest)) {
+        add("ok", "package.update", `sentinel-ir-mcp ${version} is newer than npm's ${tag} (${newest})`);
+        return;
+    }
+    const spec = `sentinel-ir-mcp@${tag}`;
+    const globals = globalDirs(io.env, io.platform, io.execPath || process.execPath).flatMap((g) => [g, realDir(g)]);
+    const from = installKind(io.packageDir || PACKAGE_DIR, globals);
+    const where = { npx: `the npx cache (${from.dir})`, global: `a global install (${from.dir})`, other: from.dir }[from.kind];
+    const fix = {
+        npx: `Close the client, delete that folder (npm 11: npm cache npx rm ${from.key}), then run: npx -y ${spec} setup`,
+        global: `Run: npm install -g ${spec} (or npm uninstall -g sentinel-ir-mcp), then: npx -y ${spec} doctor`,
+        other: `Run the current version: npx -y ${spec} doctor`
+    }[from.kind];
+    add("warn", "package.update", `This is sentinel-ir-mcp ${version}, npm has ${newest} (${tag}); this copy runs from ${where}`, fix);
+}
+
 // npm's cache folder: the one this copy was started from by npx, else npm's default.
 function npmCacheDir(env, platform) {
     const marker = `${path.sep}_npx${path.sep}`;
@@ -88,6 +334,21 @@ function staleNpxCopies(cacheDir) {
     return stale;
 }
 
+// A global install other than this copy that is older or runs an old sentinel-ir:
+// bare `npx sentinel-ir-mcp` and client entries without a version start it.
+function checkGlobalInstall(io, add) {
+    const running = io.packageDir || PACKAGE_DIR;
+    // only npm's current prefix: bare npx starts the global install there, not one left under an old prefix
+    for (const dir of globalDirs(io.env, io.platform, io.execPath || process.execPath).slice(0, 1)) {
+        if (sameDir(dir, running) || sameDir(realDir(dir), realDir(running)) || !fs.existsSync(path.join(dir, "package.json"))) continue;
+        const mcp = readVersion(path.join(dir, "package.json"));
+        const ir = readVersion(path.join(dir, "node_modules", "sentinel-ir", "package.json"));
+        if (!olderThan(mcp, version) && !olderThan(ir, IR_MIN)) continue;
+        add("warn", "package.global", `A global install of sentinel-ir-mcp ${mcp} (sentinel-ir ${ir}) is at ${dir}; bare npx sentinel-ir-mcp and client entries without a version start it`,
+            `Run: npm install -g ${PACKAGE_SPEC} (or npm uninstall -g sentinel-ir-mcp)`);
+    }
+}
+
 function checkNpxCache(env, platform, add) {
     const cacheDir = npmCacheDir(env, platform);
     const stale = staleNpxCopies(cacheDir);
@@ -279,6 +540,8 @@ async function runDoctor(opts, io) {
         add("fail", "package", `sentinel-ir-mcp ${version} runs sentinel-ir ${ir}, needs ${IR_MIN} or newer`,
             npxCopyDir() ? `Close the client, delete ${npxCopyDir()}, then run: npx -y ${PACKAGE_SPEC} setup` : `Reinstall it so that npm installs sentinel-ir ${dependencies["sentinel-ir"]}.`);
     } else add("ok", "package", `sentinel-ir-mcp ${version}, sentinel-ir ${ir}`);
+    await checkUpdate(io, add);
+    checkGlobalInstall(io, add);
     checkNpxCache(io.env, io.platform, add);
 
     const project = path.resolve(io.cwd, opts.project || ".");
@@ -323,9 +586,11 @@ async function runDoctor(opts, io) {
         io.stdout.write(JSON.stringify({ ok: !failed, checks }, null, 2) + "\n");
     } else {
         for (const c of checks) io.stdout.write(`${MARK[c.status]} ${c.message}\n${c.fix ? `       -> ${c.fix}\n` : ""}`);
-        io.stdout.write(failed ? "\nSome checks failed.\n" : "\nAll checks passed.\n");
+        const warnings = checks.filter((c) => c.status === "warn").length;
+        const warned = warnings ? `, ${warnings} warning${warnings > 1 ? "s" : ""} above` : "";
+        io.stdout.write(failed ? `\nSome checks failed${warned}.\n` : `\nAll checks passed${warned}.\n`);
     }
     return failed ? 1 : 0;
 }
 
-module.exports = { runDoctor, entryFolders, olderThan, staleNpxCopies, IR_MIN };
+module.exports = { runDoctor, entryFolders, olderThan, staleNpxCopies, fetchDistTags, fetchDistTagsIsolated, proxyFor, installKind, globalDirs, IR_MIN };