sparda-mcp 0.5.2 → 0.5.4

package/src/generator/express.js

@@ -13,14 +13,18 @@ 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', 'sparda_get_context']);
+  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
+      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,
@@ -44,7 +48,9 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
         tool: name,
         decision: 'audit',
         risk: 'medium',
-        reasons: [`route structure modified (fingerprint changed from ${oldFp} to ${fp})`],
+        reasons: [
+          `route structure modified (fingerprint changed from ${oldFp} to ${fp})`,
+        ],
       });
       if (sparding.events.length > 100) sparding.events.shift();
     }
@@ -55,12 +61,21 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
   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';
+  const ext = entryFile.endsWith('.ts')
+    ? '.ts'
+    : entryFile.endsWith('.mjs')
+      ? '.mjs'
+      : entryFile.endsWith('.cjs')
+        ? '.cjs'
+        : '.js';
   const routerFileName = `sparda-router${ext}`;
   const routerAbs = path.join(entryDir, routerFileName);
 
   // --- render router from template
-  let tpl = fs.readFileSync(path.join(__dirname, '..', '..', 'templates', 'express-router.txt'), 'utf8');
+  let tpl = fs.readFileSync(
+    path.join(__dirname, '..', '..', 'templates', 'express-router.txt'),
+    'utf8',
+  );
   const isESM = moduleType === 'esm';
   const isTS = ext === '.ts';
 
@@ -76,19 +91,25 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
     if (isESM) {
       importLine = "import express, { Request, Response, NextFunction } from 'express';";
     } else {
-      importLine = "import type { Request, Response, NextFunction } from 'express';\nconst express = require('express');";
+      importLine =
+        "import type { Request, Response, NextFunction } from 'express';\nconst express = require('express');";
     }
   } else {
-    importLine = isESM ? "import express from 'express';" : "const express = require('express');";
+    importLine = isESM
+      ? "import express from 'express';"
+      : "const express = require('express');";
   }
 
   tpl = tpl
     .replace('__IMPORT_LINE__', importLine)
     .replace('__SPARDING_POLICIES__', JSON.stringify(sparding.policies ?? {}))
-    .replace('__ROUTER_DECL__', isESM
-      ? 'export const spardaRouter = express.Router();'
-      : 'const spardaRouter = express.Router();\nmodule.exports = { spardaRouter };')
-    .replace('__JSON_MW__', 'express.json()')
+    .replace(
+      '__ROUTER_DECL__',
+      isESM
+        ? 'export const spardaRouter = express.Router();'
+        : 'const spardaRouter = express.Router();\nmodule.exports = { spardaRouter };',
+    )
+    .replace('__JSON_MW__', "express.json({ limit: '64kb' })")
     .replace('__TOOLS_JSON__', JSON.stringify(tools, null, 2))
     .replace('__LOCAL_KEY__', localKey)
     .replace('__PORT__', String(port))
@@ -117,7 +138,12 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
     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 }])),
+    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 } : {}),
@@ -126,7 +152,12 @@ export function generateExpress({ cwd, entryFile, moduleType, port, routes }) {
   };
   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 };
