sparda-mcp 0.10.1 → 0.13.0

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.
@@ -93,7 +97,7 @@ npx sparda-mcp apocalypse
 This command reads the compiled `.sparda/ubg.json` (with zero source code parsing at runtime) and discharges five static correctness obligations:
 * **Unguarded Mutation (Critical)**: Flags any mutation path that does not cross a security `guard`.
 * **Non-Atomic Aggregate Write (High)**: Flags when an API writes to multiple tables of the same Consistency Domain (Aggregate) outside a single transaction scope.
-* **Unvalidated Constrained Write (Medium)**: Flags writes into columns with SQL invariants (CHECK, NOT NULL, UNIQUE) without prior validation (Zod/Pydantic).
+* **Unvalidated Constrained Write (Medium)**: Flags writes into columns with declared invariants (CHECK, NOT NULL, UNIQUE — parsed from your `.sql` DDL **or `schema.prisma`**, Prisma enums included) without prior validation (Zod/Pydantic).
 * **Irreversible Observable Effect (High)**: Flags out-of-process actions (like Stripe charges) that happen alongside state writes without a structural compensation path (like a catch-refund).
 * **Aggregate Member Bypass (Info)**: Flags mutating a member table directly without routing through the aggregate root.
 
@@ -108,6 +112,59 @@ Subsequent runs will diff the candidate graph against this baseline to detect re
 
 If any Critical or High finding is found, `apocalypse` exits with a non-zero code to block your CI pipeline.
 
