sparda-mcp 0.3.0 → 0.5.0

package/src/ui/style.js

@@ -0,0 +1,66 @@
+// ui/style.js — zero-dep ANSI styling for the HUMAN commands (init, remove,
+// doctor). Never import this from the bridge path: there, stdout is the MCP
+// protocol (hard rule #2) and stderr must stay grep-able plain text.
+
+// SPARDA identity: violet → cyan, same stops as the brand gradient
+const VIOLET = [192, 132, 252]; // #c084fc
+const CYAN = [103, 232, 249];   // #67e8f9
+const RESET = '\x1b[0m';
+
+// evaluated per call so tests (and runtime env changes) see the truth;
+// honors https://no-color.org and the FORCE_COLOR convention
+function enabled() {
+  if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== '0') return true;
+  if (process.env.NO_COLOR !== undefined) return false;
+  return Boolean(process.stdout.isTTY) && process.env.TERM !== 'dumb';
+}
+
+function truecolor() {
+  return /truecolor|24bit/i.test(process.env.COLORTERM ?? '') ||
+    ['iTerm.app', 'vscode', 'WezTerm', 'ghostty'].includes(process.env.TERM_PROGRAM ?? '') ||
+    Boolean(process.env.WT_SESSION);
+}
+
+const sgr = (open) => (s) => (enabled() ? `\x1b[${open}m${s}${RESET}` : String(s));
+
+export const c = {
+  dim: sgr('2'),
+  bold: sgr('1'),
+  green: sgr('32'),
+  yellow: sgr('33'),
+  red: sgr('31'),
+  cyan: sgr('38;5;117'),
+  violet: sgr('38;5;177'),
+};
+
+// the brand banner: per-character violet→cyan interpolation in truecolor,
+// a stepped 256-color ramp elsewhere, plain text when colors are off
+export function gradient(text) {
+  if (!enabled()) return text;
+  const chars = [...text];
+  if (truecolor()) {
+    const body = chars.map((ch, i) => {
+      const t = chars.length === 1 ? 0 : i / (chars.length - 1);
+      const [r, g, b] = VIOLET.map((v, k) => Math.round(v + (CYAN[k] - v) * t));
+      return `\x1b[1m\x1b[38;2;${r};${g};${b}m${ch}`;
+    }).join('');
+    return body + RESET;
+  }
+  const ramp = [177, 141, 147, 153, 117];
+  const body = chars.map((ch, i) => {
+    const step = ramp[Math.min(ramp.length - 1, Math.floor((i / chars.length) * ramp.length))];
+    return `\x1b[1m\x1b[38;5;${step}m${ch}`;
+  }).join('');
+  return body + RESET;
+}
+
+// single-pass JSON highlighter (keys violet, strings cyan, punctuation dim) —
+// one pass on purpose: a second regex pass would chew the ANSI escapes of the first
+export function colorizeJson(json) {
+  if (!enabled()) return json;
+  return json.replace(/("(?:[^"\\]|\\.)*")(\s*:)?|([{}[\],])/g, (m, str, colon, punct) => {
+    if (punct) return c.dim(punct);
+    if (colon !== undefined) return c.violet(str) + c.dim(colon);
+    return c.cyan(str);
+  });
+}

package/templates/express-router.txt

@@ -5,6 +5,7 @@
 __IMPORT_LINE__
 
 const SPARDA_TOOLS = __TOOLS_JSON__;
+const SPARDA_POLICIES = __SPARDING_POLICIES__;
 
 const SPARDA_LOCAL_KEY = "__LOCAL_KEY__";
 const SPARDA_PORT = __PORT__;
@@ -15,6 +16,45 @@ let SPARDA_SEQ = 0;
 // immune system: tools that keep failing are quarantined so the AI can't hammer a broken route
 const SPARDA_QUARANTINE__STATS_TYPE__ = {};
 const SPARDA_QUARANTINE_MS = Number(process.env.SPARDA_QUARANTINE_MS ?? 60000);
