sparda-mcp 0.5.4 → 0.6.0

package/README.md

@@ -157,7 +157,10 @@ protocol. The live, per-project tool list always comes from `sparda_get_context`
 runtime, so the guidance never goes stale.
 
 ## Supported frameworks
-Express 4/5 (JS/TS, ESM/CJS) and FastAPI today. We are actively expanding SPARDA internally to support more Node.js environments (including NestJS, Fastify, and Next.js API routes) in the near future.
+
+- **Next.js App Router (13/14/15)** — file-based injection. Since Next.js uses file-system routing, SPARDA simply creates a catch-all route handler under `app/mcp/[...sparda]/route.js`. **Nothing in your existing codebase's code is touched**; running `remove` simply deletes the generated file.
+- **Express 4/5** (JS/TS, ESM/CJS) — AST-based router injection.
+- **FastAPI** (Python >= 3.9) — AST-based router injection.
 
 ## Security posture (honest)
 - 4 runtime dependencies, exact-pinned.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparda-mcp",
-  "version": "0.5.4",
+  "version": "0.6.0",
   "mcpName": "io.github.zyx77550/sparda-mcp",
   "description": "Turn any codebase into an MCP server with one command. Express & FastAPI → Claude-ready in 3 minutes.",
   "type": "module",

package/src/commands/doctor.js