+**One step in your workflow — findings land in the GitHub Security tab (SARIF):**
+```yaml
+- uses: zyx77550/sparda@main
+  with:
+    sarif: 'true'
+```
+
+## Time Travel: Timeless
+
+Every production request is deterministic between its effects — the compiler knows exactly where the nondeterminism lives (db, http, clock, random, uuid: the effect nodes of the graph). Timeless records only those points (a few KB per request) and replays the request **byte-identically** against your current code, with the database, webhooks and clock virtualized from the recording:
+
+```bash
+npx sparda-mcp timeless                # list recorded flights
+npx sparda-mcp timeless replay <id>    # re-fly it — byte-identical or loud divergence
+npx sparda-mcp timeless export <id>    # the production bug is now a vitest test
+```
+
+Recording is two lines in your app (ESM), with deterministic sampling and GDPR redaction built in:
+```js
+import { getFlightBox } from 'sparda-mcp/src/flight/box.js';
+const box = getFlightBox(); box.arm();
+app.use(box.middleware({ sample: 100 }));   // 1 request in 100; passwords/tokens redacted by default
+const db = box.wrapClient(pgPool);           // your query client, tapped
+```
+
+The closed loop nobody else has: **production bug → recorded flight → failing test → AI writes the fix → `apocalypse` proves the fix breaks no guard, invariant or transaction → deploy.** Replay is per-request (concurrent-race capture is out of scope for v1 — stated, not hidden).
+
+## 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.
+
+```bash
+npx sparda-mcp ubg --openapi openapi.json
+```
+
+Security schemes become gating `guard` nodes, response schemas become typed returns, declared request bodies count as validated input. Pair the spec with your `.sql` or `schema.prisma` files and the full state layer — invariants, aggregates, state machines — fills in from declared truth. (JSON specs in v1; we refuse to half-parse YAML with zero dependencies.)
+
+## The Mirror VM: delete the framework, the app still answers
+
+The graph is not a diagram — it executes:
+
+```bash
+npx sparda-mcp mirror
+```
+
+```
+MIRROR — the graph is serving. 3 entrypoint(s) on http://127.0.0.1:4477
+  GET    /orders/{orderId}  → {amount, id, status}
+  POST   /orders  🔒 bearerAuth  → {amount, id, status}
+```
+
+No Express. No FastAPI. No source code — just `ubg.json` answering HTTP: guards actually deny (401), responses render the compiled return schemas, unknown paths 404 with the full route table. Front-end teams develop against backends that aren't deployed yet — or aren't written yet (point `mirror` at an OpenAPI spec). Every response carries `x-sparda-mirror: true`; the mirror serves declared behavior, it never invents business values.
+
 To undo everything: **`npx sparda-mcp remove`** restores your code byte-for-byte.
 
 ## The promise — every word is backed by a test in CI

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.10.1",
+  "version": "0.13.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.",
+  "description": "Compile any backend into a deterministic behavior graph (SBG). Statically prove security, simulate APIs without code, and replay bugs locally.",
   "type": "module",
   "repository": {
     "type": "git",

package/src/commands/apocalypse.js

@@ -0,0 +1,123 @@
+// commands/apocalypse.js — prove a deployment can't break the declared rules.
+// Compiles the tree to SBIR, discharges the static proof obligations, and —
+// when a baseline exists — proves the deploy removed no protection the
+// baseline had. Exit code 1 on any critical/high finding: this command is
+// built to sit in CI between "tests pass" and "deploy".
+//   sparda apocalypse                   check current tree (+ diff vs baseline if saved)
+//   sparda apocalypse --save-baseline   record the current graph as the reference
+//   sparda apocalypse --json            raw findings for tooling
+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, verdictOf } from '../ubg/apocalypse.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+const ICONS = { critical: '✗', high: '✗', medium: '⚠', info: '·' };
+
+export async function runApocalypse(opts) {
+  const { graph } = compileUBG(opts.cwd, { write: false });
+  const canonical = canonicalizeGraph(graph);
+  const baselinePath = path.join(opts.cwd, '.sparda', 'ubg.baseline.json');
+
+  if (opts.saveBaseline) {
+    fs.mkdirSync(path.dirname(baselinePath), { recursive: true });
+    atomicWrite(baselinePath, JSON.stringify(canonical, null, 2) + '\n');
+    console.log(
+      `✓ Baseline saved: .sparda/ubg.baseline.json — future deploys are proven against it`,
+    );
+  }
+
+  const { findings: staticFindings, obligations } = checkGraph(canonical);
+  let diffFindings = [];
+  let hasBaseline = false;
+  if (!opts.saveBaseline && fs.existsSync(baselinePath)) {
+    hasBaseline = true;
+    try {
+      const baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+      diffFindings = diffGraphs(baseline, canonical).findings;
+    } catch (err) {
+      console.error(`⚠ baseline unreadable (${err.message}) — static checks only`);
+    }
+  }
+
+  const findings = [...staticFindings, ...diffFindings];
+  const verdict = verdictOf(findings);
+
+  if (opts.sarif) {
+    const sarifPath = path.join(opts.cwd, '.sparda', 'apocalypse.sarif');
+    fs.mkdirSync(path.dirname(sarifPath), { recursive: true });
+    atomicWrite(sarifPath, JSON.stringify(toSarif(findings, canonical), null, 2) + '\n');
+    console.log(
+      `✓ SARIF written: .sparda/apocalypse.sarif (${findings.length} result(s))`,
+    );
+  }
+
+  if (opts.json) {
+    console.log(JSON.stringify({ verdict, obligations, findings }, null, 2));
+  } else {
+    console.log(
+      `APOCALYPSE — deployment proof over ${canonical.nodes.length} nodes, ${canonical.edges.length} edges` +
+        (hasBaseline ? ' (baseline diff included)' : ''),
+    );
+    for (const f of findings) {
+      console.log(`  ${ICONS[f.severity]} [${f.severity}] ${f.rule} — ${f.message}`);
+      if (opts.verbose) for (const ev of f.evidence) console.log(`      evidence: ${ev}`);
+    }
+    if (verdict.clean) {
+      console.log(
+        `✓ PROVEN — ${obligations} obligation(s) discharged, zero violations. No declared guard, invariant, transaction or aggregate boundary can be broken by this tree.`,
+      );
+    } else {
+      const c = verdict.counts;
+      console.log(
+        `${verdict.safe ? '⚠ RISKY' : '✗ NOT PROVEN'} — ${c.critical} critical, ${c.high} high, ${c.medium} medium, ${c.info} info`,
+      );
+    }
+  }
+
+  if (!verdict.safe) process.exitCode = 1; // CI gates on this
+  return { verdict, findings, obligations };
+}
+
+// SARIF 2.1.0 — GitHub code scanning eats this directly
+const SARIF_LEVEL = { critical: 'error', high: 'error', medium: 'warning', info: 'note' };
+
+function toSarif(findings, canonical) {
+  const nodeById = new Map(canonical.nodes.map((n) => [n.id, n]));
+  return {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: 'sparda-apocalypse',
+            informationUri: 'https://github.com/zyx77550/sparda',
+            rules: [...new Set(findings.map((f) => f.rule))].sort().map((id) => ({ id })),
+          },
+        },
+        results: findings.map((f) => {
+          const loc = nodeById.get(f.entrypoint)?.loc;
+          return {
+            ruleId: f.rule,
+            level: SARIF_LEVEL[f.severity] ?? 'warning',
+            message: { text: f.message },
+            ...(loc
+              ? {
+                  locations: [
+                    {
+                      physicalLocation: {
+                        artifactLocation: { uri: loc.file },
+                        region: { startLine: loc.line || 1 },
+                      },
+                    },
+                  ],
+                }
+              : {}),
+          };
+        }),
+      },
+    ],
+  };
+}

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/commands/mirror.js

