@yemi33/minions 0.1.2154 → 0.1.2155

package/engine/db/migrations/013-backfill-broken-note-links.js

@@ -0,0 +1,31 @@
+// engine/db/migrations/013-backfill-broken-note-links.js
+//
+// One-time data repair (not a schema change). Before the work-item rewriter
+// covered completion-report artifact links (W-mq1j85cj00055a8f, extended to
+// _artifacts.notes[] / artifacts[]), any inbox note the engine auto-archived
+// left the work item's note link pointing at the gone `notes/inbox/<name>` path
+// — a dangling pill. This migration runs the backfill exactly once on the next
+// engine start: it scans existing work_items, finds links whose inbox file is
+// missing, discovers where the note went (notes/archive/ or knowledge/<cat>/),
+// and repoints them. Best-effort and self-isolating — wrapped so a failure can
+// never wedge boot or roll back the migration batch.
+
+module.exports = {
+  version: 13,
+  description: 'one-time backfill: repoint broken inbox note links in existing work items',
+  up(db) {
+    try {
+      const { backfillBrokenNoteLinks } = require('../../note-link-backfill');
+      const res = backfillBrokenNoteLinks(db);
+      if (res && res.fixedLinks > 0) {
+        // eslint-disable-next-line no-console -- migrate.js logs progress to stdout
+        console.log(`[db-migrate] v13: repointed ${res.fixedLinks} broken note link(s) across ${res.fixedItems} work item(s) (${res.scanned} scanned)`);
+      }
+    } catch (e) {
+      // One-time cosmetic repair — never block boot. Record the version anyway
+      // so it doesn't retry forever against the same un-repairable state.
+      // eslint-disable-next-line no-console -- surface the skip without throwing
+      console.warn(`[db-migrate] v13: note-link backfill skipped: ${e && e.message ? e.message : e}`);
+    }
+  },
+};

package/engine/note-link-backfill.js

