sparda-mcp 0.12.0 → 0.13.1

package/README.md

@@ -6,6 +6,10 @@
 
 <br/>
 
+> 🇫🇷 **Français** : Pour comprendre SPARDA en 10 minutes (douleur, architecture, vision), lisez le document du fondateur : [SPARDA-EXPLIQUE.md](docs/SPARDA-EXPLIQUE.md).
+
+---
+
 **Compile your backend into a deterministic behavior runtime.**
 
 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.

package/SKILL.md

@@ -137,6 +137,10 @@ Writes are **disabled by default**. The protocol is not optional:
   manifest validity, the semantic/immune cache, host reachability, and quarantine;
   it exits non-zero so it can gate CI.
 - **Formal Deployment Proof** → `sparda apocalypse` reads the compiled graph (`ubg.json`) and proves five correctness obligations: catches unguarded mutations, non-atomic aggregate writes, unvalidated writes to constrained tables, uncompensated observable effects, and aggregate root bypasses. Run `sparda apocalypse --save-baseline` to store the reference graph; subsequent runs diff against the baseline to catch dropped guards, dropped SQL invariants, or grown blast radiuses.
+- **OpenAPI Ingestion** → Run `sparda ubg --openapi <openapi_spec.json_or_yaml>` to compile any non-JS/Python backend (Go, Java, Rails, Laravel, .NET) into a SPARDA Behavior Graph by mapping security schemes into guards and request/response structures.
+- **Executing the Graph (No code mock)** → Run `sparda mirror` to host a mock HTTP simulation server directly from `ubg.json` without any backend code. Enforces authentication guards, returns typed responses, and acts as a contract sandbox.
+- **Exporting OpenAPI 3.1 Spec** → Run `sparda openapi` to generate a valid, deterministic OpenAPI 3.1 spec dynamically from the compiled behavior graph.
+- **Self-Verification** → Run `sparda verify` to test the compiler's own invariants (byte-determinism, soundness, and spec round-trip) to guarantee trust.
 - **Clone learning / Transfer sémantique** → Use `sparda seed export` to package your app's descriptions, workflows, and antibodies. Then `sparda seed import --germinate` in another clone to import the structure and germinate simulated twin instances.
 - **Learn exemplars** → Start your live app and run `sparda twin --learn` to fetch actual response data and construct `.sparda/twin.json` locally.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "sparda-mcp",
-  "version": "0.12.0",
+  "version": "0.13.1",
   "mcpName": "io.github.zyx77550/sparda-mcp",
