sparda-mcp 0.8.1 → 0.9.0

package/README.md

@@ -6,23 +6,27 @@
 
 <br/>
 
-**Your AI can write code. It still can't operate your app.**
+**Compile your backend into a deterministic behavior runtime.**
 
-Claude, Cursor & friends read your *files* — not your *running product*. They can
-refactor a controller, but they can't create an order, fetch a real user, or see why
-production is failing. And giving an AI real access to your API usually means: write
-an OpenAPI spec, build an MCP server, host it, secure it, keep it in sync with every
-route change — and pray it never `DELETE`s the wrong row. Days of glue code, per
-project, forever drifting.
+For twenty years, software communicated via APIs. Then AI agents arrived. The industry's response was simply to expose more endpoints (MCP). But an agent doesn't understand your application; it only sees a list of disconnected tools. That is enough for a human, but not for an autonomous machine.
 
-SPARDA deletes that work:
+SPARDA analyzes your Express, FastAPI, or Next.js application, extracts its behavior, and compiles it into a **SPARDA Behavior Graph (SBG)**. 
+
+This graph acts as a local, deterministic runtime that powers:
+* **MCP Server Integration**: Exposing your endpoints to AI clients dynamically.
+* **SPARDA Twin**: An executable, offline simulation clone of your backend for safe agent testing.
+* **SPARDA Immune**: Real-time graph-based anomaly defense, latency alerts, and auto-quarantine.
+* **SPARDA Evolution**: Statically inferred grammar mapping and in-memory workflow optimization.
+
+All executed 100% locally, with zero runtime dependencies and zero cloud connection.
 
 ```bash
-npx sparda-mcp init   # scan your Express/FastAPI app, inject the MCP router — 3 minutes
-npx sparda-mcp dev    # connect Claude Desktop / Claude Code. Done.
+npx sparda-mcp init   # Scan your app, compile the UBG, inject the SPARDA Runtime
+npx sparda-mcp dev    # Connect Claude Desktop / Cursor over stdio
 ```
 
-No OpenAPI spec. No account. No API key. No server to host.
+No OpenAPI spec to write. No cloud account. No API key. No server to host.
+Exposing raw APIs to AI is the old way. SPARDA compiles the whole system's behavior.
 
 ## Quickstart
 
@@ -169,6 +173,7 @@ runtime, so the guidance never goes stale.
 
 ## Security posture (honest)
 - 4 runtime dependencies, exact-pinned.
+- **Dynamic Local Key Resolution.** The generated router contains no baked secrets. It resolves authorization keys at runtime from the `SPARDA_LOCAL_KEY` environment variable or the local gitignored `.sparda/key` file, and fails closed (503) when neither is found. For custom production or staging setups, you can override this behavior by exposing `SPARDA_LOCAL_KEY` in your environment.
 - Local key on every router call; self-reference loop protection; 30s timeouts; 8 KB output truncation.
 - AST-positioned injection with backup and post-injection re-parse; `npx sparda-mcp remove` leaves a clean git diff.
 - Persistence is **value-free**: SPARDA records structure (tool names, field names, fingerprints), never your payloads.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparda-mcp",
-  "version": "0.8.1",
+  "version": "0.9.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/ubg.js

