@viloforge/vfkb 0.2.3 → 0.4.0

package/dist/broadcast.js

@@ -0,0 +1,134 @@
+// ADR-0063 §3 — `vfkb broadcast`: write one cross-repo record fact into each
+// target repo's brain, through the engine, stamping mechanically what the v1
+// convention leaves to discipline (the `cross-repo` tag, the CROSS-REPO marker
+// with origin + date). Refusals are per-target and loud — a partial broadcast
+// must be visible, never silent — and the writer NEVER commits the target
+// (§4: the entry rides the target's own ADR-0033 discipline).
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
+import { addEntry } from './engine.js';
+import { writeManifest } from './manifest.js';
+import { defaultProject } from './storage.js';
+import { SCHEMA_VERSION } from './version.js';
+/** The resident-pin tags a broadcast record must never carry (ADR-0063 §1). */
+const FORBIDDEN_TAGS = new Set(['handoff', 'next']);
+function targetBrainDir(target) {
+    const abs = resolve(target);
+    return basename(abs) === '.vfkb' ? abs : join(abs, '.vfkb');
+}
+function gitPosture(repoDir) {
+    const git = (...a) => execFileSync('git', ['-C', repoDir, ...a], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    try {
+        const branch = git('rev-parse', '--abbrev-ref', 'HEAD');
+        const parked = branch === 'main' || branch === 'master';
+        return `uncommitted; target on ${branch}${parked ? ' (parked — rides until a topic-branch brain commit)' : ''}`;
+    }
+    catch {
+        // rev-parse HEAD fails on a repo with no commits yet — distinguish that
+        // from "not a repo at all" (review finding: unborn HEAD was misreported).
+        try {
+            if (git('rev-parse', '--is-inside-work-tree') === 'true') {
+                return 'uncommitted; target git repository on an unborn branch (no commits yet)';
+            }
+        }
+        catch {
+            /* fall through */
+        }
+        return 'uncommitted; target not a git repository';
+    }
+}
+/**
+ * Broadcast one record to N target brains. Origin is derived from the INVOKING
+ * repo's project label, captured before any env switching. Targets without a
+ * brain are refused (never bootstrap a wire-less brain — ADR-0063 §3): no
+ * `entries.jsonl` means wire-less; a wired brain merely missing its
+ * `manifest.json` (plugin-born, vfkb#193) is healed, visibly. Brains whose
+ * schema the running engine does not support are refused (promoting doctor's
+ * diagnostic to a hard refusal).
+ */
+export function broadcast(text, targets, opts = {}) {
+    const origin = defaultProject();
+    const date = new Date().toISOString().slice(0, 10);
+    const extraTags = opts.tags ?? [];
+    for (const t of extraTags) {
+        if (FORBIDDEN_TAGS.has(t)) {
+            throw new Error(`broadcast: tag '${t}' is forbidden on cross-repo records — it claims the resident's ADR-0049 continuity pin (ADR-0063 §1)`);
+        }
+    }
+    const op = (opts.op || 'OPERATION').toUpperCase();
+    // No-double-stamp applies only to a COMPLETE marker (op + date + origin) —
+    // a bare "CROSS-REPO " prefix must not waive the stamping this command
+    // exists to mechanize (review finding: the loose prefix test let a record
+    // land with no origin and no date, the ADR-0051 §3 quiet-success shape).
+    const MARKER = /^CROSS-REPO \S+ \(\d{4}-\d{2}-\d{2}, from [^)]+\):/;
+    const stamped = MARKER.test(text) ? text : `CROSS-REPO ${op} (${date}, from ${origin}): ${text}`;
+    const results = [];
+    const written = new Set();
+    for (const target of targets) {
+        const brain = targetBrainDir(target);
+        // "Exactly one record per affected repo" (ADR-0063 §1) also holds across
+        // path spellings of the same target within one broadcast.
+        if (written.has(brain)) {
+            results.push({ target, ok: false, reason: 'duplicate target (already written in this broadcast)' });
+            continue;
+        }
+        const repoDir = resolve(brain, '..');
+        const manifestPath = join(brain, 'manifest.json');
+        let healed = false;
+        if (!existsSync(manifestPath)) {
+            // §3's rule is "never bootstrap a WIRE-LESS brain". A brain with a live
+            // entries.jsonl is wired — the manifest is just missing because only
+            // `vfkb init` ever writes it (plugin-born brains, vfkb#193). Heal it
+            // (engine-written stamp) instead of refusing; refuse only when there are
+            // no entries at all, which is the true wire-less case.
+            if (!existsSync(join(brain, 'entries.jsonl'))) {
+                results.push({ target, ok: false, reason: `no brain (no entries.jsonl in ${brain}) — never bootstrap a wire-less brain (ADR-0063 §3)` });
+                continue;
+            }
+            try {
+                writeManifest(brain);
+            }
+            catch (err) {
+                // Per-target and loud, never a thrown abort — a heal failure on one
+                // target must not swallow the rest of a partial broadcast.
+                results.push({ target, ok: false, reason: `manifest heal failed: ${err.message}` });
+                continue;
+            }
+            healed = true;
+        }
+        let schema;
+        try {
+            schema = JSON.parse(readFileSync(manifestPath, 'utf8')).schema_version;
+        }
+        catch {
+            results.push({ target, ok: false, reason: 'unreadable manifest.json' });
+            continue;
+        }
+        if (schema !== SCHEMA_VERSION) {
+            results.push({ target, ok: false, reason: `brain schema ${JSON.stringify(schema)} unsupported by engine schema v${SCHEMA_VERSION}` });
+            continue;
+        }
+        // brainDir() resolves VFKB_DATA_DIR fresh on every call (the RFC-013/033
+        // verified transport), so an env swap scopes the engine write to the target.
+        const prev = process.env.VFKB_DATA_DIR;
+        try {
+            process.env.VFKB_DATA_DIR = brain;
+            const e = addEntry('fact', stamped, { role: 'executor', tags: [...new Set(['cross-repo', ...extraTags])] });
+            written.add(brain);
+            results.push({ target, ok: true, id: e.id, posture: gitPosture(repoDir), ...(healed ? { healed } : {}) });
+        }
+        catch (err) {
+            // healed still reported on failure — the manifest stamp happened even
+            // though the record did not land (heal is never silent).
+            results.push({ target, ok: false, reason: err.message, ...(healed ? { healed } : {}) });
+        }
+        finally {
+            if (prev === undefined)
+                delete process.env.VFKB_DATA_DIR;
+            else
+                process.env.VFKB_DATA_DIR = prev;
+        }
+    }
+    return results;
+}

