sparda-mcp 0.5.4 → 0.7.0

package/src/commands/seed.js

@@ -0,0 +1,282 @@
+// commands/seed.js — the genome (R4.5 lite): everything the organism LEARNED,
+// distilled into a file that can regerminate elsewhere (dev → prod, or a
+// community seed for a popular stack) without re-paying the learning.
+//
+// The closed circle: app → usage → seed → next app. Structure and lessons
+// only — never a value, never a secret, never a security decision:
+//   EXPORTED : semantic descriptions/workflows, immune antibodies, failure
+//              lessons, Labs circuit structure.
+//   NEVER    : localKey, port, policies, per-tool `enabled`, events, paths.
+// An imported seed is UNTRUSTED input: every text field is re-sanitized, the
+// security fields are stripped even if present, and nothing it contains can
+// enable a write or change a policy (hard rule #3 is not negotiable by file).
+import fs from 'node:fs';
+import path from 'node:path';
+import { sanitizeDescription } from '../security/sanitize.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+const SEED_VERSION = 'sparda-seed/v1';
+const MAX_ANTIBODIES = 50; // same cap as the bridge
+const MAX_WORKFLOWS = 20;
+const MAX_CIRCUITS = 30; // same cap as the condenser
+const MAX_FAILURES = 50;
+
+const clean = (raw, fallback = '') => sanitizeDescription(raw, fallback).text;
+
+// ── pure: manifest → seed ──────────────────────────────────────────────────
+
+export function buildSeed(manifest) {
+  const seed = {
+    version: SEED_VERSION,
+    framework: manifest.framework ?? 'unknown',
+    exportedAt: new Date().toISOString(),
+    semantic: { descriptions: {}, workflows: [] },
+    antibodies: {},
+    failures: {},
+    circuits: {},
+  };
+
+  for (const [tool, desc] of Object.entries(manifest.semantic?.descriptions ?? {})) {
+    seed.semantic.descriptions[tool] = clean(desc);
+  }
+  for (const wf of (manifest.semantic?.workflows ?? []).slice(0, MAX_WORKFLOWS)) {
+    seed.semantic.workflows.push({
+      name: clean(wf.name, 'workflow'),
+      description: clean(wf.description),
+      steps: Array.isArray(wf.steps) ? wf.steps.map((s) => clean(s)).slice(0, 20) : [],
+    });
+  }
+  for (const [sig, a] of Object.entries(manifest.immune?.antibodies ?? {}).slice(
+    0,
+    MAX_ANTIBODIES,
+  )) {
+    seed.antibodies[sig] = { diagnosis: clean(a.diagnosis), hits: Number(a.hits) || 0 };
+  }
+  for (const [sig, f] of Object.entries(manifest.sparding?.failures ?? {}).slice(
+    0,
+    MAX_FAILURES,
+  )) {
+    seed.failures[sig] = { count: Number(f.count) || 0, lesson: clean(f.lesson) };
+  }
+  for (const [key, cir] of Object.entries(manifest.labs?.circuits ?? {}).slice(
+    0,
+    MAX_CIRCUITS,
+  )) {
+    // structure only, exactly what the condenser persists — never values
+    seed.circuits[key] = {
+      steps: Array.isArray(cir.steps) ? cir.steps : [],
+      links: Array.isArray(cir.links) ? cir.links : [],
+      seen: Number(cir.seen) || 0,
+      ...(cir.composite
+        ? {
+            composite: {
+              name: clean(cir.composite.name, 'composite'),
+              description: clean(cir.composite.description),
+              source: 'seed',
+            },
+          }
+        : {}),
+    };
+  }
+  return seed;
+}
+
+// ── pure: (manifest, seed) → merged manifest — local knowledge wins ────────
+
+export function mergeSeed(manifest, seed) {
+  if (!seed || seed.version !== SEED_VERSION) {
+    throw Object.assign(new Error('not a SPARDA seed (missing/unknown version field).'), {
+      code: 'USER',
+      hint: `expected "version": "${SEED_VERSION}" — re-export with npx sparda-mcp seed export`,
+    });
+  }
+  const m = structuredClone(manifest);
+  const toolNames = new Set(Object.keys(m.tools ?? {}));
+  const sigToolExists = (sig) => {
+    // signatures are `source|tool|status` — a lesson about a tool this app
+    // does not have is noise, not knowledge
+    const tool = String(sig).split('|')[1];
+    return tool === 'null' || tool === 'undefined' || toolNames.has(tool);
+  };
+  const report = {
+    descriptions: 0,
+    workflows: 0,
+    antibodies: 0,
+    failures: 0,
+    circuits: 0,
+    skipped: 0,
+  };
+
+  m.semantic ??= { descriptions: {}, workflows: [] };
+  m.semantic.descriptions ??= {};
+  m.semantic.workflows ??= [];
+  for (const [tool, desc] of Object.entries(seed.semantic?.descriptions ?? {})) {
+    if (!toolNames.has(tool)) {
+      report.skipped++;
+      continue;
+    }
+    if (m.semantic.descriptions[tool]) continue; // local knowledge wins
+    m.semantic.descriptions[tool] = clean(desc);
+    report.descriptions++;
+  }
+  const wfNames = new Set(m.semantic.workflows.map((w) => w.name));
+  for (const wf of (seed.semantic?.workflows ?? []).slice(0, MAX_WORKFLOWS)) {
+    const name = clean(wf.name, 'workflow');
+    if (wfNames.has(name) || m.semantic.workflows.length >= MAX_WORKFLOWS) continue;
+    wfNames.add(name);
+    m.semantic.workflows.push({
+      name,
+      description: clean(wf.description),
+      steps: Array.isArray(wf.steps) ? wf.steps.map((s) => clean(s)).slice(0, 20) : [],
+      source: 'seed',
+    });
+    report.workflows++;
+  }
+
+  m.immune ??= { antibodies: {} };
+  m.immune.antibodies ??= {};
+  for (const [sig, a] of Object.entries(seed.antibodies ?? {})) {
+    if (!sigToolExists(sig)) {
+      report.skipped++;
+      continue;
+    }
+    if (
+      Object.keys(m.immune.antibodies).length >= MAX_ANTIBODIES &&
+      !m.immune.antibodies[sig]
+    )
+      continue;
+    const existing = m.immune.antibodies[sig];
+    if (existing) {
+      existing.hits = Math.max(Number(existing.hits) || 0, Number(a.hits) || 0);
+    } else {
+      m.immune.antibodies[sig] = {
+        diagnosis: clean(a.diagnosis),
+        hits: Number(a.hits) || 0,
+        firstSeen: new Date().toISOString(),
+        lastSeen: new Date().toISOString(),
+        source: 'seed',
+      };
+      report.antibodies++;
+    }
+  }
+
+  m.sparding ??= {};
+  m.sparding.failures ??= {};
+  for (const [sig, f] of Object.entries(seed.failures ?? {})) {
+    if (!sigToolExists(sig)) {
+      report.skipped++;
+      continue;
+    }
+    const existing = m.sparding.failures[sig];
+    if (existing) {
+      existing.count = Math.max(Number(existing.count) || 0, Number(f.count) || 0);
+    } else if (Object.keys(m.sparding.failures).length < MAX_FAILURES) {
+      m.sparding.failures[sig] = { count: Number(f.count) || 0, lesson: clean(f.lesson) };
+      report.failures++;
+    }
+  }
+
+  m.labs ??= {};
+  m.labs.circuits ??= {};
+  for (const [key, cir] of Object.entries(seed.circuits ?? {})) {
+    if (m.labs.circuits[key]) continue; // local observation wins
+    const stepTools = (Array.isArray(cir.steps) ? cir.steps : [])
+      .map((s) => (typeof s === 'string' ? s : s?.tool))
+      .filter(Boolean);
+    if (!stepTools.every((t) => toolNames.has(t))) {
+      report.skipped++;
+      continue;
+    }
+    if (Object.keys(m.labs.circuits).length >= MAX_CIRCUITS) continue;
+    m.labs.circuits[key] = {
+      steps: cir.steps,
+      links: Array.isArray(cir.links) ? cir.links : [],
+      seen: Number(cir.seen) || 0,
+      firstSeen: new Date().toISOString(),
+      lastSeen: new Date().toISOString(),
+      ...(cir.composite
+        ? {
+            composite: {
+              name: clean(cir.composite.name, 'composite'),
+              description: clean(cir.composite.description),
+              source: 'seed',
+              createdAt: new Date().toISOString(),
+            },
+          }
+        : {}),
+    };
+    report.circuits++;
+  }
+
+  // the file may claim anything — the organism's security is not up for
+  // negotiation: whatever a seed carries, these never cross (hard rule #3/#5)
+  // (localKey, port, policies and per-tool `enabled` were simply never read.)
+  return { manifest: m, report };
+}
+
+// ── the command: seed export [--out f] | seed import <file> ───────────────
+
+export async function runSeed(opts, args) {
+  const sub = args[0];
+  const manifestPath = path.join(opts.cwd, 'sparda.json');
+  if (!fs.existsSync(manifestPath)) {
+    throw Object.assign(new Error('sparda.json not found.'), {
+      code: 'USER',
+      hint: 'run `npx sparda-mcp init` first',
+    });
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  } catch {
+    throw Object.assign(new Error('sparda.json is not valid JSON.'), {
+      code: 'USER',
+      hint: 'restore it from git or re-run `npx sparda-mcp init`',
+    });
+  }
+
+  if (sub === 'export') {
+    const seed = buildSeed(manifest);
+    const out = opts.out ?? 'sparda-seed.json';
+    atomicWrite(path.resolve(opts.cwd, out), JSON.stringify(seed, null, 2) + '\n');
+    console.log(
+      `✓ Seed exported: ${out} — ${Object.keys(seed.antibodies).length} antibodies, ${Object.keys(seed.semantic.descriptions).length} descriptions, ${seed.semantic.workflows.length} workflows, ${Object.keys(seed.circuits).length} circuits, ${Object.keys(seed.failures).length} lessons`,
+    );
+    console.log('  Structure and lessons only. No key, no policy, no value ever leaves.');
+    return { seed };
+  }
+
+  if (sub === 'import') {
+    const file = args[1];
+    if (!file) {
+      throw Object.assign(new Error('missing seed file.'), {
+        code: 'USER',
+        hint: 'usage: npx sparda-mcp seed import <sparda-seed.json>',
+      });
+    }
+    const abs = path.resolve(opts.cwd, file);
+    if (!fs.existsSync(abs)) {
+      throw Object.assign(new Error(`seed file not found: ${file}`), { code: 'USER' });
+    }
+    let seed;
+    try {
+      seed = JSON.parse(fs.readFileSync(abs, 'utf8'));
+    } catch {
+      throw Object.assign(new Error('seed file is not valid JSON.'), { code: 'USER' });
+    }
+    const { manifest: merged, report } = mergeSeed(manifest, seed);
+    atomicWrite(manifestPath, JSON.stringify(merged, null, 2) + '\n');
+    console.log(
+      `✓ Seed germinated into sparda.json — +${report.antibodies} antibodies, +${report.descriptions} descriptions, +${report.workflows} workflows, +${report.circuits} circuits, +${report.failures} lessons (${report.skipped} entries skipped: unknown tools here)`,
+    );
+    console.log(
+      '  Local knowledge always wins; keys, policies and enabled flags were never read.',
+    );
+    return { report };
+  }
+
+  throw Object.assign(new Error(`unknown seed subcommand: ${sub ?? '(none)'}`), {
+    code: 'USER',
+    hint: 'usage: npx sparda-mcp seed export [--out file] | seed import <file>',
+  });
+}

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