@@ -0,0 +1,71 @@
+// commands/ubg.js — compile the codebase to its Unified Behavior Graph.
+// The UBG is the IR every future SPARDA tool reads (time-travel debuggers,
+// deploy provers, state-machine runtimes): compile once here, write passes
+// there. Artifact: .sparda/ubg.json — regenerable, deterministic, never
+// committed. `--json` prints the raw graph, `--out <file>` redirects it.
+import { compileUBG } from '../ubg/compile.js';
+
+export async function runUbg(opts) {
+  const { report, json, outPath } = compileUBG(opts.cwd, {
+    write: true,
+    out: opts.out,
+  });
+
+  if (opts.json) {
+    console.log(json);
+    return { report };
+  }
+
+  const { counts } = report;
+  console.log(
+    `✓ UBG compiled: ${rel(outPath, opts.cwd)} — ${counts.totalNodes} nodes, ${counts.totalEdges} edges`,
+  );
+  console.log(
+    `  ${report.framework} · ${report.routes} routes · ${report.tables} SQL tables`,
+  );
+  console.log(`  Nodes: ${fmtCounts(counts.nodes)}`);
+  console.log(`  Edges: ${fmtCounts(counts.edges)}`);
+
+  for (const p of report.passes) {
+    if (p.pass === 'DeadPathElimination' && p.removed)
+      console.log(`  ${p.pass}: ${p.removed} dead node(s) removed`);
+    else if (p.pass === 'StateMinimization' && p.merged)
+      console.log(`  ${p.pass}: ${p.merged} logic block(s) merged`);
+    else if (p.pass === 'TypePropagation' && (p.resolved || p.entrypointsTyped))
+      console.log(
+        `  ${p.pass}: ${p.entrypointsTyped} entrypoint return schema(s), ${p.resolved} type(s) resolved`,
+      );
+    else if (p.pass === 'EffectAlgebra' && p.classified)
+      console.log(
+        `  ${p.pass}: ${p.classified} effect(s) classified, ${p.observable} observable`,
+      );
+    else if (p.pass === 'ConsistencyDomains' && Object.keys(p.domains ?? {}).length) {
+      const names = Object.keys(p.domains).sort();
+      console.log(
+        `  ${p.pass}: ${names.length} domain(s) — ${names.join(', ')}${p.cycles.length ? ` (⚠ FK cycle: ${p.cycles.join(', ')})` : ''}`,
+      );
+    }
+  }
+
+  if (report.link.inferredTables.length)
+    console.log(
+      `  ⚠ tables referenced in code but absent from .sql schemas: ${report.link.inferredTables.join(', ')}`,
+    );
+  if (report.skipped.length) {
+    console.log(`  · ${report.skipped.length} construct(s) out of static reach:`);
+    for (const s of report.skipped.slice(0, opts.verbose ? 100 : 5))
+      console.log(`    - ${s.reason}${s.file ? ` (${s.file})` : ''}`);
+    if (!opts.verbose && report.skipped.length > 5)
+      console.log(`    … ${report.skipped.length - 5} more (--verbose)`);
+  }
+  return { report };
+}
+
+const fmtCounts = (obj) =>
+  Object.entries(obj)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([k, v]) => `${k} ${v}`)
+    .join(' · ');
+
+const rel = (abs, cwd) =>
+  abs.startsWith(cwd) ? abs.slice(cwd.length + 1).replaceAll('\\', '/') : abs;

package/src/index.js

@@ -94,6 +94,11 @@ try {
       await runEvolve(opts);
       break;
     }