+// recycling gauge: calls answered from SPARDA's own knowledge vs calls that paid the host route.
+// Day 1 it reads 0% — the circle fills with usage (a measure, never a promise).
+const SPARDA_RECYCLE__STATS_TYPE__ = { servedByCircle: 0, paidFull: 0 };
+function spardaRecycleRate() {
+  const total = SPARDA_RECYCLE.servedByCircle + SPARDA_RECYCLE.paidFull;
+  return total ? Math.round((SPARDA_RECYCLE.servedByCircle * 100) / total) : 0;
+}
+// thermodynamic route classification: a GET whose repeated identical args keep
+// returning identical bodies is observed-pure (its result pre-exists — recyclable);
+// writes erase by definition. Observation only, never a guess.
+const SPARDA_PURITY__STATS_TYPE__ = {};
+function spardaHash(s__ANY_TYPE__) {
+  let h = 0x811c9dc5; // FNV-1a, capped: a fingerprint, not a checksum of megabytes
+  for (let i = 0; i < s.length && i < 65536; i++) { h ^= s.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; }
+  return h;
+}
+function spardaObservePurity(tool__ANY_TYPE__, argsig__ANY_TYPE__, body__ANY_TYPE__) {
+  const pu = SPARDA_PURITY[tool] ?? (SPARDA_PURITY[tool] = { sigs: {}, repeats: 0, mismatches: 0 });
+  const h = spardaHash(body);
+  const known = pu.sigs[argsig];
+  if (known === undefined) {
+    if (Object.keys(pu.sigs).length >= 20) return; // bounded: enough sigs to judge
+    pu.sigs[argsig] = h;
+  } else if (known === h) pu.repeats += 1;
+  else { pu.mismatches += 1; pu.sigs[argsig] = h; } // the latest real answer is the truth
+}
+function spardaPuritySnapshot() {
+  const out__STATS_TYPE__ = {};
+  for (const [name, spec] of Object.entries(SPARDA_TOOLS)) {
+    if (spec.method !== 'GET') { out[name] = { class: 'erasing', repeats: 0, mismatches: 0 }; continue; }
+    const pu = SPARDA_PURITY[name];
+    out[name] = {
+      class: !pu ? 'unknown' : pu.mismatches > 0 ? 'volatile' : pu.repeats >= 3 ? 'pure' : 'unknown',
+      repeats: pu ? pu.repeats : 0,
+      mismatches: pu ? pu.mismatches : 0,
+    };
+  }
+  return out;
+}
 function spardaEvent(source__ANY_TYPE__, tool__ANY_TYPE__, status__ANY_TYPE__, message__ANY_TYPE__) {
   SPARDA_EVENTS.push({ seq: ++SPARDA_SEQ, ts: new Date().toISOString(), source, tool, status, message: String(message ?? '').slice(0, 500) });
   if (SPARDA_EVENTS.length > 100) SPARDA_EVENTS.shift();
@@ -22,6 +62,134 @@ function spardaEvent(source__ANY_TYPE__, tool__ANY_TYPE__, status__ANY_TYPE__, m
 // observe-only: uncaughtExceptionMonitor never changes the host app's crash behavior
 process.on('uncaughtExceptionMonitor', (err__ANY_TYPE__) => spardaEvent('process', null, null, err && err.message ? err.message : err));
 
+function spardaProof(tool__ANY_TYPE__, spec__ANY_TYPE__, args__ANY_TYPE__) {
+  const checks = {
+    knownTool: spec !== undefined,
+    enabled: spec ? spec.enabled : false,
+    loopSafe: spec ? !spec.path.startsWith('/mcp') : false,
+    methodClass: spec ? (spec.method === 'GET' ? 'read' : 'write') : 'read',
+    pathParamsPresent: true,
+    hasBodyForWrite: true,
+    reversibleHint: false,
+    quarantineSafe: true,
+  };
+
+  const reasons = [];
+
+  if (!checks.knownTool) {
+    reasons.push('unknown tool');
+    return {
+      version: 'sparding-proof/v0.1',
+      risk: 'blocked',
+      decision: 'block',
+      reasons,
+      checks,
+    };
+  }
+
+  if (!checks.enabled) {
+    reasons.push('tool disabled (write-safety)');
+  }
+  if (!checks.loopSafe) {
+    reasons.push('self-referential tool blocked (loop protection)');
+  }
+
+  const quarantined = SPARDA_QUARANTINE[tool];
+  if (quarantined) {
+    if (Date.now() < quarantined.until) {
+      checks.quarantineSafe = false;
+      reasons.push(`tool quarantined (immune system): ${quarantined.reason}`);
+    } else {
+      delete SPARDA_QUARANTINE[tool];
+      if (SPARDA_STATS[tool]) SPARDA_STATS[tool].consecutive5xx = 2;
+    }
+  }
+
+  for (const name of spec.pathParams ?? []) {
+    if (args[name] === undefined) {
+      checks.pathParamsPresent = false;
+      reasons.push(`missing path param: ${name}`);
+    }
+  }
+
+  if (checks.methodClass === 'write') {
+    if (args.body === undefined) {
+      checks.hasBodyForWrite = false;
+    }
+  }
+
+  if (spec.method === 'GET') {
+    checks.reversibleHint = true;
+  } else {
+    checks.reversibleHint = Object.values(SPARDA_TOOLS).some((t__ANY_TYPE__) => t.method === 'GET' && t.path === spec.path);
+  }
+
+  let risk = 'low';
+  let decision = 'allow';
+
+  if (!checks.enabled || !checks.loopSafe || !checks.quarantineSafe || !checks.pathParamsPresent) {
+    decision = 'block';
+    risk = 'blocked';
+    return {
+      version: 'sparding-proof/v0.1',
+      risk,
+      decision,
+      reasons,
+      checks,
+    };
+  }
+
+  const policies = SPARDA_POLICIES ?? {};
+  if (checks.methodClass === 'read') {
+    const readPolicy = policies.reads ?? 'allow';
+    if (readPolicy === 'block') {
+      decision = 'block';
+      risk = 'blocked';
+      reasons.push('read policy blocks execution');
+    } else if (readPolicy === 'require_human') {
+      decision = 'require_human';
+      risk = 'medium';
+      reasons.push('read policy requires human confirmation');
+    }
+  } else {
+    const isDelete = spec.method === 'DELETE';
+    const deletePolicy = policies.deletes ?? 'block';
+    const writePolicy = policies.writes ?? 'require_human';
+
+    if (isDelete && deletePolicy === 'block') {
+      decision = 'block';
+      risk = 'blocked';
+      reasons.push('delete policy blocks execution');
+    } else if (isDelete && deletePolicy === 'require_human') {
+      decision = 'require_human';
+      risk = 'high';
+      reasons.push('delete operation requires human confirmation');
+    } else if (isDelete && deletePolicy === 'allow') {
+      decision = 'allow';
+      risk = 'low';
+    } else if (writePolicy === 'block') {
+      decision = 'block';
+      risk = 'blocked';
+      reasons.push('write policy blocks execution');
+    } else if (writePolicy === 'require_human') {
+      decision = 'require_human';
+      risk = 'medium';
+      reasons.push('write operation requires human confirmation');
+    } else {
+      decision = 'allow';
+      risk = 'low';
+    }
+  }
+
+  return {
+    version: 'sparding-proof/v0.1',
+    risk,
+    decision,
+    reasons,
+    checks,
+  };
+}
+
 __ROUTER_DECL__
 
 spardaRouter.use((req__REQ_TYPE__, res__RES_TYPE__, next__NEXT_TYPE__) => {
@@ -33,7 +201,7 @@ spardaRouter.use((req__REQ_TYPE__, res__RES_TYPE__, next__NEXT_TYPE__) => {
 
 spardaRouter.get('/tools', (_req__REQ_TYPE__, res__RES_TYPE__) => res.json(SPARDA_TOOLS));
 
-spardaRouter.get('/stats', (_req__REQ_TYPE__, res__RES_TYPE__) => res.json({ uptimeSec: Math.round(process.uptime()), stats: SPARDA_STATS, quarantine: SPARDA_QUARANTINE }));
+spardaRouter.get('/stats', (_req__REQ_TYPE__, res__RES_TYPE__) => res.json({ uptimeSec: Math.round(process.uptime()), stats: SPARDA_STATS, quarantine: SPARDA_QUARANTINE, recycle: { servedByCircle: SPARDA_RECYCLE.servedByCircle, paidFull: SPARDA_RECYCLE.paidFull, ratePct: spardaRecycleRate() }, purity: spardaPuritySnapshot() }));
 
 spardaRouter.get('/events', (req__REQ_TYPE__, res__RES_TYPE__) => {
   const since = Number(req.query.since ?? 0) || 0;
@@ -44,26 +212,46 @@ spardaRouter.post('/invoke', __JSON_MW__, async (req__REQ_TYPE__, res__RES_TYPE_
   const { tool, args = {} } = req.body ?? {};
   const t0 = Date.now();
   const spec = SPARDA_TOOLS[tool];
-  if (!spec) return res.status(404).json({ error: `unknown tool: ${tool}` });
-  if (!spec.enabled) {
-    return res.status(403).json({ error: `tool disabled (write-safety): ${tool}`, hint: 'Enable it in sparda.json, then re-run: npx sparda-mcp init' });
-  }
-  if (spec.path.startsWith('/mcp')) {
-    return res.status(400).json({ error: 'self-referential tool blocked (loop protection)' });
-  }
-  const quarantined = SPARDA_QUARANTINE[tool];
-  if (quarantined) {
-    if (Date.now() < quarantined.until) {
-      return res.status(503).json({ error: `tool quarantined (immune system): ${tool}`, reason: quarantined.reason, retryInMs: quarantined.until - Date.now() });
+
+  const proof = spardaProof(tool, spec, args);
+
+  if (proof.decision === 'block') {
+    let status = 400;
+    let error = 'bad request';
+    if (!proof.checks.knownTool) {
+      status = 404;
+      error = `unknown tool: ${tool}`;
+    } else if (!proof.checks.enabled) {
+      status = 403;
+      error = `tool disabled (write-safety): ${tool}`;
+      return res.status(status).json({ error, hint: 'Enable it in sparda.json, then re-run: npx sparda-mcp init', spardingProof: proof });
+    } else if (!proof.checks.loopSafe) {
+      status = 400;
+      error = 'self-referential tool blocked (loop protection)';
+    } else if (!proof.checks.quarantineSafe) {
+      status = 503;
+      const quarantined = SPARDA_QUARANTINE[tool];
+      error = `tool quarantined (immune system): ${tool}`;
+      SPARDA_RECYCLE.servedByCircle += 1;
+      return res.status(status).json({
+        error,
+        reason: quarantined ? quarantined.reason : '',
+        retryInMs: quarantined ? Math.max(0, quarantined.until - Date.now()) : 0,
+        spardingProof: proof
+      });
+    } else {
+      status = 400;
+      error = proof.reasons[0] || 'blocked';
+      if (proof.reasons.some((r__ANY_TYPE__) => r.includes('policy blocks execution'))) {
+        status = 403;
+      }
     }
-    // half-open: cooldown elapsed — allow one probe; a single new 5xx re-quarantines
-    delete SPARDA_QUARANTINE[tool];
-    if (SPARDA_STATS[tool]) SPARDA_STATS[tool].consecutive5xx = 2;
+    return res.status(status).json({ error, spardingProof: proof });
   }
+
   try {
     let url = spec.path.replace(/:(\w+)/g, (_, name) => {
       const v = args[name];
-      if (v === undefined) throw Object.assign(new Error(`missing path param: ${name}`), { status: 400 });
       return encodeURIComponent(String(v));
     });
     const query = [];
@@ -78,28 +266,35 @@ spardaRouter.post('/invoke', __JSON_MW__, async (req__REQ_TYPE__, res__RES_TYPE_
       init.headers['content-type'] = 'application/json';
       init.body = JSON.stringify(args.body);
     }
+    SPARDA_RECYCLE.paidFull += 1; // the host route is about to be exercised — full price
     const upstream = await fetch(`http://127.0.0.1:${SPARDA_PORT}${url}`, { ...init, signal: AbortSignal.timeout(30_000) });
     const text = await upstream.text();
     let data; try { data = JSON.parse(text); } catch { data = text; }
     spardaRecord(tool, upstream.status, Date.now() - t0);
+    if (spec.method === 'GET' && upstream.status === 200) {
+      // canonical argsig: sorted entries, so the AI's argument order never splits a signature
+      spardaObservePurity(tool, JSON.stringify(Object.entries(args).filter((e__ANY_TYPE__) => e[1] !== undefined).sort()), text);
+    }
     if (upstream.status >= 500) spardaEvent('invoke', tool, upstream.status, text.slice(0, 200));
-    return res.status(200).json({ upstreamStatus: upstream.status, data });
+    return res.status(200).json({ upstreamStatus: upstream.status, data, spardingProof: proof });
   } catch (err__ANY_TYPE__) {
     spardaRecord(tool, err.status ?? 502, Date.now() - t0);
     spardaEvent('invoke', tool, err.status ?? 502, err.message);
-    return res.status(err.status ?? 502).json({ error: err.message });
+    return res.status(err.status ?? 502).json({ error: err.message, spardingProof: proof });
   }
 });
 
 function spardaRecord(tool__ANY_TYPE__, status__ANY_TYPE__, ms__ANY_TYPE__) {
-  const st = SPARDA_STATS[tool] ?? (SPARDA_STATS[tool] = { calls: 0, errors: 0, totalMs: 0, lastStatus: null, lastTs: null, consecutive5xx: 0 });
+  const st = SPARDA_STATS[tool] ?? (SPARDA_STATS[tool] = { calls: 0, errors: 0, clientErrors: 0, totalMs: 0, lastStatus: null, lastTs: null, consecutive5xx: 0 });
   // innate immunity: latency far beyond the learned baseline is an antigen
   if (st.calls >= 5 && ms > Math.max((st.totalMs / st.calls) * 10, 200)) {
     spardaEvent('immune', tool, status, `latency anomaly: ${ms}ms vs ~${Math.round(st.totalMs / st.calls)}ms baseline`);
   }
   st.calls += 1;
   st.totalMs += ms;
-  if (status >= 400) st.errors += 1;
+  // 5xx = server failure (feeds the immune system); 4xx = a valid client answer (404 etc), tracked apart so the count doesn't lie
+  if (status >= 500) st.errors += 1;
+  else if (status >= 400) st.clientErrors += 1;
   st.lastStatus = status;
   st.lastTs = new Date().toISOString();
   if (status >= 500) st.consecutive5xx += 1;