sparda-mcp 0.71.1 → 0.71.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparda-mcp",
-  "version": "0.71.1",
+  "version": "0.71.3",
   "mcpName": "io.github.zyx77550/sparda-mcp",
   "description": "AI writes. SPARDA proves. A deterministic, offline gate that catches when an AI edit removes a guard, exposes a route, or breaks an invariant \u2014 no API key, right in the agent edit loop.",
   "type": "module",

package/src/probe/express-shim.cjs

@@ -34,6 +34,12 @@ function installShim() {
   const net = require('net');
   const Module = require('module');
 
+  // Did we ever get our hands on the express module? The probe used to report "the app did not
+  // boot" for this, which is a WRONG diagnosis — sending the user to debug their app when the
+  // app was fine and the SHIM never hooked (E-109). Reported to the parent so the reason it
+  // prints is the true one.
+  let patched = false;
+
   const IPC_PORT = parseInt(process.env.SPARDA_IPC_PORT, 10) || 0;
 
   // ── Transport: fork IPC or TCP fallback ────────────────────────────────────
@@ -73,6 +79,7 @@ function installShim() {
   }
 
   function sendDone() {
+    flush(); // the staged routes must go out BEFORE the parent is told there are no more
     if (typeof process.send === 'function') {
       try {
         process.send({ type: '__done__' });
@@ -96,11 +103,65 @@ function installShim() {
     idleTimer = setTimeout(sendDone, IDLE_MS);
   }
 
-  function record(method, path) {
-    sendMsg({ type: 'route', method, path });
+  // ── Routes are STAGED, not emitted — the mount point is not known yet ──────
+  //
+  // E-110. `usersRouter.get('/:id')` runs at import time; `app.use('/api/users', usersRouter)`
+  // runs later. Emitting at registration therefore reported `GET /:id`, and reconcile compared
+  // that against the compiler's (correct) `/api/users/:id` and called it a route the app serves
+  // and the compiler never saw. On demo-app: two FALSE premise gaps out of three.
+  //
+  // False gaps are in the SAFE direction for a verdict — they only make SPARDA refuse to claim
+  // PROVEN — which is exactly why this could sit unnoticed. They are in the WRONG direction for
+  // anything that consumes gaps as findings: every real Express app uses routers, so the most
+  // load-bearing signal the runtime oracle produces was also its noisiest.
+  //
+  // So: buffer each route with the OBJECT it was registered on, record the mount edges, and
+  // resolve full paths once the app is fully wired (at `listen`, or on idle).
+  const staged = [];
+  const mounts = []; // { parent, child, path }
+  let flushed = false;
+
+  function stage(owner, method, path) {
+    staged.push({ owner, method, path });
     resetIdle();
   }
 
+  const joinPaths = (prefix, path) => {
+    const a = String(prefix || '').replace(/\/+$/, '');
+    const b = String(path || '');
+    if (b === '/' || b === '') return a || '/';
+    return a + (b.startsWith('/') ? b : '/' + b) || '/';
+  };
+
+  // Every full path this owner is reachable at. A router CAN be mounted more than once, and then
+  // its routes genuinely exist at several paths — so this returns a list, never a single answer.
+  function prefixesOf(owner, depth = 0) {
+    if (depth > 12) return ['']; // pathological nesting or a cycle — stop, do not hang
+    const edges = mounts.filter((m) => m.child === owner);
+    if (edges.length === 0) return ['']; // a root (the app itself, or an unmounted router)
+    const out = [];
+    for (const e of edges) {
+      for (const up of prefixesOf(e.parent, depth + 1)) out.push(joinPaths(up, e.path));
+    }
+    return out.length ? out : [''];
+  }
+
+  function flush() {
+    if (flushed) return;
+    flushed = true;
+    const seen = new Set();
+    for (const r of staged) {
+      for (const prefix of prefixesOf(r.owner)) {
+        const full = joinPaths(prefix, r.path);
+        const key = `${r.method} ${full}`;
+        if (seen.has(key)) continue; // the same route reached twice is one route
+        seen.add(key);
+        sendMsg({ type: 'route', method: r.method, path: full });
+      }
+    }
+    staged.length = 0;
+  }
+
   // ── HTTP method list ───────────────────────────────────────────────────────
 
   const HTTP_METHODS = [
@@ -131,11 +192,34 @@ function installShim() {
         // Only record route registrations (path + at least one handler/middleware).
         if (typeof path === 'string' && rest.length > 0) {
           const verb = m === 'del' ? 'DELETE' : m.toUpperCase();
-          record(verb, path);
+          stage(this, verb, path);
         }
         return orig.call(this, path, ...rest);
       };
     }
+
+    // `use` is what makes a path mean something. Recorded, never altered: we only need to know
+    // WHICH object was mounted WHERE, so a route registered on it can be reported at the address
+    // the framework actually serves it from.
+    if (typeof target.use === 'function' && !target.__sparda_use_wrapped__) {
+      const origUse = target.use;
+      target.use = function spardaUse(...args) {
+        const mountPath = typeof args[0] === 'string' ? args[0] : '/';
+        for (const h of args) {
+          // A mounted router is a function carrying a middleware `stack` — that is what tells it
+          // apart from a plain handler like `express.json()`.
+          if (typeof h === 'function' && Array.isArray(h.stack))
+            mounts.push({ parent: this, child: h, path: mountPath });
+        }
+        return origUse.apply(this, args);
+      };
+      try {
+        Object.defineProperty(target, '__sparda_use_wrapped__', {
+          value: true,
+          configurable: true,
+        });
+      } catch {}
+    }
     try {
       Object.defineProperty(target, '__sparda_wrapped__', {
         value: true,
@@ -217,7 +301,10 @@ function installShim() {
   const originalLoad = Module._load;
   Module._load = function spardaLoad(request) {
     const result = originalLoad.apply(this, arguments);
-    if (request === 'express') patchExpress(result);
+    if (request === 'express') {
+      patched = true;
+      patchExpress(result);
+    }
     return result;
   };
 
@@ -231,10 +318,43 @@ function installShim() {
     );
     for (const p of expressPaths) {
       const cached = require.cache[p];
-      if (cached && cached.exports) patchExpress(cached.exports);
+      if (cached && cached.exports) {
+        patched = true;
+        patchExpress(cached.exports);
+      }
     }
   } catch {}
 
+  // ── ESM entries: the hook above CANNOT fire, so pull express in ourselves ──
+  //
+  // E-109. `Module._load` interception is a CJS-loader mechanism. On Node 22 an ESM
+  // `import express from 'express'` does NOT go through `Module._load` — measured, and it
+  // contradicts the comment this shim's ESM wrapper used to carry. So for every Express app
+  // written in ESM (the modern default: `.mjs`, or `.js` under `"type": "module"`) the shim
+  // installed itself and then intercepted nothing, forever. The probe reported a timeout, the
+  // premise stayed `unmeasured`, and an ESM Express app could never reach PROVEN.
+  //
+  // The fix does not need a loader hook. express is CJS, and a CJS module loaded through the
+  // ESM bridge comes from the SAME `require.cache`: so if we require it FIRST, the app's later
+  // `import` receives the already-patched instance. Verified — the marker survives the import.
+  //
+  // Resolved from the ENTRY FILE, never from this shim's own directory: SPARDA carries express
+  // as a devDependency, and patching SPARDA's copy while the app imports its own would hook a
+  // module nobody uses — the same instance-identity trap, one level down.
+  if (!patched) {
+    try {
+      const path = require('path');
+      const from = process.argv[1] || path.join(process.cwd(), 'index.js');
+      const appRequire = Module.createRequire(path.resolve(from));
+      appRequire('express'); // goes through Module._load → sets `patched`, runs patchExpress
+    } catch {
+      // no express resolvable from the app — `patched` stays false and the parent is told so,
+      // which is a different statement from "the app did not boot"
+    }
+  }
+
+  sendMsg({ type: '__shim__', patched });
+
   // ── Safety nets ────────────────────────────────────────────────────────────
 
   process.on('exit', () => {
@@ -247,5 +367,5 @@ function installShim() {
     setTimeout(() => process.exit(0), 200);
   });
 
-  module.exports = { record, sendDone };
+  module.exports = { stage, flush, sendDone };
 }

package/src/probe/probe.js

@@ -52,12 +52,28 @@ async function probeExpress({ entryFile, projectRoot, timeoutMs }) {
     return [];
   }
 
+  // Which shim FLAG is used turns out not to matter, and that is worth stating because the
+  // obvious "fix" for E-109 was to detect `"type": "module"` here and switch to `--import`. It
+  // changes nothing measurable: `--require` preloads the CJS shim fine ahead of an ESM entry, and
+  // the shim's own eager `require('express')` is what actually closes the hole. A second
+  // mechanism that no test can distinguish is dead weight — E-106, one week old, is what happens
+  // when such a line is kept.
   const isEsm = ext === '.mjs';
   const shimFlag = isEsm ? ['--import', SHIM_ESM] : ['--require', SHIM_CJS];
 
   const routes = [];
   let child;
 
+  // WHY the probe saw nothing is a different fact from THAT it saw nothing, and the old code
+  // could only say the second (E-109). It reported every silence as "the app did not boot",
+  // which sent users to debug a healthy app while the real cause was the shim never hooking.
+  // `shimPatched` stays null until the child says; the child's stderr is KEPT rather than
+  // dropped on the floor, because it is the only place an app's own crash is written down.
+  let shimPatched = null;
+  let timedOut = false;
+  let exitCode = null;
+  let stderrTail = '';
+
   return new Promise((resolve_) => {
     let settled = false;
     let killTimer;
@@ -69,10 +85,23 @@ async function probeExpress({ entryFile, projectRoot, timeoutMs }) {
       try {
         child && child.kill('SIGKILL');
       } catch {}
+      // Non-enumerable so `probeRoutes` keeps returning exactly an array of routes: every
+      // existing caller and assertion is untouched, and the reason travels with it.
+      Object.defineProperty(result, 'diagnostic', {
+        value: diagnose({
+          count: result.length,
+          shimPatched,
+          timedOut,
+          exitCode,
+          stderrTail,
+        }),
+        enumerable: false,
+      });
       resolve_(result);
     }
 
     killTimer = setTimeout(() => {
+      timedOut = true;
       process.stderr.write(
         '[sparda] --probe: timeout waiting for Express routes; using static floor.\n',
       );
@@ -95,10 +124,19 @@ async function probeExpress({ entryFile, projectRoot, timeoutMs }) {
       return;
     }
 
-    child.stderr?.on('data', () => {});
+    // KEPT, capped. The target's own boot error ("cannot connect to postgres") is written
+    // nowhere else, and discarding it is what made a shim that hooked nothing look identical
+    // to an app that refused to start.
+    child.stderr?.on('data', (chunk) => {
+      if (stderrTail.length < 4000) stderrTail += String(chunk);
+    });
 
     child.on('message', (msg) => {
       if (!msg || typeof msg !== 'object') return;
+      if (msg.type === '__shim__') {
+        shimPatched = msg.patched === true;
+        return;
+      }
       if (msg.type === '__done__') {
         settle(routes);
         return;
@@ -121,10 +159,69 @@ async function probeExpress({ entryFile, projectRoot, timeoutMs }) {
       settle(routes);
     });
 
-    child.on('exit', () => settle(routes));
+    // `exit` gives the code; `close` is the one that means the stdio streams have been fully
+    // drained. Settling on `exit` races the last chunk of the child's stderr — under load the
+    // diagnostic came out without the very error it exists to carry.
+    child.on('exit', (code) => {
+      exitCode = code;
+    });
+    child.on('close', () => settle(routes));
   });
 }
 
+/**
+ * Why did the probe see what it saw? Four distinguishable states, and the point of naming them
+ * is that three of them used to print as the fourth (E-109):
+ *
+ *   observed        routes came back — nothing to explain
+ *   not-instrumented the shim never got hold of express. NOT a boot failure: the app may be
+ *                   running perfectly. This is the ESM case, and the one that hid for a release.
+ *   no-routes       express WAS instrumented and the app registered none before we stopped.
+ *   did-not-start   the child never reported in at all, or exited non-zero — the app itself.
+ *
+ * `reason` is the sentence a user acts on, so it must never assert the app is broken when what
+ * actually happened is that SPARDA could not look.
+ */
+export function diagnose({ count, shimPatched, timedOut, exitCode, stderrTail }) {
+  const tail = String(stderrTail || '')
+    .trim()
+    .split('\n')
+    .slice(-3)
+    .join(' | ')
+    .slice(0, 300);
+  if (count > 0)
+    return { state: 'observed', reason: `${count} route(s) observed at runtime` };
+  // A non-zero exit wins over everything below: whatever we managed to instrument, the app
+  // itself died, and that is the fact its author needs. (Our own timeout SIGKILLs the child,
+  // which leaves exitCode null — so this cannot swallow the timeout cases.)
+  if (exitCode != null && exitCode !== 0)
+    return {
+      state: 'did-not-start',
+      reason: `the app exited ${exitCode} before serving anything`,
+      stderrTail: tail,
+    };
+  if (shimPatched === false)
+    return {
+      state: 'not-instrumented',
+      reason:
+        'the probe never got hold of the express module, so nothing could be observed — the app may well be running fine (this is not a boot failure)',
+      stderrTail: tail,
+    };
+  if (shimPatched === true)
+    return {
+      state: 'no-routes',
+      reason: timedOut
+        ? 'express was instrumented but no route was registered before the timeout — the app may boot slowly or block on a dependency'
+        : 'express was instrumented and the app registered no routes',
+      stderrTail: tail,
+    };
+  return {
+    state: 'did-not-start',
+    reason: `the probe child never reported in${exitCode != null ? ` (exit ${exitCode})` : ''} — the app did not start`,
+    stderrTail: tail,
+  };
+}
+
 // ── FastAPI probe ─────────────────────────────────────────────────────────────
 
 async function probeFastAPI({ entryFile, projectRoot, timeoutMs }) {

package/src/ubg/premise.js

@@ -108,12 +108,20 @@ export async function verifyPremise(
   // "an app with no routes". Treating that as a clean bill of health would be the
   // worst possible reading — a broken oracle would silently CONFIRM every proof. So
   // an empty probe is "unavailable", never "verified".
+  //
+  // The reason, however, must be the TRUE one. This used to read "the app did not boot, or
+  // exposes none" for every silence, including the case where the app was running perfectly and
+  // the shim had simply never hooked express — a wrong diagnosis that pointed the user at their
+  // own code (E-109). `probeRoutes` now attaches which of the four states actually happened.
   if (!Array.isArray(probed) || probed.length === 0)
     return {
       available: false,
       gaps: [],
       probed: 0,
-      reason: 'probe returned no routes — the app did not boot, or exposes none',
+      reason:
+        probed?.diagnostic?.reason ??
+        'probe returned no routes — the app did not boot, or exposes none',
+      ...(probed?.diagnostic ? { probeState: probed.diagnostic.state } : {}),
     };
 
   const { gaps } = reconcile(entrypointsAsRoutes(graph), probed);