klypix-mcp 1.4.1 → 1.6.0

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, opBrainNote,
 } 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.',
@@ -138,6 +147,21 @@ server.registerTool('add_to_canvas', {
   return toContent(await opAddToCanvas({ vault: VAULT, canvas, cards, connections, via }));
 });
 
+server.registerTool('brain_note', {
+  title: 'Write a deliberate note to the project brain (decision / question / milestone / resolve / update)',
+  description: 'Record something in the project brain ON DEMAND — the agent-neutral twin of the Claude-Code capture hook, so any client (Cursor / Cline / Desktop) can write the brain, not just read it. Unlike add_to_canvas (a flat append), this routes through the brain\'s capture engine, so a new decision SUPERSEDES a heavily-overlapping older one, ✓ RESOLVES/archives a matching card, closes: resolves the strategy/question a milestone fulfils, and ~ UPDATES a card in place — the full decision lifecycle, with dedup. Use it to remember a decision, ask an open question, mark a milestone, resolve a finished item, or correct a card. Defaults to the project brain ("brain").',
+  inputSchema: {
+    text: z.string().describe('The note — one concise idea; the first line becomes the card title.'),
+    marker: z.enum(['', '?', '!', '✓', '~']).optional().describe('(none)=decision · ?=open question · !=milestone · ✓=resolve+archive the best-matching card · ~=update the matching card in place. Default: decision.'),
+    area: z.string().optional().describe('Area/topic — routes the card into that titled container and becomes a #tag (e.g. "Auth", "Release").'),
+    closes: z.string().optional().describe('Title or [[wikilink]] of a strategy/question card this note fulfils — resolves+archives it and draws a "closed by" arrow.'),
+    canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
+  },
+}, async ({ text, marker, area, closes, canvas }) => {
+  let via; try { via = server.server.getClientVersion()?.name; } catch { /* optional */ }
+  return toContent(await opBrainNote({ vault: VAULT, canvas, text, area, marker: marker || '', closes, via }));
+});
+
 const transport = new StdioServerTransport();
 await server.connect(transport);
 log(`ready · vault=${VAULT}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.4.1",
+  "version": "1.6.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, captureIntoBrain, tidyBrain, noteToCaptureInput,
 } from './klypix-format.mjs';
 
 // ── Card / connection input shape (single source for every face) ─────────────
@@ -109,8 +110,16 @@ export function getEmbedder(log = () => {}) {
       let t;
       try { t = await import('@huggingface/transformers'); }
       catch {
-        const local = path.join(PB_DIR, 'semantic', 'node_modules', '@huggingface', 'transformers', 'dist', 'transformers.mjs');
-        t = await import(new URL('file:///' + local.replace(/\\/g, '/')).href);
+        // The optional dep ships dist/transformers.node.mjs on v4 (Node build) and
+        // dist/transformers.mjs on older lines — try both so a correct one-click
+        // install resolves regardless of version.
+        const base = path.join(PB_DIR, 'semantic', 'node_modules', '@huggingface', 'transformers', 'dist');
+        let lastErr;
+        for (const f of ['transformers.node.mjs', 'transformers.mjs']) {
+          try { t = await import(new URL('file:///' + path.join(base, f).replace(/\\/g, '/')).href); lastErr = null; break; }
+          catch (e) { lastErr = e; }
+        }
+        if (!t) throw lastErr;
       }
       t.env.cacheDir = path.join(PB_DIR, 'hf-cache');
       return await t.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { dtype: 'q8' });
@@ -325,6 +334,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}.`);
@@ -424,5 +473,31 @@ export async function opAddToCanvas({ vault, canvas, cards, connections, via })
   }
 }
 
