@luanpdd/kit-mcp 1.34.0 → 1.36.0

package/src/core/error-redaction.js

@@ -1,76 +1,76 @@
-// SEC-14-06 — central redaction helpers shared by mcp-server, reflect, and replays.
-//
-// Pure module: no I/O, no globals other than the constant regex set.
-//
-// Why a single choke point: the threat model is "leakage of API keys, Bearer
-// tokens, and absolute filesystem paths through MCP error envelopes / persisted
-// replays". Scattering redaction across each call site invites drift. One file,
-// one regex set, three import sites — and a single grep proves coverage.
-//
-// Order rationale (PATTERNS array):
-//   1. sk-ant-* before sk-* — Anthropic prefix is more specific. (In practice
-//      the openai pattern's [A-Za-z0-9] character class would NOT swallow
-//      "sk-ant-" because of the dash, but ordering keeps intent legible.)
-//   2. x-api-key header before Bearer — both are distinct shapes; order is
-//      arbitrary but stable.
-//   3. Path patterns last — broadest character class, matched after specific
-//      secrets so a secret that contains slash-like characters has been
-//      stripped already.
-//
-// Non-false-positive contract (verified by test/unit/error-redaction.test.js):
-//   - "Compare A:B" stays unchanged          (no `\` or `/` after `:`)
-//   - "Modal: hello"  stays unchanged        (no `\` or `/` after `:`)
-//   - "Visit https://example.com/path" stays (lowercase scheme, no Drive: pattern)
-//   - "Bearer x"      stays unchanged        (1 char, below 20 minimum)
-//   - "sk-foo"        stays unchanged        (3 chars after sk-, below 20 minimum)
-//   - "see /etc/passwd" stays unchanged      (etc not in {home,Users,root} allowlist)
-//
-// Idempotency: redactSecrets(redactSecrets(x)) === redactSecrets(x). The
-// substitution strings ('[REDACTED:*]', '[PATH]', etc.) contain no characters
-// that match any of the patterns themselves.
-
-const PATTERNS = [
-  { re: /sk-ant-[A-Za-z0-9_\-]{20,}/g,        sub: '[REDACTED:anthropic_key]' },
-  { re: /sk-[A-Za-z0-9]{20,}/g,                sub: '[REDACTED:openai_key]' },
-  { re: /x-api-key\s*:\s*[^\s,;'"]+/gi,        sub: 'x-api-key: [REDACTED]' },
-  { re: /Bearer\s+[A-Za-z0-9._\-]{20,}/gi,     sub: 'Bearer [REDACTED]' },
-  { re: /[A-Z]:[\\\/][^\s'"`<>]+/g,            sub: '[PATH]' },
-  { re: /\/(home|Users|root)\/[^\s'"`<>]+/g,   sub: '[PATH]' },
-];
-
-/**
- * Strip secrets and absolute filesystem paths from a string. Defensive: coerces
- * non-string inputs via String(value); null/undefined return ''.
- *
- * @param {unknown} text
- * @returns {string}
- */
-export function redactSecrets(text) {
-  if (text == null) return '';
-  let s = String(text);
-  for (const { re, sub } of PATTERNS) {
-    s = s.replace(re, sub);
-  }
-  return s;
-}
-
-/**
- * Build the public MCP error envelope for an arbitrary thrown value. The
- * server-side stderr keeps the full trace for operator debugging; the
- * JSON-RPC client receives only `{error, code}` — no trace field is emitted.
- *
- * Preserves err.code when present (Phase 83.03 added `EMANIFESTMISMATCH`;
- * downstream callers can keep dispatching on that code).
- *
- * @param {unknown} err
- * @returns {{ error: string, code: string }}
- */
-export function sanitizeMcpError(err) {
-  const msg = err && typeof err === 'object' && 'message' in err
-    ? err.message
-    : err;
-  return {
-    error: redactSecrets(msg ?? 'unknown error'),
-    code:  (err && typeof err === 'object' && err.code) ? err.code : 'MCP_INTERNAL_ERROR',
-  };
-}
+// SEC-14-06 — central redaction helpers shared by mcp-server, reflect, and replays.
+//
+// Pure module: no I/O, no globals other than the constant regex set.
+//
+// Why a single choke point: the threat model is "leakage of API keys, Bearer
+// tokens, and absolute filesystem paths through MCP error envelopes / persisted
+// replays". Scattering redaction across each call site invites drift. One file,
+// one regex set, three import sites — and a single grep proves coverage.
+//
+// Order rationale (PATTERNS array):
+//   1. sk-ant-* before sk-* — Anthropic prefix is more specific. (In practice
+//      the openai pattern's [A-Za-z0-9] character class would NOT swallow
+//      "sk-ant-" because of the dash, but ordering keeps intent legible.)
+//   2. x-api-key header before Bearer — both are distinct shapes; order is
+//      arbitrary but stable.
+//   3. Path patterns last — broadest character class, matched after specific
+//      secrets so a secret that contains slash-like characters has been
+//      stripped already.
+//
+// Non-false-positive contract (verified by test/unit/error-redaction.test.js):
+//   - "Compare A:B" stays unchanged          (no `\` or `/` after `:`)
+//   - "Modal: hello"  stays unchanged        (no `\` or `/` after `:`)
+//   - "Visit https://example.com/path" stays (lowercase scheme, no Drive: pattern)
+//   - "Bearer x"      stays unchanged        (1 char, below 20 minimum)
+//   - "sk-foo"        stays unchanged        (3 chars after sk-, below 20 minimum)
+//   - "see /etc/passwd" stays unchanged      (etc not in {home,Users,root} allowlist)
+//
+// Idempotency: redactSecrets(redactSecrets(x)) === redactSecrets(x). The
+// substitution strings ('[REDACTED:*]', '[PATH]', etc.) contain no characters
+// that match any of the patterns themselves.
+
+const PATTERNS = [
+  { re: /sk-ant-[A-Za-z0-9_\-]{20,}/g,        sub: '[REDACTED:anthropic_key]' },
+  { re: /sk-[A-Za-z0-9]{20,}/g,                sub: '[REDACTED:openai_key]' },
+  { re: /x-api-key\s*:\s*[^\s,;'"]+/gi,        sub: 'x-api-key: [REDACTED]' },
+  { re: /Bearer\s+[A-Za-z0-9._\-]{20,}/gi,     sub: 'Bearer [REDACTED]' },
+  { re: /[A-Z]:[\\\/][^\s'"`<>]+/g,            sub: '[PATH]' },
+  { re: /\/(home|Users|root)\/[^\s'"`<>]+/g,   sub: '[PATH]' },
+];
+
+/**
+ * Strip secrets and absolute filesystem paths from a string. Defensive: coerces
+ * non-string inputs via String(value); null/undefined return ''.
+ *
+ * @param {unknown} text
+ * @returns {string}
+ */
+export function redactSecrets(text) {
+  if (text == null) return '';
+  let s = String(text);
+  for (const { re, sub } of PATTERNS) {
+    s = s.replace(re, sub);
+  }
+  return s;
+}
+
+/**
+ * Build the public MCP error envelope for an arbitrary thrown value. The
+ * server-side stderr keeps the full trace for operator debugging; the
+ * JSON-RPC client receives only `{error, code}` — no trace field is emitted.
+ *
+ * Preserves err.code when present (Phase 83.03 added `EMANIFESTMISMATCH`;
+ * downstream callers can keep dispatching on that code).
+ *
+ * @param {unknown} err
+ * @returns {{ error: string, code: string }}
+ */
+export function sanitizeMcpError(err) {
+  const msg = err && typeof err === 'object' && 'message' in err
+    ? err.message
+    : err;
+  return {
+    error: redactSecrets(msg ?? 'unknown error'),
+    code:  (err && typeof err === 'object' && err.code) ? err.code : 'MCP_INTERNAL_ERROR',
+  };
+}

package/src/core/failures.js

@@ -1,153 +1,153 @@
-// Failure dataset — closes the learning loop.
-//
-// Aggregates resolved debug sessions (`.planning/debug/resolved/*.md`),
-// failed verifications (`.planning/phases/*/[0-9]*-VERIFICATION.md` with status: gaps_found),
-// and forensics reports into a structured dataset that can be queried to find
-// recurring failure patterns per agent.
-//
-// Output is written to `.planning/learnings/{agent}.md` so future agent edits
-// have evidence-based input.
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-
-export async function collectFailures(opts = {}) {
-  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
-  const planning    = path.join(projectRoot, '.planning');
-
-  const [debugFailures, verifyFailures, forensicsReports] = await Promise.all([
-    readDebugSessions(path.join(planning, 'debug', 'resolved')),
-    readFailedVerifications(path.join(planning, 'phases')),
-    readForensics(path.join(planning, 'forensics')),
-  ]);
-
-  return {
-    projectRoot,
-    counts: {
-      debug:     debugFailures.length,
-      verify:    verifyFailures.length,
-      forensics: forensicsReports.length,
-    },
-    items: [...debugFailures, ...verifyFailures, ...forensicsReports],
-  };
-}
-
-export async function summarizeByAgent(failures) {
-  const byAgent = {};
-  for (const item of failures.items) {
-    const agent = item.agentHint ?? 'unknown';
-    byAgent[agent] ??= { agent, count: 0, samples: [] };
-    byAgent[agent].count++;
-    if (byAgent[agent].samples.length < 5) byAgent[agent].samples.push(item);
-  }
-  return Object.values(byAgent).sort((a, b) => b.count - a.count);
-}
-
-export async function writeLearnings(failures, opts = {}) {
-  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
-  const outDir = path.join(projectRoot, '.planning', 'learnings');
-  await fs.mkdir(outDir, { recursive: true });
-
-  const summaries = await summarizeByAgent(failures);
-  const written = [];
-  for (const s of summaries) {
-    const out = path.join(outDir, `${s.agent}.md`);
-    const md  = renderLearningDoc(s);
-    await fs.writeFile(out, md, 'utf8');
-    written.push(out);
-  }
-  return { written, summaries };
-}
-
-// --- readers ---
-
-async function readDebugSessions(dir) {
-  return readDir(dir, raw => ({
-    source: 'debug',
-    agentHint: detectAgentHint(raw),
-    summary: firstHeading(raw),
-    raw: raw.slice(0, 2000),
-  }));
-}
-
-async function readFailedVerifications(phasesDir) {
-  let out = [];
-  let phases;
-  try { phases = await fs.readdir(phasesDir, { withFileTypes: true }); }
-  catch { return out; }
-  for (const p of phases) {
-    if (!p.isDirectory()) continue;
-    const phaseDir = path.join(phasesDir, p.name);
-    let files;
-    try { files = await fs.readdir(phaseDir); } catch { continue; }
-    for (const f of files) {
-      if (!/-VERIFICATION\.md$/.test(f)) continue;
-      const raw = await fs.readFile(path.join(phaseDir, f), 'utf8');
-      if (!/^status:\s*gaps_found/m.test(raw)) continue;
-      out.push({
-        source: 'verify',
-        agentHint: 'verifier',
-        phase: p.name,
-        summary: firstHeading(raw),
-        raw: raw.slice(0, 2000),
-      });
-    }
-  }
-  return out;
-}
-
-async function readForensics(dir) {
-  return readDir(dir, raw => ({
-    source: 'forensics',
-    agentHint: detectAgentHint(raw),
-    summary: firstHeading(raw),
-    raw: raw.slice(0, 2000),
-  }));
-}
-
-async function readDir(dir, mapper) {
-  let entries;
-  try { entries = await fs.readdir(dir, { withFileTypes: true }); }
-  catch { return []; }
-  const out = [];
-  for (const e of entries) {
-    if (!e.isFile() || !e.name.endsWith('.md')) continue;
-    const raw = await fs.readFile(path.join(dir, e.name), 'utf8');
-    out.push({ file: e.name, ...mapper(raw) });
-  }
-  return out;
-}
-
-function detectAgentHint(raw) {
-  for (const a of ['executor', 'verifier', 'planner', 'debugger', 'phase-researcher',
-                   'plan-checker', 'integration-checker', 'nyquist-auditor', 'ui-checker']) {
-    if (raw.toLowerCase().includes(a)) return a;
-  }
-  return 'unknown';
-}
-
-function firstHeading(raw) {
-  const m = raw.match(/^#+\s*(.+)$/m);
-  return m ? m[1].trim() : '';
-}
-
-function renderLearningDoc(s) {
-  return `# Learnings — ${s.agent}
-
-**Failure samples:** ${s.count}
-**Generated:** ${new Date().toISOString()}
-
-## Recurring patterns
-
-> Review the samples below and edit \`kit/agents/${s.agent}.md\` to address recurring causes.
-
-## Samples
-
-${s.samples.map((x, i) => `### Sample ${i + 1} (${x.source})
-${x.summary ? `*${x.summary}*\n` : ''}
-\`\`\`
-${x.raw.slice(0, 800)}
-\`\`\`
-`).join('\n---\n\n')}
-`;
-}
+// Failure dataset — closes the learning loop.
+//
+// Aggregates resolved debug sessions (`.planning/debug/resolved/*.md`),
+// failed verifications (`.planning/phases/*/[0-9]*-VERIFICATION.md` with status: gaps_found),
+// and forensics reports into a structured dataset that can be queried to find
+// recurring failure patterns per agent.
+//
+// Output is written to `.planning/learnings/{agent}.md` so future agent edits
+// have evidence-based input.
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
+export async function collectFailures(opts = {}) {
+  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
+  const planning    = path.join(projectRoot, '.planning');
+
+  const [debugFailures, verifyFailures, forensicsReports] = await Promise.all([
+    readDebugSessions(path.join(planning, 'debug', 'resolved')),
+    readFailedVerifications(path.join(planning, 'phases')),
+    readForensics(path.join(planning, 'forensics')),
+  ]);
+
+  return {
+    projectRoot,
+    counts: {
+      debug:     debugFailures.length,
+      verify:    verifyFailures.length,
+      forensics: forensicsReports.length,
+    },
+    items: [...debugFailures, ...verifyFailures, ...forensicsReports],
+  };
+}
+
+export async function summarizeByAgent(failures) {
+  const byAgent = {};
+  for (const item of failures.items) {
+    const agent = item.agentHint ?? 'unknown';
+    byAgent[agent] ??= { agent, count: 0, samples: [] };
+    byAgent[agent].count++;
+    if (byAgent[agent].samples.length < 5) byAgent[agent].samples.push(item);
+  }
+  return Object.values(byAgent).sort((a, b) => b.count - a.count);
+}
+
+export async function writeLearnings(failures, opts = {}) {
+  const projectRoot = path.resolve(opts.projectRoot ?? process.cwd());
+  const outDir = path.join(projectRoot, '.planning', 'learnings');
+  await fs.mkdir(outDir, { recursive: true });
+
+  const summaries = await summarizeByAgent(failures);
+  const written = [];
+  for (const s of summaries) {
+    const out = path.join(outDir, `${s.agent}.md`);
+    const md  = renderLearningDoc(s);
+    await fs.writeFile(out, md, 'utf8');
+    written.push(out);
+  }
+  return { written, summaries };
+}
+
+// --- readers ---
+
+async function readDebugSessions(dir) {
+  return readDir(dir, raw => ({
+    source: 'debug',
+    agentHint: detectAgentHint(raw),
+    summary: firstHeading(raw),
+    raw: raw.slice(0, 2000),
+  }));
+}
+
+async function readFailedVerifications(phasesDir) {
+  let out = [];
+  let phases;
+  try { phases = await fs.readdir(phasesDir, { withFileTypes: true }); }
+  catch { return out; }
+  for (const p of phases) {
+    if (!p.isDirectory()) continue;
+    const phaseDir = path.join(phasesDir, p.name);
+    let files;
+    try { files = await fs.readdir(phaseDir); } catch { continue; }
+    for (const f of files) {
+      if (!/-VERIFICATION\.md$/.test(f)) continue;
+      const raw = await fs.readFile(path.join(phaseDir, f), 'utf8');
+      if (!/^status:\s*gaps_found/m.test(raw)) continue;
+      out.push({
+        source: 'verify',
+        agentHint: 'verifier',
+        phase: p.name,
+        summary: firstHeading(raw),
+        raw: raw.slice(0, 2000),
+      });
+    }
+  }
+  return out;
+}
+
+async function readForensics(dir) {
+  return readDir(dir, raw => ({
+    source: 'forensics',
+    agentHint: detectAgentHint(raw),
+    summary: firstHeading(raw),
+    raw: raw.slice(0, 2000),
+  }));
+}
+
+async function readDir(dir, mapper) {
+  let entries;
+  try { entries = await fs.readdir(dir, { withFileTypes: true }); }
+  catch { return []; }
+  const out = [];
+  for (const e of entries) {
+    if (!e.isFile() || !e.name.endsWith('.md')) continue;
+    const raw = await fs.readFile(path.join(dir, e.name), 'utf8');
+    out.push({ file: e.name, ...mapper(raw) });
+  }
+  return out;
+}
+
+function detectAgentHint(raw) {
+  for (const a of ['executor', 'verifier', 'planner', 'debugger', 'phase-researcher',
+                   'plan-checker', 'integration-checker', 'nyquist-auditor', 'ui-checker']) {
+    if (raw.toLowerCase().includes(a)) return a;
+  }
+  return 'unknown';
+}
+
+function firstHeading(raw) {
+  const m = raw.match(/^#+\s*(.+)$/m);
+  return m ? m[1].trim() : '';
+}
+
+function renderLearningDoc(s) {
+  return `# Learnings — ${s.agent}
+
+**Failure samples:** ${s.count}
+**Generated:** ${new Date().toISOString()}
+
+## Recurring patterns
+
+> Review the samples below and edit \`kit/agents/${s.agent}.md\` to address recurring causes.
+
+## Samples
+
+${s.samples.map((x, i) => `### Sample ${i + 1} (${x.source})
+${x.summary ? `*${x.summary}*\n` : ''}
+\`\`\`
+${x.raw.slice(0, 800)}
+\`\`\`
+`).join('\n---\n\n')}
+`;
+}