klypix-mcp 1.4.0 → 1.5.0

package/bin/klypix-a2a.mjs

@@ -36,7 +36,16 @@ import {
 } from '../src/klypix-core.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const PKG = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+// Resolve the package version across layouts: the published package (bin/ →
+// ../package.json) and the desktop-bundled FLAT layout (~/.claude/project-brain/,
+// ./package.json, which may carry no version) — degrade gracefully either way.
+function readVersion() {
+  for (const p of [path.join(__dirname, '..', 'package.json'), path.join(__dirname, 'package.json')]) {
+    try { const v = JSON.parse(fs.readFileSync(p, 'utf8')).version; if (v) return v; } catch { /* try next */ }
+  }
+  return '1.x';
+}
+const PKG = { version: readVersion() };
 const log = (...a) => console.error('[klypix-a2a]', ...a);
 
 const arg = (flag) => { const i = process.argv.indexOf(flag); return i >= 0 ? process.argv[i + 1] : undefined; };

package/bin/klypix-mcp.mjs

@@ -23,7 +23,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import {
   resolveVault, getEmbedder, buildKlypixMap, cardSchema, connSchema,
   opListCanvases, opReadCanvas, opSearchCanvases, opSearchAllBrains,
-  opBrainInsights, opBrainConnect, opCreateCanvas, opAddToCanvas,
+  opBrainInsights, opBrainConnect, opBrainReconcile, opCreateCanvas, opAddToCanvas,
 } from '../src/klypix-core.mjs';
 
 // IMPORTANT: stdout is the JSON-RPC channel. Never console.log — only stderr.
@@ -112,6 +112,15 @@ server.registerTool('brain_connect', {
   },
 }, async ({ canvas, apply, max, threshold }) => toContent(await opBrainConnect({ vault: VAULT, canvas, apply, max, threshold, log })));
 