+// brain_note — the DELIBERATE, marker-aware write every agent (not just the
+// Claude-Code Stop hook) can make on demand. Routes through the SAME captureInto-
+// Brain engine the hook uses, so supersede / resolve / close-link / dedup behave
+// identically to a harvested 🧠 marker. The agent-neutral half of "the brain is an
+// open file any agent reads AND writes": a hookless client (Cursor/Cline/Desktop)
+// can now record a decision, ask an open question, mark a milestone, resolve a card,
+// or correct one — with the full lifecycle, not just a flat append.
+export async function opBrainNote({ vault, canvas, text: noteText, area, marker = '', closes, via }) {
+  const file = resolveCanvas(vault, canvas || 'brain') || resolveCanvas(vault, 'brain.klypix');
+  if (!file) return err(`No brain canvas found in ${vault}. Pass canvas: "<name>".`);
+  if (!noteText || !String(noteText).trim()) return err('brain_note needs a non-empty text.');
+  if (!['', '?', '!', '✓', '~'].includes(marker)) return err(`Invalid marker "${marker}" — use: (none)=decision · ?=open question · !=milestone · ✓=resolve a matching card · ~=update a matching card.`);
+  const input = noteToCaptureInput({ text: noteText, area, marker, closes: closes || '', createdVia: via || 'mcp' });
+  try {
+    const res = await captureIntoBrain(fs.readFileSync(file), input);
+    let out = res.buffer; try { out = (await tidyBrain(res.buffer)).buffer; } catch { /* keep append result if tidy fails */ }
+    await atomicWrite(file, out);
+    const s = res.stats || {};
+    const bits = [`${s.added || 0} added`];
+    for (const k of ['resolved', 'updated', 'closed', 'superseded', 'linked']) if (s[k]) bits.push(`${s[k]} ${k}`);
+    return { blocks: [text(`✓ brain_note → ${path.relative(vault, file)} (${bits.join(' · ')}). Reopen the brain in KLYPIX to see it.`)] };
+  } catch (e) {
+    return err(`brain_note failed (brain unchanged): ${e.message}`);
+  }
+}
+
 // Re-export the format helpers the bins need for non-op work (init onboarding).
 export { buildKlypixMap, parseKlypix };

package/src/klypix-format.mjs

@@ -573,8 +573,11 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
     const live = texts.filter(c => !isArchived(c));
     const focus = live.filter(isFocus);
     const rest = live.filter(c => !isFocus(c));
-    const open = rest.filter(c => /❓/.test(c.text));
-    const miles = rest.filter(c => /🏁/.test(c.text) && !/❓/.test(c.text));
+    // 🎯 (goal/target) reads as an OPEN item alongside ❓ — a goal card is
+    // still-to-do until a ✓/closes: or a covering milestone closes it (so it
+    // must NOT masquerade as a plain decision that quietly ages out of view).
+    const open = rest.filter(c => /❓|🎯/.test(c.text));
+    const miles = rest.filter(c => /🏁/.test(c.text) && !/❓|🎯/.test(c.text));
     const plain = rest.filter(c => !open.includes(c) && !miles.includes(c));
     const recent = plain.filter(c => c.createdAt >= cutoff).sort((a, b) => b.createdAt - a.createdAt).slice(0, maxRecent);
     const archivedCount = texts.length - live.length;
