sparda-mcp 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,89 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             Residual Labs (residual-labs.fr)
+Licensed Work:        SPARDA (sparda-mcp)
+                      The Licensed Work is (c) 2026 Residual Labs.
+Additional Use Grant: You may use the Licensed Work in production, free of
+                      charge, except to provide a commercial offering (paid
+                      service, hosted or distributed product) whose value
+                      derives, entirely or substantially, from the
+                      functionality of the Licensed Work.
+Change Date:          2030-06-11
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed
+Work, please contact Residual Labs (residual-labs.fr).
+
+Notice
+
+License text copyright © 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN “AS IS” BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.
+
+MariaDB hereby grants you permission to use this License’s text to license
+your works, and to refer to it using the trademark “Business Source License”,
+as long as you comply with the Covenants of Licensor below.
+
+Covenants of Licensor
+
+In consideration of the right to use this License’s text and the “Business
+Source License” name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where “compatible” means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text “None”.
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

package/README.md

@@ -1,26 +1,69 @@
 # SPARDA
 
-**Turn any codebase into an MCP server with one command.**
+**Your AI can write code. It still can't operate your app.**
+
+Claude, Cursor & friends read your *files* — not your *running product*. They can refactor a controller, but they can't create an order, check a real user, or see why production is failing. And today, giving an AI real access to your API 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.
+
+SPARDA deletes that work:
 
 ```bash
-npx sparda-mcp init   # scan your Express app, generate + inject the MCP router
-npx sparda-mcp dev    # MCP stdio bridge — connect Claude Desktop / Claude Code
+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.
 ```
 