@@ -0,0 +1,202 @@
+// engine/note-link-backfill.js
+//
+// One-time repair for work-item note links that broke BEFORE the live
+// rewrite landed (W-mq1j85cj00055a8f extended to _artifacts.notes / artifacts).
+//
+// Before the rewriter covered completion-report artifact links, any inbox note
+// that the engine auto-archived (or that was promoted to KB) left the work
+// item's link pointing at the now-gone `notes/inbox/<name>` path — a dangling
+// pill in the dashboard. This module scans existing work items, finds links
+// whose inbox file is GONE, discovers where the note actually went (the flat
+// `notes/archive/` dir or a `knowledge/<cat>/` dir), and repoints the link —
+// re-encoding the `_artifacts.notes[].file` token to the renderer's
+// `archive:<base>` / `kb:<cat>/<file>` form so the pill resolves again.
+//
+// It only ever touches links that are PROVABLY broken (inbox file missing) AND
+// resolvable (a matching archive/KB file exists). Valid links, already-relocated
+// tokens, and notes with no discoverable destination (e.g. merged into the flat
+// notes.md) are left untouched. Idempotent: a second pass finds nothing because
+// the repaired links no longer reference `notes/inbox/`.
+//
+// Wired as a one-time SQL migration (db/migrations/013-*) so it runs exactly
+// once on the next engine start after an update. Updates the canonical SQL
+// `work_items` rows only; the JSON mirror self-heals on the next mutateWorkItems
+// write and SQL is what readers serve (work-items-store), so rewriting the
+// passive mirror here would only risk dropping rows for no benefit.
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const INBOX_REF_RE = /(?:^|\/)notes\/inbox\/([^/?#]+)/;
+
+// Extract the inbox basename from a `…/notes/inbox/<name>` string (tolerating a
+// trailing ?query / #fragment), or null if the string isn't an inbox ref.
+function inboxNameFromRef(str) {
+  if (typeof str !== 'string') return null;
+  const m = str.match(INBOX_REF_RE);
+  return m ? m[1] : null;
+}
+
+// Build a resolver: inbox basename → { newLocation, fileToken } | null.
+//   - null when the note is STILL in the inbox (link isn't broken), or when no
+//     destination can be discovered (note merged into notes.md, or deleted).
+//   - newLocation is the MINIONS_DIR-relative path; fileToken is the prefixed
+//     basename the work-item renderer resolves for note pills.
+// The archive dir is flat: consolidation writes `${YYYY-MM-DD}-${name}` (with an
+// optional uniquePath `-N` collision suffix). We index each archived file by the
+// basename it derived from (date prefix stripped) and by its literal name.
+function buildNoteResolver(dirs) {
+  const inboxDir = dirs.inboxDir;
+  const archiveDir = dirs.archiveDir;
+  const knowledgeDir = dirs.knowledgeDir;
+  const kbCategories = Array.isArray(dirs.kbCategories) ? dirs.kbCategories : [];
+  // Reuse the live rewriter's encoder so the backfill and the live path emit
+  // byte-identical pill tokens (one source for the archive:/kb: grammar).
+  const tokenFor = require('./shared')._artifactNoteFileToken;
+
+  const archiveByBase = new Map();
+  let archiveFiles = [];
+  try { archiveFiles = fs.readdirSync(archiveDir); } catch { archiveFiles = []; }
+  for (const f of archiveFiles) {
+    const origin = f.replace(/^\d{4}-\d{2}-\d{2}-/, '');
+    for (const key of new Set([origin, f])) {
+      const prev = archiveByBase.get(key);
+      // Lexicographic max keeps the newest date-prefixed file for a given note.
+      if (!prev || f > prev) archiveByBase.set(key, f);
+    }
+  }
+
+  const kbByBase = new Map();
+  for (const cat of kbCategories) {
+    let files = [];
+    try { files = fs.readdirSync(path.join(knowledgeDir, cat)); } catch { files = []; }
+    for (const f of files) if (!kbByBase.has(f)) kbByBase.set(f, cat + '/' + f);
+  }
+
+  return function resolve(baseName) {
+    if (!baseName) return null;
+    try { if (fs.existsSync(path.join(inboxDir, baseName))) return null; } catch { /* treat as gone */ }
+    const arch = archiveByBase.get(baseName);
+    if (arch) { const nl = 'notes/archive/' + arch; return { newLocation: nl, fileToken: tokenFor(nl) }; }
+    const kb = kbByBase.get(baseName);
+    if (kb) { const nl = 'knowledge/' + kb; return { newLocation: nl, fileToken: tokenFor(nl) }; }
+    return null;
+  };
+}
+
+// Repoint every broken inbox note link on one work item in place. `resolve` is a
+// buildNoteResolver() result (returns null for non-broken / unresolvable). Mirrors
+// the link shapes shared.rewriteInboxRefsAcrossProjects handles: references[],
+// _artifacts.notes[] (string + object), and artifacts[].path. Returns the count
+// of links repointed.
+function repointItemNoteLinks(item, resolve) {
+  if (!item || typeof item !== 'object') return 0;
+  let fixed = 0;
+
+  if (Array.isArray(item.references)) {
+    for (let i = 0; i < item.references.length; i++) {
+      const ref = item.references[i];
+      if (typeof ref === 'string') {
+        const name = inboxNameFromRef(ref);
+        if (name) { const d = resolve(name); if (d) { item.references[i] = d.newLocation; fixed++; } }
+      } else if (ref && typeof ref === 'object') {
+        for (const key of ['url', 'path', 'href']) {
+          const name = inboxNameFromRef(ref[key]);
+          if (name) { const d = resolve(name); if (d) { ref[key] = d.newLocation; fixed++; break; } }
+        }
+      }
+    }
+  }
+
+  const notes = item._artifacts && item._artifacts.notes;
+  if (Array.isArray(notes)) {
+    for (let i = 0; i < notes.length; i++) {
+      const n = notes[i];
+      if (typeof n === 'string') {
+        // Bare basename = an inbox pill. Skip tokens already relocated.
+        if (n.startsWith('archive:') || n.startsWith('kb:')) continue;
+        const d = resolve(n);
+        if (d && d.fileToken) { notes[i] = d.fileToken; fixed++; }
+      } else if (n && typeof n === 'object') {
+        let name = inboxNameFromRef(n.path);
+        if (!name && typeof n.file === 'string'
+            && !n.file.startsWith('archive:') && !n.file.startsWith('kb:')) {
+          name = n.file;
+        }
+        if (name) {
+          const d = resolve(name);
+          if (d) {
+            if (typeof n.path === 'string') n.path = d.newLocation;
+            if (d.fileToken && typeof n.file === 'string') n.file = d.fileToken;
+            fixed++;
+          }
+        }
+      }
+    }
+  }
+
+  if (Array.isArray(item.artifacts)) {
+    for (const a of item.artifacts) {
+      if (a && typeof a === 'object') {
+        const name = inboxNameFromRef(a.path);
+        if (name) { const d = resolve(name); if (d) { a.path = d.newLocation; fixed++; } }
+      }
+    }
+  }
+
+  return fixed;
+}
+
+// Scan the canonical SQL `work_items` table and repair broken note links in
+// place. db is a node:sqlite DatabaseSync (the migration's connection). Per-row
+// try/catch so one corrupt row can't abort the pass. Returns a summary.
+function backfillBrokenNoteLinks(db, opts = {}) {
+  const shared = require('./shared');
+  const minionsDir = opts.minionsDir || shared.MINIONS_DIR;
+  const resolve = buildNoteResolver({
+    inboxDir: path.join(minionsDir, 'notes', 'inbox'),
+    archiveDir: path.join(minionsDir, 'notes', 'archive'),
+    knowledgeDir: path.join(minionsDir, 'knowledge'),
+    kbCategories: shared.KB_CATEGORIES,
+  });
+
+  let scopes;
+  try {
+    scopes = db.prepare('SELECT DISTINCT scope FROM work_items').all().map(r => r.scope);
+  } catch {
+    return { scanned: 0, fixedItems: 0, fixedLinks: 0 };
+  }
+
+  const now = opts.now || Date.now();
+  const upd = db.prepare('UPDATE work_items SET data = ?, updated_at = ? WHERE scope = ? AND id = ?');
+  let scanned = 0, fixedItems = 0, fixedLinks = 0;
+
+  for (const scope of scopes) {
+    let rows;
+    try { rows = db.prepare('SELECT id, data FROM work_items WHERE scope = ?').all(scope); } catch { continue; }
+    for (const row of rows) {
+      let item;
+      try { item = JSON.parse(row.data); } catch { continue; }
+      scanned++;
+      try {
+        const n = repointItemNoteLinks(item, resolve);
+        if (n > 0) {
+          upd.run(JSON.stringify(item), now, scope, item.id);
+          fixedItems++;
+          fixedLinks += n;
+        }
+      } catch { /* skip unfixable row */ }
+    }
+  }
+
+  return { scanned, fixedItems, fixedLinks };
+}
+
+module.exports = {
+  inboxNameFromRef,
+  buildNoteResolver,
+  repointItemNoteLinks,
+  backfillBrokenNoteLinks,
+};

package/engine/shared.js

@@ -7503,6 +7503,7 @@ module.exports = {
   extractWorkItemPrRef,
   extractStructuredWorkItemPrRef,
   rewriteInboxRefsAcrossProjects,
+  _artifactNoteFileToken, // exported so the one-time note-link backfill shares the token grammar
   getProjectPrScope,
   getPrNumber,
   getPrDisplayId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2154",
+  "version": "0.1.2155",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"