dotmd-cli 0.87.0 → 0.87.1

package/src/decisions.mjs

@@ -15,7 +15,7 @@ import { die } from './util.mjs';
 //     section: 'Decisions',          // the word a decisions heading names
 //     types: ['plan'],               // which document types carry decisions
 //     paths: ['docs/plans'],         // only documents under these, when set
-//     id: '[A-Z]{1,3}-?\\d{1,3}[a-z]?',
+//     id: '[A-Z]{1,3}-?[A-Z]?\\d{1,3}[a-z]?(?:[-.][A-Z0-9]{1,3}\\b)?',
 //     prose: false,                  // also read a disposition out of prose
 //     vocabulary: { open: [...], held: [...], ruled: [...], closed: [...] },
 //     patterns: { ruled: ['regex source', ...] }, // extra prose markers per disposition
@@ -29,7 +29,9 @@ export const DEFAULTS = Object.freeze({
   section: 'Decisions',
   types: ['plan'],
   paths: null,
-  id: '[A-Z]{1,3}-?[A-Z]?\\d{1,3}[a-z]?',
+  // A compound id (`P4-D2`, `D1-R`, `D1.2`) is read whole; `D1.` at a
+  // sentence end is still `D1`.
+  id: '[A-Z]{1,3}-?[A-Z]?\\d{1,3}[a-z]?(?:[-.][A-Z0-9]{1,3}\\b)?',
   prose: false,
   vocabulary: {
     ruled: ['ruled', 'ratified', 'resolved', 'approved', 'decided', 'answered', 'settled', 'locked'],
@@ -79,7 +81,10 @@ export function isDecisionHeading(text, section = DEFAULTS.section) {
   return words.some(w => w === stem || w === `${stem}s`);
 }
 
-function itemPatterns(id) {
+// A row may index a run of decisions written as a range, `A2 to A12`; the
+// range is its id.
+function itemPatterns(single) {
+  const id = `${single}(?:\\s+(?:to|through)\\s+${single})?`;
   return [
     { kind: 'register', re: new RegExp(`^(${id})\\s{1,3}(\\S.*)$`), registerOnly: true },
     { kind: 'table', re: new RegExp(`^\\|\\s*\\**(${id})\\**\\s*\\|(.*)$`) },
@@ -142,7 +147,11 @@ export function parseDecisionItems(text, settings = DEFAULTS) {
         const level = h[1].length;
         // A heading that shouts a disposition (`Decisions, both RESOLVED
         // 2025-01-01`) marks the items under it, as a bold lead does.
-        context = s.prose ? proseDisposition(h[2], vocab, s.patterns, { shoutedOnly: true }) : null;
+        // So does one that records a dated ruling (`Decisions, ruled by the
+        // owner 2025-01-01`): a date makes the ruling unambiguous in lowercase.
+        context = s.prose
+          ? proseDisposition(h[2], vocab, s.patterns, { shoutedOnly: true }) ?? datedRulingHeading(h[2], vocab, s.patterns)
+          : null;
         const open = items.at(-1);
         if (open && !open.closed && open.kind === 'heading' && level > open.level) {
           // A subheading inside a heading record is part of it.
@@ -179,7 +188,10 @@ export function parseDecisionItems(text, settings = DEFAULTS) {
         matched = true;
         break;
       }
-      if (!matched && !inRegister && UNNAMED.test(line)) {
+      // A bold `Decision:` field inside a heading record is part of that record.
+      const last = items.at(-1);
+      const insideRecord = last && !last.closed && last.kind === 'heading';
+      if (!matched && !inRegister && !insideRecord && UNNAMED.test(line)) {
         closeOpen(items);
         items.push({ id: null, line: i + 1, kind: 'unnamed', level: 0, context, lines: [line] });
         matched = true;
@@ -321,6 +333,13 @@ export function recordParts(text, settings = DEFAULTS) {
   return { prose, citation, answers };
 }
 
+/** A heading that records a ruling with its date, and no other disposition. */
+function datedRulingHeading(text, vocab, patterns) {
+  const dated = new RegExp(`\\b(?:${wordsRe(vocab.ruled ?? [])})\\b[^.;?!\\n]{0,40}?${DATE}`, 'i');
+  if (!dated.test(text)) return null;
+  return proseMarkers(text, vocab, patterns).every(m => m.kind === 'ruled') ? 'ruled' : null;
+}
+
 /** Documents an item points at, by basename. */
 export function pointedDocs(text) {
   const out = new Set();
@@ -331,6 +350,171 @@ export function pointedDocs(text) {
 
 // ── Assembly ─────────────────────────────────────────────────────────────────
 
+const LINK = /\[[^\]]*\]\(([^)\s]*\.md)(?:#[^)]*)?\)|\b([\w.-]+\.md)\b/g;
+const BESIDE = 24;
+
+/**
+ * Documents an item points at about its own id, by basename. A register or
+ * table row is one line indexing one id, so any document it names counts;
+ * elsewhere the id has to sit beside the link on its line (`other.md`
+ * Decisions, D1, or D1 in [other](other.md)). A record that cites another
+ * document for something else does not make that document's same id its peer.
+ */
+export function idPointedDocs(text, id, kind) {
+  if (!id) return new Set();
+  if (kind === 'register' || kind === 'table') return pointedDocs(text);
+  const out = new Set();
+  // The item's text starts after its id; the id is put back on its first line.
+  for (const line of `${id} ${text}`.split('\n')) {
+    for (const file of linksBesideId(line, id)) out.add(file);
+  }
+  return out;
+}
+
+const idPattern = id => new RegExp(`(?<![\\w.-])${escapeRe(id)}(?![\\w]|[-.][A-Z0-9])`, 'g');
+
+/** The documents, by basename, linked within a few characters of `id` on one line. */
+function linksBesideId(line, id) {
+  const out = new Set();
+  const at = [...line.matchAll(idPattern(id))].map(m => [m.index, m.index + m[0].length]);
+  if (!at.length) return out;
+  for (const m of line.matchAll(LINK)) {
+    const start = m.index;
+    const end = m.index + m[0].length;
+    if (at.some(([a, b]) => (a >= end && a - end <= BESIDE) || (b <= start && start - b <= BESIDE))) {
+      out.add((m[1] ?? m[2]).split('/').pop());
+    }
+  }
+  return out;
+}
+
+// ── What each decision blocks ────────────────────────────────────────────────
+
+// A range written out (`A2 to A12`, `A2-A12`, `A2 through 12`) names every id in it.
+const RANGE = /(?<![\w.-])([A-Z]{1,3}-?)(\d{1,3})\s*(?:to|through|thru|–|—|-)\s*(?:\1)?(\d{1,3})(?![\w])/g;
+
+/** Whether a line names `id`, on its own or inside a written range. An id
+ * that is itself a range (`A2 to A12`) is named when any id in it is. */
+export function namesId(line, id, ranges = writtenRanges(line)) {
+  const span = id.match(/^([A-Z]{1,3}-?)(\d{1,3})\s+(?:to|through)\s+\1?(\d{1,3})$/);
+  if (span) {
+    if (line.includes(id)) return true;
+    const [lo, hi] = [Number(span[2]), Number(span[3])];
+    for (let n = lo; n <= hi && n - lo < 100; n++) if (namesId(line, `${span[1]}${n}`, ranges)) return true;
+    return false;
+  }
+  if (line.includes(id) && idPattern(id).test(line)) return true;
+  if (!ranges.length) return false;
+  const m = id.match(/^([A-Z]{1,3}-?)(\d{1,3})$/);
+  if (!m) return false;
+  const n = Number(m[2]);
+  return ranges.some(([prefix, lo, hi]) => prefix === m[1] && lo <= n && n <= hi);
+}
+
+function writtenRanges(line) {
+  return [...line.matchAll(RANGE)].map(r => [r[1], Number(r[2]), Number(r[3])]);
+}
+
+// What the record says it holds up: `blocks Phase 5`, `gates the sizing`,
+// `which switch sizing waits on`.
+// The verb has to open a clause (after a comma, a colon, `it`, `this`, `which`
+// or `and`), so a noun such as "code blocks" is not read as one.
+const STATED = [
+  /(?:^|[,;:(]\s*|\b(?:it|this|which|and|that)\s+)(?:blocks|gates|is blocking|holds up)\s+(?!on\b|nothing\b|none\b)([^.;:,()\n|]{3,80})/gi,
+  /\bwhich\s+([^.;:,()\n|]{3,60}?)\s+waits?\s+on\b/gi,
+];
+
+export function statedBlocks(text) {
+  const body = clean(text);
+  const out = [];
+  for (const re of STATED) {
+    for (const m of body.matchAll(re)) {
+      const what = m[1].trim().replace(/\s+(?:and|or|until|unless|while|when)$/i, '');
+      if (what && !out.includes(what)) out.push(what);
+    }
+  }
+  return out;
+}
+
+const OPEN_BOX = /^\s*[-*+]\s+\[ \]\s+(.*)$/;
+const BLOCKER_KEYS = /^(?:blockers|blocked_by):\s*(.*)$/;
+
+/**
+ * The open work in one document, one entry per line that can wait on a
+ * decision: an unticked checklist item, or a frontmatter blocker. Each carries
+ * the heading it sits under. Pure.
+ */
+export function openWork(text) {
+  const lines = text.split('\n');
+  const out = [];
+  let i = 0;
+  if (lines[0] === '---') {
+    const end = lines.indexOf('---', 1);
+    let inBlockers = false;
+    for (i = 1; i < (end > 0 ? end : 0); i++) {
+      const line = lines[i];
+      const key = line.match(/^([A-Za-z_][\w-]*):/);
+      if (key) {
+        const b = line.match(BLOCKER_KEYS);
+        inBlockers = Boolean(b);
+        if (b && b[1].trim() && !/^\[\s*\]$/.test(b[1].trim())) out.push({ line: i + 1, kind: 'blocker', section: null, text: b[1] });
+        continue;
+      }
+      const item = inBlockers && line.match(/^\s+-\s+(.*)$/);
+      if (item) out.push({ line: i + 1, kind: 'blocker', section: null, text: item[1].replace(/^["']|["']$/g, '') });
+    }
+    if (end > 0) i = end + 1;
+  }
+  let section = null;
+  let fence = null;
+  for (; i < lines.length; i++) {
+    const line = lines[i];
+    const f = line.match(/^\s*(`{3,}|~{3,})/);
+    if (f) { fence = fence === null ? f[1][0] : (f[1][0] === fence ? null : fence); continue; }
+    if (fence !== null) continue;
+    const h = line.match(/^#{1,6}\s+(.+)$/);
+    if (h) { section = clean(h[1]).replace(/\s*[⬜✅🟡🟢🔴⏳]\uFE0F?(?:\s*(?:todo|done|wip|in progress|partial))?\s*$/iu, ''); continue; }
+    const box = line.match(OPEN_BOX);
+    if (box) out.push({ line: i + 1, kind: 'item', section, text: box[1] });
+  }
+  return out;
+}
+
+const clip = (t, n) => (t.length > n ? `${t.slice(0, n - 1).trimEnd()}…` : t);
+
+/**
+ * What waits on each pending decision: what its record says it blocks, and
+ * every unticked checklist item or frontmatter blocker that names it. In its
+ * own document an entry naming the id counts; in another document the id has
+ * to sit beside a link to the decision's document, the rule records pair by.
+ * `items` are the ones asked about; `all` is every item read, so no record is
+ * counted as waiting on another. Returns a Map from item to
+ * `[{ doc, line, kind, section, text }]`.
+ */
+export function blocksOf(items, docs, all = items) {
+  const work = docs.map(d => ({
+    path: d.path,
+    entries: openWork(d.text).map(e => ({ ...e, ranges: writtenRanges(e.text) })),
+  }));
+  // An entry that is itself a decision item is the record, not what waits on it.
+  const starts = new Set(all.map(i => `${i.doc}:${i.line}`));
+  const out = new Map();
+  for (const item of items) {
+    if (!item.id) continue;
+    const found = statedBlocks(item.text).map(text => ({ doc: item.doc, line: item.line, kind: 'stated', section: null, text }));
+    for (const d of work) {
+      const own = d.path === item.doc;
+      for (const e of d.entries) {
+        if (starts.has(`${d.path}:${e.line}`) || !namesId(e.text, item.id, e.ranges)) continue;
+        if (!own && !linksBesideId(e.text, item.id).has(item.file)) continue;
+        found.push({ doc: d.path, line: e.line, kind: e.kind, section: e.section, text: clip(clean(e.text), 240) });
+      }
+    }
+    out.set(item, found);
+  }
+  return out;
+}
+
 /**
  * Every item across the given documents with its disposition, its parts (its
  * own plus a linked record's) and what it is missing. Pure.
@@ -344,10 +528,11 @@ export function analyzeDecisions(docs, settings = DEFAULTS) {
       items.push({
         ...item,
         doc: doc.path,
+        docTitle: doc.title ?? null,
         file: path.basename(doc.path),
         disposition: dispositionOf(item, s),
         own: recordParts(item.text, s),
-        points: pointedDocs(item.text),
+        points: idPointedDocs(item.text, item.id, item.kind),
       });
     }
   }
@@ -377,8 +562,12 @@ export function analyzeDecisions(docs, settings = DEFAULTS) {
   return items;
 }
 
-/** The pending rows, one per decision: linked pairs collapse, a register row preferred. */
-export function pendingRows(items, { doc = null, all = false } = {}) {
+/**
+ * The pending rows, one per decision: linked pairs collapse, a register row
+ * preferred. With `blocks` (from `blocksOf`), each row carries what waits on
+ * it, gathered across the record and every peer it collapsed.
+ */
+export function pendingRows(items, { doc = null, all = false, blocks = null } = {}) {
   let rows = items.filter(i => i.id && (all || PENDING.has(i.effective)));
   if (doc) rows = rows.filter(i => i.doc === doc);
   const kept = [];
@@ -391,16 +580,34 @@ export function pendingRows(items, { doc = null, all = false } = {}) {
   for (const k of kept) shared.set(k.id, (shared.get(k.id) ?? 0) + 1);
   return kept
     .sort((a, b) => a.id.localeCompare(b.id, 'en', { numeric: true }) || a.doc.localeCompare(b.doc))
-    .map(item => ({
-      id: item.id,
-      label: shared.get(item.id) > 1 ? `${item.id} (${item.file})` : item.id,
-      doc: item.doc,
-      line: item.line,
-      kind: item.kind,
-      disposition: item.effective,
-      missing: item.missing,
-      text: renderLine(item),
-    }));
+    .map(item => {
+      const row = {
+        id: item.id,
+        label: shared.get(item.id) > 1 ? `${item.id} (${item.file})` : item.id,
+        doc: item.doc,
+        docTitle: item.docTitle ?? null,
+        line: item.line,
+        kind: item.kind,
+        disposition: item.effective,
+        missing: item.missing,
+        question: questionOf(item),
+        text: renderLine(item),
+      };
+      if (blocks) {
+        const seen = new Set();
+        row.blocks = [item, ...item.peers].flatMap(i => blocks.get(i) ?? [])
+          .filter(b => { const k = `${b.doc}:${b.line}:${b.text}`; return !seen.has(k) && seen.add(k); });
+      }
+      return row;
+    });
+}
+
+/** The record's question, even when the record is incomplete: its first
+ * sentence ending in `?`, else its first sentence. */
+function questionOf(item) {
+  const parts = sentences(clean(item.text).replace(/^(?:open|held|ruled|closed)\b[^.:]*[.:]\s*/i, ''));
+  const q = parts.find(t => t.endsWith('?')) ?? parts[0] ?? '';
+  return clip(q.replace(/^[^\p{L}\p{N}"'(]+/u, ''), 300);
 }
 
 const clean = t => t
@@ -461,7 +668,7 @@ export function loadDecisionDocs(config, settings) {
     // A document whose frontmatter did not parse has no type; it is read rather than dropped.
     .filter(d => (types.has(d.type) || !d.type) && d.status !== 'archived' && !d.path.split('/').includes(archiveDir))
     .filter(d => !s.paths || [].concat(s.paths).some(p => d.path === p || d.path.startsWith(`${p.replace(/\/$/, '')}/`)))
-    .map(d => ({ path: d.path, text: readFileSync(path.join(config.repoRoot, d.path), 'utf8') }));
+    .map(d => ({ path: d.path, title: d.title ?? null, text: readFileSync(path.join(config.repoRoot, d.path), 'utf8') }));
 }
 
 export function runDecisions(args, config) {
@@ -494,7 +701,12 @@ export function runDecisions(args, config) {
     else die(`No document or decision id matches "${target}".`);
   }
 
-  const rows = pendingRows(items, { doc: docFilter, all });
+  let blocks = null;
+  if (json) {
+    const asked = items.filter(i => i.id && (all || PENDING.has(i.effective)) && (!docFilter || i.doc === docFilter));
+    blocks = blocksOf([...new Set(asked.flatMap(i => [i, ...i.peers]))], docs, items);
+  }
+  const rows = pendingRows(items, { doc: docFilter, all, blocks });
   if (json) {
     process.stdout.write(`${JSON.stringify(rows, null, 2)}\n`);
     return;

package/src/diff.mjs

@@ -3,7 +3,7 @@ import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath, die, warn } from './util.mjs';
 import { gitDiffSince } from './git.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
-import { summarizeDiffText, DEFAULT_MODEL } from './ai.mjs';
+import { summarizeDiffText } from './ai.mjs';
 import { bold, dim } from './color.mjs';
 
 export function runDiff(argv, config) {
@@ -12,7 +12,7 @@ export function runDiff(argv, config) {
   let stat = false;
   let sinceOverride = null;
   let summarize = false;
-  let model = DEFAULT_MODEL;
+  let model;
 
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--stat') { stat = true; continue; }

package/src/errors-read.mjs

@@ -0,0 +1,30 @@
+import { readGlobalErrors, globalErrorLogPath } from './journal.mjs';
+import { die } from './util.mjs';
+import { dim, red } from './color.mjs';
+
+// `runlist errors` — the newest failed runlist commands, from the cross-repo
+// error log every failing invocation appends to.
+function parseArgs(argv) {
+  const opts = { limit: 20, repo: null, asJson: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--limit' || a === '--tail') {
+      const n = Number(argv[++i]);
+      if (!Number.isInteger(n) || n < 1) die(`${a} takes a whole number of entries, 1 or more.`);
+      opts.limit = n;
+    } else if (a === '--repo' && argv[i + 1]) opts.repo = argv[++i];
+    else if (a === '--json') opts.asJson = true;
+  }
+  return opts;
+}
+
+export function runErrors(argv) {
+  const opts = parseArgs(argv);
+  const entries = readGlobalErrors({ limit: opts.limit, repo: opts.repo });
+  if (opts.asJson) { process.stdout.write(`${JSON.stringify(entries, null, 2)}\n`); return; }
+  if (!entries.length) { process.stdout.write(`No failed runlist commands recorded in ${globalErrorLogPath()}.\n`); return; }
+  for (const e of entries) {
+    const repo = e.repo ? dim(` ${e.repo.split('/').pop()}`) : '';
+    process.stdout.write(`[${e.at}]${repo} ${e.command}\n  ${red(e.message ?? '(no message)')}\n`);
+  }
+}

package/src/journal.mjs

@@ -322,6 +322,32 @@ export function recordGlobalError({ config, startMs, args, err, version }) {
   }
 }
 
+// The newest failures first, as `{ at, command, message, repo, exit }`: the
+// current file, then its one rollover. Reads what `recordGlobalError` wrote
+// (argv and message already sanitized there); nothing else is kept per line.
+export function readGlobalErrors({ limit = 20, repo = null } = {}) {
+  const file = globalErrorLogPath();
+  const backup = globalErrorLogBackupPath();
+  purgeLegacyTelemetry(file, backup);
+  pruneStaleBackup(backup);
+  const out = [];
+  for (const source of [file, backup]) {
+    const lines = readLogLines(source).reverse();
+    for (const e of lines) {
+      if (repo && !String(e.repo ?? '').includes(repo)) continue;
+      out.push({
+        at: e.ts ?? null,
+        command: ['runlist', ...(Array.isArray(e.argv) ? e.argv : [])].join(' '),
+        message: e.err ?? null,
+        repo: e.repo ?? null,
+        exit: e.exit ?? null,
+      });
+      if (limit && out.length >= limit) return out;
+    }
+  }
+  return out;
+}
+
 // Misuse log: always-on, cross-repo, append-only record of every wrong-move the
 // PreToolUse guard intercepts (committing a gitignored prompt, `cat`-ing a
 // prompt instead of `dotmd use`, hand-editing a `status:` field, …). This is

package/src/lint.mjs

@@ -4,7 +4,7 @@ import { extractFrontmatter, parseSimpleFrontmatter, replaceFrontmatter } from '
 import { asString, toRepoPath, escapeRegex, warn } from './util.mjs';
 import { buildIndex, collectDocFiles } from './index.mjs';
 import { updateFrontmatter } from './lifecycle.mjs';
-import { runMLX, checkUvAvailable } from './ai.mjs';
+import { runModel } from './ai.mjs';
 import { bold, green, yellow, dim } from './color.mjs';
 import { authorizeManagedSweep, findLexicalDocsRoot } from './managed-path.mjs';
 
@@ -274,7 +274,7 @@ export function runLint(argv, config, opts = {}) {
         const statusList = inferTypeSet ? [...inferTypeSet].join(', ') : config.statusOrder.join(', ');
         const { body } = extractFrontmatter(raw);
         const prompt = `Given this markdown document, classify it into exactly one of these statuses: ${statusList}.\nReply with ONLY the status word, nothing else.\n\nFile: ${repoPath}\n\n${(body ?? '').slice(0, 4000)}`;
-        const result = runMLX(prompt, { maxTokens: 10 });
+        const result = runModel(prompt, { maxTokens: 10 });
         const suggested = result?.trim().toLowerCase().split(/\s+/)[0];
         const inferValid = inferTypeSet ?? config.validStatuses;
         if (suggested && inferValid.has(suggested)) {

package/src/model-request.mjs

@@ -0,0 +1,33 @@
+// HTTP requests to the local model server, run as a child process so the
+// synchronous callers (summaries, lint's status inference) can wait on them
+// without every render path turning async. Reads a list of
+// {url, method, body, timeoutMs} as JSON on stdin, sends them in order, and
+// writes the list of {ok, status, json, error} as JSON on stdout.
+
+const input = JSON.parse(await new Promise(resolve => {
+  let data = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { data += chunk; });
+  process.stdin.on('end', () => resolve(data));
+}));
+
+async function send(input) {
+  try {
+    const res = await fetch(input.url, {
+      method: input.method ?? 'GET',
+      headers: input.body ? { 'content-type': 'application/json' } : undefined,
+      body: input.body ? JSON.stringify(input.body) : undefined,
+      signal: AbortSignal.timeout(input.timeoutMs ?? 10000),
+    });
+    const text = await res.text();
+    let json = null;
+    try { json = JSON.parse(text); } catch { /* non-JSON body; status says enough */ }
+  return { ok: res.ok, status: res.status, json, error: res.ok ? null : (json?.error ?? text.slice(0, 200)) };
+  } catch (err) {
+    return { ok: false, status: 0, json: null, error: err.name === 'TimeoutError' ? 'timed out' : (err.cause?.code ?? err.message) };
+  }
+}
+
+const out = [];
+for (const req of [input].flat()) out.push(await send(req));
+process.stdout.write(JSON.stringify(Array.isArray(input) ? out : out[0]));