dotmd-cli 0.45.3 → 0.47.0

package/bin/dotmd.mjs

@@ -6,6 +6,7 @@ import path from 'node:path';
 import { resolveConfig } from '../src/config.mjs';
 import { die, warn, levenshtein } from '../src/util.mjs';
 import { recordCliInvocation } from '../src/journal.mjs';
+import { findRepeatFailureHint } from '../src/hints.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -1556,7 +1557,15 @@ function _journalExit(err) {
 main()
   .then(() => { _journalExit(null); })
   .catch(err => {
-    process.stderr.write(`${err.message}\n`);
+    let out = err.message;
+    // F17c: append a repeat-failure tip when the journal shows this same shape
+    // has already failed in this session within the lookup window. Lookup is
+    // a no-op when the journal is disabled or DOTMD_NO_HINTS=1.
+    try {
+      const hint = findRepeatFailureHint(_invocationArgs, _resolvedConfig);
+      if (hint) out = `${out}\n\nTip: ${hint}`;
+    } catch { /* hint must never break error reporting */ }
+    process.stderr.write(`${out}\n`);
     process.exitCode = 1;
     _journalExit(err);
   });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.45.3",
+  "version": "0.47.0",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/hints.mjs

@@ -0,0 +1,133 @@
+import { existsSync } from 'node:fs';
+import { readJournalEntries, isJournalEnabled, journalFilePath } from './journal.mjs';
+import { currentSessionId } from './lease.mjs';
+
+// F17c: repeat-failure hints. When an agent runs the same broken invocation
+// twice in the same session within HINT_WINDOW_MS, the second die() output is
+// suffixed with a Tip: paragraph informed by the prior failure's recorded
+// stderr. First failures stay terse — don't punish humans typing a command
+// for the first time. The lookup is skipped cleanly when the journal is
+// disabled or DOTMD_NO_HINTS=1, so this costs nothing for non-opt-in users.
+
+const HINT_WINDOW_MS = 10 * 60 * 1000;
+const OVERLAP_THRESHOLD = 0.75;
+
+const TEMPLATES = [
+  {
+    match: /Too many arguments|Usage:/i,
+    hint: ({ count, argv }) =>
+      `${count}× the same shape on \`${argv[0]} ${argv[1] ?? ''}\` in this session. Run \`dotmd ${argv[0]} --help\` for the expected positional args.`,
+  },
+  {
+    match: /Already (consumed|archived)/i,
+    hint: ({ count, argv }) =>
+      `${count}× attempts to use a path that is already archived. Use \`dotmd prompts list\` to see what is actually pending, or \`dotmd next\` for the oldest live prompt.`,
+  },
+  {
+    match: /No pending prompts/i,
+    hint: ({ count }) =>
+      `${count}× \`dotmd next\` with no pending prompts in the queue. Either queue one with \`dotmd new prompt <slug> "..."\` or pass an explicit prompt file to \`dotmd use\`.`,
+  },
+  {
+    match: /Unknown command/i,
+    hint: ({ count }) =>
+      `${count}× the same unknown command. Run \`dotmd --help\` to list available commands; the dispatch already prints a did-you-mean for close misses.`,
+  },
+  {
+    match: /File not found|does not resolve/i,
+    hint: ({ count, argv }) =>
+      `${count}× pointing at a path that doesn't exist. Confirm the file with \`dotmd query\` or \`dotmd plans\` — paths resolve relative to repo root or doc roots, not the cwd.`,
+  },
+  {
+    match: /Lease conflict|in-session|held by/i,
+    hint: ({ count }) =>
+      `${count}× lease conflict in this session. Run \`dotmd plans --status in-session\` to see what's held; pass \`--takeover\` if the holder is stale, or close the other session first.`,
+  },
+  {
+    match: /Unknown status|Unknown surface/i,
+    hint: ({ count }) =>
+      `${count}× rejected by the taxonomy validator. Run \`dotmd statuses list\` or \`dotmd surfaces\` to print the valid values for this project.`,
+  },
+];
+
+// Global value-consuming flags must be skipped together with the token that
+// follows them — otherwise `--config /tmp/foo` injects the tempdir path as
+// "positional" and dilutes Jaccard overlap below threshold. Keep this list
+// aligned with the global flag-strip list in bin/dotmd.mjs (SCRUB_*).
+const VALUE_FLAGS = new Set([
+  '--config', '--root', '--type', '--limit', '--sort', '--group',
+  '--status', '--owner', '--module', '--surface', '--domain',
+  '--audience', '--execution-mode', '--updated-since',
+  '--summarize-limit', '--model',
+]);
+
+function nonFlagSet(argv) {
+  const out = new Set();
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (typeof a !== 'string') continue;
+    if (a.startsWith('-')) {
+      if (VALUE_FLAGS.has(a)) i++;
+      continue;
+    }
+    out.add(a);
+  }
+  return out;
+}
+
+function jaccard(a, b) {
+  if (a.size === 0 && b.size === 0) return 1;
+  const aArr = [...a];
+  const inter = aArr.filter(x => b.has(x)).length;
+  const union = new Set([...a, ...b]).size;
+  return union === 0 ? 0 : inter / union;
+}
+
+// Returns a hint string (no `Tip:` prefix) or null. The caller is responsible
+// for formatting. Failures inside this function are swallowed — a malformed
+// journal must never break the error-reporting path.
+export function findRepeatFailureHint(failingArgv, config) {
+  try {
+    if (process.env.DOTMD_NO_HINTS === '1') return null;
+    if (!config) return null;
+    if (!isJournalEnabled(config)) return null;
+    if (!existsSync(journalFilePath(config))) return null;
+    if (!Array.isArray(failingArgv) || failingArgv.length === 0) return null;
+
+    const sid = currentSessionId();
+    const now = Date.now();
+    const cutoff = now - HINT_WINDOW_MS;
+    const failingShape = nonFlagSet(failingArgv);
+
+    const entries = readJournalEntries(config);
+    const matches = [];
+    for (const entry of entries) {
+      if (!entry || entry.sid !== sid) continue;
+      if (!Array.isArray(entry.argv) || entry.argv.length === 0) continue;
+      if (entry.argv[0] !== failingArgv[0]) continue;
+      if ((entry.exit ?? 0) === 0) continue;
+      const ts = new Date(entry.ts).getTime();
+      if (Number.isNaN(ts) || ts < cutoff) continue;
+      const priorShape = nonFlagSet(entry.argv);
+      if (jaccard(failingShape, priorShape) < OVERLAP_THRESHOLD) continue;
+      matches.push({ entry, ts });
+    }
+
+    if (matches.length === 0) return null;
+    matches.sort((a, b) => b.ts - a.ts);
+    const last = matches[0].entry;
+    const count = matches.length + 1;
+    const prevErr = last.err ?? '';
+    const ageMin = Math.max(1, Math.round((now - matches[0].ts) / 60000));
+
+    for (const tmpl of TEMPLATES) {
+      if (tmpl.match.test(prevErr)) {
+        return tmpl.hint({ count, argv: failingArgv, prev: last, ageMin });
+      }
+    }
+
+    return `${count}× the same failing shape on \`${failingArgv[0]}\` in this session (last attempt ${ageMin}m ago). Check the args — \`dotmd ${failingArgv[0]} --help\` shows what's expected.`;
+  } catch {
+    return null;
+  }
+}