package/dist/bundles/vfkb-mcp.mjs

@@ -3648,49 +3648,49 @@ var require_fast_uri = __commonJS({
       schemelessOptions.skipEscape = true;
       return serialize(resolved, schemelessOptions);
     }
-    function resolveComponent(base, relative, options, skipNormalization) {
+    function resolveComponent(base, relative2, options, skipNormalization) {
       const target = {};
       if (!skipNormalization) {
         base = parse3(serialize(base, options), options);
-        relative = parse3(serialize(relative, options), options);
+        relative2 = parse3(serialize(relative2, options), options);
       }
       options = options || {};
-      if (!options.tolerant && relative.scheme) {
-        target.scheme = relative.scheme;
-        target.userinfo = relative.userinfo;
-        target.host = relative.host;
-        target.port = relative.port;
-        target.path = removeDotSegments(relative.path || "");
-        target.query = relative.query;
+      if (!options.tolerant && relative2.scheme) {
+        target.scheme = relative2.scheme;
+        target.userinfo = relative2.userinfo;
+        target.host = relative2.host;
+        target.port = relative2.port;
+        target.path = removeDotSegments(relative2.path || "");
+        target.query = relative2.query;
       } else {
-        if (relative.userinfo !== void 0 || relative.host !== void 0 || relative.port !== void 0) {
-          target.userinfo = relative.userinfo;
-          target.host = relative.host;
-          target.port = relative.port;
-          target.path = removeDotSegments(relative.path || "");
-          target.query = relative.query;
+        if (relative2.userinfo !== void 0 || relative2.host !== void 0 || relative2.port !== void 0) {
+          target.userinfo = relative2.userinfo;
+          target.host = relative2.host;
+          target.port = relative2.port;
+          target.path = removeDotSegments(relative2.path || "");
+          target.query = relative2.query;
         } else {
-          if (!relative.path) {
+          if (!relative2.path) {
             target.path = base.path;
-            if (relative.query !== void 0) {
-              target.query = relative.query;
+            if (relative2.query !== void 0) {
+              target.query = relative2.query;
             } else {
               target.query = base.query;
             }
           } else {
-            if (relative.path[0] === "/") {
-              target.path = removeDotSegments(relative.path);
+            if (relative2.path[0] === "/") {
+              target.path = removeDotSegments(relative2.path);
             } else {
               if ((base.userinfo !== void 0 || base.host !== void 0 || base.port !== void 0) && !base.path) {
-                target.path = "/" + relative.path;
+                target.path = "/" + relative2.path;
               } else if (!base.path) {
-                target.path = relative.path;
+                target.path = relative2.path;
               } else {
-                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative.path;
+                target.path = base.path.slice(0, base.path.lastIndexOf("/") + 1) + relative2.path;
               }
               target.path = removeDotSegments(target.path);
             }
-            target.query = relative.query;
+            target.query = relative2.query;
           }
           target.userinfo = base.userinfo;
           target.host = base.host;
@@ -3698,7 +3698,7 @@ var require_fast_uri = __commonJS({
         }
         target.scheme = base.scheme;
       }
-      target.fragment = relative.fragment;
+      target.fragment = relative2.fragment;
       return target;
     }
     function equal(uriA, uriB, options) {
@@ -30956,7 +30956,7 @@ var StdioServerTransport = class {
 import { randomBytes as randomBytes2 } from "node:crypto";
 
 // src/storage.ts
-import { basename, dirname, join as join3, resolve } from "node:path";
+import { basename, dirname as dirname2, join as join4, resolve } from "node:path";
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 
@@ -31154,6 +31154,23 @@ function storageBackend() {
   return current;
 }
 
+// src/journal.ts
+import { appendFileSync as appendFileSync2, existsSync as existsSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync3, renameSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname, join as join3, relative, sep } from "node:path";
+var walPath = (brain) => join3(brain, ".journal", "wal.jsonl");
+function journalAppend(brain, rec) {
+  if (process.env.VFKB_NO_JOURNAL) return;
+  try {
+    mkdirSync3(join3(brain, ".journal"), { recursive: true });
+    appendFileSync2(walPath(brain), JSON.stringify(rec) + "\n", "utf8");
+  } catch (err) {
+    process.stderr.write(
+      `vfkb: journal mirror failed (primary append proceeds unprotected): ${err.message}
+`
+    );
+  }
+}
+
 // src/validate.ts
 var ROLE = external_exports.enum(["architect", "pm", "executor", "judge", "human", "init", "import"]);
 var PROV_STATUS = external_exports.enum(["verified", "unverified", "stale", "expired"]);
@@ -31205,7 +31222,7 @@ function isTombstone(r) {
   return r.deleted === true;
 }
 function brainDir() {
-  return process.env.VFKB_DATA_DIR || process.env.VFKB_DIR || join3(homedir(), ".vfkb");
+  return process.env.VFKB_DATA_DIR || process.env.VFKB_DIR || join4(homedir(), ".vfkb");
 }
 function defaultProject() {
   const raw = (() => {
@@ -31214,7 +31231,7 @@ function defaultProject() {
     if (explicit) {
       const abs = resolve(explicit);
       const name = basename(abs);
-      return name.startsWith(".") ? basename(dirname(abs)) : name;
+      return name.startsWith(".") ? basename(dirname2(abs)) : name;
     }
     const root = process.env.CLAUDE_PROJECT_DIR;
     if (root) return basename(resolve(root));
@@ -31223,7 +31240,9 @@ function defaultProject() {
   return raw.replace(/["<>&]/g, "") || "spike";
 }
 function appendRecord(rec) {
-  storageBackend().append(rec);
+  const be = storageBackend();
+  if (be.name === "jsonl-fs") journalAppend(be.location(), rec);
+  be.append(rec);
   writeMeta();
 }
 function withExclusive(fn) {
@@ -31387,15 +31406,15 @@ function assertNoSecrets(text2) {
 }
 
 // src/counters.ts
-import { appendFileSync as appendFileSync2, mkdirSync as mkdirSync3, readFileSync as readFileSync3, existsSync as existsSync2 } from "node:fs";
-import { join as join4 } from "node:path";
+import { appendFileSync as appendFileSync3, mkdirSync as mkdirSync4, readFileSync as readFileSync4, existsSync as existsSync3 } from "node:fs";
+import { join as join5 } from "node:path";
 function signalsFile() {
-  return join4(brainDir(), ".signals", "counters.jsonl");
+  return join5(brainDir(), ".signals", "counters.jsonl");
 }
 function readSignals() {
   const f = signalsFile();
-  if (!existsSync2(f)) return [];
-  return readFileSync3(f, "utf8").split("\n").filter((l) => l.trim().length > 0).map((l) => JSON.parse(l));
+  if (!existsSync3(f)) return [];
+  return readFileSync4(f, "utf8").split("\n").filter((l) => l.trim().length > 0).map((l) => JSON.parse(l));
 }
 function tally(entryId, signals = readSignals()) {
   let helpful = 0;
@@ -31740,6 +31759,22 @@ function latestHandoff(all = readAll(), today = nowIso().slice(0, 10), supersede
   }
   return latest;
 }
+var CROSS_REPO_PIN_CAP_CHARS = 2e3;
+function latestCrossRepo(all = readAll(), today = nowIso().slice(0, 10), superseded = supersededIds(all)) {
+  let latest = null;
+  for (const e of all) {
+    if (!e.tags.includes("cross-repo")) continue;
+    if (e.tags.includes("handoff") || e.tags.includes("next")) continue;
+    if (!isInjectable(e, today, superseded)) continue;
+    if (!latest) {
+      latest = e;
+      continue;
+    }
+    const cmp = e.updated.localeCompare(latest.updated) || e.created.localeCompare(latest.created);
+    if (cmp >= 0) latest = e;
+  }
+  return latest;
+}
 function renderContextBundle(project = defaultProject(), budget = SESSION_BUDGET_CHARS) {
   const all = readAll();
   const today = nowIso().slice(0, 10);
@@ -31767,25 +31802,57 @@ function renderContextBundle(project = defaultProject(), budget = SESSION_BUDGET
     body += `## Last handoff
 - [${handoff.type} ${trustGlyph(handoff)}] ${text2}
 
+`;
+  }
+  const crossRepo = latestCrossRepo(all, today, superseded);
+  if (crossRepo && !constitutionalIds.has(crossRepo.id)) {
+    const text2 = crossRepo.text.length > CROSS_REPO_PIN_CAP_CHARS ? `${crossRepo.text.slice(0, CROSS_REPO_PIN_CAP_CHARS)}\u2026 (truncated \u2014 kb_get ${crossRepo.id} for the rest)` : crossRepo.text;
+    body += `## Cross-repo operations
+- [${crossRepo.type} ${trustGlyph(crossRepo)}] ${text2}
+
 `;
   }
   body += renderContextMap() + "\n\n";
+  const kept = [];
+  let keptLen = 0;
   let dropped = 0;
+  const fixedLen = () => header.length + body.length + footer.length;
   for (const e of injectable) {
     if (constitutionalIds.has(e.id)) continue;
     if (handoff && e.id === handoff.id) continue;
+    if (crossRepo && e.id === crossRepo.id) continue;
     const line2 = `- [${e.type} ${trustGlyph(e)}] ${e.text}
 `;
-    if (header.length + body.length + line2.length + footer.length > budget) {
+    if (fixedLen() + keptLen + line2.length > budget) {
       dropped++;
       continue;
     }
-    body += line2;
+    kept.push(line2);
+    keptLen += line2.length;
   }
   if (dropped > 0) {
-    const note = `<!-- ${dropped} lower-ranked entries omitted for the ${budget}-char budget -->
+    const note = () => `(+ ${dropped} lower-ranked entries omitted for the ${budget}-char budget \u2014 kb_search / kb_list pulls them)
 `;
-    if (header.length + body.length + note.length + footer.length <= budget) body += note;
+    const evicted = [];
+    while (kept.length > 0 && fixedLen() + keptLen + note().length > budget) {
+      const line2 = kept.pop();
+      keptLen -= line2.length;
+      evicted.push(line2);
+      dropped++;
+    }
+    if (fixedLen() + keptLen + note().length <= budget) {
+      body += kept.join("") + note();
+    } else {
+      while (evicted.length > 0) {
+        const line2 = evicted.pop();
+        kept.push(line2);
+        keptLen += line2.length;
+        dropped--;
+      }
+      body += kept.join("");
+    }
+  } else {
+    body += kept.join("");
   }
   return header + body + footer;
 }
@@ -31940,7 +32007,7 @@ function queryExplained(opts = {}) {
 }
 
 // src/version.ts
-var ENGINE_VERSION = true ? "0.2.3" : ownPackageVersion();
+var ENGINE_VERSION = true ? "0.4.0" : ownPackageVersion();
 
 // src/mcp-server.ts
 var SEARCH_DEFAULT_LIMIT = 25;