sparda-mcp 0.1.0 → 0.3.0

package/src/generator/express.js

@@ -5,13 +5,14 @@ import crypto from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { parse } from '@babel/parser';
 import { toolNameFor } from '../parser/express.js';
+import { carryOverManifest } from './manifest.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const MARK_START = '// >>> sparda-injection (do not edit this block) >>>';
 const MARK_END = '// <<< sparda-injection <<<';
 
 export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
-  const taken = new Set(['sparda_info', 'sparda_list_disabled_tools']);
+  const taken = new Set(['sparda_info', 'sparda_list_disabled_tools', 'sparda_get_context']);
   const tools = {};
   for (const r of routes) {
     const name = toolNameFor(r, taken);
@@ -25,8 +26,10 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
       confidence: r.confidence,
     };
   }
+  const prev = carryOverManifest(cwd, tools);
 
-  const localKey = crypto.randomUUID();
+  // stable across re-runs so a running bridge/host pair never desyncs
+  const localKey = prev?.localKey ?? crypto.randomUUID();
   const entryAbs = path.resolve(cwd, entryFile);
   const entryDir = path.dirname(entryAbs);
   const ext = entryFile.endsWith('.ts') ? '.ts' : entryFile.endsWith('.mjs') ? '.mjs' : entryFile.endsWith('.cjs') ? '.cjs' : '.js';
@@ -36,20 +39,49 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
   // --- render router from template
   let tpl = fs.readFileSync(path.join(__dirname, '..', '..', 'templates', 'express-router.txt'), 'utf8');
   const isESM = moduleType === 'esm';
+  const isTS = ext === '.ts';
+
+  let importLine = '';
+  let reqType = '';
+  let resType = '';
+  let nextType = '';
+
+  if (isTS) {
+    reqType = ': Request';
+    resType = ': Response';
+    nextType = ': NextFunction';
+    if (isESM) {
+      importLine = "import express, { Request, Response, NextFunction } from 'express';";
+    } else {
+      importLine = "import type { Request, Response, NextFunction } from 'express';\nconst express = require('express');";
+    }
+  } else {
+    importLine = isESM ? "import express from 'express';" : "const express = require('express');";
+  }
+
   tpl = tpl
-    .replace('__IMPORT_LINE__', isESM ? "import express from 'express';" : "const express = require('express');")
+    .replace('__IMPORT_LINE__', importLine)
     .replace('__ROUTER_DECL__', isESM
       ? 'export const spardaRouter = express.Router();'
       : 'const spardaRouter = express.Router();\nmodule.exports = { spardaRouter };')
     .replace('__JSON_MW__', 'express.json()')
     .replace('__TOOLS_JSON__', JSON.stringify(tools, null, 2))
     .replace('__LOCAL_KEY__', localKey)
-    .replace('__PORT__', String(port));
+    .replace('__PORT__', String(port))
+    .replace(/__REQ_TYPE__/g, reqType)
+    .replace(/__RES_TYPE__/g, resType)
+    .replace(/__NEXT_TYPE__/g, nextType)
+    .replace(/__STATS_TYPE__/g, isTS ? ': Record<string, any>' : '')
+    .replace(/__EVENTS_TYPE__/g, isTS ? ': any[]' : '')
+    .replace(/__ANY_TYPE__/g, isTS ? ': any' : '');
   atomicWrite(routerAbs, tpl);
 
   // --- inject into entry file (line-based via AST positions)
   const injection = injectIntoEntry({ entryAbs, moduleType, routerFileName, cwd });
 
+  // record what init did to .gitignore so `remove` can revert it exactly (hard rule #4, E-010)
+  const gitignore = ensureGitignore(cwd) ?? prev?.gitignore ?? null;
+
   // --- manifest
   const manifest = {
     version: 1,
@@ -62,10 +94,12 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
     injectedFiles: injection.injected ? [entryFile] : [],
     createdAt: new Date().toISOString(),
     tools: Object.fromEntries(Object.entries(tools).map(([k, v]) => [k, { method: v.method, path: v.path, enabled: v.enabled }])),
+    ...(gitignore ? { gitignore } : {}),
+    ...(prev?.semantic ? { semantic: prev.semantic } : {}),
+    ...(prev?.immune ? { immune: prev.immune } : {}),
   };
   atomicWrite(path.join(cwd, 'sparda.json'), JSON.stringify(manifest, null, 2) + '\n');
 