@@ -90,7 +90,7 @@ export async function runDoctor(opts) {
             }
           }
         } catch {
-          const startCmd = m.framework === 'express' ? 'npm run dev' : 'fastapi dev';
+          const startCmd = m.framework === 'fastapi' ? 'fastapi dev' : 'npm run dev';
           fail(
             `  ✗ Host app on :${m.port} — NOT reachable\n      → start it with: ${startCmd}`,
           );

package/src/commands/init.js

@@ -5,9 +5,11 @@ import * as p from '@clack/prompts';
 import { detectStack } from '../detect.js';
 import { parseExpressProject } from '../parser/express.js';
 import { parseFastAPIProject } from '../parser/fastapi.js';
+import { parseNextProject } from '../parser/nextjs.js';
 import { sanitizeDescription } from '../security/sanitize.js';
 import { generateExpress } from '../generator/express.js';
 import { generateFastAPI } from '../generator/fastapi.js';
+import { generateNext } from '../generator/nextjs.js';
 import { c, gradient, colorizeJson } from '../ui/style.js';
 
 const VERSION = JSON.parse(
@@ -39,6 +41,13 @@ export async function runInit(opts) {
     s.stop(
       `Stack detected: ${c.cyan('FastAPI')} — entry: ${stack.entryFile}, port: ${stack.port}`,
     );
+  } else if (stack.framework === 'nextjs') {
+    const res = parseNextProject(opts.cwd, stack.entryFile);
+    routes = res.routes;
+    skipped = res.skipped;
+    s.stop(
+      `Stack detected: ${c.cyan('Next.js (App Router)')} — app dir: ${stack.entryFile}/, port: ${stack.port}`,
+    );
   }
 
   // Opt-in runtime probe (Brief #3): static is the floor, probe only ADDS routes
@@ -46,7 +55,11 @@ export async function runInit(opts) {
   // 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) {
+  if (opts.probe && stack.framework === 'nextjs') {
+    p.log.warn(
+      '--probe is not supported on Next.js (file-based routing needs no runtime probe).',
+    );
+  } else 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).",
     );
@@ -77,7 +90,10 @@ export async function runInit(opts) {
   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.`,
+      hint:
+        stack.framework === 'nextjs'
+          ? `SPARDA found Next.js but no route.js handlers under ${stack.entryFile}/. Page components are not API routes — SPARDA exposes route handlers only.`
+          : `SPARDA found ${stack.framework === 'express' ? 'Express' : 'FastAPI'} but no literal-path routes. Dynamic routing is not supported in v0.`,
     });
   }
 
@@ -118,7 +134,9 @@ export async function runInit(opts) {
     );
 
   let inject = true;
-  if (!opts.yes) {
+  // Next.js is file-based: SPARDA adds one route-handler file and touches
+  // nothing else — there is no injection decision to make.
+  if (!opts.yes && stack.framework !== 'nextjs') {
     const answer = await p.select({
       message: `Inject the MCP router into ${stack.entryFile}?`,
       options: [
@@ -145,14 +163,21 @@ export async function runInit(opts) {
           port: stack.port,
           routes,
         })
-      : generateFastAPI({
-          cwd: opts.cwd,
-          entryFile: stack.entryFile,
-          port: stack.port,
-          routes,
-          entryAppVars,
-          pythonCmd: stack.pythonCmd,
-        });
+      : stack.framework === 'nextjs'
+        ? generateNext({
+            cwd: opts.cwd,
+            appDir: stack.entryFile,
+            port: stack.port,
+            routes,
+          })
+        : generateFastAPI({
+            cwd: opts.cwd,
+            entryFile: stack.entryFile,
+            port: stack.port,
+            routes,
+            entryAppVars,
+            pythonCmd: stack.pythonCmd,
+          });
 
   fs.mkdirSync(path.join(opts.cwd, '.sparda'), { recursive: true });
   const scanReport = { routes, skipped };
@@ -163,7 +188,11 @@ export async function runInit(opts) {
   );
 
   p.log.success(`Generated ${result.routerFile}`);
-  if (inject && result.injection.injected)
+  if (result.injection.fileBased)
+    p.log.success(
+      'File-based injection: your code was not modified (remove deletes the file)',
+    );
+  else if (inject && result.injection.injected)
     p.log.success(`Injected into ${stack.entryFile} (backup: .sparda/backup/)`);
   else if (result.injection.manual) {
     p.note(
@@ -187,7 +216,7 @@ export async function runInit(opts) {
   p.outro(`${c.green(`Done in ${((Date.now() - t0) / 1000).toFixed(1)}s.`)}
 
    Next steps:
-   1. Start your app:        ${c.cyan(stack.framework === 'express' ? 'npm run dev' : 'fastapi dev')}
+   1. Start your app:        ${c.cyan(stack.framework === 'fastapi' ? 'fastapi dev' : 'npm run dev')}
    2. Start the MCP bridge:  ${c.cyan('npx sparda-mcp dev')}
    3. Add to Claude Desktop config (claude_desktop_config.json):
 

package/src/commands/remove.js

@@ -61,6 +61,23 @@ export async function runRemove(opts) {
       console.log(`✓ Deleted ${f}`);
     }
   }
+  // nextjs: the generated route lives in its own directory chain
+  // (app/mcp/[...sparda]/) — prune the now-empty dirs up to the app root so
+  // the tree is byte-identical, not just the git diff.
+  if (manifest.framework === 'nextjs') {
+    const stopAt = path.resolve(opts.cwd, manifest.entryFile ?? '.');
+    for (const f of manifest.generatedFiles ?? []) {
+      let dir = path.dirname(path.resolve(opts.cwd, f));
+      while (dir.startsWith(stopAt) && dir !== stopAt) {
+        try {
+          fs.rmdirSync(dir); // throws if not empty — that is the stop condition
+        } catch {
+          break;
+        }
+        dir = path.dirname(dir);
+      }
+    }
+  }
   if (revertGitignore(opts.cwd, manifest.gitignore))
     console.log('✓ Reverted .gitignore edit');
   if (removeHook(opts.cwd)) console.log('✓ Uninstalled post-commit sentinel hook');

package/src/commands/sync.js

@@ -4,9 +4,11 @@ import path from 'node:path';
 import { detectStack } from '../detect.js';
 import { parseExpressProject } from '../parser/express.js';
 import { parseFastAPIProject } from '../parser/fastapi.js';
+import { parseNextProject } from '../parser/nextjs.js';
 import { sanitizeDescription } from '../security/sanitize.js';
 import { generateExpress } from '../generator/express.js';
 import { generateFastAPI } from '../generator/fastapi.js';
+import { generateNext } from '../generator/nextjs.js';
 
 export async function runSync(opts) {
   const log = (m) => {
@@ -25,6 +27,8 @@ export async function runSync(opts) {
   let routes, entryAppVars;
   if (stack.framework === 'express') {
     ({ routes } = parseExpressProject(opts.cwd, stack.entryFile));
+  } else if (stack.framework === 'nextjs') {
+    ({ routes } = parseNextProject(opts.cwd, stack.entryFile));
   } else {
     ({ routes, entryAppVars } = parseFastAPIProject(
       opts.cwd,
@@ -52,22 +56,31 @@ export async function runSync(opts) {
   }
 
   // regenerate; carry-over keeps enabled overrides, semantic cache and localKey
-  stack.framework === 'express'
-    ? generateExpress({
-        cwd: opts.cwd,
-        entryFile: stack.entryFile,
-        moduleType: stack.moduleType,
-        port: manifest.port ?? stack.port,
-        routes,
-      })
-    : generateFastAPI({
-        cwd: opts.cwd,
-        entryFile: stack.entryFile,
-        port: manifest.port ?? stack.port,
-        routes,
-        entryAppVars,
-        pythonCmd: stack.pythonCmd,
-      });
+  if (stack.framework === 'express') {
+    generateExpress({
+      cwd: opts.cwd,
+      entryFile: stack.entryFile,
+      moduleType: stack.moduleType,
+      port: manifest.port ?? stack.port,
+      routes,
+    });
+  } else if (stack.framework === 'nextjs') {
+    generateNext({
+      cwd: opts.cwd,
+      appDir: stack.entryFile,
+      port: manifest.port ?? stack.port,
+      routes,
+    });
+  } else {
+    generateFastAPI({
+      cwd: opts.cwd,
+      entryFile: stack.entryFile,
+      port: manifest.port ?? stack.port,
+      routes,
+      entryAppVars,
+      pythonCmd: stack.pythonCmd,
+    });
+  }
 
   for (const a of added) log(`[sparda] + ${a}`);
   for (const r of removed) log(`[sparda] - ${r}`);

package/src/detect.js

@@ -10,6 +10,25 @@ export function detectStack(cwd) {
   if (fs.existsSync(pkgPath)) {
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+    // next before express: a project with the next dep IS a Next app (express is
+    // occasionally present as a utility dep and would misroute detection)
+    if (deps.next) {
+      const appDir = ['app', 'src/app'].find((d) => {
+        const abs = path.join(cwd, d);
+        return fs.existsSync(abs) && fs.statSync(abs).isDirectory();
+      });
+      if (!appDir)
+        throw err(
+          'Next.js detected but no App Router directory (app/ or src/app/).',
+          'SPARDA supports the App Router only (route.js handlers) — the Pages Router is not supported.',
+        );
+      return {
+        framework: 'nextjs',
+        entryFile: appDir,
+        port: detectNextPort(cwd, pkg),
+        nextVersion: deps.next,
+      };
+    }
     if (deps.express) {
       const entryFile = findExpressEntry(cwd, pkg);
       const moduleType = detectModuleType(cwd, pkg, entryFile);
@@ -22,7 +41,7 @@ export function detectStack(cwd) {
         expressVersion: deps.express,
       };
     }
-    const known = ['@nestjs/core', 'next', 'fastify', 'koa'].find((d) => deps[d]);
+    const known = ['@nestjs/core', 'fastify', 'koa'].find((d) => deps[d]);
     if (known)
       throw err(
         `${known} detected — not supported yet. Express & FastAPI only in v0.`,
@@ -47,6 +66,27 @@ export function detectStack(cwd) {
   );
 }
 
+// `next dev -p 3001` / `--port 3001` in scripts, then PORT= in .env, then 3000
+function detectNextPort(cwd, pkg) {
+  for (const script of [pkg.scripts?.dev, pkg.scripts?.start]) {
+    if (!script) continue;
+    const m = script.match(/(?:-p|--port)[\s=]+(\d{2,5})/);
+    if (m) return Number(m[1]);
+  }
+  const envPath = path.join(cwd, '.env');
+  if (fs.existsSync(envPath)) {
+    const line = fs
+      .readFileSync(envPath, 'utf8')
+      .split(/\r?\n/)
+      .find((l) => l.startsWith('PORT='));
+    if (line) {
+      const v = Number(line.split('=')[1].trim());
+      if (v) return v;
+    }
+  }
+  return 3000;
+}
+
 function detectPython() {
   const cmds = ['python3', 'python', 'py'];
   for (const cmd of cmds) {

package/src/generator/express.js

@@ -283,7 +283,8 @@ export function removeInjection(cwd, manifest) {
 
 // Returns what was done ('created' | 'appended' | null) so the manifest can
 // record it and `remove` can revert the exact edit (byte-for-byte promise).
-function ensureGitignore(cwd) {
+// Exported: the Next.js generator shares the exact same contract.
+export function ensureGitignore(cwd) {
   const gi = path.join(cwd, '.gitignore');
   const line = '.sparda/';
   if (fs.existsSync(gi)) {

package/src/generator/nextjs.js

@@ -0,0 +1,113 @@
+// generator/nextjs.js — file-based injection for the App Router.
+// Next.js has no `app = express()` line to inject after: the filesystem is the
+// router, so SPARDA's injection IS a generated catch-all route handler at
+// <appDir>/mcp/[...sparda]/route.js. Nothing in the user's code is touched —
+// `remove` deletes the file and the diff is clean by construction.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { toolNameFor } from '../parser/express.js';
+import { ensureGitignore } from './express.js';
+import { carryOverManifest, defaultSpardingMemory } from './manifest.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function generateNext({ cwd, appDir, port, routes }) {
+  const taken = new Set([
+    'sparda_info',
+    'sparda_list_disabled_tools',
+    'sparda_get_context',
+  ]);
+  const tools = {};
+  for (const r of routes) {
+    const name = toolNameFor(r, taken);
+    tools[name] = {
+      method: r.method.toUpperCase(),
+      path: r.path,
+      enabled: !r.mutating, // write-safety: mutating tools off by default
+      pathParams: r.params.filter((p) => p.in === 'path').map((p) => p.name),
+      description: r.description,
+      params: r.params,
+      confidence: r.confidence,
+    };
+  }
+  const prev = carryOverManifest(cwd, tools);
+
+  // --- sparding safety memory & fingerprints (same contract as Express/FastAPI)
+  const sparding = defaultSpardingMemory(prev);
+  const oldFingerprints = sparding.toolFingerprints ?? {};
+  const newFingerprints = {};
+  for (const [name, t] of Object.entries(tools)) {
+    const raw = `${t.method}|${t.path}|${JSON.stringify(t.params)}`;
+    const fp = crypto.createHash('sha256').update(raw).digest('hex').slice(0, 8);
+    newFingerprints[name] = fp;
+    const oldFp = oldFingerprints[name];
+    if (oldFp && oldFp !== fp) {
+      sparding.events.push({
+        ts: new Date().toISOString(),
+        tool: name,
+        decision: 'audit',
+        risk: 'medium',
+        reasons: [
+          `route structure modified (fingerprint changed from ${oldFp} to ${fp})`,
+        ],
+      });
+      if (sparding.events.length > 100) sparding.events.shift();
+    }
+  }
+  sparding.toolFingerprints = newFingerprints;
+
+  // stable across re-runs so a running bridge/host pair never desyncs
+  const localKey = prev?.localKey ?? crypto.randomUUID();
+
+  // .js on purpose: Next enables allowJs in the tsconfig it manages, so the
+  // generated handler compiles untouched inside TS projects too.
+  const routerRel = `${appDir}/mcp/[...sparda]/route.js`;
+  const routerAbs = path.join(cwd, ...routerRel.split('/'));
+  fs.mkdirSync(path.dirname(routerAbs), { recursive: true });
+
+  let tpl = fs.readFileSync(
+    path.join(__dirname, '..', '..', 'templates', 'nextjs-router.txt'),
+    'utf8',
+  );
+  tpl = tpl
+    .replace('__TOOLS_JSON__', JSON.stringify(tools, null, 2))
+    .replace('__SPARDING_POLICIES__', JSON.stringify(sparding.policies ?? {}))
+    .replace('__LOCAL_KEY__', localKey)
+    .replace('__PORT__', String(port));
+  atomicWrite(routerAbs, tpl);
+
+  const gitignore = ensureGitignore(cwd) ?? prev?.gitignore ?? null;
+
+  const manifest = {
+    version: 1,
+    framework: 'nextjs',
+    entryFile: appDir, // the scanned App Router root, not a code entry point
+    port,
+    localKey,
+    generatedFiles: [routerRel],
+    injectedFiles: [], // file-based injection: no user file is ever modified
+    createdAt: new Date().toISOString(),
+    tools: Object.fromEntries(
+      Object.entries(tools).map(([k, v]) => [
+        k,
+        { method: v.method, path: v.path, enabled: v.enabled },
+      ]),
+    ),
+    ...(gitignore ? { gitignore } : {}),
+    ...(prev?.semantic ? { semantic: prev.semantic } : {}),
+    ...(prev?.immune ? { immune: prev.immune } : {}),
+    ...(prev?.labs ? { labs: prev.labs } : {}),
+    sparding,
+  };
+  atomicWrite(path.join(cwd, 'sparda.json'), JSON.stringify(manifest, null, 2) + '\n');
+
+  return {
+    tools,
+    manifest,
+    routerFile: routerRel,
+    injection: { injected: false, manual: null, fileBased: true },
+  };
+}

package/src/parser/nextjs.js

@@ -0,0 +1,248 @@
+// parser/nextjs.js — App Router route-handler extraction.
+// The filesystem IS the router: a route.{js,ts} file's directory chain is the
+// URL. We walk app/ (groups stripped, dynamic segments mapped to :params) and
+// AST-parse each route file for its exported HTTP-verb handlers. Catch-all,
+// optional catch-all, parallel slots and interception segments are skipped
+// with a reason (scan-report), never guessed.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from '@babel/parser';
+
+const VERBS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+const ROUTE_FILES = new Set([
+  'route.js',
+  'route.ts',
+  'route.mjs',
+  'route.jsx',
+  'route.tsx',
+]);
+const EXCLUDE = new Set(['node_modules', '.git', '.next', 'dist', 'build', '.sparda']);
+
+export function parseNextProject(cwd, appDir) {
+  const routes = [];
+  const skipped = [];
+  const seen = new Set(); // `${METHOD} ${path}` — group collapse can collide: (a)/x + (b)/x → /x
+
+  walk(path.resolve(cwd, appDir), []);
+  return { routes, skipped };
+
+  function walk(dir, segments) {
+    let items;
+    try {
+      items = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const item of items) {
+      const abs = path.join(dir, item.name);
+      if (item.isDirectory()) {
+        const name = item.name;
+        if (EXCLUDE.has(name)) continue;
+        if (name.startsWith('_')) continue; // private folder — excluded from routing by Next itself
+        if (name.startsWith('@')) {
+          skipped.push({
+            reason: `parallel route slot ${name} — not a URL segment, skipped`,
+            file: rel(abs),
+          });
+          continue;
+        }
+        if (/^\(\.{1,3}\)/.test(name)) {
+          skipped.push({
+            reason: `intercepting route ${name} — UI-layer routing, skipped`,
+            file: rel(abs),
+          });
+          continue;
+        }
+        if (/^\[\[\.\.\..+\]\]$/.test(name) || /^\[\.\.\..+\]$/.test(name)) {
+          skipped.push({
+            reason: `catch-all segment ${name} — variable-arity paths not supported in v1`,
+            file: rel(abs),
+          });
+          continue;
+        }
+        if (/^\(.+\)$/.test(name)) {
+          walk(abs, segments); // route group — organizational only, stripped from the URL
+          continue;
+        }
+        const m = name.match(/^\[(.+)\]$/);
+        walk(abs, [...segments, m ? `:${m[1]}` : name]);
+      } else if (item.isFile() && ROUTE_FILES.has(item.name)) {
+        const urlPath = '/' + segments.join('/');
+        if (urlPath === '/mcp' || urlPath.startsWith('/mcp/')) {
+          skipped.push({
+            reason: `self-referential path ${urlPath} blocked`,
+            file: rel(abs),
+          });
+          continue;
+        }
+        parseRouteFile(abs, urlPath || '/');
+      }
+    }
+  }
+
+  function parseRouteFile(absFile, urlPath) {
+    let src;
+    try {
+      src = fs.readFileSync(absFile, 'utf8');
+    } catch {
+      return;
+    }
+    let ast;
+    try {
+      ast = parse(src, {
+        sourceType: 'unambiguous',
+        plugins: ['typescript', 'jsx', ['decorators', { decoratorsBeforeExport: true }]],
+        attachComment: true,
+      });
+    } catch (e) {
+      skipped.push({
+        reason: `parse error in ${rel(absFile)}: ${e.message.slice(0, 80)}`,
+        file: rel(absFile),
+      });
+      return;
+    }
+
+    for (const node of ast.program.body) {
+      if (node.type !== 'ExportNamedDeclaration') continue;
+      const found = []; // [{ verb, fnNode|null }]
+
+      const decl = node.declaration;
+      if (decl?.type === 'FunctionDeclaration' && VERBS.has(decl.id?.name)) {
+        found.push({ verb: decl.id.name, fnNode: decl });
+      } else if (decl?.type === 'VariableDeclaration') {
+        for (const d of decl.declarations) {
+          if (d.id?.type !== 'Identifier' || !VERBS.has(d.id.name)) continue;
+          const isFn =
+            d.init?.type === 'ArrowFunctionExpression' ||
+            d.init?.type === 'FunctionExpression';
+          found.push({ verb: d.id.name, fnNode: isFn ? d.init : null });
+        }
+      } else if (!decl && node.specifiers?.length) {
+        // export { GET } [from './impl'] — verb confirmed, body out of reach
+        for (const spec of node.specifiers) {
+          const name = spec.exported?.name ?? spec.exported?.value;
+          if (VERBS.has(name)) found.push({ verb: name, fnNode: null });
+        }
+      }
+
+      for (const { verb, fnNode } of found) {
+        const method = verb.toLowerCase();
+        const key = `${verb} ${urlPath}`;
+        if (seen.has(key)) {
+          skipped.push({
+            reason: `route group collision: ${key} already extracted from another group`,
+            file: rel(absFile),
+            line: node.loc?.start.line,
+          });
+          continue;
+        }
+        seen.add(key);
+
+        const description = (node.leadingComments ?? [])
+          .map((c) =>
+            c.value
+              .replace(/^\*+/gm, '')
+              .replace(/^\s*\*\s?/gm, '')
+              .trim(),
+          )
+          .filter(Boolean)
+          .join(' ')
+          .slice(0, 400);
+
+        const params = [...urlPath.matchAll(/:(\w+)/g)].map((mm) => ({
+          name: mm[1],
+          in: 'path',
+          type: 'string',
+          required: true,
+          description: 'path parameter',
+        }));
+        const taken = new Set(params.map((x) => x.name));
+        for (const q of queryParamsOf(fnNode)) {
+          if (taken.has(q)) continue;
+          taken.add(q);
+          params.push({
+            name: q,
+            in: 'query',
+            type: 'string',
+            required: false,
+            description: 'query parameter',
+          });
+        }
+
+        const mutating = method !== 'get';
+        let confidence = fnNode ? 'high' : 'low'; // re-exported handler body is unreadable here
+        if (mutating) {
+          params.push({
+            name: 'body',
+            in: 'body',
+            type: 'object',
+            required: false,
+            description: 'JSON body — schema not statically detected',
+          });
+          confidence = 'low';
+        }
+
+        routes.push({
+          method,
+          path: urlPath,
+          handlerName: verb,
+          sourceFile: rel(absFile),
+          sourceLine: node.loc?.start.line ?? 0,
+          params,
+          description,
+          mutating,
+          confidence,
+        });
+      }
+    }
+  }
+
+  function rel(abs) {
+    return path.relative(cwd, abs).split(path.sep).join('/');
+  }
+}
+
+// Query params only surface in the handler body — the canonical App Router
+// shapes are `searchParams.get('x')` / `.getAll('x')`, whether searchParams
+// came from `new URL(request.url)` or `request.nextUrl`. Plain recursive AST
+// walk (no scope needed), bounded to 15 like the Express scanner.
+function queryParamsOf(fnNode) {
+  const found = [];
+  if (!fnNode) return found;
+  visit(fnNode.body);
+  return [...new Set(found)];
+
+  function visit(node) {
+    if (!node || typeof node !== 'object' || found.length >= 15) return;
+    if (Array.isArray(node)) {
+      for (const n of node) visit(n);
+      return;
+    }
+    if (
+      node.type === 'CallExpression' &&
+      node.callee?.type === 'MemberExpression' &&
+      !node.callee.computed &&
+      (node.callee.property?.name === 'get' || node.callee.property?.name === 'getAll') &&
+      node.arguments[0]?.type === 'StringLiteral'
+    ) {
+      const obj = node.callee.object;
+      const isSearchParams =
+        (obj.type === 'Identifier' && obj.name === 'searchParams') ||
+        (obj.type === 'MemberExpression' &&
+          !obj.computed &&
+          obj.property?.name === 'searchParams');
+      if (isSearchParams) found.push(node.arguments[0].value);
+    }
+    for (const k of Object.keys(node)) {
+      if (
+        k === 'loc' ||
+        k === 'range' ||
+        k === 'leadingComments' ||
+        k === 'trailingComments'
+      )
+        continue;
+      const v = node[k];
+      if (v && typeof v === 'object') visit(v);
+    }
+  }
+}

package/src/server/stdio.js

@@ -1059,7 +1059,7 @@ async function waitForHost(port, key, framework, ctx) {
       }
     }
     if (attempt === 0) {
-      const startCmd = framework === 'express' ? 'npm run dev' : 'fastapi dev';
+      const startCmd = framework === 'fastapi' ? 'fastapi dev' : 'npm run dev';
       console.error(
         `[sparda] Waiting for host app on :${port} ... (start it with ${startCmd} — Ctrl+C to abort)`,
       );

package/templates/nextjs-router.txt

@@ -0,0 +1,383 @@
+// ============================================================
+// SPARDA ROUTER (Next.js App Router) — Auto-generated. DO NOT EDIT.
+// Regenerate: npx sparda-mcp init   •   Remove: npx sparda-mcp remove
+// File-based injection: this catch-all handler IS the /mcp router.
+// Web-standard Request/Response only — zero imports, zero dependencies.
+// ============================================================
+
+const SPARDA_TOOLS = __TOOLS_JSON__;
+const SPARDA_POLICIES = __SPARDING_POLICIES__;
+
+const SPARDA_LOCAL_KEY = "__LOCAL_KEY__";
+const SPARDA_PORT = __PORT__;
+
+// never statically optimized, always on the Node.js runtime (process, timers)
+export const dynamic = 'force-dynamic';
+export const runtime = 'nodejs';
+
+// Module-scope state survives requests on a long-lived server (next start /
+// next dev). On serverless each instance keeps its own gauges — RAM-only by
+// design, the durable memory lives in sparda.json via the bridge.
+const SPARDA_STATS = {};
+const SPARDA_EVENTS = [];
+let SPARDA_SEQ = 0;
+// immune system: tools that keep failing are quarantined so the AI can't hammer a broken route
+const SPARDA_QUARANTINE = {};
+const SPARDA_QUARANTINE_MS = Number(process.env.SPARDA_QUARANTINE_MS ?? 60000);
+// recycling gauge: calls answered from SPARDA's own knowledge vs calls that paid the host route.
+const SPARDA_RECYCLE = { servedByCircle: 0, paidFull: 0 };
+function spardaRecycleRate() {
+  const total = SPARDA_RECYCLE.servedByCircle + SPARDA_RECYCLE.paidFull;
+  return total ? Math.round((SPARDA_RECYCLE.servedByCircle * 100) / total) : 0;
+}
+// thermodynamic route classification — observation only, never a guess.
+const SPARDA_PURITY = {};
+function spardaHash(s) {
+  let h = 0x811c9dc5; // FNV-1a, capped: a fingerprint, not a checksum of megabytes
+  for (let i = 0; i < s.length && i < 65536; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; }
+  return h;
+}
+function spardaObservePurity(tool, argsig, body) {
+  const pu = SPARDA_PURITY[tool] ?? (SPARDA_PURITY[tool] = { sigs: {}, repeats: 0, mismatches: 0 });
+  const h = spardaHash(body);
+  const known = pu.sigs[argsig];
+  if (known === undefined) {
+    if (Object.keys(pu.sigs).length >= 20) return; // bounded: enough sigs to judge
+    pu.sigs[argsig] = h;
+  } else if (known === h) pu.repeats += 1;
+  else { pu.mismatches += 1; pu.sigs[argsig] = h; } // the latest real answer is the truth
+}
+function spardaPuritySnapshot() {
+  const out = {};
+  for (const [name, spec] of Object.entries(SPARDA_TOOLS)) {
+    if (spec.method !== 'GET') { out[name] = { class: 'erasing', repeats: 0, mismatches: 0 }; continue; }
+    const pu = SPARDA_PURITY[name];
+    out[name] = {
+      class: !pu ? 'unknown' : pu.mismatches > 0 ? 'volatile' : pu.repeats >= 3 ? 'pure' : 'unknown',
+      repeats: pu ? pu.repeats : 0,
+      mismatches: pu ? pu.mismatches : 0,
+    };
+  }
+  return out;
+}
+// ── horizontal scale: Quorum Sensing × G-Map CRDT (same contract as Express) ──
+const SPARDA_PEERS = (process.env.SPARDA_PEERS ?? '').split(',').map((s) => s.trim().replace(/\/$/, '')).filter((s) => /^https?:\/\//.test(s));
+const SPARDA_GOSSIP_MS = Math.max(50, Number(process.env.SPARDA_GOSSIP_MS) || 30000);
+const SPARDA_GOSSIP_TIMEOUT_MS = Math.max(250, Number(process.env.SPARDA_GOSSIP_TIMEOUT_MS) || 2000);
+function spardaGossipSnapshot() {
+  const out = {};
+  for (const [name, pu] of Object.entries(SPARDA_PURITY)) out[name] = { repeats: pu.repeats, mismatches: pu.mismatches };
+  return out;
+}
+function spardaMergeGossip(remote) {
+  if (!remote || typeof remote !== 'object' || Array.isArray(remote)) return 0;
+  let merged = 0;
+  for (const [name, rv] of Object.entries(remote)) {
+    if (!SPARDA_TOOLS[name] || !rv || typeof rv !== 'object') continue;
+    const r = Number(rv.repeats), m = Number(rv.mismatches);
+    if (!Number.isFinite(r) || !Number.isFinite(m) || r < 0 || m < 0) continue;
+    const pu = SPARDA_PURITY[name] ?? (SPARDA_PURITY[name] = { sigs: {}, repeats: 0, mismatches: 0 });
+    if (r > pu.repeats) pu.repeats = r;
+    if (m > pu.mismatches) pu.mismatches = m;
+    merged += 1;
+  }
+  return merged;
+}
+function spardaGossipTick() {
+  if (SPARDA_PEERS.length === 0) return;
+  const body = JSON.stringify(spardaGossipSnapshot());
+  for (const peer of SPARDA_PEERS) {
+    fetch(`${peer}/mcp/gossip`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json', 'x-sparda-key': SPARDA_LOCAL_KEY },
+      body,
+      signal: AbortSignal.timeout(SPARDA_GOSSIP_TIMEOUT_MS),
+    }).catch(() => {});
+  }
+}
+function spardaEvent(source, tool, status, message) {
+  SPARDA_EVENTS.push({ seq: ++SPARDA_SEQ, ts: new Date().toISOString(), source, tool, status, message: String(message ?? '').slice(0, 500) });
+  if (SPARDA_EVENTS.length > 100) SPARDA_EVENTS.shift();
+}
+// hot-reload guard: dev re-evaluates this module; process listeners and timers
+// must be registered exactly once per process.
+if (!globalThis.__SPARDA_WIRED__) {
+  globalThis.__SPARDA_WIRED__ = true;
+  process.on('uncaughtExceptionMonitor', (err) => spardaEvent('process', null, null, err && err.message ? err.message : err));
+  if (SPARDA_PEERS.length > 0) {
+    spardaEvent('gossip', null, null, `horizontal scale: gossiping to ${SPARDA_PEERS.length} peer(s) every ${SPARDA_GOSSIP_MS}ms`);
+    setInterval(spardaGossipTick, SPARDA_GOSSIP_MS).unref();
+  }
+}
+
+// two-phase commit: a write/delete flagged require_human is NOT executed on /invoke.
+const SPARDA_PENDING = {};
+const SPARDA_CONFIRM_TTL_MS = Number(process.env.SPARDA_CONFIRM_TTL_MS ?? 120000);
+function spardaNonce() {
+  return 'cfm_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 10);
+}
+function spardaSweepPending() {
+  const now = Date.now();
+  for (const k of Object.keys(SPARDA_PENDING)) if (now > SPARDA_PENDING[k].expiresAt) delete SPARDA_PENDING[k];
+}
+
+function spardaProof(tool, spec, args) {
+  const checks = {
+    knownTool: spec !== undefined,
+    enabled: spec ? spec.enabled : false,
+    loopSafe: spec ? !spec.path.startsWith('/mcp') : false,
+    methodClass: spec ? (spec.method === 'GET' ? 'read' : 'write') : 'read',
+    pathParamsPresent: true,
+    hasBodyForWrite: true,
+    reversibleHint: false,
+    quarantineSafe: true,
+  };
+  const reasons = [];
+  if (!checks.knownTool) {
+    reasons.push('unknown tool');
+    return { version: 'sparding-proof/v0.1', risk: 'blocked', decision: 'block', reasons, checks };
+  }
+  if (!checks.enabled) reasons.push('tool disabled (write-safety)');
+  if (!checks.loopSafe) reasons.push('self-referential tool blocked (loop protection)');
+  const quarantined = SPARDA_QUARANTINE[tool];
+  if (quarantined) {
+    if (Date.now() < quarantined.until) {
+      checks.quarantineSafe = false;
+      reasons.push(`tool quarantined (immune system): ${quarantined.reason}`);
+    } else {
+      delete SPARDA_QUARANTINE[tool];
+      if (SPARDA_STATS[tool]) SPARDA_STATS[tool].consecutive5xx = 2;
+    }
+  }
+  for (const name of spec.pathParams ?? []) {
+    if (args[name] === undefined) {
+      checks.pathParamsPresent = false;
+      reasons.push(`missing path param: ${name}`);
+    }
+  }
+  if (checks.methodClass === 'write' && args.body === undefined) checks.hasBodyForWrite = false;
+  if (spec.method === 'GET') checks.reversibleHint = true;
+  else checks.reversibleHint = Object.values(SPARDA_TOOLS).some((t) => t.method === 'GET' && t.path === spec.path);
+
+  let risk = 'low';
+  let decision = 'allow';
+  if (!checks.enabled || !checks.loopSafe || !checks.quarantineSafe || !checks.pathParamsPresent) {
+    return { version: 'sparding-proof/v0.1', risk: 'blocked', decision: 'block', reasons, checks };
+  }
+  const policies = SPARDA_POLICIES ?? {};
+  if (checks.methodClass === 'read') {
+    const readPolicy = policies.reads ?? 'allow';
+    if (readPolicy === 'block') { decision = 'block'; risk = 'blocked'; reasons.push('read policy blocks execution'); }
+    else if (readPolicy === 'require_human') { decision = 'require_human'; risk = 'medium'; reasons.push('read policy requires human confirmation'); }
+  } else {
+    const isDelete = spec.method === 'DELETE';
+    const deletePolicy = policies.deletes ?? 'block';
+    const writePolicy = policies.writes ?? 'require_human';
+    if (isDelete && deletePolicy === 'block') { decision = 'block'; risk = 'blocked'; reasons.push('delete policy blocks execution'); }
+    else if (isDelete && deletePolicy === 'require_human') { decision = 'require_human'; risk = 'high'; reasons.push('delete operation requires human confirmation'); }
+    else if (isDelete && deletePolicy === 'allow') { decision = 'allow'; risk = 'low'; }
+    else if (writePolicy === 'block') { decision = 'block'; risk = 'blocked'; reasons.push('write policy blocks execution'); }
+    else if (writePolicy === 'require_human') { decision = 'require_human'; risk = 'medium'; reasons.push('write operation requires human confirmation'); }
+    else { decision = 'allow'; risk = 'low'; }
+  }
+  return { version: 'sparding-proof/v0.1', risk, decision, reasons, checks };
+}
+
+function spardaRecord(tool, status, ms) {
+  const st = SPARDA_STATS[tool] ?? (SPARDA_STATS[tool] = { calls: 0, errors: 0, clientErrors: 0, totalMs: 0, lastStatus: null, lastTs: null, consecutive5xx: 0 });
+  if (st.calls >= 5 && ms > Math.max((st.totalMs / st.calls) * 10, 200)) {
+    spardaEvent('immune', tool, status, `latency anomaly: ${ms}ms vs ~${Math.round(st.totalMs / st.calls)}ms baseline`);
+  }
+  st.calls += 1;
+  st.totalMs += ms;
+  if (status >= 500) st.errors += 1;
+  else if (status >= 400) st.clientErrors += 1;
+  st.lastStatus = status;
+  st.lastTs = new Date().toISOString();
+  if (status >= 500) st.consecutive5xx += 1;
+  else if (status < 400) st.consecutive5xx = 0;
+  if (st.consecutive5xx >= 3 && !SPARDA_QUARANTINE[tool]) {
+    SPARDA_QUARANTINE[tool] = { since: new Date().toISOString(), until: Date.now() + SPARDA_QUARANTINE_MS, reason: `${st.consecutive5xx} consecutive 5xx` };
+    spardaEvent('immune', tool, 503, `quarantined after ${st.consecutive5xx} consecutive 5xx (cooldown ${SPARDA_QUARANTINE_MS}ms)`);
+  }
+}
+
+const spardaJson = (status, obj) =>
+  new Response(JSON.stringify(obj), { status, headers: { 'content-type': 'application/json' } });
+
+// SPARDA owns its endpoints' body parsing: 64KB cap and a JSON 400 on malformed
+// bodies — never a framework HTML error page.
+async function spardaReadJson(request) {
+  let text;
+  try { text = await request.text(); } catch { return { error: spardaJson(400, { error: 'unreadable body' }) }; }
+  if (text.length > 65536) return { error: spardaJson(413, { error: 'payload too large (64KB max)' }) };
+  if (!text) return { data: {} };
+  try { return { data: JSON.parse(text) }; } catch {
+    spardaEvent('router', null, 400, 'invalid JSON body');
+    return { error: spardaJson(400, { error: 'invalid JSON body' }) };
+  }
+}
+
+// the actual host-route call, shared by the allow-path and the confirm-path.
+// The "host" is this same Next server: SPARDA proxies to 127.0.0.1 like on
+// Express, so handlers run with their full middleware/context untouched.
+async function spardaExecute(tool, spec, args, proof, t0) {
+  try {
+    let url = spec.path.replace(/:(\w+)/g, (_, name) => encodeURIComponent(String(args[name])));
+    const query = [];
+    for (const [k, v] of Object.entries(args)) {
+      if (k === 'body' || (spec.pathParams ?? []).includes(k) || v === undefined) continue;
+      query.push(`${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`);
+    }
+    if (query.length) url += `?${query.join('&')}`;
+    const init = { method: spec.method, headers: {} };
+    if (spec.method !== 'GET' && args.body !== undefined) {
+      init.headers['content-type'] = 'application/json';
+      init.body = JSON.stringify(args.body);
+    }
+    SPARDA_RECYCLE.paidFull += 1; // the host route is about to be exercised — full price
+    const upstream = await fetch(`http://127.0.0.1:${SPARDA_PORT}${url}`, { ...init, signal: AbortSignal.timeout(30_000) });
+    const text = await upstream.text();
+    let data; try { data = JSON.parse(text); } catch { data = text; }
+    spardaRecord(tool, upstream.status, Date.now() - t0);
+    if (spec.method === 'GET' && upstream.status === 200) {
+      spardaObservePurity(tool, JSON.stringify(Object.entries(args).filter((e) => e[1] !== undefined).sort()), text);
+    }
+    if (upstream.status >= 500) spardaEvent('invoke', tool, upstream.status, text.slice(0, 200));
+    return spardaJson(200, { upstreamStatus: upstream.status, data, spardingProof: proof });
+  } catch (err) {
+    spardaRecord(tool, err.status ?? 502, Date.now() - t0);
+    spardaEvent('invoke', tool, err.status ?? 502, err.message);
+    return spardaJson(err.status ?? 502, { error: err.message, spardingProof: proof });
+  }
+}
+
+async function spardaInvoke(request) {
+  const t0 = Date.now();
+  const read = await spardaReadJson(request);
+  if (read.error) return read.error;
+  const reqBody = read.data ?? {};
+  const tool = reqBody.tool;
+  if (reqBody.args !== undefined && (reqBody.args === null || typeof reqBody.args !== 'object' || Array.isArray(reqBody.args))) {
+    return spardaJson(400, { error: 'args must be a JSON object', got: reqBody.args === null ? 'null' : Array.isArray(reqBody.args) ? 'array' : typeof reqBody.args });
+  }
+  const args = reqBody.args ?? {};
+  const spec = SPARDA_TOOLS[tool];
+  const proof = spardaProof(tool, spec, args);
+
+  if (proof.decision === 'block') {
+    if (!proof.checks.knownTool) return spardaJson(404, { error: `unknown tool: ${tool}`, spardingProof: proof });
+    if (!proof.checks.enabled)
+      return spardaJson(403, { error: `tool disabled (write-safety): ${tool}`, hint: 'Enable it in sparda.json, then re-run: npx sparda-mcp init', spardingProof: proof });
+    if (!proof.checks.loopSafe)
+      return spardaJson(400, { error: 'self-referential tool blocked (loop protection)', spardingProof: proof });
+    if (!proof.checks.quarantineSafe) {
+      const quarantined = SPARDA_QUARANTINE[tool];
+      SPARDA_RECYCLE.servedByCircle += 1; // the doomed host call was never paid
+      return spardaJson(503, {
+        error: `tool quarantined (immune system): ${tool}`,
+        reason: quarantined ? quarantined.reason : '',
+        retryInMs: quarantined ? Math.max(0, quarantined.until - Date.now()) : 0,
+        spardingProof: proof,
+      });
+    }
+    const status = proof.reasons.some((r) => r.includes('policy blocks execution')) ? 403 : 400;
+    return spardaJson(status, { error: proof.reasons[0] || 'blocked', spardingProof: proof });
+  }
+
+  if (proof.decision === 'require_human') {
+    spardaSweepPending();
+    const confirm = spardaNonce();
+    SPARDA_PENDING[confirm] = { tool, args, expiresAt: Date.now() + SPARDA_CONFIRM_TTL_MS, createdAt: new Date().toISOString() };
+    let siblingName = null;
+    for (const [n, t] of Object.entries(SPARDA_TOOLS)) { if (t.method === 'GET' && t.path === spec.path) { siblingName = n; break; } }
+    spardaEvent('confirm', tool, 202, `gated, awaiting confirmation (risk: ${proof.risk})`);
+    return spardaJson(202, {
+      status: 'awaiting_confirmation',
+      confirm,
+      expiresInMs: SPARDA_CONFIRM_TTL_MS,
+      preview: {
+        tool,
+        method: spec.method,
+        path: spec.path,
+        willSendBody: spec.method !== 'GET' && args.body !== undefined,
+        reversibleHint: proof.checks.reversibleHint,
+        inspectFirst: siblingName ? { tool: siblingName, why: 'GET on the same path — read current state before committing this write' } : null,
+      },
+      instruction: `NOT EXECUTED. ${spec.method} ${spec.path} is gated by policy (${proof.reasons[0] || 'require_human'}); the host route was not touched.${siblingName ? ` First call "${siblingName}" to inspect current state, then` : ' To'} confirm via POST /invoke/confirm { "confirm": "${confirm}" }. Single-use, expires in ${Math.round(SPARDA_CONFIRM_TTL_MS / 1000)}s.`,
+      spardingProof: proof,
+    });
+  }
+
+  return spardaExecute(tool, spec, args, proof, t0);
+}
+
+async function spardaConfirm(request) {
+  const t0 = Date.now();
+  const read = await spardaReadJson(request);
+  if (read.error) return read.error;
+  const confirm = (read.data ?? {}).confirm;
+  if (typeof confirm !== 'string' || !confirm) {
+    return spardaJson(400, { error: 'missing confirm token (expected { confirm: "..." })' });
+  }
+  spardaSweepPending();
+  const pending = SPARDA_PENDING[confirm];
+  if (pending) delete SPARDA_PENDING[confirm]; // consume first — a token can never replay
+  if (!pending) return spardaJson(409, { error: 'unknown or expired confirmation token', hint: 're-issue the write via /invoke to mint a fresh token' });
+  if (Date.now() > pending.expiresAt) return spardaJson(409, { error: 'confirmation token expired', hint: 're-issue the write via /invoke' });
+  const spec = SPARDA_TOOLS[pending.tool];
+  const proof = spardaProof(pending.tool, spec, pending.args); // re-judge at commit time
+  if (proof.decision === 'block') {
+    return spardaJson(403, { error: 'confirmation no longer valid', reason: proof.reasons[0] || 'blocked', spardingProof: proof });
+  }
+  spardaEvent('confirm', pending.tool, 200, 'confirmed -> executing');
+  return spardaExecute(pending.tool, spec, pending.args, proof, t0);
+}
+
+async function spardaHandle(request, ctx) {
+  try {
+    if (request.headers.get('x-sparda-key') !== SPARDA_LOCAL_KEY) {
+      return spardaJson(401, { error: 'unauthorized' });
+    }
+    const params = ctx?.params ? await ctx.params : {};
+    const seg = Array.isArray(params.sparda) ? params.sparda : [];
+    const sub = '/' + seg.join('/');
+    const method = request.method;
+
+    if (sub === '/tools' && method === 'GET') return spardaJson(200, SPARDA_TOOLS);
+    if (sub === '/stats' && method === 'GET')
+      return spardaJson(200, {
+        uptimeSec: Math.round(process.uptime()),
+        stats: SPARDA_STATS,
+        quarantine: SPARDA_QUARANTINE,
+        recycle: { servedByCircle: SPARDA_RECYCLE.servedByCircle, paidFull: SPARDA_RECYCLE.paidFull, ratePct: spardaRecycleRate() },
+        purity: spardaPuritySnapshot(),
+      });
+    if (sub === '/events' && method === 'GET') {
+      const since = Number(new URL(request.url).searchParams.get('since') ?? 0) || 0;
+      return spardaJson(200, { seq: SPARDA_SEQ, events: SPARDA_EVENTS.filter((e) => e.seq > since) });
+    }
+    if (sub === '/gossip' && method === 'POST') {
+      const read = await spardaReadJson(request);
+      if (read.error) return read.error;
+      spardaMergeGossip(read.data);
+      return new Response(null, { status: 204 });
+    }
+    if (sub === '/invoke' && method === 'POST') return spardaInvoke(request);
+    if (sub === '/invoke/confirm' && method === 'POST') return spardaConfirm(request);
+    if (sub === '/invoke' || sub === '/invoke/confirm')
+      return spardaJson(405, { error: 'method not allowed', allow: 'POST' });
+    return spardaJson(404, { error: 'not found', path: sub });
+  } catch (err) {
+    // error envelope: the stack stays server-side, correlated to /events by errorId
+    const errorId = 'err_' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+    spardaEvent('router', null, (err && err.status) || 500, `[${errorId}] ${err && err.message ? err.message : err}`);
+    return spardaJson((err && err.status) || 500, { error: 'internal error', errorId });
+  }
+}
+
+export async function GET(request, ctx) { return spardaHandle(request, ctx); }
+export async function POST(request, ctx) { return spardaHandle(request, ctx); }
+export async function PUT(request, ctx) { return spardaHandle(request, ctx); }
+export async function PATCH(request, ctx) { return spardaHandle(request, ctx); }
+export async function DELETE(request, ctx) { return spardaHandle(request, ctx); }