+server.registerTool('brain_reconcile', {
+  title: 'Reconcile the brain against committed migrations (find unrecorded rollouts)',
+  description: 'External-state check the brain otherwise CANNOT do: a brain only knows facts someone narrated (a marker, a commit body), so a DB migration APPLIED to prod — which narrates nothing — silently never lands. This lists committed migration files (Supabase / Rails / Prisma / Knex / generic) under the project and flags any that NO brain card references, so you can confirm the rollout with one marker. It reads ONLY the filesystem — never the database, never the network — and never claims a migration was applied, only that it is unrecorded. Defaults to the migrations dir beside the project brain; pass root to point elsewhere. Run it when you want to be sure the brain reflects what actually shipped.',
+  inputSchema: {
+    canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
+    root: z.string().optional().describe("Project root holding the migrations dir (default: the brain file's folder)."),
+  },
+}, async ({ canvas, root }) => toContent(await opBrainReconcile({ vault: VAULT, canvas, root })));
+
 server.registerTool('create_canvas', {
   title: 'Create a KLYPIX canvas',
   description: 'Create a new .klypix canvas from cards + connections and save it to the vault. The user opens it in KLYPIX (Canvas → Open). Prefer short, titled cards (one idea each) connected by meaningful arrows.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "An open, local-first, agent-neutral canvas file your AI reads and writes over MCP — works with Claude, Cursor, Cline, any model.",
   "type": "module",
   "license": "MIT",

package/src/klypix-core.mjs

@@ -24,6 +24,7 @@ import { z } from 'zod';
 import {
   parseKlypix, buildKlypix, buildKlypixMap, appendToKlypix, structToMarkdown,
   brainInsights, insightsToMarkdown, addBrainConnections, proposeStructuralConnections, atomicWrite,
+  findUnrecordedMigrations,
 } from './klypix-format.mjs';
 
 // ── Card / connection input shape (single source for every face) ─────────────
@@ -325,6 +326,46 @@ export async function opBrainInsights({ vault, canvas, staleDays }) {
   }
 }
 
+// ── Migration reconcile (external-state omission tripwire) ────────────────────
+// Lists committed migration files under a project root (Supabase / Rails / Prisma
+// / Knex / generic layouts) and feeds them to the pure findUnrecordedMigrations(),
+// returning the ones no live brain card records. Portable: pure fs, no DB, no
+// network, no credentials — it flags "committed but unmentioned", NEVER claims
+// "applied to prod". Degrades to a clean message for a project with no migrations.
+const MIGRATION_DIRS = ['supabase/migrations', 'db/migrate', 'db/migrations', 'prisma/migrations', 'migrations'];
+export function collectMigrationFiles(root) {
+  const out = [];
+  for (const rel of MIGRATION_DIRS) {
+    const abs = path.join(root, ...rel.split('/'));
+    let entries;
+    try { entries = fs.readdirSync(abs, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (e.isFile() && /\.sql$/i.test(e.name)) out.push(rel + '/' + e.name);
+      // Prisma nests each migration in its own folder holding a migration.sql.
+      else if (e.isDirectory()) {
+        try { if (fs.statSync(path.join(abs, e.name, 'migration.sql')).isFile()) out.push(rel + '/' + e.name + '/migration.sql'); } catch { /* not a prisma migration dir */ }
+      }
+    }
+  }
+  return out;
+}
+export async function opBrainReconcile({ vault, canvas, root }) {
+  const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
+  if (!file) return err(`No brain canvas found in ${vault}. Pass canvas: "<name>".`);
+  let struct;
+  try { ({ struct } = await parseKlypix(fs.readFileSync(file))); } catch (e) { return err(`Read failed: ${e.message}`); }
+  // Migrations live in the CODE repo (usually beside brain.klypix), not in a
+  // separate canvas vault — so default the root to the brain file's folder.
+  const repoRoot = root ? path.resolve(root) : path.dirname(file);
+  const files = collectMigrationFiles(repoRoot);
+  if (!files.length) return { blocks: [text(`No migration files under ${repoRoot} (looked in: ${MIGRATION_DIRS.join(', ')}). Nothing to reconcile.`)] };
+  const { gaps, total } = findUnrecordedMigrations(struct, files, { max: 20 });
+  if (!gaps.length) return { blocks: [text(`✓ All ${files.length} migration(s) under ${path.basename(repoRoot)} are referenced by a brain card — no unrecorded rollouts.`)] };
+  const lines = gaps.map(g => `- \`${g.path}\` — committed, but no brain card mentions it. If applied to prod, record it:\n    \`🧠 BRAIN [DB] !: migration ${g.file.replace(/\.sql$/i, '')} applied to prod ev: ${g.path}\``);
+  const more = total > gaps.length ? `\n\n…and ${total - gaps.length} more.` : '';
+  return { blocks: [text(`# ⚠️ ${total} migration(s) committed but unrecorded in the brain\n_The brain can't see prod — it flags migrations that are in git but unmentioned, so you can confirm the rollout. It never asserts a migration was applied. To dismiss one without applying, record any card that names it (e.g. "committed, not applied")._\n\n${lines.join('\n')}${more}`)] };
+}
+
 export async function opBrainConnect({ vault, canvas, apply = false, max = 24, threshold = 0.45, log = () => {} }) {
   const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
   if (!file) return err(`No brain canvas found in ${vault}.`);

package/src/klypix-format.mjs

@@ -688,6 +688,53 @@ export function scoreCardsAgainstQuery(struct, query, { topK = 6, minScore = 2,
     return scored.filter(s => s.score >= minScore).slice(0, topK);
 }
 
+// ── External-state reconcile — migration omission tripwire ───────────────────
+// The brain is a NARRATION-capture system: a fact exists only if someone wrote a
+// 🧠 marker or a rationale-bearing commit body. Applying a DB migration to prod
+// is an OBSERVED side-effect that narrates nothing, so it silently never lands —
+// and the brain can't tell a *committed* migration from an *applied* one. These
+// two pure functions are the portable seam that closes that blind spot WITHOUT
+// making the brain omniscient: no I/O, no DB probe, no network, no credentials. A
+// collector (the Claude-Code hook, or the brain_reconcile MCP tool) hands them
+// the migration FILES found on disk; they return the ones NO LIVE card references,
+// so the surface can PROMPT the human to confirm the rollout — never assert it.
+// Recall-first by design: ANY plausible hit counts as "recorded", erring toward
+// silence over a false nag.
+const MIG_STOP = new Set(['migration', 'migrations', 'sql', 'create', 'alter', 'table', 'drop', 'add', 'update', 'init', 'schema', 'public', 'new', 'fix', 'set', 'col', 'column', 'index']);
+// Split on EVERY non-alphanumeric (unlike the shared wordsOf, which keeps _- glued)
+// so `20260620000000_canvas_blob_size_limit` and the `#file-…` tag both tokenize
+// into the same words a card's prose carries — the precise match signal.
+const migWords = (s) => new Set(String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, ' ').split(' ').filter(Boolean));
+export function migrationSignature(file) {
+    const orig = String(file || '').replace(/\\/g, '/');
+    const base = orig.split('/').pop() || '';
+    const stem = base.replace(/\.[a-z0-9]+$/i, '');
+    const ts = (stem.match(/^\d{8,}/) || [''])[0];                      // leading timestamp id (Supabase/Prisma/Knex)
+    const distinctive = stem.replace(/^\d{8,}[_-]?/, '')               // drop the timestamp prefix → the descriptive name
+        .split(/[^a-z0-9]+/i).map(t => t.toLowerCase())
+        .filter(t => t.length >= 3 && !MIG_STOP.has(t));
+    return { path: orig, file: base, ts, distinctive };
+}
+// A migration is "recorded" if some LIVE (non-archived) card mentions its timestamp
+// id OR every distinctive word of its name (so "canvas" alone never claims to record
+// canvas_blob_size_limit, but a card carrying the #file-<stem> tag or the applied-
+// marker prose does). Returns the UNrecorded ones (capped); [] when there are no
+// migrations (plain projects stay silent).
+export function findUnrecordedMigrations(struct, files, { max = 6 } = {}) {
+    const empty = { gaps: [], total: 0, scanned: 0 };
+    const sigs = (files || []).map(migrationSignature).filter(s => s.ts || s.distinctive.length);
+    if (!sigs.length || !struct || !Array.isArray(struct.cards)) return empty;
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const cardWords = struct.cards
+        .filter(c => c && c.type !== 'container' && !isArchived(c))
+        .map(c => migWords(String(c.text || '') + ' ' + (c.tags || []).join(' ')));
+    const recorded = (sig) => cardWords.some(ws =>
+        (sig.ts && ws.has(sig.ts))
+        || (sig.distinctive.length > 0 && sig.distinctive.every(t => ws.has(t))));
+    const unrecorded = sigs.filter(s => !recorded(s));
+    return { gaps: unrecorded.slice(0, max).map(s => ({ file: s.file, path: s.path, ts: s.ts })), total: unrecorded.length, scanned: sigs.length };
+}
+
 // ── Repeat / redundancy detection ("you already did this in another session") ─
 // The PRECISION-first sibling of scoreCardsAgainstQuery. Instead of "related
 // context" it answers a sharper question: is the user about to REDO work that's