-  "description": "Turn any codebase into an MCP server with one command. Express & FastAPI → Claude-ready in 3 minutes.",
+  "description": "Compile backends to behavior graphs. Statically prove security, simulate APIs, and replay bugs.",
   "type": "module",
   "repository": {
     "type": "git",

package/src/commands/heal.js

@@ -0,0 +1,182 @@
+// commands/heal.js — the closed loop as one gesture.
+//   sparda heal <flightId>                    diagnose + write the fix brief
+//   sparda heal <flightId> --agent "claude -p"   let an AI attempt the fix, then gate
+//   sparda heal <flightId> --check [--expect '{"status":200}']   gate a fix (human or AI)
+// The gate is the product: lenient replay against the recorded taps must meet
+// the EXPECTATION (not the recorded bug), compiler laws must hold (verify),
+// and apocalypse must find no new critical/high and no removed guard. SPARDA
+// orchestrates and proves — whoever writes the fix, the machine judges it.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { loadFlight } from '../flight/format.js';
+import { getFlightBox } from '../flight/box.js';
+import { replayFlight } from '../flight/replayer.js';
+import { evaluateHealing, buildBrief } from '../flight/heal.js';
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import { checkGraph, diffGraphs, verdictOf } from '../ubg/apocalypse.js';
+import { verifyProject } from '../ubg/verify.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+const err = (message, hint) => Object.assign(new Error(message), { code: 'USER', hint });
+
+export async function runHeal(opts, args) {
+  const id = args.filter((a) => !a.startsWith('--'))[0];
+  if (!id) throw err('flight id required', 'run `sparda timeless` to list flights');
+  const flight = loadFlight(opts.cwd, id);
+  const healDir = path.join(opts.cwd, '.sparda', 'heal', id);
+  fs.mkdirSync(healDir, { recursive: true });
+
+  if (opts.check) return gate(opts, id, flight, healDir);
+
+  // ---- phase 1: diagnose + brief -----------------------------------------
+  const compiled = compileUBG(opts.cwd, { write: false });
+  const graph = canonicalizeGraph(compiled.graph);
+  const app = await loadAppFor(opts.cwd);
+  const box = getFlightBox();
+  box.arm();
+  let strict;
+  try {
+    strict = await replayFlight(app, flight, box);
+  } finally {
+    box.disarm();
+  }
+
+  // freeze the pre-fix graph: the gate diffs the fixed tree against THIS
+  atomicWrite(path.join(healDir, 'baseline.json'), JSON.stringify(graph, null, 2) + '\n');
+  const brief = buildBrief(flight, graph, strict, id);
+  const briefPath = path.join(healDir, 'BRIEF.md');
+  atomicWrite(briefPath, brief);
+
+  console.log(`HEAL — flight ${id}: ${flight.request.method} ${flight.request.url}`);
+  console.log(
+    strict.match
+      ? '  ✓ bug reproduced byte-identically against current code'
+      : '  ⚠ current code already answers differently — the bug may be partially fixed',
+  );
+  console.log(`  ✓ brief written: .sparda/heal/${id}/BRIEF.md`);
+  console.log(`  ✓ pre-fix graph frozen: .sparda/heal/${id}/baseline.json`);
+
+  if (opts.agent) {
+    console.log(`  ▸ handing the brief to: ${opts.agent}`);
+    const run = spawnSync(opts.agent, {
+      input: brief,
+      shell: true,
+      cwd: opts.cwd,
+      encoding: 'utf8',
+      timeout: 600_000,
+    });
+    if (run.status !== 0)
+      throw err(`agent exited ${run.status}`, (run.stderr ?? '').slice(0, 200));
+    console.log('  ✓ agent finished — gating the fix now');
+    return gate(opts, id, flight, healDir);
+  }
+
+  console.log('\nNext: apply the fix (yourself or an agent), then:');
+  console.log(`  sparda heal ${id} --check --expect '{"status":200}'`);
+  return { brief: briefPath };
+}
+
+// ---- phase 2: the gate ----------------------------------------------------
+async function gate(opts, id, flight, healDir) {
+  const expectation = opts.expect ? JSON.parse(opts.expect) : null;
+
+  // 1. lenient replay: recorded inputs, candidate code, expected outcome
+  const app = await loadAppFor(opts.cwd);
+  const box = getFlightBox();
+  box.arm();
+  let replay;
+  try {
+    replay = await replayFlight(app, flight, box, { lenient: true });
+  } finally {
+    box.disarm();
+  }
+  const healing = evaluateHealing(flight, replay, expectation);
+
+  // 2. compiler laws still hold on the fixed tree
+  const laws = verifyProject(opts.cwd);
+
+  // 3. apocalypse: no new critical/high, nothing protected got removed
+  const fixedGraph = canonicalizeGraph(compileUBG(opts.cwd, { write: false }).graph);
+  const staticFindings = checkGraph(fixedGraph).findings;
+  let regressions = [];
+  const baselinePath = path.join(healDir, 'baseline.json');
+  if (fs.existsSync(baselinePath)) {
+    const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+    regressions = diffGraphs(baseline, fixedGraph).findings;
+    // pre-existing static findings are not the fix's fault — only NEW ones gate
+    const before = new Set(
+      checkGraph(baseline).findings.map((f) => `${f.rule}:${f.entrypoint}`),
+    );
+    regressions = [
+      ...regressions,
+      ...staticFindings.filter((f) => !before.has(`${f.rule}:${f.entrypoint}`)),
+    ];
+  } else {
+    regressions = staticFindings;
+  }
+  const apocalypse = verdictOf(regressions);
+
+  // ---- verdict -------------------------------------------------------------
+  console.log(`HEAL GATE — flight ${id}`);
+  console.log(
+    `  ${healing.healed ? '✓' : '✗'} behavior: ${healing.healed ? `bug gone (${healing.before.status} → ${healing.after.status})` : healing.reasons.join('; ')}`,
+  );
+  if (healing.relabels.length)
+    console.log(
+      `    · ${healing.relabels.length} tap(s) relabeled by the fix (allowed): ${healing.relabels.map((r) => r.kind).join(', ')}`,
+    );
+  console.log(`  ${laws.ok ? '✓' : '✗'} compiler laws: ${laws.passed}/${laws.total}`);
+  console.log(
+    `  ${apocalypse.safe ? '✓' : '✗'} apocalypse: ${regressions.length === 0 ? 'no new findings' : regressions.map((f) => f.rule).join(', ')}`,
+  );
+
+  const ok = healing.healed && laws.ok && apocalypse.safe;
+  const report = { id, healed: healing, laws: laws.checks, regressions, ok };
+  atomicWrite(path.join(healDir, 'report.json'), JSON.stringify(report, null, 2) + '\n');
+
+  if (ok) {
+    console.log(
+      `✓ HEALED & PROVEN — same recorded inputs, correct output, zero law broken, zero protection lost. Ship it.`,
+    );
+  } else {
+    console.log(
+      '✗ NOT PROVEN — the gate stays closed. Details: .sparda/heal/' +
+        id +
+        '/report.json',
+    );
+    process.exitCode = 1;
+  }
+  return report;
+}
+
+// same entry-loading discipline as timeless replay (listen suppressed)
+async function loadAppFor(cwd) {
+  const { detectStack } = await import('../detect.js');
+  const http = await import('node:http');
+  const { pathToFileURL } = await import('node:url');
+  const stack = detectStack(cwd);
+  if (stack.framework !== 'express')
+    throw err('heal supports Express apps in v1', 'FastAPI replay is a later round');
+  const origListen = http.default.Server.prototype.listen;
+  http.default.Server.prototype.listen = function suppressed(...a) {
+    const cb = a.find((x) => typeof x === 'function');
+    if (cb) setImmediate(cb);
+    return this;
+  };
+  try {
+    // cache-bust: the gate must load the FIXED code, not the pre-fix module
+    const entry = pathToFileURL(path.resolve(cwd, stack.entryFile)).href;
+    const mod = await import(`${entry}?sparda-heal=${Date.now()}`);
+    const app = mod.default ?? mod;
+    if (typeof app !== 'function')
+      throw err(
+        'the entry file does not export the Express app',
+        'add `module.exports = app`',
+      );
+    return app;
+  } finally {
+    http.default.Server.prototype.listen = origListen;
+  }
+}

package/src/flight/box.js

@@ -7,8 +7,14 @@
 // context is untouched (AsyncLocalStorage decides), so arming the box in
 // production changes nothing for non-instrumented paths.
 import { AsyncLocalStorage } from 'node:async_hooks';
+import crypto from 'node:crypto';
 import { saveFlight } from './format.js';
 
+if (typeof globalThis.crypto === 'undefined' || !globalThis.crypto.randomUUID) {
+  // Polyfill global crypto for Node 18 and test runner environments
+  globalThis.crypto = crypto;
+}
+
 const MAX_BODY_BYTES = 262144; // 256 KB per recorded http body — bounded flights
 
 export class FlightDivergence extends Error {
@@ -23,6 +29,8 @@ export function createFlightBox() {
   const als = new AsyncLocalStorage();
   const originals = {};
   let armed = false;
+  let insideUUID = false;
+  let insideFetch = false;
 
   function arm() {
     if (armed) return;
@@ -34,7 +42,7 @@ export function createFlightBox() {
 
     Date.now = function spardaDateNow() {
       const store = als.getStore();
-      if (!store) return originals.dateNow();
+      if (!store || insideUUID || insideFetch) return originals.dateNow();
       if (store.mode === 'record') {
         const v = originals.dateNow();
         tapOut(store, 'time', 'Date.now', v);
@@ -45,7 +53,7 @@ export function createFlightBox() {
 
     Math.random = function spardaRandom() {
       const store = als.getStore();
-      if (!store) return originals.random();
+      if (!store || insideUUID || insideFetch) return originals.random();
       if (store.mode === 'record') {
         const v = originals.random();
         tapOut(store, 'random', 'Math.random', v);
@@ -61,9 +69,14 @@ export function createFlightBox() {
           const store = als.getStore();
           if (!store) return originals.randomUUID();
           if (store.mode === 'record') {
-            const v = originals.randomUUID();
-            tapOut(store, 'uuid', 'crypto.randomUUID', v);
-            return v;
+            insideUUID = true;
+            try {
+              const v = originals.randomUUID();
+              tapOut(store, 'uuid', 'crypto.randomUUID', v);
+              return v;
+            } finally {
+              insideUUID = false;
+            }
           }
           return takeTap(store, 'uuid', 'crypto.randomUUID');
         },
@@ -77,11 +90,16 @@ export function createFlightBox() {
       const method = (init?.method ?? 'GET').toUpperCase();
       const label = `${method} ${url}`;
       if (store.mode === 'record') {
-        const res = await originals.fetch(input, init);
-        const text = (await res.text()).slice(0, MAX_BODY_BYTES);
-        const headers = { 'content-type': res.headers.get('content-type') ?? '' };
-        tapOut(store, 'http', label, { status: res.status, headers, body: text });
-        return new Response(text, { status: res.status, headers });
+        insideFetch = true;
+        try {
+          const res = await originals.fetch(input, init);
+          const text = (await res.text()).slice(0, MAX_BODY_BYTES);
+          const headers = { 'content-type': res.headers.get('content-type') ?? '' };
+          tapOut(store, 'http', label, { status: res.status, headers, body: text });
+          return new Response(text, { status: res.status, headers });
+        } finally {
+          insideFetch = false;
+        }
       }
       const rec = takeTap(store, 'http', label);
       return new Response(rec.body, { status: rec.status, headers: rec.headers });

package/src/flight/heal.js

@@ -0,0 +1,199 @@
+// flight/heal.js — the healing brain (pure functions, no I/O).
+// heal = the closed loop as ONE decision: given the recorded flight (the
+// bug), the lenient replay against current code (the candidate fix), and an
+// expectation, decide HEALED or NOT — then the command gates it behind
+// verify + apocalypse. The subtlety this module owns: the exported flight
+// test asserts the PAST; healing asserts the OPPOSITE — same deterministic
+// inputs (the recorded taps), a NEW expected outcome. Without an explicit
+// expectation we accept exactly one default: the recorded response was a 5xx
+// and the replay no longer is. Anything subtler demands --expect; guessing
+// intent would be dishonest.
+
+// expectation: null | { status?: number, body?: object (subset match) }
+export function evaluateHealing(flight, replay, expectation = null) {
+  const recorded = { status: flight.response.status, body: flight.response.body };
+  const reasons = [];
+
+  if (replay.divergences.length) {
+    reasons.push(
+      `replay diverged structurally (${replay.divergences.length}): the fix must keep the same effect ORDER and KINDS — only labels may change`,
+    );
+  }
+
+  const stillIdentical =
+    replay.actual.status === recorded.status &&
+    bodiesEqual(replay.actual.body, recorded.body);
+  if (stillIdentical && !replay.divergences.length) {
+    reasons.push('response is byte-identical to the recorded bug — nothing changed');
+  }
+
+  let expectationMet = null;
+  if (expectation) {
+    expectationMet = true;
+    if (expectation.status !== undefined && replay.actual.status !== expectation.status) {
+      expectationMet = false;
+      reasons.push(`expected status ${expectation.status}, got ${replay.actual.status}`);
+    }
+    if (expectation.body !== undefined) {
+      const actualBody = parseMaybe(replay.actual.body);
+      if (!subsetMatch(expectation.body, actualBody)) {
+        expectationMet = false;
+        reasons.push(`response body does not contain the expected subset`);
+      }
+    }
+  } else if (recorded.status >= 500) {
+    // the one honest default: a crash that no longer crashes
+    expectationMet = replay.actual.status < 500;
+    if (!expectationMet)
+      reasons.push(
+        `still failing: recorded ${recorded.status}, replay ${replay.actual.status}`,
+      );
+  } else {
+    expectationMet = false;
+    reasons.push(
+      `recorded response was ${recorded.status} (not a crash) — pass --expect '{"status":200,...}' to state what CORRECT looks like`,
+    );
+  }
+
+  const healed =
+    expectationMet === true && !stillIdentical && replay.divergences.length === 0;
+  return {
+    healed,
+    reasons,
+    before: recorded,
+    after: replay.actual,
+    relabels: replay.relabels ?? [],
+    leftover: replay.leftover,
+  };
+}
+
+// the brief the fixing agent (or human) receives — self-contained, built from
+// the flight AND the compiler's understanding of the entrypoint
+export function buildBrief(flight, graph, strictReplay, flightId) {
+  const ep = matchEntrypoint(graph, flight.request);
+  const nodes = Array.isArray(graph.nodes)
+    ? new Map(graph.nodes.map((n) => [n.id, n]))
+    : graph.nodes;
+
+  const lines = [
+    `# SPARDA Heal Brief — flight ${flightId}`,
+    '',
+    '## The bug (recorded from production)',
+    `- Request: \`${flight.request.method} ${flight.request.url}\``,
+    `- Request body: \`${JSON.stringify(flight.request.body)}\``,
+    `- Response: **${flight.response.status}** \`${flight.response.body.slice(0, 300)}\``,
+    `- Recorded taps: ${flight.taps.map((t) => t.kind).join(', ') || 'none'}`,
+    '',
+    '## Replay against current code',
+    strictReplay.match
+      ? '- Reproduces byte-identically — the bug is alive in this tree.'
+      : `- Differs already: status ${strictReplay.actual.status}; divergences: ${strictReplay.divergences.length}`,
+    '',
+  ];
+
+  if (ep) {
+    lines.push('## What the compiler knows about this entrypoint');
+    if (ep.loc) lines.push(`- Handler: \`${ep.loc.file}:${ep.loc.line}\``);
+    if (ep.meta.capabilities?.length)
+      lines.push(
+        `- Capabilities (must not grow): \`${ep.meta.capabilities.join(', ')}\``,
+      );
+    if (ep.meta.mutatesDomains?.length)
+      lines.push(`- Mutates aggregates: \`${ep.meta.mutatesDomains.join(', ')}\``);
+    const guards = guardsOf(graph, nodes, ep.id);
+    if (guards.length)
+      lines.push(
+        `- Guarded by: \`${guards.join(', ')}\` — REMOVING A GUARD FAILS THE GATE`,
+      );
+    const effectLocs = effectsOf(graph, nodes, ep.id);
+    if (effectLocs.length) {
+      lines.push('- Effects on this path:');
+      for (const e of effectLocs) lines.push(`  - ${e}`);
+    }
+    lines.push('');
+  }
+
+  lines.push(
+    '## Acceptance criteria (mechanically gated — `sparda heal <id> --check`)',
+    '1. Lenient replay of the flight must produce the EXPECTED response (not the recorded bug).',
+    '2. Effect order and kinds must be preserved (labels may change).',
+    '3. `sparda verify` — all compiler laws still hold.',
+    '4. `sparda apocalypse` — zero new critical/high findings; no guard removed.',
+    '',
+    'Fix the code. Do not edit flights, tests, or `.sparda/`.',
+    '',
+  );
+  return lines.join('\n');
+}
+
+function matchEntrypoint(graph, request) {
+  const nodes = Array.isArray(graph.nodes) ? graph.nodes : [...graph.nodes.values()];
+  const url = request.url.split('?')[0];
+  const method = request.method.toLowerCase();
+  for (const n of nodes) {
+    if (n.kind !== 'entrypoint' || n.meta.method !== method) continue;
+    const escaped = n.meta.path
+      .replace(/[.*+?^$()[\]\\|]/g, '\\$&')
+      .replace(/:(\w+)/g, '([^/]+)')
+      .replace(/\\?\{(\w+)\\?\}/g, '([^/]+)');
+    if (new RegExp(`^${escaped}/?$`).test(url)) return n;
+  }
+  return null;
+}
+
+function guardsOf(graph, nodes, epId) {
+  const chain = graph.edges.filter(
+    (e) => e.kind === 'control_flow' && e.meta?.route === epId,
+  );
+  const chainIds = new Set(chain.map((e) => e.to));
+  return [...chainIds]
+    .map((id) => nodes.get(id))
+    .filter((n) => n?.kind === 'guard')
+    .map((n) => n.label)
+    .sort();
+}
+
+function effectsOf(graph, nodes, epId) {
+  const chain = graph.edges.filter(
+    (e) => e.kind === 'control_flow' && e.meta?.route === epId,
+  );
+  const handler = chain.reduce(
+    (a, b) => (!a || b.meta.order > a.meta.order ? b : a),
+    null,
+  );
+  if (!handler) return [];
+  return graph.edges
+    .filter((e) => e.kind === 'control_flow' && e.from === handler.to && !e.meta?.route)
+    .map((e) => nodes.get(e.to))
+    .filter((n) => n?.kind === 'effect')
+    .map((n) => `${n.label} (${n.loc ? `${n.loc.file}:${n.loc.line}` : '?'})`)
+    .sort();
+}
+
+const parseMaybe = (s) => {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return s;
+  }
+};
+
+const bodiesEqual = (a, b) => {
+  if (a === b) return true;
+  try {
+    return JSON.stringify(JSON.parse(a)) === JSON.stringify(JSON.parse(b));
+  } catch {
+    return false;
+  }
+};
+
+// every key in `expected` must be present and equal (deep) in `actual`
+function subsetMatch(expected, actual) {
+  if (expected === null || typeof expected !== 'object')
+    return JSON.stringify(expected) === JSON.stringify(actual);
+  if (actual === null || typeof actual !== 'object') return false;
+  for (const [k, v] of Object.entries(expected)) {
+    if (!subsetMatch(v, actual[k])) return false;
+  }
+  return true;
+}

package/src/flight/replayer.js

@@ -8,8 +8,8 @@
 //   3. every tap was consumed (the code didn't silently skip a step).
 import http from 'node:http';
 
-export async function replayFlight(app, flight, box) {
-  const store = box.makeReplayStore(flight);
+export async function replayFlight(app, flight, box, { lenient = false } = {}) {
+  const store = box.makeReplayStore(flight, { lenient });
 
   const server = http.createServer((req, res) => {
     box.runWith(store, () => app(req, res));
@@ -51,6 +51,7 @@ export async function replayFlight(app, flight, box) {
     expected,
     actual,
     divergences: store.divergences,
+    relabels: store.relabels ?? [],
     leftover,
   };
 }

package/src/index.js

@@ -25,9 +25,12 @@ const opts = {
   app: flags.has('--app'),
   learn: flags.has('--learn'),
   germinate: flags.has('--germinate'),
+  check: flags.has('--check'),
   port: getOpt('port', null),
   out: getOpt('out', null),
   openapi: getOpt('openapi', null),
+  expect: getOpt('expect', null),
+  agent: getOpt('agent', null),
   cwd: process.cwd(),
 };
 
@@ -127,6 +130,11 @@ try {
       await runVerify(opts);
       break;
     }
+    case 'heal': {
+      const { runHeal } = await import('./commands/heal.js');
+      await runHeal(opts, rest);
+      break;
+    }
     default:
       console.log(`SPARDA v${VERSION} — Turn any codebase into an MCP server.
 
@@ -149,6 +157,8 @@ Usage:
   npx sparda-mcp mirror    Serve the compiled graph over HTTP — no framework, no source (--port)
   npx sparda-mcp openapi   Emit an OpenAPI 3.1 spec FROM the graph (--out / --json)
   npx sparda-mcp verify    Prove the compiler's own laws (determinism, soundness, round-trip) on this app
+  npx sparda-mcp heal      Close the loop: <flightId> writes the fix brief; --check gates the fix
+                           (--expect '{"status":200}' states correctness; --agent "cmd" lets an AI try)
 
 Flags: --yes (skip prompts)  --port <n>  --quiet  --verbose
        --probe (init: also run the app to discover dynamic routes the AST missed)