@@ -607,7 +610,7 @@ export function structToBrief(struct, { recentDays = 14, maxRecent = 40, maxMile
         push('', '## 📌 Human focus (cards the human placed here — act on these first)');
         for (const c of focus) push(`- ${fr(c)}${flat(c.text)}`);
     }
-    if (open.length) { push('', '## Open questions'); for (const c of open) push(`- ${fr(c)}${flat(c.text)}`); }
+    if (open.length) { push('', '## Open questions & goals'); for (const c of open) push(`- ${fr(c)}${flat(c.text)}`); }
     // ⚠️ Conflicts — pairs flagged conflicts_with (e.g. by parallel sessions);
     // surfaced HIGH so the next session reconciles them, not buries them.
     const conflicts = (struct.connections || []).filter(c => c.relationship === 'conflicts_with');
@@ -688,6 +691,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
@@ -790,7 +840,7 @@ export function brainInsights(struct, { staleDays = 21, topHubs = 6 } = {}) {
         if (cn.toId) deg.set(cn.toId, (deg.get(cn.toId) || 0) + 1);
     }
     const headline = (c) => String(c.text || '').replace(/\s+/g, ' ').trim().replace(/^(.*?)([.!?](\s|$)|$)/, '$1').slice(0, 120);
-    const isQuestion = (c) => /❓/.test(c.text);
+    const isQuestion = (c) => /❓|🎯/.test(c.text); // ❓ open question + 🎯 goal both read as "open"
     const hubs = live
         .map(c => ({ id: c.id, area: c.area, degree: deg.get(c.id) || 0, headline: headline(c) }))
         .filter(x => x.degree > 0)
@@ -995,7 +1045,7 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
             let best = null, bestScore = 0;
             for (const c of liveTextCards()) {
                 if (r.area && (c.area || '').toLowerCase() !== r.area.toLowerCase()) continue;
-                const s = overlapScore(rTok, tokenSet(c.text)) + (/❓/.test(c.text) ? 0.15 : 0);
+                const s = overlapScore(rTok, tokenSet(c.text)) + (/❓|🎯/.test(c.text) ? 0.15 : 0);
                 if (s > bestScore) { bestScore = s; best = c; }
             }
             if (best && bestScore >= RESOLVE_AT) {
@@ -1045,7 +1095,7 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
         // to the new card is drawn in pass 2 (after the new ids exist), matched
         // back by remembering which old card each new card displaced.
         for (const card of cards) {
-            if (/❓|🏁/.test(card.text)) continue; // only plain decisions supersede
+            if (/❓|🎯|🏁/.test(card.text)) continue; // only plain decisions supersede (not questions/goals/milestones)
             const nTok = tokenSet(card.text);
             const area = (card.area || '').toLowerCase();
             let best = null, bestScore = 0;
@@ -1150,6 +1200,60 @@ export async function captureIntoBrain(buffer, { cards = [], resolutions = [], u
     return { buffer: work, stats };
 }
 
+// ── Stale-open reconcile ("marked open, but a milestone says it's done") ─────
+// The READ-side twin of the closes: write path. An open ❓/🎯 card lingers as
+// "still to do" forever unless someone emits a ✓/closes: for it — so a goal that
+// quietly SHIPPED keeps surfacing in recall as a "next move". This pure pass
+// finds open cards a LATER live 🏁 milestone appears to fulfil (its text COVERS
+// the open card's distinctive tokens) and returns them so the surface can PROMPT
+// the human to close them — never auto-archives (precision-first, suggestion-only,
+// like the migration tripwire). Requires the milestone to post-date the goal so a
+// pre-existing milestone can't "fulfil" a newer goal. No I/O, node-runnable.
+export function findStaleOpenCards(struct, { coverAt = 0.6, max = 5 } = {}) {
+    const empty = { gaps: [], total: 0 };
+    if (!struct || !Array.isArray(struct.cards)) return empty;
+    const isArchived = (c) => /^archive$/i.test(c.area || '');
+    const isOpen = (c) => /❓|🎯/.test(c.text);
+    const live = struct.cards.filter(c => c.type !== 'container' && (c.text || '').trim() && !isArchived(c) && !/↩|✅/.test(c.text));
+    const opens = live.filter(isOpen);
+    const miles = live.filter(c => /🏁/.test(c.text) && !isOpen(c));
+    if (!opens.length || !miles.length) return empty;
+    const out = [];
+    for (const o of opens) {
+        const oTok = tokenSet(o.text);
+        if (oTok.size < 3) continue;                       // too vague to match safely → leave it
+        let best = null, bestCov = 0;
+        for (const m of miles) {
+            if ((m.createdAt || 0) <= (o.createdAt || 0)) continue; // only a milestone shipped AFTER the goal
+            const cov = coverageOf(oTok, tokenSet(m.text));          // how much of the goal the milestone covers
+            if (cov > bestCov) { bestCov = cov; best = m; }
+        }
+        if (best && bestCov >= coverAt) out.push({ open: o, by: best, cov: Math.round(bestCov * 100) / 100 });
+    }
+    out.sort((a, b) => b.cov - a.cov);
+    return { gaps: out.slice(0, max), total: out.length };
+}
+
+// ── Deliberate note → capture input ──────────────────────────────────────────
+// Turn ONE structured note into captureIntoBrain's input shape — the deliberate
+// twin of the Stop hook's transcript marker parser. This is what lets an ON-DEMAND
+// write (the brain_note MCP tool, the brain-note CLI — any agent, not just the
+// Claude-Code hook) get IDENTICAL supersede / resolve / close / dedup semantics as
+// a harvested 🧠 marker. marker ∈ '' (decision) | '?' (open question) | '!'
+// (milestone) | '✓' (resolve+archive a match) | '~' (update a match in place).
+export function noteToCaptureInput({ text = '', area = '', marker = '', closes = '', evidence = null, createdVia = 'mcp' } = {}) {
+    const body = String(text).trim();
+    if (!body) return { cards: [], resolutions: [], updates: [] };
+    const a = String(area || '').trim();
+    if (marker === '✓') return { cards: [], resolutions: [{ area: a, text: body }], updates: [] };
+    if (marker === '~') return { cards: [], resolutions: [], updates: [{ area: a, text: body, createdVia, ...(evidence ? { evidence } : {}) }] };
+    const prefix = marker === '?' ? '❓ ' : marker === '!' ? '🏁 ' : '';
+    const borderColor = marker === '?' ? 'rgba(245,166,35,0.8)' : marker === '!' ? 'rgba(59,130,246,0.8)' : 'rgba(16,185,129,0.6)';
+    const tag = a ? `\n#${a.toLowerCase().replace(/[^a-z0-9]+/g, '-')}` : '';
+    const cardText = (a ? `${a}: ${prefix}${body}` : `${prefix}${body}`) + tag;
+    return { cards: [{ text: cardText, area: a, color: '#e8e8ed', borderColor, createdVia, ...(closes ? { closes } : {}), ...(evidence ? { evidence } : {}) }], resolutions: [], updates: [] };
+}
+
 /**
  * Build a RICH "map" .klypix: areas become titled containers, their cards
  * stack inside, connections draw across. Produces a real spatial board (used by