+    case 'ubg': {
+      const { runUbg } = await import('./commands/ubg.js');
+      await runUbg(opts);
+      break;
+    }
     default:
       console.log(`SPARDA v${VERSION} — Turn any codebase into an MCP server.
 
@@ -110,6 +115,7 @@ Usage:
   npx sparda-mcp twin      The living mock (--learn from the live app, then serve the ghost)
   npx sparda-mcp grammar   Which call sequences mean something (observed + hypotheses)
   npx sparda-mcp evolve    Trial hypothesis chains against the twin; survivors become suggestions
+  npx sparda-mcp ubg       Compile the codebase to its Unified Behavior Graph (.sparda/ubg.json)
 
 Flags: --yes (skip prompts)  --port <n>  --quiet  --verbose
        --probe (init: also run the app to discover dynamic routes the AST missed)

package/src/ubg/compile.js

@@ -0,0 +1,84 @@
+// ubg/compile.js — the orchestrator: codebase in, UBG out.
+// detect → extract (framework routes + SQL schemas) → translate → link →
+// optimize → canonicalize. 100% local, zero network, zero LLM, deterministic:
+// the only inputs are the bytes of the source tree, the only output is the
+// graph plus an honest report of everything the static eye could NOT see.
+import { detectStack } from '../detect.js';
+import { clearModuleCache } from './extract.js';
+import { extractExpress } from './express.js';
+import { extractNext } from './nextjs.js';
+import { extractFastAPI } from './fastapi.js';
+import { parseSqlSchemas } from './sql.js';
+import { translate } from './translate.js';
+import { linkDataFlow } from './link.js';
+import { optimize } from './pipeline.js';
+import { validateGraph } from './schema.js';
+import { serializeGraph, sourceHashOf, writeGraph } from './serialize.js';
+
+export function compileUBG(
+  cwd,
+  { write = true, out = null, optimizePasses = true } = {},
+) {
+  clearModuleCache(); // each compile run parses fresh — no stale-file ghosts
+
+  const stack = detectStack(cwd);
+  const extractors = {
+    express: () => extractExpress(cwd, stack.entryFile),
+    nextjs: () => extractNext(cwd, stack.entryFile),
+    fastapi: () => extractFastAPI(cwd, stack.entryFile, stack.pythonCmd),
+  };
+  if (!extractors[stack.framework]) {
+    throw Object.assign(
+      new Error(`UBG compiler has no lowering for ${stack.framework} yet.`),
+      { code: 'USER' },
+    );
+  }
+  const extracted = extractors[stack.framework]();
+
+  const sql = parseSqlSchemas(cwd);
+
+  const graph = translate({
+    framework: stack.framework,
+    routes: extracted.routes,
+    globalMiddlewares: extracted.globalMiddlewares,
+    helpers: extracted.helpers,
+    tables: sql.tables,
+  });
+  validateGraph(graph);
+
+  const linkReport = linkDataFlow(graph);
+  validateGraph(graph);
+
+  const passReports = optimizePasses ? optimize(graph) : [];
+
+  graph.meta = {
+    framework: stack.framework,
+    entry: stack.entryFile,
+    sourceHash: sourceHashOf(cwd, [
+      ...extracted.scannedFiles,
+      ...sql.tables.map((t) => t.sourceFile),
+    ]),
+  };
+
+  const report = {
+    framework: stack.framework,
+    entry: stack.entryFile,
+    routes: extracted.routes.length,
+    tables: sql.tables.length,
+    link: linkReport,
+    passes: passReports,
+    skipped: [...extracted.skipped, ...sql.skipped],
+    counts: countGraph(graph),
+  };
+
+  const outPath = write ? writeGraph(graph, cwd, out) : null;
+  return { graph, json: serializeGraph(graph), report, outPath };
+}
+
+function countGraph(graph) {
+  const nodes = {};
+  const edges = {};
+  for (const n of graph.nodes.values()) nodes[n.kind] = (nodes[n.kind] ?? 0) + 1;
+  for (const e of graph.edges) edges[e.kind] = (edges[e.kind] ?? 0) + 1;
+  return { nodes, edges, totalNodes: graph.nodes.size, totalEdges: graph.edges.length };
+}

package/src/ubg/express.js

@@ -0,0 +1,258 @@
+// ubg/express.js — Express codebase → route facts for the UBG translator.
+// Richer than parser/express.js (which only needs tool signatures): here the
+// FULL handler chain matters — every middleware between path and handler
+// becomes a graph node, and identifier handlers are resolved to their function
+// bodies (same file, then relative imports) so the microscope can scan them.
+// Depth stays bounded like the v0 parser: entry file + mounted routers.
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseModule, resolveRelImport } from './extract.js';
+
+const HTTP = new Set(['get', 'post', 'put', 'patch', 'delete']);
+
+// → { routes, globalMiddlewares, helpers, skipped, scannedFiles }
+export function extractExpress(cwd, entryFile) {
+  const routes = [];
+  const globalMiddlewares = []; // app.use(fn) — applies to every route
+  const helpers = []; // top-level functions of scanned files (dead-path candidates)
+  const skipped = [];
+  const scannedFiles = [];
+  const visited = new Set();
+  const mounts = [];
+
+  scanFile(path.resolve(cwd, entryFile), '', 0);
+  for (const m of [...mounts]) {
+    if (m.file && fs.existsSync(m.file)) scanFile(m.file, m.prefix, 1);
+    else if (!m.file)
+      skipped.push({
+        reason: `router "${m.ident}" mounted at ${m.prefix} — source file not resolved`,
+        file: m.fromFile,
+      });
+  }
+
+  routes.sort((a, b) => a.path.localeCompare(b.path) || a.method.localeCompare(b.method));
+  return { routes, globalMiddlewares, helpers, skipped, scannedFiles };
+
+  function scanFile(absFile, prefix, depth) {
+    const key = `${absFile}::${prefix}`;
+    if (depth > 2 || visited.has(key)) return;
+    visited.add(key);
+
+    const mod = parseModule(absFile);
+    const relFile = rel(absFile);
+    if (mod.error) {
+      skipped.push({ reason: `${mod.error} in ${relFile}`, file: relFile });
+      return;
+    }
+    scannedFiles.push(relFile);
+
+    // every top-level function is a potential dead-path candidate
+    for (const [name, f] of mod.functions) {
+      helpers.push({ name, sourceFile: relFile, sourceLine: f.line, fn: f.node });
+    }
+
+    const appVars = new Set();
+    const routerVars = new Set();
+    for (const node of mod.ast.program.body) collectAppVars(node, appVars, routerVars);
+
+    walkStatements(mod.ast.program.body);
+
+    function walkStatements(body) {
+      for (const stmt of body) {
+        const expr =
+          stmt.type === 'ExpressionStatement' && stmt.expression.type === 'CallExpression'
+            ? stmt.expression
+            : null;
+        if (!expr) continue;
+        const callee = expr.callee;
+        if (callee.type !== 'MemberExpression' || callee.property.type !== 'Identifier')
+          continue;
+        const objName = callee.object.type === 'Identifier' ? callee.object.name : null;
+        if (!objName || (!appVars.has(objName) && !routerVars.has(objName))) continue;
+        const method = callee.property.name;
+        const args = expr.arguments;
+
+        if (method === 'use') {
+          handleUse(args, stmt);
+          continue;
+        }
+        if (!HTTP.has(method)) continue;
+
+        const pathArg = args[0];
+        if (!pathArg || pathArg.type !== 'StringLiteral') {
+          skipped.push({
+            reason: `dynamic path on ${method.toUpperCase()} (non-literal first arg)`,
+            file: relFile,
+            line: expr.loc?.start.line,
+          });
+          continue;
+        }
+        const fullPath = joinPath(prefix, pathArg.value);
+
+        const chain = [];
+        for (let i = 1; i < args.length; i++) {
+          const resolved = resolveCallable(args[i], mod, absFile, relFile);
+          if (!resolved) {
+            skipped.push({
+              reason: `unresolvable handler arg #${i} on ${method.toUpperCase()} ${fullPath}`,
+              file: relFile,
+              line: args[i].loc?.start.line,
+            });
+            continue;
+          }
+          resolved.role = i === args.length - 1 ? 'handler' : 'middleware';
+          chain.push(resolved);
+        }
+
+        const description = (stmt.leadingComments ?? expr.leadingComments ?? [])
+          .map((c) =>
+            c.value
+              .replace(/^\*+/gm, '')
+              .replace(/^\s*\*\s?/gm, '')
+              .trim(),
+          )
+          .filter(Boolean)
+          .join(' ')
+          .slice(0, 400);
+
+        routes.push({
+          method,
+          path: fullPath,
+          sourceFile: relFile,
+          sourceLine: expr.loc?.start.line ?? 0,
+          params: pathParamsOf(fullPath),
+          chain,
+          description,
+        });
+      }
+    }
+
+    function handleUse(args, stmt) {
+      if (!args.length) return;
+      // app.use('/prefix', router) → mount for second pass
+      if (args[0].type === 'StringLiteral' && args[1]?.type === 'Identifier') {
+        mounts.push({
+          prefix: joinPath(prefix, args[0].value),
+          file: mod.imports.get(args[1].name) ?? null,
+          ident: args[1].name,
+          fromFile: relFile,
+        });
+        return;
+      }
+      // app.use(fn) / app.use(ident) at depth 0 → global middleware
+      if (depth === 0) {
+        for (const a of args) {
+          if (a.type === 'StringLiteral') continue;
+          // express.json() & friends: framework plumbing, not app behavior
+          if (
+            a.type === 'CallExpression' &&
+            ((a.callee.type === 'MemberExpression' &&
+              a.callee.object.type === 'Identifier' &&
+              a.callee.object.name === 'express') ||
+              (a.callee.type === 'Identifier' &&
+                /^(cors|helmet|morgan|compression|cookieparser|bodyparser)$/i.test(
+                  a.callee.name,
+                )))
+          )
+            continue;
+          const resolved = resolveCallable(a, mod, absFile, relFile);
+          if (resolved) {
+            resolved.role = 'middleware';
+            globalMiddlewares.push(resolved);
+          } else if (a.type !== 'CallExpression') {
+            skipped.push({
+              reason: `unresolvable app.use() argument`,
+              file: relFile,
+              line: stmt.loc?.start.line,
+            });
+          }
+        }
+      }
+    }
+  }
+
+  // Identifier → function body in this module, else in the module it was
+  // imported from. Inline functions pass through as-is.
+  function resolveCallable(arg, mod, absFile, relFile) {
+    if (arg.type === 'ArrowFunctionExpression' || arg.type === 'FunctionExpression') {
+      return {
+        name: arg.id?.name ?? 'anonymous',
+        sourceFile: relFile,
+        sourceLine: arg.loc?.start.line ?? 0,
+        fn: arg,
+      };
+    }
+    if (arg.type !== 'Identifier') return null;
+
+    const local = mod.functions.get(arg.name);
+    if (local) {
+      return {
+        name: arg.name,
+        sourceFile: relFile,
+        sourceLine: local.line,
+        fn: local.node,
+      };
+    }
+    const importedFrom = mod.imports.get(arg.name);
+    if (importedFrom) {
+      const target = parseModule(importedFrom);
+      const fn = target.functions.get(arg.name) ?? target.functions.get('default');
+      if (fn) {
+        const fromRel = rel(importedFrom);
+        if (!scannedFiles.includes(fromRel)) {
+          scannedFiles.push(fromRel);
+          for (const [name, f] of target.functions)
+            helpers.push({
+              name,
+              sourceFile: fromRel,
+              sourceLine: f.line,
+              fn: f.node,
+            });
+        }
+        return { name: arg.name, sourceFile: fromRel, sourceLine: fn.line, fn: fn.node };
+      }
+    }
+    // known but bodyless — node exists, microscope stays blind
+    return {
+      name: arg.name,
+      sourceFile: relFile,
+      sourceLine: arg.loc?.start.line ?? 0,
+      fn: null,
+    };
+  }
+
+  function rel(abs) {
+    return path.relative(cwd, abs).split(path.sep).join('/');
+  }
+}
+
+function collectAppVars(node, appVars, routerVars) {
+  if (node.type === 'ExportNamedDeclaration' && node.declaration)
+    return collectAppVars(node.declaration, appVars, routerVars);
+  if (node.type !== 'VariableDeclaration') return;
+  for (const d of node.declarations) {
+    if (d.id?.type !== 'Identifier' || d.init?.type !== 'CallExpression') continue;
+    const callee = d.init.callee;
+    if (callee.type === 'Identifier' && callee.name === 'express') appVars.add(d.id.name);
+    if (callee.type === 'Identifier' && callee.name === 'Router')
+      routerVars.add(d.id.name);
+    if (callee.type === 'MemberExpression' && callee.property?.name === 'Router')
+      routerVars.add(d.id.name);
+  }
+}
+
+function pathParamsOf(fullPath) {
+  return [...fullPath.matchAll(/:(\w+)/g)].map((m) => ({
+    name: m[1],
+    in: 'path',
+    type: 'string',
+    required: true,
+  }));
+}
+
+function joinPath(prefix, p) {
+  const joined = `${prefix ?? ''}${p === '/' && prefix ? '' : p}`.replace(/\/{2,}/g, '/');
+  return joined.startsWith('/') ? joined : `/${joined}`;
+}
+
+export { resolveRelImport };