-Your software, AI-controlled, in under 3 minutes. No config. No OpenAPI spec. No infra.
+No OpenAPI spec. No account. No API key. No server to host. By [Residual Labs](https://residual-labs.fr).
+
+## The promise — every word is backed by a test in CI
+
+1. **Three minutes, one command.** AST scan, router generation, reversible injection — no config.
+2. **Try it for free, leave for free.** `npx sparda-mcp remove` restores your code **byte-for-byte** (tested on JS, TS, Python, even Windows CRLF files). No trace, no lock-in.
+3. **The AI cannot write until you say so.** Every POST/PUT/DELETE is disabled by default; you enable per tool, and your choice survives every re-run.
+4. **Your app defends itself.** A route failing 3 times in a row is quarantined — the AI can't hammer your broken production. Latency anomalies are flagged. Zero LLM needed.
+5. **Nothing leaves your machine.** No telemetry to us, no cloud, local key auth, 4 exact-pinned dependencies.
+6. **What it learns is never lost.** Diagnoses, descriptions, settings — versioned with your git, surviving every re-init.
+
+What we *don't* promise: see the honest limits in [docs/SECURITY.md](./docs/SECURITY.md).
 
 ## How it works
 1. `npx sparda-mcp init` parses your codebase (AST), extracts every route, and injects a tiny marked router (`/mcp`) into your app — fully reversible with `npx sparda-mcp remove`.
 2. Tool calls run **inside your live app process** — warm DB pools, real auth chain, real data.
-3. Write tools (POST/PUT/DELETE) are **disabled by default** (write-safety). You opt in per tool in `sparda.json`.
+3. Write tools (POST/PUT/DELETE) are **disabled by default** (write-safety). You opt in per tool in `sparda.json` — your choices survive re-runs.
 4. Suspicious docstrings are purged before they ever reach the AI (prompt-injection defense).
 
+## v0.2 — the trust layer
+- **Free semantic layer, zero API key.** On first connection, your AI client's own model (via MCP sampling) rewrites tool descriptions in business terms and proposes multi-tool workflows — cached in `sparda.json`, exposed as MCP prompts. Nothing to configure, nothing to pay.
+- **Write confirmation in your AI's UI.** When the client supports MCP elicitation, every write asks you for approval before touching your live app.
+- **Proof-after-write.** Each successful write is followed by a read-back of the same path, so the AI sees the real effect of its action.
+- **Your app reports its own errors.** The router records upstream failures and uncaught exceptions; the bridge streams them to your AI as live notifications. `GET /mcp/stats` and `/mcp/events` expose per-tool telemetry.
+- **Never out of sync.** `npx sparda-mcp sync` re-syncs the router when routes change; `npx sparda-mcp hook` makes it automatic after every commit.
+
+## v0.3 — the immune system
+Your app learns what "self" looks like — and defends itself:
+- **Innate immunity (zero LLM).** The router learns each route's latency baseline and status profile; deviations (latency ×10, 5xx bursts) are flagged locally in a few lines of math.
+- **Quarantine.** A tool that fails 3 consecutive 5xx is quarantined (503 + reason + retry delay), then re-tried after a cooldown (half-open). The AI can no longer hammer a broken route of your live app.
+- **Adaptive immunity.** On a new failure signature, the bridge wakes your AI client's own model (MCP sampling) to diagnose it — costly intelligence is summoned only when the body has a fever.
+- **Immune memory.** Diagnoses are cached as antibodies in `sparda.json` (git-versioned): the same failure later is diagnosed instantly, zero tokens. Your app accumulates antibodies as it lives — cloning the code doesn't clone its immune system.
+- **`sparda_get_context`.** One tool call gives the AI the full living context: tools, workflows, runtime telemetry, quarantine state, immune memory. Every AI session resumes where the last one stopped.
+
+Where this is going: [ROADMAP.md](./ROADMAP.md).
+
 ## v0 supports
-Express 4/5 (JS/TS, ESM/CJS). FastAPI next. Vote for your framework in the pinned issue.
+Express 4/5 (JS/TS, ESM/CJS) and FastAPI. Vote for your next framework in the pinned issue.
 
 ## Security posture (v0, honest)
 - 4 runtime dependencies, exact-pinned.
 - Local key on every router call; loop protection; 30s timeouts; 8KB output truncation.
 - AST-positioned injection with backup + post-injection re-parse; `npx sparda-mcp remove` leaves a clean git diff.
 
-MIT — by [Residual Labs](https://residual-labs.fr)
+## Documentation
+The full project bible lives in [`docs/`](./docs/README.md) — architecture,
+decision log, error knowledge base, security model, testing guide, and the
+session handoff protocol. The product vision and build order: [`ROADMAP.md`](./ROADMAP.md).
+AI contributors start at [`CLAUDE.md`](./CLAUDE.md).
+
+## License
+[Business Source License 1.1](./LICENSE) — free to use, including in production.
+You may not resell SPARDA or offer it as a competing commercial service.
+Each version converts to Apache 2.0 four years after its release.
+
+By [Residual Labs](https://residual-labs.fr)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sparda-mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Turn any codebase into an MCP server with one command. Express & FastAPI → Claude-ready in 3 minutes.",
   "type": "module",
   "bin": {
@@ -12,7 +12,8 @@
   "files": [
     "src",
     "templates",
-    "README.md"
+    "README.md",
+    "LICENSE"
   ],
   "engines": {
     "node": ">=18"
@@ -27,14 +28,15 @@
     "codegen"
   ],
   "author": "Residual Labs (residual-labs.fr)",
-  "license": "MIT",
+  "license": "BUSL-1.1",
   "dependencies": {
     "@babel/parser": "7.26.5",
     "@babel/traverse": "7.26.5",
     "@clack/prompts": "0.9.1",
-    "@modelcontextprotocol/sdk": "1.12.0"
+    "@modelcontextprotocol/sdk": "1.29.0"
   },
   "devDependencies": {
+    "express": "4.21.2",
     "vitest": "^3.2.6"
   }
 }

package/src/commands/doctor.js

@@ -3,32 +3,70 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { detectStack } from '../detect.js';
 
+// Returns { healthy } so the CLI can exit non-zero on any ✗ — scripts/CI can
+// gate on `sparda doctor` (E-012). Informational '·' lines never fail it.
 export async function runDoctor(opts) {
+  let healthy = true;
+  const fail = (msg) => { healthy = false; console.log(msg); };
+
   console.log('SPARDA doctor');
   const node = process.versions.node;
-  console.log(`  ${Number(node.split('.')[0]) >= 18 ? '✓' : '✗'} Node ${node} (≥18 required)`);
+  if (Number(node.split('.')[0]) >= 18) console.log(`  ✓ Node ${node} (≥18 required)`);
+  else fail(`  ✗ Node ${node} (≥18 required)`);
   let stack = null;
   try {
     stack = detectStack(opts.cwd);
     console.log(`  ✓ Framework: ${stack.framework} — entry: ${stack.entryFile} — port: ${stack.port}`);
   } catch (e) {
-    console.log(`  ✗ ${e.message}`);
+    fail(`  ✗ ${e.message}`);
   }
   const manifest = path.join(opts.cwd, 'sparda.json');
   if (fs.existsSync(manifest)) {
     try {
       const m = JSON.parse(fs.readFileSync(manifest, 'utf8'));
-      console.log(`  ✓ sparda.json valid (${Object.keys(m.tools ?? {}).length} tools)`);
+      const tools = Object.values(m.tools ?? {});
+      console.log(`  ✓ sparda.json valid (${tools.length} tools, ${tools.filter((t) => t.enabled).length} enabled)`);
+
+      if (m.semantic) {
+        console.log(`  ✓ Semantic cache: ${Object.keys(m.semantic.descriptions ?? {}).length} descriptions, ${(m.semantic.workflows ?? []).length} workflows`);
+      } else {
+        console.log('  · Semantic cache: empty — fills on first AI connection (needs MCP sampling)');
+      }
+      const antibodies = Object.keys(m.immune?.antibodies ?? {}).length;
+      console.log(antibodies
+        ? `  ✓ Immune memory: ${antibodies} antibod${antibodies > 1 ? 'ies' : 'y'} (cached diagnoses, zero-token on recurrence)`
+        : '  · Immune memory: empty — antibodies grow as new failures get diagnosed');
+
       if (stack) {
+        const headers = { 'x-sparda-key': m.localKey };
         try {
-          const r = await fetch(`http://127.0.0.1:${m.port}/mcp/tools`, { headers: { 'x-sparda-key': m.localKey }, signal: AbortSignal.timeout(1500) });
-          console.log(r.ok ? `  ✓ Host app reachable on :${m.port}, router responding` : `  ✗ Host app on :${m.port} answered ${r.status}`);
+          const r = await fetch(`http://127.0.0.1:${m.port}/mcp/tools`, { headers, signal: AbortSignal.timeout(1500) });
+          if (!r.ok) {
+            fail(`  ✗ Host app on :${m.port} answered ${r.status}`);
+          } else {
+            const s = await fetch(`http://127.0.0.1:${m.port}/mcp/stats`, { headers, signal: AbortSignal.timeout(1500) })
+              .then((x) => (x.ok ? x.json() : null)).catch(() => null);
+            if (s) {
+              const totals = Object.values(s.stats ?? {}).reduce((a, t) => ({ calls: a.calls + t.calls, errors: a.errors + t.errors }), { calls: 0, errors: 0 });
+              console.log(`  ✓ Host app reachable on :${m.port} — uptime ${s.uptimeSec}s, ${totals.calls} calls, ${totals.errors} errors`);
+              const quarantined = Object.entries(s.quarantine ?? {});
+              if (quarantined.length) {
+                for (const [tool, q] of quarantined) fail(`  ✗ Quarantined: ${tool} (${q.reason}) — immune system is protecting this route`);
+              } else {
+                console.log('  ✓ Quarantine: empty — no route is currently sick');
+              }
+            } else {
+              console.log(`  ✓ Host app reachable on :${m.port}, router responding (stats unavailable — router predates v0.3, re-run \`npx sparda-mcp init\`)`);
+            }
+          }
         } catch {
-          console.log(`  ✗ Host app on :${m.port} — NOT reachable\n      → start it with: npm run dev`);
+          const startCmd = m.framework === 'express' ? 'npm run dev' : 'fastapi dev';
+          fail(`  ✗ Host app on :${m.port} — NOT reachable\n      → start it with: ${startCmd}`);
         }
       }
-    } catch { console.log('  ✗ sparda.json invalid JSON'); }
+    } catch { fail('  ✗ sparda.json invalid JSON'); }
   } else {
     console.log('  · sparda.json not found (run `npx sparda-mcp init`)');
   }
+  return { healthy };
 }

package/src/commands/hook.js

@@ -0,0 +1,29 @@
+// commands/hook.js — install the git sentinel (post-commit sync)
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MARKER = '# sparda-sentinel';
+
+export async function runHook(opts) {
+  const gitDir = path.join(opts.cwd, '.git');
+  if (!fs.existsSync(gitDir)) {
+    throw Object.assign(new Error('Not a git repository.'), { code: 'USER', hint: 'Run this from your project root (where .git lives).' });
+  }
+  const hooksDir = path.join(gitDir, 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  const hookPath = path.join(hooksDir, 'post-commit');
+
+  const line = `${MARKER}\nnpx --no-install sparda-mcp sync --quiet || true\n`;
+  if (fs.existsSync(hookPath)) {
+    const existing = fs.readFileSync(hookPath, 'utf8');
+    if (existing.includes(MARKER)) {
+      console.error('[sparda] sentinel already installed (post-commit).');
+      return;
+    }
+    fs.appendFileSync(hookPath, `\n${line}`);
+  } else {
+    fs.writeFileSync(hookPath, `#!/bin/sh\n${line}`);
+  }
+  fs.chmodSync(hookPath, 0o755);
+  console.error('[sparda] sentinel installed: routes re-sync after every commit (post-commit hook).');
+}

package/src/commands/init.js

@@ -4,21 +4,38 @@ import fs from 'node:fs';
 import * as p from '@clack/prompts';
 import { detectStack } from '../detect.js';
 import { parseExpressProject } from '../parser/express.js';
+import { parseFastAPIProject } from '../parser/fastapi.js';
 import { sanitizeDescription } from '../security/sanitize.js';
 import { generateExpress } from '../generator/express.js';
+import { generateFastAPI } from '../generator/fastapi.js';
+
+
+const VERSION = JSON.parse(fs.readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
 
 export async function runInit(opts) {
   const t0 = Date.now();
-  p.intro('SPARDA v0.1.0');
+  p.intro(`SPARDA v${VERSION}`);
 
   const s = p.spinner();
   s.start('Scanning project...');
   const stack = detectStack(opts.cwd);
-  const { routes, skipped } = parseExpressProject(opts.cwd, stack.entryFile);
-  s.stop(`Stack detected: Express (${stack.moduleType.toUpperCase()}) — entry: ${stack.entryFile}, port: ${stack.port}`);
+  
+  let routes, skipped, entryAppVars;
+  if (stack.framework === 'express') {
+    const res = parseExpressProject(opts.cwd, stack.entryFile);
+    routes = res.routes;
+    skipped = res.skipped;
+    s.stop(`Stack detected: Express (${stack.moduleType.toUpperCase()}) — entry: ${stack.entryFile}, port: ${stack.port}`);
+  } else if (stack.framework === 'fastapi') {
+    const res = parseFastAPIProject(opts.cwd, stack.entryFile, stack.pythonCmd);
+    routes = res.routes;
+    skipped = res.skipped;
+    entryAppVars = res.entryAppVars;
+    s.stop(`Stack detected: FastAPI — entry: ${stack.entryFile}, port: ${stack.port}`);
+  }
 
   if (routes.length === 0) {
-    throw Object.assign(new Error('0 routes extracted.'), { code: 'USER', hint: 'SPARDA found Express but no literal-path routes. Dynamic routing is not supported in v0.' });
+    throw Object.assign(new Error('0 routes extracted.'), { code: 'USER', hint: `SPARDA found ${stack.framework === 'express' ? 'Express' : 'FastAPI'} but no literal-path routes. Dynamic routing is not supported in v0.` });
   }
 
   let flaggedCount = 0;
@@ -52,7 +69,9 @@ export async function runInit(opts) {
     inject = answer;
   }
 
-  const result = generateExpress({ cwd: opts.cwd, entryFile: stack.entryFile, moduleType: stack.moduleType, port: stack.port, routes });
+  const result = stack.framework === 'express'
+    ? generateExpress({ cwd: opts.cwd, entryFile: stack.entryFile, moduleType: stack.moduleType, port: stack.port, routes })
+    : generateFastAPI({ cwd: opts.cwd, entryFile: stack.entryFile, port: stack.port, routes, entryAppVars, pythonCmd: stack.pythonCmd });
 
   fs.mkdirSync(path.join(opts.cwd, '.sparda'), { recursive: true });
   fs.writeFileSync(path.join(opts.cwd, '.sparda', 'scan-report.json'), JSON.stringify({ routes, skipped }, null, 2));
@@ -60,7 +79,7 @@ export async function runInit(opts) {
   p.log.success(`Generated ${result.routerFile}`);
   if (inject && result.injection.injected) p.log.success(`Injected into ${stack.entryFile} (backup: .sparda/backup/)`);
   else if (result.injection.manual) {
-    p.note(result.injection.manual.join('\n'), `Add these 2 lines to ${stack.entryFile} (after app = express())`);
+    p.note(result.injection.manual.join('\n'), `Add these lines to ${stack.entryFile} (after FastAPI/express instantiation)`);
   }
   p.log.success('Wrote sparda.json');
 
@@ -68,7 +87,7 @@ export async function runInit(opts) {
   p.outro(`Done in ${((Date.now() - t0) / 1000).toFixed(1)}s.
 
    Next steps:
-   1. Start your app:        npm run dev
+   1. Start your app:        ${stack.framework === 'express' ? 'npm run dev' : 'fastapi dev'}
    2. Start the MCP bridge:  npx sparda-mcp dev
    3. Add to Claude Desktop config (claude_desktop_config.json):
 

package/src/commands/remove.js

@@ -2,7 +2,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import * as p from '@clack/prompts';
-import { removeInjection } from '../generator/express.js';
+import { removeInjection as removeExpress } from '../generator/express.js';
+import { removeInjection as removeFastAPI } from '../generator/fastapi.js';
+import { detectStack } from '../detect.js';
 
 export async function runRemove(opts) {
   const manifestPath = path.join(opts.cwd, 'sparda.json');
@@ -12,11 +14,26 @@ export async function runRemove(opts) {
   const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
 
   if (!opts.yes) {
+    // clack crashes with uv_tty_init EBADF when stdin is not a TTY (CI, pipes)
+    if (!process.stdin.isTTY) {
+      throw Object.assign(new Error('Cannot ask for confirmation: stdin is not a TTY.'), { code: 'USER', hint: 'Re-run with --yes to skip the prompt.' });
+    }
     const ok = await p.confirm({ message: 'Remove SPARDA from this project? (deletes generated files + injected block)' });
     if (p.isCancel(ok) || !ok) { p.cancel('Aborted.'); process.exit(1); }
   }
 
-  const results = removeInjection(opts.cwd, manifest);
+  let pythonCmd = 'python';
+  try {
+    const stack = detectStack(opts.cwd);
+    if (stack.pythonCmd) pythonCmd = stack.pythonCmd;
+  } catch {
+    // ignore
+  }
+
+  const results = manifest.framework === 'fastapi'
+    ? removeFastAPI(opts.cwd, manifest, pythonCmd)
+    : removeExpress(opts.cwd, manifest);
+
   for (const r of results) {
     if (r.ok) console.log(`✓ Removed injection from ${r.file} (file still parses)`);
     else console.log(`✗ Could not safely remove from ${r.file} — restore from .sparda/backup/`);
@@ -25,8 +42,36 @@ export async function runRemove(opts) {
     const abs = path.resolve(opts.cwd, f);
     if (fs.existsSync(abs)) { fs.rmSync(abs); console.log(`✓ Deleted ${f}`); }
   }
+  if (revertGitignore(opts.cwd, manifest.gitignore)) console.log('✓ Reverted .gitignore edit');
   fs.rmSync(manifestPath);
   fs.rmSync(path.join(opts.cwd, '.sparda'), { recursive: true, force: true });
   console.log('✓ Deleted sparda.json and .sparda/');
-  console.log('\nSPARDA removed. `git diff` should be clean (minus a .gitignore line).');
+  console.log('\nSPARDA removed. `git diff` should be clean.');
+}
+
+// Undo exactly what init's ensureGitignore did (recorded in the manifest),
+// so init→remove leaves a byte-for-byte clean tree (hard rule #4, E-010).
+// Manifests written before v0.3.1 carry no `gitignore` field → no-op, as before.
+function revertGitignore(cwd, action) {
+  if (!action) return false;
+  const gi = path.join(cwd, '.gitignore');
+  if (!fs.existsSync(gi)) return false;
+  const content = fs.readFileSync(gi, 'utf8');
+  const created = `.sparda/\n`;
+  const appended = `\n.sparda/\n`;
+  if (action === 'created' && content === created) {
+    fs.rmSync(gi);
+    return true;
+  }
+  if (content.endsWith(appended)) {
+    fs.writeFileSync(gi, content.slice(0, -appended.length));
+    return true;
+  }
+  // user edited around our line since init — best effort: drop the bare line
+  const lines = content.split('\n');
+  const idx = lines.indexOf('.sparda/');
+  if (idx === -1) return false;
+  lines.splice(idx, 1);
+  fs.writeFileSync(gi, lines.join('\n'));
+  return true;
 }

package/src/commands/sync.js

@@ -0,0 +1,49 @@
+// commands/sync.js — sentinel: keep the generated router in sync with the routes
+import fs from 'node:fs';
+import path from 'node:path';
+import { detectStack } from '../detect.js';
+import { parseExpressProject } from '../parser/express.js';
+import { parseFastAPIProject } from '../parser/fastapi.js';
+import { sanitizeDescription } from '../security/sanitize.js';
+import { generateExpress } from '../generator/express.js';
+import { generateFastAPI } from '../generator/fastapi.js';
+
+export async function runSync(opts) {
+  const log = (m) => { if (!opts.quiet) console.error(m); };
+  const manifestPath = path.join(opts.cwd, 'sparda.json');
+  if (!fs.existsSync(manifestPath)) {
+    throw Object.assign(new Error('sparda.json not found.'), { code: 'USER', hint: 'Run `npx sparda-mcp init` first.' });
+  }
+  const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+  const stack = detectStack(opts.cwd);
+
+  let routes, entryAppVars;
+  if (stack.framework === 'express') {
+    ({ routes } = parseExpressProject(opts.cwd, stack.entryFile));
+  } else {
+    ({ routes, entryAppVars } = parseFastAPIProject(opts.cwd, stack.entryFile, stack.pythonCmd));
+  }
+  for (const r of routes) {
+    r.description = sanitizeDescription(r.description, `${r.method.toUpperCase()} ${r.path}`).text;
+  }
+
+  const current = new Set(Object.values(manifest.tools ?? {}).map((t) => `${t.method} ${t.path}`));
+  const next = new Set(routes.map((r) => `${r.method.toUpperCase()} ${r.path}`));
+  const added = [...next].filter((x) => !current.has(x));
+  const removed = [...current].filter((x) => !next.has(x));
+
+  if (added.length === 0 && removed.length === 0) {
+    log('[sparda] in sync — no route changes.');
+    return { changed: false, added, removed };
+  }
+
+  // regenerate; carry-over keeps enabled overrides, semantic cache and localKey
+  stack.framework === 'express'
+    ? generateExpress({ cwd: opts.cwd, entryFile: stack.entryFile, moduleType: stack.moduleType, port: manifest.port ?? stack.port, routes })
+    : generateFastAPI({ cwd: opts.cwd, entryFile: stack.entryFile, port: manifest.port ?? stack.port, routes, entryAppVars, pythonCmd: stack.pythonCmd });
+
+  for (const a of added) log(`[sparda] + ${a}`);
+  for (const r of removed) log(`[sparda] - ${r}`);
+  log(`[sparda] router regenerated (${added.length} added, ${removed.length} removed). Restart your app or let hot-reload pick it up.`);
+  return { changed: true, added, removed };
+}

package/src/detect.js

@@ -1,6 +1,7 @@
 // detect.js — framework, entry file, port detection (spec: blueprint 03-PARSING §A)
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 
 const err = (message, hint) => Object.assign(new Error(message), { code: 'USER', hint });
 
@@ -21,10 +22,102 @@ export function detectStack(cwd) {
   for (const f of ['requirements.txt', 'pyproject.toml']) {
     const p = path.join(cwd, f);
     if (fs.existsSync(p) && fs.readFileSync(p, 'utf8').toLowerCase().includes('fastapi')) {
-      throw err('FastAPI detected — Python support lands next release.', 'Watch the repo: github.com/zyx77550/sparda');
+      const entryFile = findFastAPIEntry(cwd);
+      const port = detectFastAPIPort(cwd, entryFile);
+      const pythonCmd = detectPython();
+      return { framework: 'fastapi', entryFile, port, pythonCmd };
     }
   }
-  throw err('No supported framework found (Express, FastAPI).', 'Run sparda inside your project root, next to package.json.');
+  throw err('No supported framework found (Express, FastAPI).', 'Run sparda-mcp inside your project root, next to package.json.');
+}
+
+function detectPython() {
+  const cmds = ['python3', 'python', 'py'];
+  for (const cmd of cmds) {
+    const args = cmd === 'py' ? ['-3', '--version'] : ['--version'];
+    try {
+      const res = spawnSync(cmd, args, { encoding: 'utf8', timeout: 2000 });
+      if (res.status === 0) {
+        const out = (res.stdout || res.stderr || '').trim();
+        const m = out.match(/Python\s+(\d+\.\d+\.\d+)/i);
+        if (m) {
+          const ver = m[1];
+          const [major, minor] = ver.split('.').map(Number);
+          if (major === 3 && minor >= 9) {
+            return cmd;
+          }
+        }
+      }
+    } catch {
+      // ignore
+    }
+  }
+  throw err('Python 3 (>= 3.9) introuvable dans le PATH.', 'Installe Python >= 3.9 pour utiliser SPARDA sur un projet FastAPI.');
+}
+
+function findFastAPIEntry(cwd) {
+  const candidates = [
+    'main.py', 'app.py', 'src/main.py', 'app/main.py'
+  ];
+  for (const rel of candidates) {
+    const abs = path.resolve(cwd, rel);
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile()) {
+      const src = fs.readFileSync(abs, 'utf8');
+      if (src.includes('FastAPI(')) {
+        return path.relative(cwd, abs).split(path.sep).join('/');
+      }
+    }
+  }
+  
+  const entry = searchPyFiles(cwd, cwd);
+  if (entry) {
+    return path.relative(cwd, entry).split(path.sep).join('/');
+  }
+
+  throw err('Could not locate your FastAPI entry file (the one calling FastAPI()).', 'Specify it manually, or make sure FastAPI() is declared in one of your python files.');
+}
+
+function searchPyFiles(dir, root, countRef = { val: 0 }) {
+  const EXCLUDE = new Set(['node_modules', '.git', 'venv', '.venv', 'tests', '__pycache__']);
+  let items;
+  try {
+    items = fs.readdirSync(dir);
+  } catch {
+    return null;
+  }
+
+  for (const item of items) {
+    const abs = path.join(dir, item);
+    let stat;
+    try {
+      stat = fs.statSync(abs);
+    } catch {
+      continue;
+    }
+
+    if (stat.isDirectory()) {
+      if (EXCLUDE.has(item)) continue;
+      const found = searchPyFiles(abs, root, countRef);
+      if (found) return found;
+    } else if (stat.isFile() && item.endsWith('.py')) {
+      countRef.val++;
+      if (countRef.val > 200) return null;
+      const src = fs.readFileSync(abs, 'utf8');
+      if (src.includes('FastAPI(')) {
+        return abs;
+      }
+    }
+  }
+  return null;
+}
+
+function detectFastAPIPort(cwd, entryFile) {
+  const abs = path.resolve(cwd, entryFile);
+  if (!fs.existsSync(abs)) return 8000;
+  const src = fs.readFileSync(abs, 'utf8');
+  const m = src.match(/uvicorn\.run\([^)]*port\s*=\s*(\d+)/s);
+  if (m) return Number(m[1]);
+  return 8000;
 }
 
 function findExpressEntry(cwd, pkg) {
@@ -77,6 +170,9 @@ function detectExpressPort(cwd, entryFile) {
       }
     }
   }
+  // env fallback literal, wrapped or not: Number(process.env.PORT ?? 4477), process.env.APP_PORT || 4488
+  m = src.match(/process\.env\.\w*PORT\w*\s*(?:\?\?|\|\|)\s*(\d{2,5})/i);
+  if (m) return Number(m[1]);
   // PORT env var or const PORT = 3000 pattern
   m = src.match(/(?:PORT|port)\s*=\s*(?:process\.env\.\w+\s*(?:\|\||\?\?)\s*)?(\d{2,5})/);
   if (m) return Number(m[1]);