sparda-mcp 0.13.2 → 0.14.0

package/src/commands/review.js

@@ -0,0 +1,206 @@
+// commands/review.js — the SEMANTIC diff of a pull request (roadmap R5/M3).
+// Everyone diffs a PR's TEXT; nobody diffs its BEHAVIOR. `sparda review` compiles
+// the base ref and the working tree to the UBG and answers, with zero config and
+// zero spec written by hand: what endpoints did this change add or remove, whose
+// blast radius grew, which guard or invariant did it drop, and what new provable
+// risk did it introduce. It is `apocalypse` made relative — the baseline is git,
+// not a file you remembered to save. Composes the existing prover passes
+// (checkGraph/diffGraphs/verdictOf) over two graphs, so every word is a
+// counterexample, never a heuristic.
+//   sparda review                 diff the working tree against the default base
+//   sparda review --base main     pick the base ref explicitly
+//   sparda review --json          machine-readable envelope
+//   sparda review --markdown      a PR-comment-ready block
+// Exit code 1 on any critical/high — drop it in CI between "tests pass" and "merge".
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph, cmp } from '../ubg/schema.js';
+import { checkGraph, diffGraphs, verdictOf } from '../ubg/apocalypse.js';
+
+const ICONS = { critical: '✗', high: '✗', medium: '⚠', info: '·' };
+const err = (message, hint) => Object.assign(new Error(message), { code: 'USER', hint });
+
+// A finding's stable identity, so a risk the base already had is never re-blamed
+// on this PR (introduced = present now, absent in the base).
+const findingKey = (f) => `${f.rule}|${f.entrypoint}`;
+const entrypointsOf = (graph) =>
+  graph.nodes.filter((n) => n.kind === 'entrypoint').map((n) => n.id);
+
+// ---------------------------------------------------------------------------
+// Pure core — two canonical graphs in, a review out. No git, no disk, no LLM.
+// ---------------------------------------------------------------------------
+export function reviewGraphs(baseGraph, candidateGraph) {
+  // protections this deploy REMOVED (guards, invariants, entrypoints, blast radius)
+  const removed = diffGraphs(baseGraph, candidateGraph).findings;
+
+  // provable risks this deploy INTRODUCED: static findings now, minus the ones the
+  // base already carried (a pre-existing sin is not this PR's fault).
+  const { findings: candStatic, obligations } = checkGraph(candidateGraph);
+  const baseKeys = new Set(checkGraph(baseGraph).findings.map(findingKey));
+  const introduced = candStatic.filter((f) => !baseKeys.has(findingKey(f)));
+
+  // union, de-duped by (rule, entrypoint) — a removed guard can surface both as
+  // GUARD_REMOVED (diff) and UNGUARDED_MUTATION (static); keep the strongest once.
+  const byKey = new Map();
+  for (const f of [...removed, ...introduced]) {
+    const k = findingKey(f);
+    if (!byKey.has(k)) byKey.set(k, f);
+  }
+  const findings = [...byKey.values()].sort(
+    (a, b) => rank(a.severity) - rank(b.severity) || cmp(findingKey(a), findingKey(b)),
+  );
+
+  const baseEps = new Set(entrypointsOf(baseGraph));
+  const candEps = new Set(entrypointsOf(candidateGraph));
+  const added = [...candEps].filter((e) => !baseEps.has(e)).sort(cmp);
+  const removedEps = [...baseEps].filter((e) => !candEps.has(e)).sort(cmp);
+
+  return {
+    verdict: verdictOf(findings),
+    obligations,
+    findings,
+    endpoints: { added, removed: removedEps },
+  };
+}
+
+const SEVERITY_RANK = { critical: 0, high: 1, medium: 2, info: 3 };
+const rank = (s) => SEVERITY_RANK[s] ?? 9;
+
+// ---------------------------------------------------------------------------
+// Orchestration — resolve a base ref, compile it in an isolated git worktree,
+// compile the working tree, review, render.
+// ---------------------------------------------------------------------------
+export async function runReview(opts) {
+  const cwd = opts.cwd;
+  const base = resolveBase(cwd, opts.base);
+
+  const candidate = canonicalizeGraph(
+    compileUBG(cwd, { write: false, openapi: opts.openapi }).graph,
+  );
+  const baseGraph = compileAtRef(cwd, base, opts);
+
+  const review = { base, ...reviewGraphs(baseGraph, candidate) };
+
+  if (opts.json) console.log(JSON.stringify(review, null, 2));
+  else if (opts.markdown) console.log(renderMarkdown(review));
+  else renderHuman(review);
+
+  if (!review.verdict.safe) process.exitCode = 1; // CI gate
+  return review;
+}
+
+// First base ref that resolves. Explicit --base wins; otherwise the usual PR
+// targets, newest-intent first, falling back to the previous commit.
+function resolveBase(cwd, explicit) {
+  const candidates = explicit
+    ? [explicit]
+    : ['origin/HEAD', 'origin/main', 'origin/master', 'main', 'master', 'HEAD~1'];
+  for (const ref of candidates) {
+    try {
+      execFileSync(
+        'git',
+        ['-C', cwd, 'rev-parse', '--verify', '--quiet', `${ref}^{commit}`],
+        {
+          stdio: 'pipe',
+        },
+      );
+      return ref;
+    } catch {
+      /* try the next candidate */
+    }
+  }
+  throw err(
+    explicit ? `base ref '${explicit}' not found` : 'could not resolve a base ref',
+    'run inside a git repo and pass one with --base <ref> (e.g. --base main)',
+  );
+}
+
+// Compile the tree AT a git ref without disturbing the working tree: a detached
+// worktree, compiled, then removed. Static compile — no npm install needed.
+function compileAtRef(cwd, ref, opts) {
+  const tmp = path.join(os.tmpdir(), `sparda-review-${process.pid}-${Date.now()}`);
+  try {
+    execFileSync('git', ['-C', cwd, 'worktree', 'add', '--detach', '--quiet', tmp, ref], {
+      stdio: 'pipe',
+    });
+  } catch (e) {
+    throw err(
+      `could not check out base ref '${ref}': ${String(e.stderr ?? e.message).trim()}`,
+      'ensure the ref exists (e.g. `git fetch origin main`) or pass --base <ref>',
+    );
+  }
+  try {
+    return canonicalizeGraph(
+      compileUBG(tmp, { write: false, openapi: opts.openapi }).graph,
+    );
+  } finally {
+    try {
+      execFileSync('git', ['-C', cwd, 'worktree', 'remove', '--force', tmp], {
+        stdio: 'pipe',
+      });
+    } catch {
+      /* best effort */
+    }
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Renderers
+// ---------------------------------------------------------------------------
+function renderHuman(r) {
+  const { verdict: v, findings, endpoints } = r;
+  console.log(`REVIEW — behavior diff of the working tree vs ${r.base}`);
+  if (endpoints.added.length)
+    console.log(`  + new endpoints: ${endpoints.added.map(shortEp).join(', ')}`);
+  if (endpoints.removed.length)
+    console.log(`  - removed endpoints: ${endpoints.removed.map(shortEp).join(', ')}`);
+  if (!endpoints.added.length && !endpoints.removed.length)
+    console.log('  · no endpoints added or removed');
+
+  if (findings.length) {
+    console.log('\n  Behavior risks changed by this diff:');
+    for (const f of findings)
+      console.log(`  ${ICONS[f.severity]} [${f.severity}] ${f.rule} — ${f.message}`);
+  }
+
+  const c = v.counts;
+  if (v.clean)
+    console.log(
+      '\n✓ PROVEN — this diff removes no protection and introduces no new risk.',
+    );
+  else
+    console.log(
+      `\n${v.safe ? '⚠ RISKY' : '✗ NOT PROVEN'} — ${c.critical} critical, ${c.high} high, ${c.medium} medium, ${c.info} info`,
+    );
+}
+
+function renderMarkdown(r) {
+  const { verdict: v, findings, endpoints } = r;
+  const c = v.counts;
+  const head = v.clean
+    ? '✓ **PROVEN** — no protection removed, no new risk introduced.'
+    : `${v.safe ? '⚠ **RISKY**' : '✗ **NOT PROVEN**'} — ${c.critical} critical, ${c.high} high, ${c.medium} medium, ${c.info} info.`;
+  const lines = [`## 🔍 SPARDA semantic review (vs \`${r.base}\`)`, '', head, ''];
+  if (endpoints.added.length || endpoints.removed.length) {
+    lines.push('### Endpoint surface');
+    for (const e of endpoints.added) lines.push(`- 🆕 \`${shortEp(e)}\``);
+    for (const e of endpoints.removed) lines.push(`- ❌ \`${shortEp(e)}\` (removed)`);
+    lines.push('');
+  }
+  if (findings.length) {
+    lines.push('### Protections removed / risks introduced');
+    for (const f of findings)
+      lines.push(`- ${ICONS[f.severity]} **[${f.severity}] ${f.rule}** — ${f.message}`);
+    lines.push('');
+  }
+  lines.push(
+    '<sub>Derived from the code + schema by SPARDA — a counterexample, not a heuristic.</sub>',
+  );
+  return lines.join('\n');
+}
+
+const shortEp = (id) => id.replace(/^entrypoint:/, '');

package/src/flight/box.js

@@ -29,8 +29,11 @@ export function createFlightBox() {
   const als = new AsyncLocalStorage();
   const originals = {};
   let armed = false;
-  let insideUUID = false;
-  let insideFetch = false;
+  // Node 18: fetch (undici) and crypto.randomUUID call Date.now()/Math.random()
+  // internally — those must NOT be recorded as entropy taps. The suppression
+  // flag lives ON THE STORE (per-request), not on the box: a global flag would
+  // let one request's fetch window swallow a concurrent request's entropy taps
+  // and silently corrupt its flight.
 
   function arm() {
     if (armed) return;
@@ -42,7 +45,7 @@ export function createFlightBox() {
 
     Date.now = function spardaDateNow() {
       const store = als.getStore();
-      if (!store || insideUUID || insideFetch) return originals.dateNow();
+      if (!store || store.suppressEntropy) return originals.dateNow();
       if (store.mode === 'record') {
         const v = originals.dateNow();
         tapOut(store, 'time', 'Date.now', v);
@@ -53,7 +56,7 @@ export function createFlightBox() {
 
     Math.random = function spardaRandom() {
       const store = als.getStore();
-      if (!store || insideUUID || insideFetch) return originals.random();
+      if (!store || store.suppressEntropy) return originals.random();
       if (store.mode === 'record') {
         const v = originals.random();
         tapOut(store, 'random', 'Math.random', v);
@@ -69,13 +72,13 @@ export function createFlightBox() {
           const store = als.getStore();
           if (!store) return originals.randomUUID();
           if (store.mode === 'record') {
-            insideUUID = true;
+            store.suppressEntropy = true;
             try {
               const v = originals.randomUUID();
               tapOut(store, 'uuid', 'crypto.randomUUID', v);
               return v;
             } finally {
-              insideUUID = false;
+              store.suppressEntropy = false;
             }
           }
           return takeTap(store, 'uuid', 'crypto.randomUUID');
@@ -90,7 +93,7 @@ export function createFlightBox() {
       const method = (init?.method ?? 'GET').toUpperCase();
       const label = `${method} ${url}`;
       if (store.mode === 'record') {
-        insideFetch = true;
+        store.suppressEntropy = true;
         try {
           const res = await originals.fetch(input, init);
           const text = (await res.text()).slice(0, MAX_BODY_BYTES);
@@ -98,7 +101,7 @@ export function createFlightBox() {
           tapOut(store, 'http', label, { status: res.status, headers, body: text });
           return new Response(text, { status: res.status, headers });
         } finally {
-          insideFetch = false;
+          store.suppressEntropy = false;
         }
       }
       const rec = takeTap(store, 'http', label);

package/src/generator/express.js

@@ -7,10 +7,11 @@ import { parse } from '@babel/parser';
 import { toolNameFor } from '../parser/express.js';
 import { carryOverManifest, defaultSpardingMemory, ensureSpardaKey } from './manifest.js';
 import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+import { makeInjectionMarkers } from './injection.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const MARK_START = '// >>> sparda-injection (do not edit this block) >>>';
-const MARK_END = '// <<< sparda-injection <<<';
+const { MARK_START, MARK_END, stripForReinit, stripForRemoval } =
+  makeInjectionMarkers('//');
 
 export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
   const taken = new Set([
@@ -115,6 +116,12 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
       '__FS_IMPORT__',
       isESM ? "import spardaFs from 'node:fs';" : "const spardaFs = require('node:fs');",
     )
+    .replace(
+      '__CRYPTO_IMPORT__',
+      isESM
+        ? "import spardaCrypto from 'node:crypto';"
+        : "const spardaCrypto = require('node:crypto');",
+    )
     .replace('__PORT__', String(port))
     .replace(/__REQ_TYPE__/g, reqType)
     .replace(/__RES_TYPE__/g, resType)
@@ -188,13 +195,8 @@ function injectIntoEntry({ entryAbs, moduleType, routerFileName, cwd }) {
       ? `import { spardaRouter } from '${importSpec}';`
       : `const { spardaRouter } = require('${importSpec}');`;
 
-  // strip previous injection blocks (idempotence)
-  let body = src;
-  const blockRx = new RegExp(
-    `\\n?${escapeRx(MARK_START)}[\\s\\S]*?${escapeRx(MARK_END)}\\n?`,
-    'g',
-  );
-  body = body.replace(blockRx, '\n');
+  // strip previous injection blocks (idempotence) — shared inverse-safe strip
+  const body = stripForReinit(src);
 
   let ast;
   try {
@@ -276,11 +278,7 @@ export function removeInjection(cwd, manifest) {
     const abs = path.resolve(cwd, relFile);
     if (!fs.existsSync(abs)) continue;
     const src = fs.readFileSync(abs, 'utf8');
-    const blockRx = new RegExp(
-      `\\n?${escapeRx(MARK_START)}[\\s\\S]*?${escapeRx(MARK_END)}`,
-      'g',
-    );
-    const out = src.replace(blockRx, '');
+    const out = stripForRemoval(src);
     try {
       parse(out, { sourceType: 'unambiguous', plugins: ['typescript', 'jsx'] });
       atomicWrite(abs, out);
@@ -307,7 +305,3 @@ export function ensureGitignore(cwd) {
   fs.writeFileSync(gi, `${line}\n`);
   return 'created';
 }
-
-function escapeRx(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}

package/src/generator/fastapi.js

@@ -7,10 +7,11 @@ import { fileURLToPath } from 'node:url';
 import { toolNameFor } from '../parser/express.js';
 import { carryOverManifest, defaultSpardingMemory, ensureSpardaKey } from './manifest.js';
 import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+import { makeInjectionMarkers } from './injection.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const MARK_START = '# >>> sparda-injection (do not edit this block) >>>';
-const MARK_END = '# <<< sparda-injection <<<';
+const { MARK_START, MARK_END, stripForReinit, stripForRemoval } =
+  makeInjectionMarkers('#');
 
 export function generateFastAPI({
   cwd,
@@ -159,13 +160,9 @@ function injectIntoEntry({ entryAbs, cwd, pythonCmd }) {
   // preserve the file's own line endings (Windows checkouts are CRLF)
   const eol = src.includes('\r\n') ? '\r\n' : '\n';
 
-  // strip previous injection blocks (idempotence)
-  let body = src;
-  const blockRx = new RegExp(
-    `\\r?\\n?${escapeRx(MARK_START)}[\\s\\S]*?${escapeRx(MARK_END)}\\r?\\n?`,
-    'g',
-  );
-  body = body.replace(blockRx, eol);
+  // strip previous injection blocks (idempotence) — shared inverse-safe strip.
+  // The block boundaries are normalized back to `eol` by the split/join below.
+  const body = stripForReinit(src);
 
   // Let's find the FastAPI() call assignment to inject right after it
   // ([ \t]*) — NOT (\s*): \s matches newlines and would swallow blank lines/CR into the "indent" (E-007)
@@ -227,11 +224,7 @@ export function removeInjection(cwd, manifest, pythonCmd = 'python') {
     const abs = path.resolve(cwd, relFile);
     if (!fs.existsSync(abs)) continue;
     const src = fs.readFileSync(abs, 'utf8');
-    const blockRx = new RegExp(
-      `\\r?\\n?${escapeRx(MARK_START)}[\\s\\S]*?${escapeRx(MARK_END)}`,
-      'g',
-    );
-    const out = src.replace(blockRx, '');
+    const out = stripForRemoval(src);
 
     if (verifyPythonSyntax(abs, out, pythonCmd)) {
       atomicWrite(abs, out);
@@ -281,7 +274,3 @@ function ensureGitignore(cwd) {
   fs.writeFileSync(gi, `${line}\n`);
   return 'created';
 }
-
-function escapeRx(s) {
-  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}

package/src/generator/injection.js

@@ -0,0 +1,36 @@
+// generator/injection.js — the marked-block contract, shared by every generator that
+// injects a router into a user's entry file. ONE definition of the markers and ONE pair
+// of strip operations, so an inject and its inverse can never drift apart (hard rule #4:
+// `sparda remove` must leave a byte-for-byte clean diff).
+//
+// Two strips, deliberately different — this asymmetry is the whole point:
+//
+//   stripForReinit — removes an existing block AND the newlines hugging it, leaving a
+//     single '\n'. Used on re-init, just before the fresh block is spliced back in.
+//
+//   stripForRemoval — the exact byte inverse of a line-spliced insert. The block is
+//     inserted as whole lines *before* an existing line, so relative to the original it
+//     adds the block text plus ONE trailing newline; the newline that precedes the block
+//     already belonged to the file. So removal consumes the block + its trailing newline
+//     only, never the leading one. (The previous regex consumed the LEADING newline
+//     instead — byte-perfect for a mid-file block, but it left a stray blank line when the
+//     block sat at the very top of the entry file, i.e. `insertAt === 0`.)
+
+export function escapeRx(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function makeInjectionMarkers(commentPrefix) {
+  const MARK_START = `${commentPrefix} >>> sparda-injection (do not edit this block) >>>`;
+  const MARK_END = `${commentPrefix} <<< sparda-injection <<<`;
+  const core = `${escapeRx(MARK_START)}[\\s\\S]*?${escapeRx(MARK_END)}`;
+  return {
+    MARK_START,
+    MARK_END,
+    // re-init: drop the old block and the newlines around it, keep one separator.
+    stripForReinit: (src) =>
+      src.replace(new RegExp(`\\r?\\n?${core}\\r?\\n?`, 'g'), '\n'),
+    // remove: block + its own trailing newline only — the leading newline is the file's.
+    stripForRemoval: (src) => src.replace(new RegExp(`${core}\\r?\\n?`, 'g'), ''),
+  };
+}

package/src/generator/nextjs.js

@@ -1,120 +1,120 @@
-// 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, ensureSpardaKey } 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 = ensureSpardaKey(cwd, prev);
-
-  // .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('__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,
-  };
-  // ADR-022: the disk copy NEVER carries the key — it lives in .sparda/key
-  // (written by ensureSpardaKey above). The in-memory return keeps it for
-  // this process only.
-  const manifestOnDisk = { ...manifest };
-  delete manifestOnDisk.localKey;
-  atomicWrite(
-    path.join(cwd, 'sparda.json'),
-    JSON.stringify(manifestOnDisk, null, 2) + '\n',
-  );
-
-  return {
-    tools,
-    manifest,
-    routerFile: routerRel,
-    injection: { injected: false, manual: null, fileBased: true },
-  };
-}
+// 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, ensureSpardaKey } 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 = ensureSpardaKey(cwd, prev);
+
+  // .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('__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,
+  };
+  // ADR-022: the disk copy NEVER carries the key — it lives in .sparda/key
+  // (written by ensureSpardaKey above). The in-memory return keeps it for
+  // this process only.
+  const manifestOnDisk = { ...manifest };
+  delete manifestOnDisk.localKey;
+  atomicWrite(
+    path.join(cwd, 'sparda.json'),
+    JSON.stringify(manifestOnDisk, null, 2) + '\n',
+  );
+
+  return {
+    tools,
+    manifest,
+    routerFile: routerRel,
+    injection: { injected: false, manual: null, fileBased: true },
+  };
+}