+  return {
+    tools,
+    manifest,
+    routerFile: path.relative(cwd, routerAbs).split(path.sep).join('/'),
+    injection,
+  };
 }
 
 function injectIntoEntry({ entryAbs, moduleType, routerFileName, cwd }) {
@@ -136,19 +167,31 @@ function injectIntoEntry({ entryAbs, moduleType, routerFileName, cwd }) {
   fs.mkdirSync(backupDir, { recursive: true });
   fs.writeFileSync(path.join(backupDir, `${path.basename(entryAbs)}.${Date.now()}`), src);
 
-  const importSpec = `./${routerFileName.replace(/\.(ts|js|mjs|cjs)$/, moduleType === 'esm' && routerFileName.endsWith('.js') ? '.js' : '')}`.replace(/\.$/, '');
-  const importLine = moduleType === 'esm'
-    ? `import { spardaRouter } from '${importSpec}';`
-    : `const { spardaRouter } = require('${importSpec}');`;
+  const importSpec =
+    `./${routerFileName.replace(/\.(ts|js|mjs|cjs)$/, moduleType === 'esm' && routerFileName.endsWith('.js') ? '.js' : '')}`.replace(
+      /\.$/,
+      '',
+    );
+  const importLine =
+    moduleType === 'esm'
+      ? `import { spardaRouter } from '${importSpec}';`
+      : `const { spardaRouter } = require('${importSpec}');`;
 
   // strip previous injection blocks (idempotence)
   let body = src;
-  const blockRx = new RegExp(`\\n?${escapeRx(MARK_START)}[\\s\\S]*?${escapeRx(MARK_END)}\\n?`, 'g');
+  const blockRx = new RegExp(
+    `\\n?${escapeRx(MARK_START)}[\\s\\S]*?${escapeRx(MARK_END)}\\n?`,
+    'g',
+  );
   body = body.replace(blockRx, '\n');
 
   let ast;
   try {
-    ast = parse(body, { sourceType: 'unambiguous', plugins: ['typescript', 'jsx'], attachComment: false });
+    ast = parse(body, {
+      sourceType: 'unambiguous',
+      plugins: ['typescript', 'jsx'],
+      attachComment: false,
+    });
   } catch {
     return manualFallback(importLine);
   }
@@ -160,7 +203,8 @@ function injectIntoEntry({ entryAbs, moduleType, routerFileName, cwd }) {
   let appName = 'app';
 
   for (const node of ast.program.body) {
-    if (node.type === 'ImportDeclaration') lastImportLine = Math.max(lastImportLine, node.loc.end.line);
+    if (node.type === 'ImportDeclaration')
+      lastImportLine = Math.max(lastImportLine, node.loc.end.line);
     if (node.type === 'VariableDeclaration') {
       for (const d of node.declarations) {
         if (d.init?.type === 'CallExpression' && d.init.callee?.name === 'express') {
@@ -172,18 +216,27 @@ function injectIntoEntry({ entryAbs, moduleType, routerFileName, cwd }) {
         }
       }
     }
-    if (node.type === 'ExpressionStatement' &&
-        node.expression.type === 'CallExpression' &&
-        node.expression.callee?.property?.name === 'listen') {
+    if (
+      node.type === 'ExpressionStatement' &&
+      node.expression.type === 'CallExpression' &&
+      node.expression.callee?.property?.name === 'listen'
+    ) {
       listenLine = node.loc.start.line;
     }
   }
 
-  const useBlock = [MARK_START, importLine, `${appName}.use('/mcp', spardaRouter);`, MARK_END];
+  const useBlock = [
+    MARK_START,
+    importLine,
+    `${appName}.use('/mcp', spardaRouter);`,
+    MARK_END,
+  ];
 
   let insertAt; // 0-based index AFTER which we DON'T insert; we splice before index
-  if (appAssignLine !== null) insertAt = appAssignLine;        // after app = express()
-  else if (listenLine !== null) insertAt = listenLine - 1;      // before app.listen
+  if (appAssignLine !== null)
+    insertAt = appAssignLine; // after app = express()
+  else if (listenLine !== null)
+    insertAt = listenLine - 1; // before app.listen
   else return manualFallback(importLine);
 
   lines.splice(insertAt, 0, ...useBlock);
@@ -212,7 +265,10 @@ export function removeInjection(cwd, manifest) {
     const abs = path.resolve(cwd, relFile);
     if (!fs.existsSync(abs)) continue;
     const src = fs.readFileSync(abs, 'utf8');
-    const blockRx = new RegExp(`\\n?${escapeRx(MARK_START)}[\\s\\S]*?${escapeRx(MARK_END)}`, 'g');
+    const blockRx = new RegExp(
+      `\\n?${escapeRx(MARK_START)}[\\s\\S]*?${escapeRx(MARK_END)}`,
+      'g',
+    );
     const out = src.replace(blockRx, '');
     try {
       parse(out, { sourceType: 'unambiguous', plugins: ['typescript', 'jsx'] });
@@ -240,4 +296,6 @@ function ensureGitignore(cwd) {
   return 'created';
 }
 
-function escapeRx(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+function escapeRx(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/generator/fastapi.js

@@ -12,15 +12,26 @@ 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']);
+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
+      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,
@@ -44,7 +55,9 @@ export function generateFastAPI({ cwd, entryFile, port, routes, entryAppVars, py
         tool: name,
         decision: 'audit',
         risk: 'medium',
-        reasons: [`route structure modified (fingerprint changed from ${oldFp} to ${fp})`],
+        reasons: [
+          `route structure modified (fingerprint changed from ${oldFp} to ${fp})`,
+        ],
       });
       if (sparding.events.length > 100) sparding.events.shift();
     }
@@ -59,19 +72,31 @@ export function generateFastAPI({ cwd, entryFile, port, routes, entryAppVars, py
   const routerAbs = path.join(entryDir, routerFileName);
 
   // --- render router from template
-  let tpl = fs.readFileSync(path.join(__dirname, '..', '..', 'templates', 'fastapi-router.txt'), 'utf8');
+  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('__SPARDING_POLICIES__', JSON.stringify(JSON.stringify(sparding.policies ?? {})))
+    .replace(
+      '__SPARDING_POLICIES__',
+      JSON.stringify(JSON.stringify(sparding.policies ?? {})),
+    )
     .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 });
+  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;
@@ -86,7 +111,12 @@ export function generateFastAPI({ cwd, entryFile, port, routes, entryAppVars, py
     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 }])),
+    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 } : {}),
@@ -96,12 +126,17 @@ export function generateFastAPI({ cwd, entryFile, port, routes, entryAppVars, py
 
   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 };
+  return {
+    tools,
+    manifest,
+    routerFile: path.relative(cwd, routerAbs).split(path.sep).join('/'),
+    injection,
+  };
 }
 
-function injectIntoEntry({ entryAbs, routerFileName, cwd, entryAppVars, pythonCmd }) {
+function injectIntoEntry({ entryAbs, cwd, pythonCmd }) {
   const src = fs.readFileSync(entryAbs, 'utf8');
-  
+
   // backup first
   const backupDir = path.join(cwd, '.sparda', 'backup');
   fs.mkdirSync(backupDir, { recursive: true });
@@ -119,7 +154,10 @@ function injectIntoEntry({ entryAbs, routerFileName, cwd, entryAppVars, pythonCm
 
   // 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');
+  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
@@ -128,7 +166,7 @@ function injectIntoEntry({ entryAbs, routerFileName, cwd, entryAppVars, pythonCm
   if (!match) {
     return {
       injected: false,
-      manual: [importLine, 'app.include_router(sparda_router, prefix="/mcp")']
+      manual: [importLine, 'app.include_router(sparda_router, prefix="/mcp")'],
     };
   }
 
@@ -140,7 +178,7 @@ function injectIntoEntry({ entryAbs, routerFileName, cwd, entryAppVars, pythonCm
     MARK_START,
     `${indent}${importLine}`,
     `${indent}${appName}.include_router(sparda_router, prefix="/mcp")`,
-    MARK_END
+    MARK_END,
   ];
 
   // We find where the matching line starts and ends in order to insert right after it.
@@ -157,7 +195,7 @@ function injectIntoEntry({ entryAbs, routerFileName, cwd, entryAppVars, pythonCm
   if (insertAt === -1) {
     return {
       injected: false,
-      manual: [importLine, `${appName}.include_router(sparda_router, prefix="/mcp")`]
+      manual: [importLine, `${appName}.include_router(sparda_router, prefix="/mcp")`],
     };
   }
 
@@ -168,7 +206,7 @@ function injectIntoEntry({ entryAbs, routerFileName, cwd, entryAppVars, pythonCm
   if (!verifyPythonSyntax(entryAbs, out, pythonCmd)) {
     return {
       injected: false,
-      manual: [importLine, `${appName}.include_router(sparda_router, prefix="/mcp")`]
+      manual: [importLine, `${appName}.include_router(sparda_router, prefix="/mcp")`],
     };
   }
 
@@ -182,9 +220,12 @@ export function removeInjection(cwd, manifest, pythonCmd = 'python') {
     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 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 });
@@ -199,7 +240,10 @@ 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 args =
+      pythonCmd === 'py'
+        ? ['-3', '-m', 'py_compile', tmpFile]
+        : ['-m', 'py_compile', tmpFile];
     // py_compile cold-starts slowly on Windows; a 2s budget falsely failed clean
     // removals (rule #4) and post-injection checks under load. 5s matches the
     // test-side syntax budget and only bounds the worst case, never the happy path.
@@ -231,4 +275,6 @@ function ensureGitignore(cwd) {
   return 'created';
 }
 
-function escapeRx(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
+function escapeRx(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}

package/src/generator/manifest.js

@@ -16,7 +16,12 @@ export function carryOverManifest(cwd, tools) {
   }
   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) {
+    if (
+      old &&
+      typeof old.enabled === 'boolean' &&
+      old.method === t.method &&
+      old.path === t.path
+    ) {
       t.enabled = old.enabled;
     }
   }
@@ -24,16 +29,18 @@ export function carryOverManifest(cwd, tools) {
 }
 
 export function defaultSpardingMemory(prev) {
-  return prev?.sparding ?? {
-    version: 1,
-    policies: {
-      reads: 'allow',
-      writes: 'require_human',
-      deletes: 'block',
-      requireProofAfterWrite: true,
-    },
-    events: [],
-    failures: {},
-    toolFingerprints: {},
-  };
+  return (
+    prev?.sparding ?? {
+      version: 1,
+      policies: {
+        reads: 'allow',
+        writes: 'require_human',
+        deletes: 'block',
+        requireProofAfterWrite: true,
+      },
+      events: [],
+      failures: {},
+      toolFingerprints: {},
+    }
+  );
 }

package/src/index.js

@@ -2,7 +2,9 @@
 // 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 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('--')));
@@ -16,12 +18,19 @@ const opts = {
   verbose: flags.has('--verbose'),
   quiet: flags.has('--quiet'),
   probe: flags.has('--probe'),
+  html: flags.has('--html'),
+  json: flags.has('--json'),
   port: getOpt('port', null),
   cwd: process.cwd(),
 };
 
 try {
   switch (cmd) {
+    case 'demo': {
+      const { runDemo } = await import('./commands/demo.js');
+      await runDemo(opts);
+      break;
+    }
     case 'init': {
       const { runInit } = await import('./commands/init.js');
       await runInit(opts);
@@ -53,19 +62,27 @@ try {
       await runHook(opts);
       break;
     }
+    case 'report': {
+      const { runReport } = await import('./commands/report.js');
+      await runReport(opts);
+      break;
+    }
     default:
       console.log(`SPARDA v${VERSION} — Turn any codebase into an MCP server.
 
 Usage:
+  npx sparda-mcp demo      Guided tour on a bundled app — no setup, nothing touched
   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
+  npx sparda-mcp report    The black box: what AI agents did to this app
 
 Flags: --yes (skip prompts)  --port <n>  --quiet  --verbose
        --probe (init: also run the app to discover dynamic routes the AST missed)
+       --html / --json (report: write .sparda/report.html / print raw JSON)
 
 By Residual Labs — residual-labs.fr`);
       process.exit(cmd ? 1 : 0);
@@ -74,6 +91,9 @@ By Residual Labs — residual-labs.fr`);
   console.error(`\n✗ ${err?.message ?? err}`);
   if (err?.hint) console.error(`  → ${err.hint}`);
   if (opts.verbose && err?.stack) console.error(err.stack);
-  else console.error('  (run with --verbose for details — or open an issue: github.com/zyx77550/sparda/issues)');
+  else
+    console.error(
+      '  (run with --verbose for details — or open an issue: github.com/zyx77550/sparda/issues)',
+    );
   process.exit(err?.code === 'USER' ? 1 : 2);
 }