sparda-mcp 0.5.0 → 0.5.2

package/package.json

@@ -1,17 +1,20 @@
 {
   "name": "sparda-mcp",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Turn any codebase into an MCP server with one command. Express & FastAPI → Claude-ready in 3 minutes.",
   "type": "module",
   "bin": {
     "sparda": "./src/index.js"
   },
   "scripts": {
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:router": "node tests/router-selftest.cjs",
+    "test:all": "vitest run && node tests/router-selftest.cjs"
   },
   "files": [
     "src",
     "templates",
+    "!templates/*.bak",
     "README.md",
     "LICENSE"
   ],
@@ -36,7 +39,7 @@
     "@modelcontextprotocol/sdk": "1.29.0"
   },
   "devDependencies": {
-    "express": "4.21.2",
+    "express": "^4.21.0",
     "vitest": "^3.2.6"
   }
 }

package/src/commands/init.js

@@ -22,6 +22,7 @@ export async function runInit(opts) {
   const stack = detectStack(opts.cwd);
   
   let routes, skipped, entryAppVars;
+  let dynamicGaps = [];
   if (stack.framework === 'express') {
     const res = parseExpressProject(opts.cwd, stack.entryFile);
     routes = res.routes;
@@ -35,6 +36,33 @@ export async function runInit(opts) {
     s.stop(`Stack detected: ${c.cyan('FastAPI')} — entry: ${stack.entryFile}, port: ${stack.port}`);
   }
 
+  // Opt-in runtime probe (Brief #3): static is the floor, probe only ADDS routes
+  // the AST missed (dynamic mounts, programmatic registration). Off by default →
+  // behavior byte-identical. Executing the host app has side-effects, so it is
+  // gated behind --probe, warned on stderr, and degrades to static-only on any
+  // failure — a probe error must never break init (R1).
+  if (opts.probe) {
+    p.log.warn('--probe runs your app to observe routes the static scan missed. Use only on code you trust (it triggers your app\'s import side-effects).');
+    try {
+      const { discoverDynamicRoutes } = await import('../probe/integrate.js');
+      const { added, gaps, probedCount } = await discoverDynamicRoutes({
+        framework:    stack.framework,
+        entryFile:    path.resolve(opts.cwd, stack.entryFile),
+        projectRoot:  opts.cwd,
+        staticRoutes: routes,
+      });
+      dynamicGaps = gaps;
+      if (added.length) {
+        routes.push(...added);
+        p.log.success(`Probe added ${added.length} dynamic route(s) the static scan missed (${probedCount} observed at runtime).`);
+      } else {
+        p.log.info(`Probe observed ${probedCount} route(s); the static scan already covered them.`);
+      }
+    } catch (err) {
+      p.log.warn(`Probe failed (${err.message}); continuing with static routes only.`);
+    }
+  }
+
   if (routes.length === 0) {
     throw Object.assign(new Error('0 routes extracted.'), { code: 'USER', hint: `SPARDA found ${stack.framework === 'express' ? 'Express' : 'FastAPI'} but no literal-path routes. Dynamic routing is not supported in v0.` });
   }
@@ -75,7 +103,9 @@ export async function runInit(opts) {
     : generateFastAPI({ cwd: opts.cwd, entryFile: stack.entryFile, port: stack.port, routes, entryAppVars, pythonCmd: stack.pythonCmd });
 
   fs.mkdirSync(path.join(opts.cwd, '.sparda'), { recursive: true });
-  fs.writeFileSync(path.join(opts.cwd, '.sparda', 'scan-report.json'), JSON.stringify({ routes, skipped }, null, 2));
+  const scanReport = { routes, skipped };
+  if (opts.probe) scanReport.dynamicGaps = dynamicGaps;   // provenance, only when probed
+  fs.writeFileSync(path.join(opts.cwd, '.sparda', 'scan-report.json'), JSON.stringify(scanReport, null, 2));
 
   p.log.success(`Generated ${result.routerFile}`);
   if (inject && result.injection.injected) p.log.success(`Injected into ${stack.entryFile} (backup: .sparda/backup/)`);

package/src/generator/express.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { parse } from '@babel/parser';
 import { toolNameFor } from '../parser/express.js';
 import { carryOverManifest, defaultSpardingMemory } from './manifest.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const MARK_START = '// >>> sparda-injection (do not edit this block) >>>';
@@ -239,10 +240,4 @@ function ensureGitignore(cwd) {
   return 'created';
 }
 
-function atomicWrite(file, content) {
-  const tmp = `${file}.sparda-tmp`;
-  fs.writeFileSync(tmp, content);
-  fs.renameSync(tmp, file);
-}
-
 function escapeRx(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }

package/src/generator/fastapi.js

@@ -6,6 +6,7 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { toolNameFor } from '../parser/express.js';
 import { carryOverManifest, defaultSpardingMemory } from './manifest.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const MARK_START = '# >>> sparda-injection (do not edit this block) >>>';
@@ -199,7 +200,10 @@ function verifyPythonSyntax(filePath, content, pythonCmd) {
   try {
     fs.writeFileSync(tmpFile, content);
     const args = pythonCmd === 'py' ? ['-3', '-m', 'py_compile', tmpFile] : ['-m', 'py_compile', tmpFile];
-    const res = spawnSync(pythonCmd, args, { timeout: 2000 });
+    // py_compile cold-starts slowly on Windows; a 2s budget falsely failed clean
+    // removals (rule #4) and post-injection checks under load. 5s matches the
+    // test-side syntax budget and only bounds the worst case, never the happy path.
+    const res = spawnSync(pythonCmd, args, { timeout: 5000 });
     return res.status === 0;
   } catch {
     return false;
@@ -227,10 +231,4 @@ function ensureGitignore(cwd) {
   return 'created';
 }
 
-function atomicWrite(file, content) {
-  const tmp = `${file}.sparda-tmp`;
-  fs.writeFileSync(tmp, content);
-  fs.renameSync(tmp, file);
-}
-
 function escapeRx(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }

package/src/index.js

@@ -15,6 +15,7 @@ const opts = {
   yes: flags.has('--yes') || flags.has('-y'),
   verbose: flags.has('--verbose'),
   quiet: flags.has('--quiet'),
+  probe: flags.has('--probe'),
   port: getOpt('port', null),
   cwd: process.cwd(),
 };
@@ -64,6 +65,7 @@ Usage:
   npx sparda-mcp doctor    Diagnose your setup
 
 Flags: --yes (skip prompts)  --port <n>  --quiet  --verbose
+       --probe (init: also run the app to discover dynamic routes the AST missed)
 
 By Residual Labs — residual-labs.fr`);
       process.exit(cmd ? 1 : 0);

package/src/probe/express-shim-esm.mjs

@@ -0,0 +1,27 @@
+/**
+ * SPARDA — Express GFP Shim (ESM wrapper, loaded via --import)
+ *
+ * Node ≥ 18.19: `--import <file>` preloads an ESM module before the entry file.
+ * This wrapper bootstraps the CJS shim (which uses Module._load patching)
+ * via createRequire, making it effective for ESM apps too.
+ *
+ * Why CJS shim via createRequire rather than a pure ESM shim?
+ * Module._load interception (the GFP mechanism) only works in CJS land.
+ * ESM imports bypass Module._load entirely. However, most Express apps —
+ * even those using ES module syntax — still resolve 'express' through the
+ * CJS loader (express itself is CJS). So patching Module._load in a
+ * createRequire context correctly intercepts all express requires regardless
+ * of whether the user's entry file is .mjs or .js with "type":"module".
+ *
+ * ESM, Node ≥ 18. Zero deps beyond node:module, node:url, node:path.
+ */
+
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve }  from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require   = createRequire(import.meta.url);
+
+// Load the CJS shim — patches Module._load globally in the CJS loader
+require(resolve(__dirname, 'express-shim.cjs'));

package/src/probe/express-shim.cjs

@@ -0,0 +1,208 @@
+/**
+ * SPARDA — Express GFP Shim v2 (CJS, loaded via --require / createRequire)
+ *
+ * CRITICAL FIX over v1: v1 patched RouterClass.prototype[method] where
+ * RouterClass = express.Router. On Express 4, Router has NO prototype HTTP
+ * methods — they live on express.application and on the Router function object
+ * itself. v1 captured ZERO routes on any normal app.get/post/... call.
+ *
+ * v2 wraps ALL THREE public surfaces with feature-detection:
+ *   - express.application          → catches app.get/post/... (Express 4 & 5)
+ *   - express.Router (fn object)   → catches router.get/... in Express 4
+ *   - express.Router.prototype     → catches router.get/... in Express 5
+ *
+ * Also fixed: app.listen is on express.application, not Router.prototype.
+ * Fixed: callback passed to app.listen is now called so post-listen routes
+ *        are captured (ANALYSE-POST-LIVRAISON §2).
+ * Added: proactive require.cache patch for monorepos (ANALYSE §1).
+ *
+ * Communication: fork IPC (process.send) preferred, TCP fallback on
+ * SPARDA_IPC_PORT for spawn() callers.
+ *
+ * CJS because Node's --require only loads CommonJS modules.
+ */
+
+'use strict';
+
+if (!process.env.SPARDA_PROBE) {
+  module.exports = {};
+} else {
+  installShim();
+}
+
+function installShim() {
+  const net    = require('net');
+  const Module = require('module');
+
+  const IPC_PORT = parseInt(process.env.SPARDA_IPC_PORT, 10) || 0;
+
+  // ── Transport: fork IPC or TCP fallback ────────────────────────────────────
+
+  let socket      = null;
+  let socketReady = false;
+  const pending   = [];
+
+  function connectTcp() {
+    if (socket || !IPC_PORT) return;
+    socket = new net.Socket();
+    socket.connect(IPC_PORT, '127.0.0.1', () => {
+      socketReady = true;
+      for (const line of pending) socket.write(line);
+      pending.length = 0;
+    });
+    socket.on('error', () => { socket = null; socketReady = false; });
+  }
+
+  function sendLine(line) {
+    if (typeof process.send === 'function') {
+      try { process.send(JSON.parse(line.trimEnd())); return; } catch {}
+    }
+    connectTcp();
+    if (socketReady && socket) socket.write(line);
+    else pending.push(line);
+  }
+
+  function sendMsg(obj)  { sendLine(JSON.stringify(obj) + '\n'); }
+
+  function sendDone() {
+    if (typeof process.send === 'function') {
+      try { process.send({ type: '__done__' }); } catch {}
+      return;
+    }
+    const finish = () => {
+      if (socket) socket.write('__SPARDA_DONE__\n', () => socket.destroy());
+    };
+    if (socketReady) finish();
+    else if (socket) socket.once('connect', finish);
+  }
+
+  // ── Idle-flush timer ───────────────────────────────────────────────────────
+
+  const IDLE_MS = 300;
+  let idleTimer = null;
+
+  function resetIdle() {
+    clearTimeout(idleTimer);
+    idleTimer = setTimeout(sendDone, IDLE_MS);
+  }
+
+  function record(method, path) {
+    sendMsg({ type: 'route', method, path });
+    resetIdle();
+  }
+
+  // ── HTTP method list ───────────────────────────────────────────────────────
+
+  const HTTP_METHODS = ['get','post','put','patch','delete','del','head','options','all'];
+
+  // ── Core wrapper — works on any target object ──────────────────────────────
+  //
+  // §A.3 exact algorithm: wrap each HTTP method on `target` if present.
+  // Guard with __sparda_wrapped__ so re-entrant calls from require.cache
+  // patch (monorepo) don't double-wrap.
+
+  function wrapMethods(target) {
+    if (!target || target.__sparda_wrapped__) return;
+    for (const m of HTTP_METHODS) {
+      if (typeof target[m] !== 'function') continue;
+      const orig = target[m];
+      target[m] = function spardaWrap(path, ...rest) {
+        // Express 4: app.get('view engine') with ONE arg is a settings getter.
+        // 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);
+        }
+        return orig.call(this, path, ...rest);
+      };
+    }
+    try {
+      Object.defineProperty(target, '__sparda_wrapped__', { value: true, configurable: true });
+    } catch {}
+  }
+
+  // ── listen patch — lives on express.application ───────────────────────────
+  //
+  // §A.4: listen is NOT on Router; it's on express.application.
+  // We intercept it to:
+  //   (a) call any callback immediately (captures post-listen routes, §ANALYSE §2)
+  //   (b) flush DONE so parent knows all sync routes are registered
+  //   (c) return a fake server — no real socket opened in probe mode
+
+  function patchListen(appProto) {
+    if (!appProto || appProto.__sparda_listen_patched__) return;
+    if (typeof appProto.listen !== 'function') return;
+    try {
+      Object.defineProperty(appProto, '__sparda_listen_patched__', { value: true, configurable: true });
+    } catch {}
+    const origListen = appProto.listen;
+    appProto.listen = function spardaListen(...args) {
+      clearTimeout(idleTimer);
+      // §ANALYSE §2: call the listen callback so routes registered inside it are captured
+      const cb = args.find(a => typeof a === 'function');
+      if (cb) { try { cb(); } catch {} }
+      sendDone();
+      // Do NOT call origListen — no real socket in probe mode
+      return {
+        on()      { return this; },
+        close()   {},
+        address() { return { port: 0, address: '127.0.0.1', family: 'IPv4' }; },
+      };
+    };
+  }
+
+  // ── Patch all three surfaces of an express export ─────────────────────────
+
+  function patchExpress(exp) {
+    if (!exp || exp.__sparda_factory_patched__) return;
+    try {
+      Object.defineProperty(exp, '__sparda_factory_patched__', { value: true, configurable: true });
+    } catch {}
+
+    // Surface 1: express.application — catches app.get/post/... (Express 4 & 5)
+    if (exp.application) {
+      wrapMethods(exp.application);
+      patchListen(exp.application);
+    }
+
+    // Surface 2: express.Router (function object) — catches router.get/... in Express 4
+    if (exp.Router) {
+      wrapMethods(exp.Router);
+    }
+
+    // Surface 3: express.Router.prototype — catches router.get/... in Express 5
+    if (exp.Router && exp.Router.prototype) {
+      wrapMethods(exp.Router.prototype);
+    }
+  }
+
+  // ── Intercept require('express') via Module._load ─────────────────────────
+
+  const originalLoad = Module._load;
+  Module._load = function spardaLoad(request, parent, isMain) {
+    const result = originalLoad.apply(this, arguments);
+    if (request === 'express') patchExpress(result);
+    return result;
+  };
+
+  // ── Monorepo: proactive patch if express already in require.cache ─────────
+  // §ANALYSE §1: if another workspace module already required express before
+  // this shim loaded, Module._load hook fires too late. Patch the cached export.
+
+  try {
+    const expressPaths = Object.keys(require.cache).filter(
+      k => /[/\\]express[/\\]index\.js$/.test(k)
+    );
+    for (const p of expressPaths) {
+      const cached = require.cache[p];
+      if (cached && cached.exports) patchExpress(cached.exports);
+    }
+  } catch {}
+
+  // ── Safety nets ────────────────────────────────────────────────────────────
+
+  process.on('exit',    () => { try { sendDone(); } catch {} });
+  process.on('SIGTERM', () => { sendDone(); setTimeout(() => process.exit(0), 200); });
+
+  module.exports = { record, sendDone };
+}

package/src/probe/fastapi-probe.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""
+SPARDA — FastAPI Route Probe
+
+Imports the user's FastAPI entry module, finds the FastAPI() instance,
+iterates app.routes, and prints a JSON array to stdout.
+
+No uvicorn, no server, no port. FastAPI/Starlette builds the full route
+table synchronously during import (include_router, add_api_route, etc.),
+so reading app.routes right after import is complete and exhaustive.
+
+Import side-effects WILL run (hence opt-in via --probe). But no network
+socket is opened by this script — just a Python import.
+
+Output format (stdout, nothing else):
+  [{"method": "GET", "path": "/users/{id}"}, ...]
+
+Python ≥ 3.9. stdlib only.
+"""
+
+import sys
+import os
+import json
+import importlib.util
+import traceback
+
+
+def find_fastapi_apps(module):
+    """
+    Scan a module's attributes for FastAPI application instances.
+    Returns a list of (name, app) tuples.
+    """
+    try:
+        from fastapi import FastAPI
+    except ImportError:
+        return []
+
+    apps = []
+    for attr_name in dir(module):
+        try:
+            val = getattr(module, attr_name)
+            if isinstance(val, FastAPI):
+                apps.append((attr_name, val))
+        except Exception:
+            pass
+    return apps
+
+
+def extract_routes(app):
+    """
+    Iterate app.routes (Starlette Route / APIRoute objects).
+    Returns list of dicts with method and path.
+    """
+    routes = []
+    try:
+        for route in app.routes:
+            try:
+                # APIRoute (FastAPI endpoints) have .methods and .path
+                path = getattr(route, 'path', None)
+                methods = getattr(route, 'methods', None)
+                if path is None:
+                    continue
+                if methods:
+                    for m in methods:
+                        routes.append({"method": m.upper(), "path": path})
+                else:
+                    # Mount or WebSocket — skip (no HTTP method)
+                    pass
+            except Exception:
+                pass
+    except Exception:
+        pass
+    return routes
+
+
+def load_entry_module(entry_file):
+    """
+    Load the user's entry file as a module without running it as __main__.
+    """
+    entry_dir = os.path.dirname(os.path.abspath(entry_file))
+    # Ensure the app's directory is on sys.path so relative imports work
+    if entry_dir not in sys.path:
+        sys.path.insert(0, entry_dir)
+
+    spec = importlib.util.spec_from_file_location("__sparda_fastapi_probe__", entry_file)
+    if spec is None:
+        raise ImportError(f"Cannot create module spec for {entry_file!r}")
+
+    module = importlib.util.module_from_spec(spec)
+    # Don't execute __main__ guards: set __name__ to something other than '__main__'
+    module.__name__ = "__sparda_fastapi_probe__"
+    spec.loader.exec_module(module)
+    return module
+
+
+def main():
+    if len(sys.argv) < 2:
+        print(json.dumps([]), flush=True)
+        sys.exit(0)
+
+    entry_file = sys.argv[1]
+
+    if not os.path.isfile(entry_file):
+        print(f"[sparda probe] Entry file not found: {entry_file}", file=sys.stderr)
+        print(json.dumps([]), flush=True)
+        sys.exit(0)
+
+    try:
+        module = load_entry_module(entry_file)
+    except SystemExit:
+        # App called sys.exit() during import (e.g. arg parsing) — not fatal
+        print("[]", flush=True)
+        sys.exit(0)
+    except Exception as e:
+        print(f"[sparda probe] Failed to import {entry_file!r}: {e}", file=sys.stderr)
+        traceback.print_exc(file=sys.stderr)
+        print(json.dumps([]), flush=True)
+        sys.exit(0)
+
+    apps = find_fastapi_apps(module)
+    if not apps:
+        # No FastAPI instance found — print empty
+        print(json.dumps([]), flush=True)
+        sys.exit(0)
+
+    all_routes = []
+    for _name, app in apps:
+        all_routes.extend(extract_routes(app))
+
+    # Deduplicate (same method+path from multiple apps is unusual but possible)
+    seen = set()
+    unique = []
+    for r in all_routes:
+        key = f"{r['method']}:{r['path']}"
+        if key not in seen:
+            seen.add(key)
+            unique.append(r)
+
+    # Deterministic: sort by key
+    unique.sort(key=lambda r: f"{r['method']}:{r['path']}")
+
+    print(json.dumps(unique), flush=True)
+
+
+if __name__ == "__main__":
+    main()

package/src/probe/integrate.js

@@ -0,0 +1,104 @@
+/**
+ * SPARDA — Dynamic route discovery integration (Brief #3, the final adapter)
+ *
+ * The "last 10%" that glues the runtime probe to SPARDA's generator pipeline:
+ *
+ *   probeRoutes()       → canonical dynamic routes (minimal shape)
+ *   reconcile()         → set-difference vs the AST floor → gaps[] the parser missed
+ *   gapToStaticRoute()  → enrich each gap into SPARDA's RICH route shape so the
+ *                         existing generators (generator/express.js, fastapi.js)
+ *                         consume it with ZERO special-casing.
+ *
+ * Static stays the floor; this only ADDS probe-only routes (§C). A probe failure
+ * degrades to static-only — probeRoutes() already returns [] on any error, and
+ * the init caller wraps this in try/catch as a second net.
+ *
+ * ESM, Node ≥ 18. Zero new deps (re-uses the sibling probe.js + reconcile.js).
+ */
+
+import { probeRoutes } from './probe.js';
+import { reconcile }   from './reconcile.js';
+
+const WRITE_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+/**
+ * Map a reconcile gap (minimal canonical shape) → SPARDA's rich static-route
+ * shape. The field set is byte-identical to what parseExpressProject /
+ * parseFastAPIProject emit, so the generators need no branch for "is this
+ * dynamic?". Provenance is carried in a non-consumed `source:'dynamic'` field.
+ *
+ * Path style mirrors the static parser per framework, so the manifest stays
+ * uniform (R6):
+ *   - express → ':id'  (the gap is already :id — keep it)
+ *   - fastapi → '{id}' (convert :id → {id} to match static FastAPI routes)
+ *
+ * Confidence is ALWAYS 'low': a probed route proves only that {method, path}
+ * exists — we never saw the handler, query params, or body schema.
+ *
+ * @param {{method:string, path:string, pathParams?:string[], writeClass?:'read'|'write'}} gap
+ * @param {'express'|'fastapi'} framework
+ */
+export function gapToStaticRoute(gap, framework) {
+  const method = (gap.method ?? 'GET').toUpperCase();
+  const lower  = method.toLowerCase();
+  const mutating = gap.writeClass ? gap.writeClass === 'write' : WRITE_METHODS.has(method);
+
+  const path = framework === 'fastapi'
+    ? (gap.path ?? '/').replace(/:([a-zA-Z_]\w*)/g, '{$1}')
+    : (gap.path ?? '/');
+
+  // Path params, in the exact param object the static parser uses.
+  const params = (gap.pathParams ?? []).map((name) => ({
+    name, in: 'path', type: 'string', required: true, description: 'path parameter',
+  }));
+  // Mirror the static parser: mutating routes get a body param (schema unknown).
+  if (mutating) {
+    params.push({
+      name: 'body', in: 'body', type: 'object', required: false,
+      description: 'JSON body — schema not statically detected',
+    });
+  }
+
+  return {
+    method: lower,
+    path,
+    handlerName: `dynamic_${lower}_${(gap.pathParams ?? []).join('_') || 'route'}`,
+    sourceFile: '(runtime probe)',
+    sourceLine: 0,
+    params,
+    description: 'Discovered at runtime via --probe; not found by static analysis.',
+    mutating,
+    confidence: 'low',   // never statically verified → always low
+    source: 'dynamic',
+  };
+}
+
+/**
+ * Probe the live app, reconcile against the static floor, and return the
+ * probe-only routes enriched to SPARDA's rich shape (ready to append to the
+ * `routes` array the generators consume).
+ *
+ * @param {{framework:'express'|'fastapi', entryFile:string, projectRoot:string, staticRoutes:object[], timeoutMs?:number}} args
+ * @returns {Promise<{ added:object[], gaps:object[], staticCount:number, dynamicCount:number, probedCount:number }>}
+ *   added       — gaps enriched to SPARDA's rich shape (append these to `routes`)
+ *   gaps        — the raw minimal gaps (stored in the scan-report for provenance)
+ *   probedCount — how many routes the probe observed (0 ⇒ probe degraded / nothing seen)
+ */
+export async function discoverDynamicRoutes({ framework, entryFile, projectRoot, staticRoutes, timeoutMs = 8000 }) {
+  const probed = await probeRoutes({ framework, entryFile, projectRoot, timeoutMs });
+  const { gaps, staticCount, dynamicCount } = reconcile(staticRoutes, probed);
+
+  // Defensive: the probe should not emit duplicate (method, path) pairs, but
+  // reconcile does not dedup gaps among themselves. Collapse here so we never
+  // synthesize two identical tools.
+  const seen = new Set();
+  const uniqueGaps = gaps.filter((g) => {
+    const k = `${g.method} ${g.path}`;
+    if (seen.has(k)) return false;
+    seen.add(k);
+    return true;
+  });
+
+  const added = uniqueGaps.map((g) => gapToStaticRoute(g, framework));
+  return { added, gaps: uniqueGaps, staticCount, dynamicCount: added.length, probedCount: probed.length };
+}