@@ -20,7 +20,9 @@ const opts = {
   probe: flags.has('--probe'),
   html: flags.has('--html'),
   json: flags.has('--json'),
+  app: flags.has('--app'),
   port: getOpt('port', null),
+  out: getOpt('out', null),
   cwd: process.cwd(),
 };
 
@@ -67,6 +69,14 @@ try {
       await runReport(opts);
       break;
     }
+    case 'seed': {
+      const { runSeed } = await import('./commands/seed.js');
+      await runSeed(
+        opts,
+        rest.filter((a) => !a.startsWith('--')),
+      );
+      break;
+    }
     default:
       console.log(`SPARDA v${VERSION} — Turn any codebase into an MCP server.
 
@@ -77,8 +87,9 @@ Usage:
   npx sparda-mcp sync      Re-sync the router after route changes (no prompts)
   npx sparda-mcp hook      Install the git sentinel (auto-sync after commits)
   npx sparda-mcp remove    Remove SPARDA from this project (clean git diff)
-  npx sparda-mcp doctor    Diagnose your setup
+  npx sparda-mcp doctor    Diagnose your setup (--app: negentropy scan — drift, dead routes, rot)
   npx sparda-mcp report    The black box: what AI agents did to this app
+  npx sparda-mcp seed      Export/import the learned genome (export [--out f] | import <f>)
 
 Flags: --yes (skip prompts)  --port <n>  --quiet  --verbose
        --probe (init: also run the app to discover dynamic routes the AST missed)