@@ -0,0 +1,42 @@
+// commands/mirror.js — serve the compiled behavior, delete the framework.
+//   sparda mirror                 compile the tree (or --openapi spec) and serve it
+//   sparda mirror --port 5050     pick the port
+//   sparda ubg --openapi api.json && sparda mirror   any backend on earth
+// The graph answers HTTP: guards deny (401), responses come out typed from
+// the compiled return schemas, unknown paths list what the graph knows.
+// Front-ends develop against backends that aren't deployed — or written.
+import fs from 'node:fs';
+import path from 'node:path';
+import { compileUBG } from '../ubg/compile.js';
+import { createMirrorServer } from '../ubg/mirror.js';
+
+export async function runMirror(opts) {
+  // prefer the already-compiled artifact; compile fresh when absent
+  const artifact = path.join(opts.cwd, '.sparda', 'ubg.json');
+  let graph;
+  if (fs.existsSync(artifact) && !opts.openapi) {
+    graph = JSON.parse(fs.readFileSync(artifact, 'utf8'));
+  } else {
+    graph = JSON.parse(
+      compileUBG(opts.cwd, { write: false, openapi: opts.openapi ?? null }).json,
+    );
+  }
+
+  const { server, routes } = createMirrorServer(graph);
+  const port = Number(opts.port ?? 4477);
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(port, '127.0.0.1', resolve);
+  });
+
+  console.log(
+    `MIRROR — the graph is serving. ${routes.length} entrypoint(s) on http://127.0.0.1:${port}`,
+  );
+  for (const r of routes) {
+    console.log(
+      `  ${r.method.toUpperCase().padEnd(6)} ${r.path}${r.guarded ? '  🔒 ' + r.guards.join(',') : ''}${r.returns ? '  → {' + Object.keys(r.returns).join(', ') + '}' : ''}`,
+    );
+  }
+  console.log('  (every response carries x-sparda-mirror: true — Ctrl+C to stop)');
+  return { server, routes, port };
+}

package/src/commands/openapi.js

