sparda-mcp 0.64.0 → 0.66.1

package/README.md

@@ -6,11 +6,12 @@
 
 <br/>
 
-> 🇫🇷 **Français** : Pour comprendre SPARDA en 10 minutes (douleur, architecture, vision), lisez le document du fondateur : [SPARDA-EXPLIQUE.md](docs/SPARDA-EXPLIQUE.md).
+> 🇫🇷 **Français** — _L'IA écrit. SPARDA prouve._ Un gate déterministe et hors-ligne qui détecte quand une modif d'IA retire une garde, expose une route ou casse un invariant — sans clé API, directement dans la boucle d'édition de l'agent. Pour tout comprendre en 10 minutes (douleur, architecture, vision) : [SPARDA-EXPLIQUE.md](docs/SPARDA-EXPLIQUE.md).
 
 ---
 
 <h1 align="center">AI writes. SPARDA proves.</h1>
+<p align="center"><em>L'IA écrit. SPARDA prouve.</em></p>
 
 **The trust layer for AI-written backends.** SPARDA compiles your backend — routes, database queries, state mutations, guards, side-effects — into one deterministic behavior graph, then **statically proves what can and can't break before you ship**: no unguarded mutation, no broken invariant, no non-atomic aggregate write.
 
@@ -24,7 +25,7 @@
 
 ## 60-second proof
 
-From your Express, FastAPI, Next.js, NestJS or Medusa app — nothing to configure:
+From your Express, FastAPI, Flask, Next.js, NestJS or Medusa app — nothing to configure:
 
 ```bash
 npx sparda-mcp apocalypse   # prove the tree is safe to deploy — exit 1 on any real risk
@@ -52,7 +53,7 @@ Under the hood it compiles your backend into one language-agnostic graph — the
 | **`heal`**         | _Self-heal, **proven**_ — the gate Copilot Autofix doesn't have: a fix ships **only if** replay matches, `verify` still passes, and `apocalypse` finds no new risk / no dropped guard. Whoever wrote the fix, the machine judges it. |
 | **`badge`**        | _The shareable artifact_ — a self-contained SVG badge + README snippet (verdict · coverage · routes)                                                                                                                                 |
 | **`dossier`**      | _The public report_ — one self-contained HTML page: verdict, risks, and SPARDA's own blind spots                                                                                                                                     |
-| **`ubg`**          | Compile the codebase to its behavior graph (Express · FastAPI · Next.js · NestJS · Medusa natively; **any** stack via OpenAPI)                                                                                                       |
+| **`ubg`**          | Compile the codebase to its behavior graph (Express · FastAPI · Flask · Next.js · NestJS · Medusa natively; **any** stack via OpenAPI)                                                                                               |
 | **`timeless`**     | _Time-travel_ — record a production request, replay it byte-identically, export the bug as a test                                                                                                                                    |
 | **`mirror`**       | _Execute the graph_ — serve the compiled behavior over HTTP with no framework and no source                                                                                                                                          |
 | **`init` / `dev`** | _Runtime, optional_ — expose the graph to AI clients as a live MCP server (+ Twin, Immune, Evolution)                                                                                                                                |
@@ -212,7 +213,7 @@ The gate is honest in both directions: an unfixed bug, or a "fix" that silently
 
 ## Any Backend On Earth: OpenAPI Lowering
 
-SPARDA parses Express, FastAPI and Next.js natively — and **every other stack through the format the industry already agreed on**. Go, Java, Rails, Laravel, .NET: if it has an OpenAPI spec, it compiles.
+SPARDA parses Express, FastAPI, Flask and Next.js natively — and **every other stack through the format the industry already agreed on**. Go, Java, Rails, Laravel, .NET: if it has an OpenAPI spec, it compiles.
 
 ```bash
 npx sparda-mcp ubg --openapi openapi.json

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "sparda-mcp",
-  "version": "0.64.0",
+  "version": "0.66.1",
   "mcpName": "io.github.zyx77550/sparda-mcp",
