sparda-mcp 0.5.4 → 0.7.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.7.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

@@ -2,6 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { detectStack } from '../detect.js';
+import { buildNegentropy, renderNegentropy } from './negentropy.js';
 
 // Returns { healthy } so the CLI can exit non-zero on any ✗ — scripts/CI can
 // gate on `sparda doctor` (E-012). Informational '·' lines never fail it.
@@ -26,9 +27,12 @@ export async function runDoctor(opts) {
     fail(`  ✗ ${e.message}`);
   }
   const manifest = path.join(opts.cwd, 'sparda.json');
+  let liveStats = null; // captured for the negentropy pass
+  let parsedManifest = null;
   if (fs.existsSync(manifest)) {
     try {
       const m = JSON.parse(fs.readFileSync(manifest, 'utf8'));
+      parsedManifest = m;
       const tools = Object.values(m.tools ?? {});
       console.log(
         `  ✓ sparda.json valid (${tools.length} tools, ${tools.filter((t) => t.enabled).length} enabled)`,
@@ -67,6 +71,7 @@ export async function runDoctor(opts) {
               .then((x) => (x.ok ? x.json() : null))
               .catch(() => null);
             if (s) {
+              liveStats = s;
               const totals = Object.values(s.stats ?? {}).reduce(
                 (a, t) => ({ calls: a.calls + t.calls, errors: a.errors + t.errors }),
                 { calls: 0, errors: 0 },
@@ -90,7 +95,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}`,
           );
@@ -102,5 +107,41 @@ export async function runDoctor(opts) {
   } else {
     console.log('  · sparda.json not found (run `npx sparda-mcp init`)');
   }
+
+  // ── negentropy pass (opt-in: doctor --app) — R3.1, deterministic ─────────
+  if (opts.app && parsedManifest) {
+    console.log('');
+    let currentRoutes = null;
+    try {
+      if (stack?.framework === 'express') {
+        const { parseExpressProject } = await import('../parser/express.js');
+        currentRoutes = parseExpressProject(opts.cwd, stack.entryFile).routes;
+      } else if (stack?.framework === 'nextjs') {
+        const { parseNextProject } = await import('../parser/nextjs.js');
+        currentRoutes = parseNextProject(opts.cwd, stack.entryFile).routes;
+      } else if (stack?.framework === 'fastapi') {
+        const { parseFastAPIProject } = await import('../parser/fastapi.js');
+        currentRoutes = parseFastAPIProject(
+          opts.cwd,
+          stack.entryFile,
+          stack.pythonCmd,
+        ).routes;
+      }
+    } catch {
+      currentRoutes = null; // drift becomes "not measurable", never a guess
+    }
+    const result = buildNegentropy({
+      manifest: parsedManifest,
+      currentRoutes,
+      live: liveStats,
+      detectedPort: stack?.port ?? null,
+      cwd: opts.cwd,
+    });
+    const { lines, failing } = renderNegentropy(result);
+    for (const l of lines) console.log(l);
+    if (failing) healthy = false;
+  } else if (opts.app) {
+    console.log('\n  · negentropy scan skipped — no sparda.json to compare against');
+  }
   return { healthy };
 }

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/negentropy.js

@@ -0,0 +1,234 @@
+// commands/negentropy.js — the Maxwell's demon pass (`doctor --app`, R3.1).
+// Detects rot, deterministically and with zero LLM: schema drift (the code
+// moved, the manifest didn't), stale/unsynced tools, dead current, chronic
+// antigens the immune system keeps diagnosing but nobody fixes, and zombie
+// config. Every finding names its repair. Honest by construction: a gauge
+// that cannot be measured says so instead of guessing.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+// same fingerprint the generators stamp into sparding.toolFingerprints —
+// method|path|params, sha256/8. Divergence = the route's shape changed.
+export function fingerprintFor(tool) {
+  const raw = `${tool.method}|${tool.path}|${JSON.stringify(tool.params ?? [])}`;
+  return crypto.createHash('sha256').update(raw).digest('hex').slice(0, 8);
+}
+
+// routes (parser output) → the tool shape the generators build, keyed the
+// same way, so fingerprints are comparable across init/sync/doctor.
+export function toolShapeOf(route) {
+  return {
+    method: route.method.toUpperCase(),
+    path: route.path,
+    params: route.params ?? [],
+  };
+}
+
+// Pure core. inputs:
+//   manifest       — parsed sparda.json (required)
+//   currentRoutes  — parser output for the code as it is NOW, or null (parse failed)
+//   live           — /mcp/stats payload, or null (host down)
+//   detectedPort   — what detect.js sees now, or null
+//   cwd            — for file existence checks (router present?)
+export function buildNegentropy({ manifest, currentRoutes, live, detectedPort, cwd }) {
+  const findings = [];
+  const add = (kind, severity, title, detail, fix) =>
+    findings.push({ kind, severity, title, detail, fix });
+
+  const tools = manifest.tools ?? {};
+  const byKey = new Map(
+    Object.entries(tools).map(([name, t]) => [`${t.method} ${t.path}`, name]),
+  );
+
+  // ── drift: manifest vs the code as parsed right now ──────────────────────
+  if (currentRoutes) {
+    const currentKeys = new Map(
+      currentRoutes.map((r) => [`${r.method.toUpperCase()} ${r.path}`, r]),
+    );
+    for (const [key, name] of byKey) {
+      if (!currentKeys.has(key)) {
+        add(
+          'drift',
+          'high',
+          `stale tool: ${name}`,
+          `${key} is in sparda.json but no longer exists in the code — the AI sees a ghost route`,
+          'npx sparda-mcp sync',
+        );
+      }
+    }
+    for (const [key] of currentKeys) {
+      if (!byKey.has(key)) {
+        add(
+          'drift',
+          'medium',
+          `unsynced route: ${key}`,
+          'exists in the code but not in sparda.json — invisible to the AI',
+          'npx sparda-mcp sync',
+        );
+      }
+    }
+    const storedFps = manifest.sparding?.toolFingerprints ?? {};
+    for (const [key, name] of byKey) {
+      const route = currentKeys.get(key);
+      if (!route || !storedFps[name]) continue;
+      const fp = fingerprintFor(toolShapeOf(route));
+      if (fp !== storedFps[name]) {
+        add(
+          'drift',
+          'medium',
+          `shape drift: ${name}`,
+          `route structure changed since the last sync (fingerprint ${storedFps[name]} → ${fp}) — params the AI knows may be wrong`,
+          'npx sparda-mcp sync',
+        );
+      }
+    }
+  } else {
+    add(
+      'drift',
+      'info',
+      'drift not measurable',
+      'the current code could not be re-parsed — drift against the manifest is unknown',
+      'fix the parse error reported above, then re-run',
+    );
+  }
+
+  // ── dead current: enabled tools nobody exercised this session ────────────
+  if (live) {
+    const stats = live.stats ?? {};
+    const totalCalls = Object.values(stats).reduce((n, s) => n + (s.calls ?? 0), 0);
+    const uptime = live.uptimeSec ?? 0;
+    if (totalCalls > 0 && uptime >= 60) {
+      for (const [name, t] of Object.entries(tools)) {
+        if (!t.enabled) continue;
+        if ((stats[name]?.calls ?? 0) === 0) {
+          add(
+            'dead',
+            'info',
+            `no current: ${name}`,
+            `${t.method} ${t.path} — zero calls since host start (${uptime}s, ${totalCalls} calls elsewhere). RAM gauge: this session only, not a lifetime verdict`,
+            'if this route is dead in the code too, delete it; if it matters, tell the AI about it (semantic pass)',
+          );
+        }
+      }
+    } else {
+      add(
+        'dead',
+        'info',
+        'current not measurable yet',
+        `host up ${uptime}s with ${totalCalls} total calls — not enough observation to call any route dead`,
+        'let the app run under real usage, then re-run',
+      );
+    }
+    for (const [name, q] of Object.entries(live.quarantine ?? {})) {
+      add(
+        'sick',
+        'high',
+        `quarantined: ${name}`,
+        `the immune system is protecting this route (${q.reason ?? 'repeated 5xx'})`,
+        'fix the underlying failure; quarantine lifts itself (half-open probe)',
+      );
+    }
+  } else {
+    add(
+      'dead',
+      'info',
+      'live gauges unavailable',
+      'host not running — dead-current and quarantine checks need the app up',
+      'start the app, then re-run npx sparda-mcp doctor --app',
+    );
+  }
+
+  // ── chronic antigens: diagnosed again and again, never fixed ─────────────
+  const failures = Object.entries(manifest.sparding?.failures ?? {})
+    .map(([sig, f]) => ({ sig, count: f.count ?? 0, lesson: f.lesson ?? '' }))
+    .filter((f) => f.count >= 3)
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 3);
+  for (const f of failures) {
+    add(
+      'sick',
+      'medium',
+      `recurring failure: ${f.sig}`,
+      `${f.count} occurrences${f.lesson ? ` — lesson on file: ${f.lesson}` : ''}`,
+      f.sig.includes('write_disabled')
+        ? 'the AI keeps hitting a write-safety wall: enable the tool deliberately, or leave it and the block keeps doing its job'
+        : 'the diagnosis exists in the journal; the fix does not — repair the route',
+    );
+  }
+  const antibodies = Object.entries(manifest.immune?.antibodies ?? {})
+    .map(([sig, a]) => ({ sig, hits: a.hits ?? 0, diagnosis: a.diagnosis ?? '' }))
+    .filter((a) => a.hits >= 3)
+    .sort((a, b) => b.hits - a.hits)
+    .slice(0, 3);
+  for (const a of antibodies) {
+    add(
+      'sick',
+      'medium',
+      `chronic antigen: ${a.sig}`,
+      `${a.hits} zero-token diagnoses served — the memory works, the wound stays open${a.diagnosis ? ` (${a.diagnosis.slice(0, 100)})` : ''}`,
+      'apply the cached diagnosis for real; the antibody then goes quiet on its own',
+    );
+  }
+
+  // ── zombie config ─────────────────────────────────────────────────────────
+  if (detectedPort && manifest.port && detectedPort !== manifest.port) {
+    add(
+      'zombie',
+      'high',
+      'port drift',
+      `sparda.json says :${manifest.port} but the app now runs on :${detectedPort} — the bridge and the proxy point at the wrong door`,
+      'npx sparda-mcp sync (re-detects and regenerates)',
+    );
+  }
+  for (const f of manifest.generatedFiles ?? []) {
+    const abs = path.resolve(cwd ?? '.', f);
+    if (!fs.existsSync(abs)) {
+      add(
+        'zombie',
+        'high',
+        'router file missing',
+        `${f} is recorded in sparda.json but absent on disk — the organism has a memory of a body it no longer has`,
+        'npx sparda-mcp init --yes (regenerates; carry-over keeps your state)',
+      );
+    } else if (
+      manifest.localKey &&
+      !fs.readFileSync(abs, 'utf8').includes(manifest.localKey)
+    ) {
+      add(
+        'zombie',
+        'high',
+        'router/manifest key mismatch',
+        `${f} does not carry the manifest's localKey — a stale router from an older init is still wired in`,
+        'npx sparda-mcp init --yes',
+      );
+    }
+  }
+
+  const summary = { drift: 0, dead: 0, sick: 0, zombie: 0 };
+  for (const f of findings) summary[f.kind] += 1;
+  const actionable = findings.filter((f) => f.severity !== 'info');
+  return { findings, summary, actionable: actionable.length };
+}
+
+// terminal rendering, doctor-style: ✗ fails CI, ⚠ warns, · informs
+export function renderNegentropy(result) {
+  const lines = [];
+  let failing = false;
+  lines.push('  Negentropy scan (doctor --app)');
+  if (result.findings.length === 0) {
+    lines.push('  ✓ no rot detected — manifest, code and gauges agree');
+    return { lines, failing };
+  }
+  for (const f of result.findings) {
+    const glyph = f.severity === 'high' ? '✗' : f.severity === 'medium' ? '⚠' : '·';
+    if (f.severity === 'high') failing = true;
+    lines.push(`  ${glyph} [${f.kind}] ${f.title}`);
+    lines.push(`      ${f.detail}`);
+    lines.push(`      → ${f.fix}`);
+  }
+  lines.push(
+    `  ${result.actionable ? '⚠' : '·'} ${result.findings.length} finding(s) — drift ${result.summary.drift} · dead ${result.summary.dead} · sick ${result.summary.sick} · zombie ${result.summary.zombie}`,
+  );
+  return { lines, failing };
+}

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');