@@ -0,0 +1,61 @@
+// commands/openapi.js — emit an OpenAPI 3.1 spec FROM the behavior graph.
+// We produce the standard the rest of the industry consumes: any backend
+// SPARDA can compile (Express, FastAPI, Next.js — or another spec via
+// --openapi) gets a valid, deterministic spec, richer than most hand-written
+// ones because it comes from what the code actually declares.
+//   sparda openapi                       write .sparda/openapi.json
+//   sparda openapi --out api.json        pick the path
+//   sparda openapi --json                print to stdout
+import path from 'node:path';
+import fs from 'node:fs';
+import { compileUBG } from '../ubg/compile.js';
+import { canonicalizeGraph } from '../ubg/schema.js';
+import { emitOpenAPI } from '../ubg/openapi-emit.js';
+import { atomicWriteFileSync as atomicWrite } from '../server/persistence.js';
+
+export async function runOpenapi(opts) {
+  const { graph } = compileUBG(opts.cwd, {
+    write: false,
+    openapi: opts.openapi ?? null,
+  });
+  const title = packageNameOf(opts.cwd);
+  const spec = emitOpenAPI(canonicalizeGraph(graph), { title });
+  const body = JSON.stringify(spec, null, 2) + '\n';
+
+  if (opts.json) {
+    console.log(body);
+    return { spec };
+  }
+  const target = opts.out
+    ? path.resolve(opts.cwd, opts.out)
+    : path.join(opts.cwd, '.sparda', 'openapi.json');
+  fs.mkdirSync(path.dirname(target), { recursive: true });
+  atomicWrite(target, body);
+
+  const pathCount = Object.keys(spec.paths).length;
+  const opCount = Object.values(spec.paths).reduce(
+    (n, p) => n + Object.keys(p).length,
+    0,
+  );
+  console.log(
+    `✓ OpenAPI 3.1 emitted: ${rel(target, opts.cwd)} — ${pathCount} path(s), ${opCount} operation(s)`,
+  );
+  console.log(
+    '  SPARDA produces the standard others consume — feed it to Swagger UI or a codegen.',
+  );
+  return { spec, target };
+}
+
+function packageNameOf(cwd) {
+  try {
+    return (
+      JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')).name ??
+      'sparda-compiled-api'
+    );
+  } catch {
+    return 'sparda-compiled-api';
+  }
+}
+
+const rel = (abs, cwd) =>
+  abs.startsWith(cwd) ? abs.slice(cwd.length + 1).replaceAll('\\', '/') : abs;

package/src/commands/ubg.js

@@ -9,6 +9,7 @@ export async function runUbg(opts) {
   const { report, json, outPath } = compileUBG(opts.cwd, {
     write: true,
     out: opts.out,
+    openapi: opts.openapi ?? null,
   });
 
   if (opts.json) {

package/src/commands/verify.js

@@ -0,0 +1,36 @@
+// commands/verify.js — prove the compiler's own laws on THIS project.
+// Runs the SBIR compiler-law audit and reports each check. Exit code 1 if any
+// law fails: run it in CI to guarantee the graph your tools trust was built
+// under determinism and soundness — not just asserted to be.
+//   sparda verify                 audit the detected app
+//   sparda verify --openapi s.json   audit an OpenAPI-lowered backend
+import { verifyProject } from '../ubg/verify.js';
+
+export async function runVerify(opts) {
+  const { checks, passed, total, ok } = verifyProject(opts.cwd, {
+    openapi: opts.openapi ?? null,
+  });
+
+  console.log(`VERIFY — SBIR compiler laws on this project (${passed}/${total} checks)`);
+  let lastLaw = null;
+  for (const c of checks) {
+    if (c.law !== lastLaw) {
+      console.log(`  ${c.law}`);
+      lastLaw = c.law;
+    }
+    console.log(
+      `    ${c.pass ? '✓' : '✗'} ${c.name}${c.pass || !c.detail ? '' : ` — ${c.detail}`}`,
+    );
+  }
+  if (ok) {
+    console.log(
+      '✓ PROVEN — every compiler law holds on this input. The graph is trustworthy.',
+    );
+  } else {
+    console.log(
+      '✗ LAW VIOLATED — the compiler broke its own contract on this input. This is a bug; please open an issue.',
+    );
+    process.exitCode = 1;
+  }
+  return { ok, checks };
+}

package/src/detect.js

@@ -199,6 +199,8 @@ function findExpressEntry(cwd, pkg) {
     'src/app.ts',
     'src/server.ts',
     'src/index.ts',
+    'src/main.ts', // Nx / NestJS-style monorepo layout
+    'main.ts',
     'app.ts',
     'server.ts',
     'index.ts',