-  "description": "Compile backends to behavior graphs. Statically prove security, simulate APIs, and replay bugs.",
+  "description": "AI writes. SPARDA proves. A deterministic, offline gate that catches when an AI edit removes a guard, exposes a route, or breaks an invariant — no API key, right in the agent edit loop.",
   "type": "module",
   "repository": {
     "type": "git",
@@ -13,7 +13,7 @@
     "url": "https://github.com/zyx77550/sparda/issues"
   },
   "bin": {
-    "sparda": "./src/index.js"
+    "sparda": "src/index.js"
   },
   "scripts": {
     "test": "vitest run",
@@ -44,12 +44,19 @@
   },
   "keywords": [
     "mcp",
+    "mcp-server",
     "model-context-protocol",
     "claude",
-    "ai",
-    "express",
-    "fastapi",
-    "codegen"
+    "claude-code",
+    "ai-code-review",
+    "code-review",
+    "guardrails",
+    "static-analysis",
+    "security",
+    "authorization",
+    "bola",
+    "ai-agents",
+    "trust-layer"
   ],
   "author": "Residual Labs (residual-labs.fr)",
   "license": "BUSL-1.1",

package/src/commands/apocalypse.js

@@ -8,12 +8,38 @@
 //   sparda apocalypse --json            raw findings for tooling
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { compileUBG } from '../ubg/compile.js';
 import { canonicalizeGraph } from '../ubg/schema.js';
-import { checkGraph, diffGraphs, verdictOf } from '../ubg/apocalypse.js';
+import {
+  checkGraph,
+  diffGraphs,
+  verdictOf,
+  verdictState,
+  buildProofObjects,
+} from '../ubg/apocalypse.js';
 import { surveyBlindspots } from '../ubg/blindspots.js';
 import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
 
+// version travels with the proof so an audit knows which prover produced it
+const SPARDA_VERSION = (() => {
+  try {
+    return JSON.parse(
+      fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8'),
+    ).version;
+  } catch {
+    return '0.0.0';
+  }
+})();
+
+// a deterministic fingerprint of the canonical graph: same source → same graph → same hash.
+// The proof object binds to it, so a third party proves it audited the SAME artifact.
+function graphHash(canonical) {
+  const h = crypto.createHash('sha256');
+  h.update(JSON.stringify({ nodes: canonical.nodes, edges: canonical.edges }));
+  return 'bh1_' + h.digest('hex').slice(0, 16);
+}
+
 const ICONS = { critical: '✗', high: '✗', medium: '⚠', info: '·' };
 
 export async function runApocalypse(opts) {
@@ -61,6 +87,21 @@ export async function runApocalypse(opts) {
     );
   }
 