-  ensureGitignore(cwd);
   return { tools, manifest, routerFile: path.relative(cwd, routerAbs).split(path.sep).join('/'), injection };
 }
 
@@ -165,15 +199,19 @@ export function removeInjection(cwd, manifest) {
   return results;
 }
 
+// Returns what was done ('created' | 'appended' | null) so the manifest can
+// record it and `remove` can revert the exact edit (byte-for-byte promise).
 function ensureGitignore(cwd) {
   const gi = path.join(cwd, '.gitignore');
   const line = '.sparda/';
   if (fs.existsSync(gi)) {
     const content = fs.readFileSync(gi, 'utf8');
-    if (!content.split(/\r?\n/).includes(line)) fs.appendFileSync(gi, `\n${line}\n`);
-  } else {
-    fs.writeFileSync(gi, `${line}\n`);
+    if (content.split(/\r?\n/).includes(line)) return null;
+    fs.appendFileSync(gi, `\n${line}\n`);
+    return 'appended';
   }
+  fs.writeFileSync(gi, `${line}\n`);
+  return 'created';
 }
 
 function atomicWrite(file, content) {

package/src/generator/fastapi.js

@@ -0,0 +1,211 @@
+// generator/fastapi.js — router generation + python injection (spec: blueprint 04-GENERATION §A)
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { toolNameFor } from '../parser/express.js';
+import { carryOverManifest } from './manifest.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const MARK_START = '# >>> sparda-injection (do not edit this block) >>>';
+const MARK_END = '# <<< sparda-injection <<<';
+
+export function generateFastAPI({ cwd, entryFile, port, routes, entryAppVars, pythonCmd = 'python' }) {
+  const taken = new Set(['sparda_info', 'sparda_list_disabled_tools', 'sparda_get_context']);
+  const tools = {};
+  for (const r of routes) {
+    const name = toolNameFor(r, taken);
+    tools[name] = {
+      method: r.method.toUpperCase(),
+      path: r.path,
+      enabled: !r.mutating,             // write-safety: mutating tools off by default
+      pathParams: r.params.filter((p) => p.in === 'path').map((p) => p.name),
+      description: r.description,
+      params: r.params,
+      confidence: r.confidence,
+    };
+  }
+  const prev = carryOverManifest(cwd, tools);
+
+  // stable across re-runs so a running bridge/host pair never desyncs
+  const localKey = prev?.localKey ?? crypto.randomUUID();
+  const entryAbs = path.resolve(cwd, entryFile);
+  const entryDir = path.dirname(entryAbs);
+  const routerFileName = 'sparda_router.py';
+  const routerAbs = path.join(entryDir, routerFileName);
+
+  // --- render router from template
+  let tpl = fs.readFileSync(path.join(__dirname, '..', '..', 'templates', 'fastapi-router.txt'), 'utf8');
+  tpl = tpl
+    // double-stringify: a JSON string literal is also a valid Python string literal,
+    // and json.loads() in the template turns it into real Python values (E-009)
+    .replace('__TOOLS_JSON__', JSON.stringify(JSON.stringify(tools)))
+    .replace('__LOCAL_KEY__', localKey)
+    .replace('__PORT__', String(port));
+
+  atomicWrite(routerAbs, tpl);
+
+  // --- inject into entry file (regex-based with compilation safety check)
+  const injection = injectIntoEntry({ entryAbs, routerFileName, cwd, entryAppVars, pythonCmd });
+
+  // record what init did to .gitignore so `remove` can revert it exactly (hard rule #4, E-010)
+  const gitignore = ensureGitignore(cwd) ?? prev?.gitignore ?? null;
+
+  // --- manifest
+  const manifest = {
+    version: 1,
+    framework: 'fastapi',
+    entryFile,
+    port,
+    localKey,
+    generatedFiles: [path.relative(cwd, routerAbs).split(path.sep).join('/')],
+    injectedFiles: injection.injected ? [entryFile] : [],
+    createdAt: new Date().toISOString(),
+    tools: Object.fromEntries(Object.entries(tools).map(([k, v]) => [k, { method: v.method, path: v.path, enabled: v.enabled }])),
+    ...(gitignore ? { gitignore } : {}),
+    ...(prev?.semantic ? { semantic: prev.semantic } : {}),
+    ...(prev?.immune ? { immune: prev.immune } : {}),
+  };
+
+  atomicWrite(path.join(cwd, 'sparda.json'), JSON.stringify(manifest, null, 2) + '\n');
+
+  return { tools, manifest, routerFile: path.relative(cwd, routerAbs).split(path.sep).join('/'), injection };
+}
+
+function injectIntoEntry({ entryAbs, routerFileName, cwd, entryAppVars, pythonCmd }) {
+  const src = fs.readFileSync(entryAbs, 'utf8');
+  
+  // backup first
+  const backupDir = path.join(cwd, '.sparda', 'backup');
+  fs.mkdirSync(backupDir, { recursive: true });
+  fs.writeFileSync(path.join(backupDir, `${path.basename(entryAbs)}.${Date.now()}`), src);
+
+  // Determine if directory has __init__.py (relative vs absolute import)
+  const entryDir = path.dirname(entryAbs);
+  const hasInit = fs.existsSync(path.join(entryDir, '__init__.py'));
+  const importLine = hasInit
+    ? 'from .sparda_router import sparda_router'
+    : 'from sparda_router import sparda_router';
+
+  // preserve the file's own line endings (Windows checkouts are CRLF)
+  const eol = src.includes('\r\n') ? '\r\n' : '\n';
+
+  // strip previous injection blocks (idempotence)
+  let body = src;
+  const blockRx = new RegExp(`\\r?\\n?${escapeRx(MARK_START)}[\\s\\S]*?${escapeRx(MARK_END)}\\r?\\n?`, 'g');
+  body = body.replace(blockRx, eol);
+
+  // Let's find the FastAPI() call assignment to inject right after it
+  // ([ \t]*) — NOT (\s*): \s matches newlines and would swallow blank lines/CR into the "indent" (E-007)
+  const match = body.match(/^([ \t]*)(\w+)\s*=\s*(?:\w+\.)?FastAPI\(/m);
+  if (!match) {
+    return {
+      injected: false,
+      manual: [importLine, 'app.include_router(sparda_router, prefix="/mcp")']
+    };
+  }
+
+  const indent = match[1];
+  const appName = match[2];
+
+  // Prepare injection block
+  const useBlock = [
+    MARK_START,
+    `${indent}${importLine}`,
+    `${indent}${appName}.include_router(sparda_router, prefix="/mcp")`,
+    MARK_END
+  ];
+
+  // We find where the matching line starts and ends in order to insert right after it.
+  const lines = body.split(/\r?\n/);
+  let insertAt = -1;
+  const linePattern = new RegExp(`^[ \\t]*${appName}\\s*=\\s*(?:\\w+\\.)?FastAPI\\(`);
+  for (let i = 0; i < lines.length; i++) {
+    if (linePattern.test(lines[i])) {
+      insertAt = i + 1; // Insert AFTER this line
+      break;
+    }
+  }
+
+  if (insertAt === -1) {
+    return {
+      injected: false,
+      manual: [importLine, `${appName}.include_router(sparda_router, prefix="/mcp")`]
+    };
+  }
+
+  lines.splice(insertAt, 0, ...useBlock);
+  const out = lines.join(eol);
+
+  // Post-injection compilation check to avoid syntax errors
+  if (!verifyPythonSyntax(entryAbs, out, pythonCmd)) {
+    return {
+      injected: false,
+      manual: [importLine, `${appName}.include_router(sparda_router, prefix="/mcp")`]
+    };
+  }
+
+  atomicWrite(entryAbs, out);
+  return { injected: true, manual: null };
+}
+
+export function removeInjection(cwd, manifest, pythonCmd = 'python') {
+  const results = [];
+  for (const relFile of manifest.injectedFiles ?? []) {
+    const abs = path.resolve(cwd, relFile);
+    if (!fs.existsSync(abs)) continue;
+    const src = fs.readFileSync(abs, 'utf8');
+    const blockRx = new RegExp(`\\r?\\n?${escapeRx(MARK_START)}[\\s\\S]*?${escapeRx(MARK_END)}`, 'g');
+    const out = src.replace(blockRx, '');
+    
+    if (verifyPythonSyntax(abs, out, pythonCmd)) {
+      atomicWrite(abs, out);
+      results.push({ file: relFile, ok: true });
+    } else {
+      results.push({ file: relFile, ok: false });
+    }
+  }
+  return results;
+}
+
+function verifyPythonSyntax(filePath, content, pythonCmd) {
+  const tmpFile = `${filePath}.syntax-check.py`;
+  try {
+    fs.writeFileSync(tmpFile, content);
+    const args = pythonCmd === 'py' ? ['-3', '-m', 'py_compile', tmpFile] : ['-m', 'py_compile', tmpFile];
+    const res = spawnSync(pythonCmd, args, { timeout: 2000 });
+    return res.status === 0;
+  } catch {
+    return false;
+  } finally {
+    try {
+      if (fs.existsSync(tmpFile)) fs.unlinkSync(tmpFile);
+    } catch {
+      // ignore
+    }
+  }
+}
+
+// Returns what was done ('created' | 'appended' | null) so the manifest can
+// record it and `remove` can revert the exact edit (byte-for-byte promise).
+function ensureGitignore(cwd) {
+  const gi = path.join(cwd, '.gitignore');
+  const line = '.sparda/';
+  if (fs.existsSync(gi)) {
+    const content = fs.readFileSync(gi, 'utf8');
+    if (content.split(/\r?\n/).includes(line)) return null;
+    fs.appendFileSync(gi, `\n${line}\n`);
+    return 'appended';
+  }
+  fs.writeFileSync(gi, `${line}\n`);
+  return 'created';
+}
+
+function atomicWrite(file, content) {
+  const tmp = `${file}.sparda-tmp`;
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, file);
+}
+
+function escapeRx(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }

package/src/generator/manifest.js

@@ -0,0 +1,23 @@
+// generator/manifest.js — carry user state across re-runs of `sparda init`
+import fs from 'node:fs';
+import path from 'node:path';
+
+// Re-running init must not wipe what the user (or the semantic/immune passes)
+// wrote into sparda.json: per-tool `enabled` overrides, the cached `semantic`
+// enrichment and the `immune` memory (antibodies) survive as long as the
+// tool's method+path are unchanged.
+export function carryOverManifest(cwd, tools) {
+  let prev = null;
+  try {
+    prev = JSON.parse(fs.readFileSync(path.join(cwd, 'sparda.json'), 'utf8'));
+  } catch {
+    return null;
+  }
+  for (const [name, t] of Object.entries(tools)) {
+    const old = prev?.tools?.[name];
+    if (old && typeof old.enabled === 'boolean' && old.method === t.method && old.path === t.path) {
+      t.enabled = old.enabled;
+    }
+  }
+  return prev;
+}

package/src/index.js

@@ -1,5 +1,8 @@
 #!/usr/bin/env node
 // SPARDA — Turn any codebase into an MCP server. Residual Labs.
+import { readFileSync } from 'node:fs';
+
+const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
 const [, , cmd, ...rest] = process.argv;
 
 const flags = new Set(rest.filter((a) => a.startsWith('--')));
@@ -11,6 +14,7 @@ const getOpt = (name, dflt) => {
 const opts = {
   yes: flags.has('--yes') || flags.has('-y'),
   verbose: flags.has('--verbose'),
+  quiet: flags.has('--quiet'),
   port: getOpt('port', null),
   cwd: process.cwd(),
 };
@@ -34,19 +38,34 @@ try {
     }
     case 'doctor': {
       const { runDoctor } = await import('./commands/doctor.js');
-      await runDoctor(opts);
+      const { healthy } = await runDoctor(opts);
+      if (!healthy) process.exitCode = 1; // let scripts/CI gate on doctor
+      break;
+    }
+    case 'sync': {
+      const { runSync } = await import('./commands/sync.js');
+      await runSync(opts);
+      break;
+    }
+    case 'hook': {
+      const { runHook } = await import('./commands/hook.js');
+      await runHook(opts);
       break;
     }
     default:
-      console.log(`SPARDA v0.1.0 — Turn any codebase into an MCP server.
+      console.log(`SPARDA v${VERSION} — Turn any codebase into an MCP server.
 
 Usage:
   npx sparda-mcp init      Scan project, generate & inject the MCP router
   npx sparda-mcp dev       Run the MCP stdio bridge (connect Claude Desktop)
+  npx sparda-mcp sync      Re-sync the router after route changes (no prompts)
+  npx sparda-mcp hook      Install the git sentinel (auto-sync after commits)
   npx sparda-mcp remove    Remove SPARDA from this project (clean git diff)
   npx sparda-mcp doctor    Diagnose your setup
 
-Flags: --yes (skip prompts)  --port <n>  --verbose`);
+Flags: --yes (skip prompts)  --port <n>  --quiet  --verbose
+
+By Residual Labs — residual-labs.fr`);
       process.exit(cmd ? 1 : 0);
   }
 } catch (err) {

package/src/parser/express.js

@@ -50,16 +50,29 @@ export function parseExpressProject(cwd, entryFile) {
     traverse(ast, {
       VariableDeclarator(p) {
         const init = p.node.init;
-        const name = p.node.id?.name;
-        if (!name || !init) return;
+        if (!init) return;
         if (init.type === 'CallExpression') {
           const callee = init.callee;
-          if (callee.type === 'Identifier' && callee.name === 'express') { appVars.add(name); exprStarts.add(p.node.loc.end.line); }
-          if (callee.type === 'Identifier' && callee.name === 'Router') routerVars.add(name);
-          if (callee.type === 'MemberExpression' && callee.property?.name === 'Router') routerVars.add(name);
           if (callee.type === 'Identifier' && callee.name === 'require' && init.arguments[0]?.type === 'StringLiteral') {
             const resolved = resolveRel(absFile, init.arguments[0].value);
-            if (resolved) importMap.set(name, resolved);
+            if (resolved) {
+              const id = p.node.id;
+              if (id.type === 'Identifier') {
+                importMap.set(id.name, resolved);
+              } else if (id.type === 'ObjectPattern') {
+                for (const prop of id.properties) {
+                  if (prop.type === 'ObjectProperty' && prop.value.type === 'Identifier') {
+                    importMap.set(prop.value.name, resolved);
+                  }
+                }
+              }
+            }
+          }
+          const name = p.node.id?.name;
+          if (name) {
+            if (callee.type === 'Identifier' && callee.name === 'express') { appVars.add(name); exprStarts.add(p.node.loc.end.line); }
+            if (callee.type === 'Identifier' && callee.name === 'Router') routerVars.add(name);
+            if (callee.type === 'MemberExpression' && callee.property?.name === 'Router') routerVars.add(name);
           }
         }
       },
@@ -97,6 +110,11 @@ export function parseExpressProject(cwd, entryFile) {
         }
 
         const fullPath = joinPath(prefix, pathArg.value);
+        if (fullPath.startsWith('/mcp')) {
+          skipped.push({ reason: `self-referential path ${fullPath} blocked`, file: rel(absFile), line: p.node.loc?.start.line });
+          return;
+        }
+
         const handler = args[args.length - 1];
         const handlerName = handler?.type === 'Identifier' ? handler.name
           : handler?.id?.name ?? `anonymous_${routes.length + 1}`;
@@ -141,7 +159,8 @@ export function parseExpressProject(cwd, entryFile) {
 
   function resolveRel(fromFile, spec) {
     if (!spec.startsWith('.')) return null;
-    const base = path.resolve(path.dirname(fromFile), spec);
+    const cleanSpec = spec.replace(/\.(m?[jt]s|cjs)$/, '');
+    const base = path.resolve(path.dirname(fromFile), cleanSpec);
     for (const cand of [base, `${base}.ts`, `${base}.js`, `${base}.mjs`, `${base}.cjs`,
       path.join(base, 'index.ts'), path.join(base, 'index.js')]) {
       if (fs.existsSync(cand) && fs.statSync(cand).isFile()) {
@@ -172,6 +191,7 @@ export function toolNameFor(route, taken) {
   let name = `${route.method}_${route.path}`
     .toLowerCase()
     .replace(/:(\w+)/g, 'by_$1')
+    .replace(/\{(\w+)\}/g, 'by_$1')
     .replace(/[^a-z0-9]+/g, '_')
     .replace(/^_+|_+$/g, '')
     .slice(0, 60) || 'tool';

package/src/parser/fastapi.js

@@ -0,0 +1,26 @@
+// parser/fastapi.js — JS wrapper executing Python AST extractor (spec: blueprint 03-PARSING §C)
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export function parseFastAPIProject(cwd, entryFile, pythonCmd = 'python') {
+  const extractorScript = path.resolve(__dirname, 'fastapi_extract.py');
+  const res = spawnSync(pythonCmd, [extractorScript, entryFile, cwd], { cwd, encoding: 'utf8' });
+  
+  if (res.status !== 0) {
+    const errorMsg = (res.stderr || res.stdout || '').trim();
+    throw new Error(`FastAPI extraction process failed: ${errorMsg}`);
+  }
+
+  try {
+    const payload = JSON.parse(res.stdout.trim());
+    if (payload.error) {
+      throw new Error(payload.error);
+    }
+    return { routes: payload.routes || [], skipped: payload.skipped || [], entryAppVars: payload.entryAppVars || [] };
+  } catch (err) {
+    throw new Error(`Failed to parse Python extractor output: ${err.message}. Raw output: ${res.stdout}`);
+  }
+}