package/src/hud.mjs

@@ -1,12 +1,13 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
-import { readLeases, findStaleLeases, currentSessionId } from './lease.mjs';
+import { readLeases, findStaleLeases, currentSessionId, isLeaseStale, STALE_LEASE_AGE_MS } from './lease.mjs';
 import { scrubStaleSilently } from './lease-scrub.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { asString, toRepoPath } from './util.mjs';
-import { dim } from './color.mjs';
+import { dim, yellow } from './color.mjs';
 import { buildIndex } from './index.mjs';
 import { refreshStaleSlashCommands } from './claude-commands.mjs';
+import { readJournalEntries, journalFilePath } from './journal.mjs';
 
 const MAX_PREVIEW = 5;
 
@@ -67,6 +68,121 @@ function findActionablePrompts(config) {
   return found.sort();
 }
 
+// F17b: hud reads journal. Three additive sections, gated on
+// existsSync(journalFilePath). Silent-when-clean — sections are omitted when
+// they have nothing to say. Caps keep hud single-screen even when the journal
+// is dense.
+
+const PREVIOUS_SELF_CAP = 3;
+const FLEET_CAP = 5;
+const REJECTIONS_CAP = 3;
+const FLEET_WINDOW_MS = 24 * 60 * 60 * 1000;
+const REJECTIONS_WINDOW_MS = 60 * 60 * 1000;
+
+function relTime(ts, now = Date.now()) {
+  const t = new Date(ts).getTime();
+  if (!Number.isFinite(t)) return '?';
+  const delta = Math.max(0, now - t);
+  const sec = Math.floor(delta / 1000);
+  if (sec < 60) return `${sec}s ago`;
+  const min = Math.floor(sec / 60);
+  if (min < 60) return `${min}m ago`;
+  const hr = Math.floor(min / 60);
+  if (hr < 24) return `${hr}h ago`;
+  return `${Math.floor(hr / 24)}d ago`;
+}
+
+// Coarse error-class for rejection grouping. Most dotmd die() messages follow
+// `<class>: <variable detail>` (e.g. "File not found: docs/foo.md", "Already
+// archived: docs/plans/x.md", "Too many arguments to status"). Take the chunk
+// before the first colon, cap at 6 words, normalize whitespace. Cheap;
+// good-enough until a proper taxonomy emerges from real journal data.
+function errorClass(err) {
+  if (typeof err !== 'string') return '';
+  const flat = err.replace(/\s+/g, ' ').trim();
+  if (!flat) return '';
+  const prefix = flat.split(':')[0];
+  return prefix.split(' ').slice(0, 6).join(' ');
+}
+
+export function buildJournalSections(config, now = Date.now()) {
+  const journalFile = journalFilePath(config);
+  if (!existsSync(journalFile)) return { previousSelf: [], fleet: [], recentRejections: [] };
+
+  let entries;
+  try { entries = readJournalEntries(config); }
+  catch { return { previousSelf: [], fleet: [], recentRejections: [] }; }
+  if (!entries.length) return { previousSelf: [], fleet: [], recentRejections: [] };
+
+  const sid = currentSessionId();
+  const leases = readLeases(config);
+  const leaseBySession = new Map();
+  for (const lease of Object.values(leases)) {
+    if (!lease?.session) continue;
+    if (!leaseBySession.has(lease.session)) leaseBySession.set(lease.session, []);
+    leaseBySession.get(lease.session).push(lease);
+  }
+
+  // 1. Previous self: this sid's last N entries (excluding the current
+  // invocation, which is recorded only at process exit so it isn't in the
+  // file yet). Newest-first.
+  const previousSelf = entries
+    .filter(e => e?.sid === sid)
+    .slice(-PREVIOUS_SELF_CAP)
+    .reverse()
+    .map(e => ({
+      argv: Array.isArray(e.argv) ? e.argv : [],
+      exit: e.exit ?? 0,
+      ts: e.ts,
+      ago: relTime(e.ts, now),
+    }));
+
+  // 2. Fleet: per-other-sid summary for entries in the last 24h.
+  const fleetCutoff = now - FLEET_WINDOW_MS;
+  const bySid = new Map();
+  for (const e of entries) {
+    if (!e?.sid || e.sid === sid) continue;
+    const t = new Date(e.ts).getTime();
+    if (!Number.isFinite(t) || t < fleetCutoff) continue;
+    if (!bySid.has(e.sid)) bySid.set(e.sid, { count: 0, lastTs: 0 });
+    const row = bySid.get(e.sid);
+    row.count++;
+    if (t > row.lastTs) row.lastTs = t;
+  }
+  const fleet = [...bySid.entries()].map(([otherSid, row]) => {
+    const myLeases = leaseBySession.get(otherSid) ?? [];
+    const stalest = myLeases.find(isLeaseStale);
+    return {
+      sid: otherSid,
+      cmds: row.count,
+      lastAgo: relTime(new Date(row.lastTs).toISOString(), now),
+      holding: myLeases.map(l => l.path),
+      stale: Boolean(stalest),
+    };
+  }).sort((a, b) => b.cmds - a.cmds).slice(0, FLEET_CAP);
+
+  // 3. Recent rejections: top error-class groups for exit!=0 entries in the
+  // last hour. Group key = `${cmd} :: ${errClass}`.
+  const rejCutoff = now - REJECTIONS_WINDOW_MS;
+  const groups = new Map();
+  for (const e of entries) {
+    if ((e?.exit ?? 0) === 0) continue;
+    const t = new Date(e.ts).getTime();
+    if (!Number.isFinite(t) || t < rejCutoff) continue;
+    const cmd = e.argv?.[0] ?? '(none)';
+    const cls = errorClass(e.err);
+    if (!cls) continue;
+    const key = `${cmd} :: ${cls}`;
+    if (!groups.has(key)) groups.set(key, { cmd, cls, count: 0 });
+    groups.get(key).count++;
+  }
+  const recentRejections = [...groups.values()]
+    .sort((a, b) => b.count - a.count)
+    .slice(0, REJECTIONS_CAP);
+
+  return { previousSelf, fleet, recentRejections };
+}
+
 export function buildHud(config) {
   // Drop stale lease entries (and flip their plan frontmatter back to
   // oldStatus) before reading anything. Without this, hud would surface
@@ -93,7 +209,9 @@ export function buildHud(config) {
     errors = index.errors.length;
   } catch { /* swallow — bad config shouldn't break the SessionStart hook */ }
 
-  return { owned, stale, prompts, errors };
+  const { previousSelf, fleet, recentRejections } = buildJournalSections(config);
+
+  return { owned, stale, prompts, errors, previousSelf, fleet, recentRejections };
 }
 
 export function runHud(argv, config) {
@@ -131,5 +249,34 @@ export function runHud(argv, config) {
     lines.push(dim(`↻ slash commands refreshed (v${from} → v${to}): ${names}`));
   }
 
+  // F17b: three journal-aware sections. Silent-when-clean: each block emits
+  // only when it has entries.
+  if (hud.previousSelf?.length) {
+    lines.push(dim('— previous self —'));
+    for (const e of hud.previousSelf) {
+      const cmd = (e.argv ?? []).join(' ');
+      const exitTag = e.exit === 0 ? '' : `, exit ${e.exit}`;
+      lines.push(dim(`  ${cmd} (${e.ago}${exitTag})`));
+    }
+  }
+
+  if (hud.fleet?.length) {
+    lines.push(dim('— fleet (last 24h) —'));
+    for (const f of hud.fleet) {
+      const heldTag = f.holding?.length
+        ? ` · holding ${f.holding.map(p => path.basename(p, '.md')).join(', ')}`
+        : '';
+      const staleTag = f.stale ? yellow(' [stale]') : '';
+      lines.push(dim(`  session ${f.sid} · ${f.cmds} cmds · last ${f.lastAgo}${heldTag}`) + staleTag);
+    }
+  }
+
+  if (hud.recentRejections?.length) {
+    lines.push(dim('— recent rejections (last 1h) —'));
+    for (const r of hud.recentRejections) {
+      lines.push(dim(`  ${r.count}× "${r.cls}" on \`${r.cmd}\``));
+    }
+  }
+
   process.stdout.write(lines.join('\n') + '\n');
 }