+  if (opts.proof) {
+    const proofPath = path.join(opts.cwd, '.sparda', 'apocalypse.proof.json');
+    fs.mkdirSync(path.dirname(proofPath), { recursive: true });
+    const proof = {
+      sparda_version: SPARDA_VERSION,
+      graph_hash: graphHash(canonical),
+      verdict: verdictState(verdict),
+      discharged: buildProofObjects(canonical),
+    };
+    atomicWrite(proofPath, JSON.stringify(proof, null, 2) + '\n');
+    console.log(
+      `✓ Proof written: .sparda/apocalypse.proof.json (${proof.discharged.length} discharged obligation(s), re-verifiable against ${proof.graph_hash})`,
+    );
+  }
+
   if (opts.json) {
     console.log(
       JSON.stringify({ verdict, obligations, findings, blindspots: blind }, null, 2),

package/src/commands/gate.js

@@ -0,0 +1,188 @@
+// commands/gate.js — the agent edit-loop gate: did THIS edit lose a protection
+// or introduce a risk, relative to the armed baseline? Delta-only by design: an
+// edit gate must never scream about pre-existing state (that noise is fatal to
+// adoption — see docs/TWO-FALSE-POSITIVE-CLASSES-2026-07-19.md), so everything
+// already true at arm time is silent and only the regression speaks.
+//
+// The load-bearing subtlety (E-GATE-1): a PostToolUse hook fires after EVERY
+// edit, including the mid-sequence ones that leave a file temporarily
+// unparseable. When a file fails to parse its routes vanish from the graph, so a
+// naive diff reads that as ENTRYPOINT_REMOVED / GUARD_REMOVED and cries a false
+// regression on the agent's own in-progress work. That false alarm, fired
+// constantly, is what gets the gate uninstalled in five minutes. So: a regression
+// whose baseline entrypoint lives in a now-unparseable file is NOT a regression —
+// it is "unproven, come back when it parses". The gate ABSTAINS, never claims
+// clean (it proved nothing) and never claims safe. An unparseable tree has no
+// defined behavior to regress against — abstention is the sound call.
+//
+// Note on PostToolUse semantics: the edit has already landed, so exit 2 does not
+// *prevent* it — it feeds the regression back to the agent as stderr, which the
+// agent reads and corrects in the same session (self-heal in the loop). That is
+// the honest claim: immediate feedback, not a hard block. (A hard pre-commit
+// block is the pre-commit hook / CI Action's job — same command, `apocalypse`.)
+//   sparda gate            report the edit's behavior delta vs baseline
+//   sparda gate --arm      freeze the current graph as the accepted baseline
+//   sparda gate --hook     Claude Code PostToolUse contract: silent when clean,
+//                          report on stderr + exit 2 (feedback to the agent) on a
+//                          real regression; abstains (exit 0) while a file is
+//                          mid-edit; arms itself on first run — zero config.
+import fs from 'node:fs';
+import path from 'node:path';
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import { checkGraph, diffGraphs } from '../ubg/apocalypse.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+// severities that block the edit; medium/info regressions are reported, never fatal
+const BLOCKING = new Set(['critical', 'high']);
+const findingKey = (f) => `${f.rule}|${f.entrypoint}`;
+// diff rules that mean "this route/protection disappeared" — the ones a vanished
+// (unparseable) file can forge. Introduced-risk rules can never be forged by a
+// missing file, so they are never suppressed.
+const REMOVAL_RULES = new Set(['ENTRYPOINT_REMOVED', 'GUARD_REMOVED']);
+
+// files the compiler could not read/parse this run — reason is prefixed by the
+// module error (`parse error: …` / `unreadable: …`) in every extractor's skipped list.
+function unparsedFiles(report) {
+  const out = new Set();
+  for (const s of report?.skipped ?? []) {
+    if (s.file && /(^|\b)(parse error|unreadable|Unexpected|SyntaxError)/i.test(s.reason))
+      out.add(s.file);
+  }
+  return out;
+}
+
+// The gate's whole judgment, pure over two canonical graphs (testable without a repo):
+// diff regressions (guard/route/invariant lost, blast radius grown) + static findings
+// the candidate has that the baseline did not — the same composition `review` proved
+// out (ADR-030), pointed at the baseline instead of a git ref. `unparsed` (the set of
+// files that failed to parse in the candidate) splits the diff removals into real
+// regressions vs in-progress edits whose baseline route lives in a now-broken file.
+export function gateDelta(baseline, candidate, unparsed = new Set()) {
+  const baseLoc = new Map((baseline.nodes ?? []).map((n) => [n.id, n.loc?.file]));
+  const diff = diffGraphs(baseline, candidate).findings;
+  const before = new Set(checkGraph(baseline).findings.map(findingKey));
+  const introduced = checkGraph(candidate).findings.filter(
+    (f) => !before.has(findingKey(f)),
+  );
+  const seen = new Set(diff.map(findingKey));
+  const all = [...diff, ...introduced.filter((f) => !seen.has(findingKey(f)))];
+
+  const findings = [];
+  const abstained = [];
+  for (const f of all) {
+    if (REMOVAL_RULES.has(f.rule) && unparsed.has(baseLoc.get(f.entrypoint)))
+      abstained.push(f);
+    else findings.push(f);
+  }
+  return {
+    findings,
+    blocking: findings.filter((f) => BLOCKING.has(f.severity)),
+    abstained,
+  };
+}
+
+function locOf(canonical, f) {
+  const loc = canonical.nodes.find((n) => n.id === f.entrypoint)?.loc;
+  return loc ? ` (${loc.file}:${loc.line || 1})` : '';
+}
+
+export async function runGate(opts) {
+  const t0 = process.hrtime.bigint();
+  const hook = opts.hook;
+  // in hook mode stdout belongs to nobody and stderr is what the agent reads
+  const say = hook ? (s) => console.error(s) : (s) => console.log(s);
+
+  const baselinePath = path.join(opts.cwd, '.sparda', 'ubg.baseline.json');
+
+  // A tree that does not compile at all (broken entry / detection throw) has no
+  // behavior to judge. Abstain instead of crashing the hook — the agent is mid-edit.
+  let graph, report;
+  try {
+    ({ graph, report } = compileUBG(opts.cwd, { write: false }));
+  } catch (err) {
+    if (opts.json)
+      console.log(JSON.stringify({ ok: true, abstained: err.message }, null, 2));
+    else if (!hook)
+      say(
+        `⏳ GATE ABSTAINED — the tree does not compile yet (${err.message}). Fix it, then re-check.`,
+      );
+    return { armed: false, findings: [], abstained: true };
+  }
+  const candidate = canonicalizeGraph(graph);
+  const unparsed = unparsedFiles(report);
+
+  const arm = () => {
+    fs.mkdirSync(path.dirname(baselinePath), { recursive: true });
+    atomicWrite(baselinePath, JSON.stringify(candidate, null, 2) + '\n');
+  };
+
+  if (opts.arm || opts.saveBaseline) {
+    arm();
+    say(
+      `✓ GATE ARMED — baseline frozen (.sparda/ubg.baseline.json). Every edit is now proven against it.`,
+    );
+    return { armed: true, findings: [] };
+  }
+
+  if (!fs.existsSync(baselinePath)) {
+    // first run arms instead of failing: a hook must work with zero configuration
+    arm();
+    say(
+      `✓ GATE ARMED (first run) — baseline frozen. Future edits are proven against it; re-arm with \`sparda gate --arm\` after intended changes.`,
+    );
+    return { armed: true, findings: [] };
+  }
+
+  const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+  const { findings, blocking, abstained } = gateDelta(baseline, candidate, unparsed);
+  const ms = Number(process.hrtime.bigint() - t0) / 1e6;
+
+  if (opts.json) {
+    console.log(
+      JSON.stringify(
+        {
+          ok: blocking.length === 0,
+          ms: Math.round(ms),
+          findings,
+          abstained: abstained.map((f) => f.entrypoint),
+        },
+        null,
+        2,
+      ),
+    );
+    if (blocking.length) process.exitCode = 1;
+    return { armed: false, findings };
+  }
+
+  // Abstention notice: a route vanished only because its file doesn't parse yet.
+  // Never blocking — this is the normal mid-edit state, not a regression.
+  if (abstained.length) {
+    const files = [...new Set([...unparsed])].join(', ');
+    say(
+      `⏳ GATE HELD — ${abstained.length} route(s) can't be proven while ${files} doesn't parse (mid-edit?). Not a regression; I'll re-check once it parses.`,
+    );
+  }
+
+  if (findings.length === 0) {
+    if (!hook && !abstained.length)
+      say(
+        `✓ GATE CLEAN — this edit lost no guard, dropped no route, grew no blast radius (proven vs baseline in ${Math.round(ms)} ms).`,
+      );
+    return { armed: false, findings };
+  }
+
+  say(
+    `✗ SPARDA GATE — this edit changed the app's proven behavior (${Math.round(ms)} ms, deterministic):`,
+  );
+  for (const f of findings)
+    say(`  [${f.severity}] ${f.rule} — ${f.message}${locOf(candidate, f)}`);
+  say(
+    blocking.length
+      ? `  → fix the edit or, if intended, accept it with \`sparda gate --arm\`.`
+      : `  → advisory only (no critical/high regression) — review, then \`sparda gate --arm\` if intended.`,
+  );
+
+  if (blocking.length) process.exitCode = hook ? 2 : 1;
+  return { armed: false, findings };
+}

package/src/detect.js

@@ -92,7 +92,7 @@ export function detectStack(cwd) {
     const known = ['fastify', 'koa'].find((d) => deps[d]);
     if (known)
       throw err(
-        `${known} detected — not supported yet. Express, NestJS & FastAPI in v0.`,
+        `${known} detected — not supported yet. Express, NestJS, FastAPI & Flask in v0.`,
         '+1 the framework vote: github.com/zyx77550/sparda/issues/1',
       );
   }
@@ -108,6 +108,18 @@ export function detectStack(cwd) {
       return { framework: 'fastapi', entryFile, port, pythonCmd };
     }
   }
+  // Flask — checked AFTER FastAPI (a FastAPI project may pull flask transitively; FastAPI
+  // wins). The same Python extractor handles it; only the entry-file marker differs.
+  for (const f of ['requirements.txt', 'pyproject.toml']) {
+    const p = path.join(cwd, f);
+    if (
+      fs.existsSync(p) &&
+      /(^|[^a-z])flask([^a-z]|$)/i.test(fs.readFileSync(p, 'utf8'))
+    ) {
+      const entryFile = findFlaskEntry(cwd);
+      return { framework: 'flask', entryFile, port: 5000, pythonCmd: detectPython() };
+    }
+  }
 
   // Last resort before giving up — monorepo app dirs whose framework config lives
   // ELSEWHERE than the pointed dir. Purely structural, so it never mis-fires on a
@@ -130,7 +142,7 @@ export function detectStack(cwd) {
 
   const suggestions = suggestAppDirs(cwd);
   throw err(
-    'No supported framework found (Express, Next.js, NestJS, Medusa, FastAPI).',
+    'No supported framework found (Express, Next.js, NestJS, Medusa, FastAPI, Flask).',
     suggestions.length
       ? `This looks like a monorepo — the analyzable app is in a sub-directory. Try:\n` +
           suggestions
@@ -401,7 +413,28 @@ function findFastAPIEntry(cwd) {
   );
 }
 
-function searchPyFiles(dir, root, countRef = { val: 0 }) {
+// Flask's entry is the file that calls `Flask(__name__)` — conventionally app.py /
+// wsgi.py / run.py / main.py, else the first .py declaring it. Same shape as the
+// FastAPI finder; the Python extractor handles both frameworks from that entry.
+function findFlaskEntry(cwd) {
+  const candidates = ['app.py', 'wsgi.py', 'run.py', 'main.py', 'src/app.py'];
+  for (const rel of candidates) {
+    const abs = path.resolve(cwd, rel);
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+      if (fs.readFileSync(abs, 'utf8').includes('Flask(')) {
+        return path.relative(cwd, abs).split(path.sep).join('/');
+      }
+    }
+  }
+  const entry = searchPyFiles(cwd, cwd, { val: 0 }, 'Flask(');
+  if (entry) return path.relative(cwd, entry).split(path.sep).join('/');
+  throw err(
+    'Could not locate your Flask entry file (the one calling Flask()).',
+    'Specify it manually, or make sure Flask() is declared in one of your python files.',
+  );
+}
+
+function searchPyFiles(dir, root, countRef = { val: 0 }, marker = 'FastAPI(') {
   const EXCLUDE = new Set([
     'node_modules',
     '.git',
@@ -434,7 +467,7 @@ function searchPyFiles(dir, root, countRef = { val: 0 }) {
       countRef.val++;
       if (countRef.val > 200) return null;
       const src = fs.readFileSync(abs, 'utf8');
-      if (src.includes('FastAPI(')) {
+      if (src.includes(marker)) {
         return abs;
       }
     }

package/src/index.js

@@ -18,6 +18,7 @@ const opts = {
   yes: flags.has('--yes') || flags.has('-y'),
   saveBaseline: flags.has('--save-baseline'),
   sarif: flags.has('--sarif'),
+  proof: flags.has('--proof'),
   verbose: flags.has('--verbose'),
   quiet: flags.has('--quiet'),
   probe: flags.has('--probe'),
@@ -27,6 +28,8 @@ const opts = {
   learn: flags.has('--learn'),
   germinate: flags.has('--germinate'),
   check: flags.has('--check'),
+  hook: flags.has('--hook'),
+  arm: flags.has('--arm'),
   markdown: flags.has('--markdown'),
   port: getOpt('port', null),
   out: getOpt('out', null),
@@ -45,7 +48,8 @@ const opts = {
 // reads opts.cwd, so `--dir <path>` works on all of them; only per-command extras are listed.
 const HELP = {
   prove: `sparda prove [--dir <path>] [--json | --markdown]\n  The whole trust verdict: proof + coverage + a shareable seal.\n  --markdown  emit a sticky-PR-comment body (used by the GitHub Action).`,
-  apocalypse: `sparda apocalypse [--dir <path>] [--sarif] [--save-baseline]\n  Prove the deploy — exit 1 on any critical/high finding.\n  --sarif         also write .sparda/apocalypse.sarif for the Security tab.\n  --save-baseline freeze this graph; later runs diff against it.`,
+  apocalypse: `sparda apocalypse [--dir <path>] [--sarif] [--proof] [--save-baseline]\n  Prove the deploy — exit 1 on any critical/high finding.\n  --sarif         also write .sparda/apocalypse.sarif for the Security tab.\n  --proof         also write .sparda/apocalypse.proof.json — a re-verifiable\n                  discharge trace (deny_path per guarded mutation) a third party\n                  can audit against the graph hash without re-compiling.\n  --save-baseline freeze this graph; later runs diff against it.`,
+  gate: `sparda gate [--dir <path>] [--arm] [--hook] [--json]\n  The agent edit-loop gate: prove THIS edit lost no guard, dropped no route,\n  grew no blast radius — delta vs the armed baseline only (pre-existing state\n  never blocks an edit). Arms itself on first run.\n  --arm   accept the current graph as the new baseline.\n  --hook  Claude Code PostToolUse contract: silent when clean, report on\n          stderr + exit 2 (blocking feedback to the agent) on regression.`,
   ubg: `sparda ubg [--dir <path>] [--json] [--out <file>] [--openapi <spec>]\n  Compile the codebase to its Unified Behavior Graph (.sparda/ubg.json).`,
   stitch: `sparda stitch <dir1> <dir2> [...] [--json]\n  Cross-service proof: join one service's outbound HTTP calls to another's routes,\n  surface cross-service trust boundaries + BOLA no mono-repo tool can see.`,
   badge: `sparda badge [--dir <path>] [--out <file>] [--json]\n  Emit a shareable SVG badge + README snippet (verdict · coverage · routes).`,
@@ -162,6 +166,11 @@ try {
       await runApocalypse(opts);
       break;
     }
+    case 'gate': {
+      const { runGate } = await import('./commands/gate.js');
+      await runGate(opts);
+      break;
+    }
     case 'review': {
       const { runReview } = await import('./commands/review.js');
       await runReview(opts);
@@ -234,6 +243,7 @@ try {
 PROVE — the point
   prove        The whole trust verdict in one gesture: proof + coverage + seal (--json / --markdown / --openapi)
   apocalypse   Prove the deploy: guards, invariants, transactions, aggregates (--save-baseline)
+  gate         The agent edit-loop gate: prove an edit lost no protection (--arm / --hook)
   review       Semantic diff of a PR vs a base ref (--base main / --json / --markdown)
   blindspots   Map SPARDA's own blindness — every unseen route/effect/guard, ranked (--json)
   badge        Emit a shareable SVG badge + README snippet (verdict · coverage · routes)