dotmd-cli 0.48.2 → 0.48.4

package/bin/dotmd.mjs

@@ -5,7 +5,7 @@ import { fileURLToPath } from 'node:url';
 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 { recordCliInvocation, recordGlobalError } from '../src/journal.mjs';
 import { findRepeatFailureHint } from '../src/hints.mjs';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -1260,7 +1260,13 @@ async function main() {
     const { scrubStaleSilently } = await import('../src/lease-scrub.mjs');
     scrubStaleSilently(config);
   }
-  const index = buildIndex(config);
+  // `dotmd check` is the one shared-buildIndex command that should auto-heal a
+  // drifted index block (frontmatter edits by direct Edit/Write, `lint --fix`,
+  // etc. leave the README out of sync; demanding the user run `dotmd index`
+  // each time was pure noise). Print/dry-run/read-only callers (`json`, `list`,
+  // `query`, `index --print`, ...) stay opt-out so they never mutate disk.
+  const AUTO_HEAL_INDEX_COMMANDS = new Set(['check']);
+  const index = buildIndex(config, { autoHealIndex: AUTO_HEAL_INDEX_COMMANDS.has(command) });
 
   // Apply --root and --type filters
   const rootFilter = rootArg;
@@ -1552,6 +1558,17 @@ function _journalExit(err) {
       version: pkg.version,
     });
   } catch { /* never break exit on journal failure */ }
+  if (err) {
+    try {
+      recordGlobalError({
+        config: _resolvedConfig,
+        startMs: _startMs,
+        args: _invocationArgs,
+        err,
+        version: pkg.version,
+      });
+    } catch { /* never break exit on error-log failure */ }
+  }
 }
 
 main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.48.2",
+  "version": "0.48.4",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",
@@ -40,6 +40,7 @@
   "scripts": {
     "test": "node --test test/*.test.mjs",
     "preversion": "npm test",
+    "version": "node bin/dotmd.mjs hud >/dev/null 2>&1; git add .claude/commands docs/docs.md 2>/dev/null; true",
     "postversion": "git push origin main --tags && gh release create v$npm_package_version --generate-notes --title v$npm_package_version && sleep 5 && gh run watch $(gh run list --workflow=publish.yml --limit 1 --json databaseId --jq '.[0].databaseId') --exit-status && sleep 10 && npm cache clean --force && npm install -g dotmd-cli@$npm_package_version"
   },
   "engines": {

package/src/claude-commands.mjs

@@ -76,6 +76,8 @@ function generatePlansCommand(config, version) {
   lines.push('- `dotmd unblocks <file>` — what depends on / is blocked by a plan');
   lines.push('- `dotmd actionable` — ready plans with next steps (what to promote)');
   lines.push('- `dotmd query --keyword <term>` — find plans by keyword');
+  lines.push('- `dotmd runlist <hub>` — show ordered children of a runlist hub (→ marks next pickup)');
+  lines.push('- `dotmd runlist next <hub>` — pick up the next non-archived child of a runlist hub');
 
   if (config.raw?.glossary) {
     lines.push('- `dotmd glossary <term>` — domain term lookup with related plans');
@@ -86,6 +88,7 @@ function generatePlansCommand(config, version) {
   lines.push('');
   lines.push('If the user asks to change a plan\'s status, use `dotmd set <status> <file>`.');
   lines.push('If the user asks to archive a plan, use `dotmd set archived <file>` (or `dotmd archive <file>`).');
+  lines.push('If the user references a runlist by name — e.g. "what\'s next on <X> runlist", "<X> runlist status", "pick up the next in <X>" — use `dotmd runlist next <X>` (or `dotmd runlist <X>` first to inspect the ordering). Do NOT fall back to `dotmd context` for runlist-scoped questions.');
   lines.push('');
   lines.push('**Saved prompts (`docs/prompts/*.md`):** if the user references a file under `docs/prompts/` — e.g. "resume via docs/prompts/foo.md", "use this prompt", "load that one" — consume it with `dotmd use <file>` (atomically prints the body and archives the prompt so it cannot be double-consumed). Do NOT `cat` it, read it with the file-reading tool, or copy its body into chat. To pick the oldest pending prompt without naming a file, run `dotmd use` with no arg.');
   lines.push('');
@@ -229,22 +232,12 @@ export function refreshStaleSlashCommands(config) {
   return results.filter(r => r.action === 'updated');
 }
 
-export function checkClaudeCommands(cwd, opts = {}) {
-  const { version = pkg.version } = opts;
-  const commandsDir = path.join(cwd, '.claude', 'commands');
-  if (!existsSync(commandsDir)) return [];
-
-  const warnings = [];
-  for (const name of ['plans.md', 'docs.md', 'baton.md']) {
-    const filePath = path.join(commandsDir, name);
-    const installedVersion = getInstalledVersion(filePath);
-    if (installedVersion && installedVersion !== version) {
-      warnings.push({
-        path: `.claude/commands/${name}`,
-        level: 'warning',
-        message: `Claude command outdated (v${installedVersion} → v${version}). Run \`dotmd doctor\` to update.`,
-      });
-    }
-  }
-  return warnings;
+// Intentionally returns []. Slash-command stamp drift is auto-healed every
+// time `dotmd hud` runs (SessionStart hook), and `dotmd doctor` regens them
+// on demand. Surfacing a warning at `dotmd check` time was pure noise — it
+// fired on every release until the next session, despite the user having no
+// action to take (the heal is automatic). Kept the function for API stability
+// in case downstream callers import it.
+export function checkClaudeCommands(_cwd, _opts = {}) {
+  return [];
 }

package/src/commands.mjs

@@ -4,7 +4,7 @@
 // templates points at a real command.
 export const KNOWN_COMMANDS = [
   'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'hud',
-  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor',
+  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'status', 'set', 'use', 'next', 'archive', 'bulk', 'bulk-tag', 'touch', 'doctor', 'runlist',
   'unblocks', 'health', 'glossary', 'modules', 'module',
   'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
   'watch', 'diff', 'new', 'init', 'completions', 'statuses', 'journal',

package/src/hud.mjs

@@ -205,7 +205,11 @@ export function buildHud(config) {
   // still run, so the error count matches `dotmd check`'s.
   let errors = 0;
   try {
-    const index = buildIndex(config, { errorsOnly: true });
+    // `autoHealIndex: true` mirrors `dotmd check` — drift from non-regen
+    // mutation paths (`lint --fix`, direct file edits, etc.) heals silently
+    // at SessionStart so the agent doesn't open every session with a
+    // spurious "Run `dotmd index`" error in the hud error count.
+    const index = buildIndex(config, { errorsOnly: true, autoHealIndex: true });
     errors = index.errors.length;
   } catch { /* swallow — bad config shouldn't break the SessionStart hook */ }
 

package/src/index-file.mjs

@@ -80,7 +80,19 @@ export function writeIndex(content, config) {
   writeFileSync(config.indexPath, content, 'utf8');
 }
 
-export function checkIndex(docs, config) {
+// `autoHeal: true` rewrites the index in place when drift is detected and
+// downgrades the result to a warning ("Auto-regenerated stale index block").
+// Drift happens when frontmatter changes (status/title/current_state/module)
+// arrive via paths that don't call `regenIndex` — direct file edits, `lint
+// --fix`, `frontmatter-fix`, `bulk-tag`, etc. The README block is fully
+// generated content; treating drift as an error forced the user to run
+// `dotmd index` themselves every session. Callers inside `buildIndex` pass
+// `autoHeal: true` because the docs there are always the canonical full set
+// (filtering happens later in the CLI dispatcher). Direct callers with a
+// filtered/synthetic docs list omit it to keep the old error semantics —
+// auto-overwriting from a partial doc list would clobber valid content.
+export function checkIndex(docs, config, opts = {}) {
+  const { autoHeal = false } = opts;
   const warnings = [];
   const errors = [];
 
@@ -98,7 +110,16 @@ export function checkIndex(docs, config) {
   const index = { docs };
   const expected = renderIndexFile(index, config);
   if (expected !== current) {
-    errors.push({ path: config.indexPath, level: 'error', message: 'Generated index block is stale. Run `dotmd index`.' });
+    if (autoHeal) {
+      try {
+        writeFileSync(config.indexPath, expected, 'utf8');
+        warnings.push({ path: config.indexPath, level: 'warning', message: 'Auto-regenerated stale index block.' });
+      } catch (err) {
+        errors.push({ path: config.indexPath, level: 'error', message: `Could not auto-regenerate stale index block: ${err.message}` });
+      }
+    } else {
+      errors.push({ path: config.indexPath, level: 'error', message: 'Generated index block is stale. Run `dotmd index`.' });
+    }
   }
 
   return { warnings, errors };

package/src/index.mjs

@@ -21,7 +21,7 @@ import { checkClaudeCommands } from './claude-commands.mjs';
 // error COUNT, so the warning-only passes are pure overhead there. Preserves
 // the invariant that hud's "✗ N validation errors" line matches `dotmd check`.
 export function buildIndex(config, opts = {}) {
-  const { fast = false, errorsOnly = false } = opts;
+  const { fast = false, errorsOnly = false, autoHealIndex = false } = opts;
   const skipWarningOnlyChecks = fast || errorsOnly;
   const docs = collectDocFiles(config).map(f => parseDocFile(f, config, { fast }));
   if (!fast) {
@@ -95,7 +95,15 @@ export function buildIndex(config, opts = {}) {
   }
 
   if (!fast && config.indexPath) {
-    const indexCheck = checkIndex(transformedDocs, config);
+    // `autoHealIndex` is opt-in from the caller (currently `dotmd check` and
+    // `dotmd hud`). When true, drift triggers an in-place rewrite and a
+    // warning instead of the old "Run `dotmd index`" error — closing the
+    // class of nags produced by mutation paths that skip `regenIndex`
+    // (`lint --fix`, direct file edits, etc). `transformedDocs` here is
+    // always the canonical full set; CLI-level `--root`/`--type` filtering
+    // runs after `buildIndex` returns, so a rewrite is safe. Off by default
+    // so dry-run / print modes never mutate disk as a side effect.
+    const indexCheck = checkIndex(transformedDocs, config, { autoHeal: autoHealIndex });
     warnings.push(...indexCheck.warnings);
     errors.push(...indexCheck.errors);
   }

package/src/journal.mjs

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, appendFileSync, statSync, renameSync, readFileSync } from 'node:fs';
 import path from 'node:path';
+import os from 'node:os';
 import { currentSessionId } from './lease.mjs';
 
 const JOURNAL_DIR = '.dotmd';
@@ -8,6 +9,9 @@ const JOURNAL_BACKUP = 'journal.jsonl.1';
 const ROTATE_SIZE_BYTES = 5 * 1024 * 1024;
 const ROTATE_AGE_MS = 30 * 24 * 60 * 60 * 1000;
 
+const ERROR_LOG_FILE = 'dotmd-errors.log';
+const ERROR_LOG_BACKUP = 'dotmd-errors.log.1';
+
 export function isJournalEnabled(config) {
   if (process.env.DOTMD_JOURNAL === '1') return true;
   if (process.env.DOTMD_JOURNAL === '0') return false;
@@ -22,12 +26,12 @@ export function journalBackupPath(config) {
   return path.join(config.repoRoot, JOURNAL_DIR, JOURNAL_BACKUP);
 }
 
-function maybeRotate(file, config) {
+function maybeRotate(file, backup) {
   if (!existsSync(file)) return;
   let st;
   try { st = statSync(file); } catch { return; }
   if (st.size > ROTATE_SIZE_BYTES) {
-    try { renameSync(file, journalBackupPath(config)); } catch {}
+    try { renameSync(file, backup); } catch {}
     return;
   }
   if (st.size === 0) return;
@@ -41,7 +45,7 @@ function maybeRotate(file, config) {
     const obj = JSON.parse(first);
     const t = new Date(obj.ts).getTime();
     if (!Number.isNaN(t) && (Date.now() - t) > ROTATE_AGE_MS) {
-      try { renameSync(file, journalBackupPath(config)); } catch {}
+      try { renameSync(file, backup); } catch {}
     }
   } catch {}
 }
@@ -53,7 +57,7 @@ export function appendJournalEntry(config, entry) {
     const dir = path.join(config.repoRoot, JOURNAL_DIR);
     if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
     const file = journalFilePath(config);
-    maybeRotate(file, config);
+    maybeRotate(file, journalBackupPath(config));
     // O_APPEND is atomic for writes under PIPE_BUF (4KB on Linux, 512B on
     // macOS). Entries are well under either threshold, so concurrent CLI
     // invocations interleave cleanly without locking.
@@ -96,3 +100,52 @@ export function recordCliInvocation({ config, startMs, args, err, version }) {
   }
   appendJournalEntry(config, entry);
 }
+
+// Global error log: always-on, cross-repo, captured per failed invocation.
+// Independent of `isJournalEnabled` so silent failures stop disappearing.
+// DOTMD_ERROR_LOG_DIR overrides the default location (for tests, or for
+// users who want the log somewhere other than ~/.claude/logs).
+
+export function globalErrorLogDir() {
+  return process.env.DOTMD_ERROR_LOG_DIR || path.join(os.homedir(), '.claude', 'logs');
+}
+
+export function globalErrorLogPath() {
+  return path.join(globalErrorLogDir(), ERROR_LOG_FILE);
+}
+
+export function globalErrorLogBackupPath() {
+  return path.join(globalErrorLogDir(), ERROR_LOG_BACKUP);
+}
+
+export function recordGlobalError({ config, startMs, args, err, version }) {
+  if (!err) return;
+  const flatMsg = String(err.message ?? err).replace(/\s+/g, ' ').trim();
+  const entry = {
+    ts: new Date().toISOString(),
+    repo: config?.repoRoot || process.cwd(),
+    sid: currentSessionId(),
+    pid: process.pid,
+    argv: args,
+    exit: process.exitCode ?? 1,
+    ms: typeof startMs === 'number' ? Date.now() - startMs : null,
+    v: version,
+    err: flatMsg.length > 500 ? flatMsg.slice(0, 497) + '...' : flatMsg,
+  };
+  if (err && err.name) entry.errName = err.name;
+  if (err && err.stack) {
+    // Keep the first few frames; stacks for DotmdError are short anyway and
+    // for unexpected exceptions five frames is usually enough to localize.
+    const stack = String(err.stack).split('\n').slice(0, 6).join('\n');
+    entry.stack = stack.length > 1000 ? stack.slice(0, 997) + '...' : stack;
+  }
+  try {
+    const dir = globalErrorLogDir();
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    const file = globalErrorLogPath();
+    maybeRotate(file, globalErrorLogBackupPath());
+    appendFileSync(file, JSON.stringify(entry) + '\n', { flag: 'a' });
+  } catch {
+    // Logging must never break exit.
+  }
+}

package/src/prompts.mjs

@@ -226,10 +226,17 @@ export function consumePrompt(filePath, config, opts) {
     return;
   }
 
+  // Archive BEFORE emitting the body. If runArchive throws (git mv failure,
+  // hook crash, anything), the body must not have already gone to stdout —
+  // otherwise `claude "$(dotmd prompts next)"` consumes the prompt without it
+  // ever being archived, and the next session sees the same prompt as pending.
+  // Body is already in memory from extractFrontmatter, so the source file
+  // can move out from under us safely.
+  runArchive([filePath], config, { noIndex, showFiles, out: process.stderr });
+
   process.stdout.write(body);
   if (!body.endsWith('\n')) process.stdout.write('\n');
 
-  runArchive([filePath], config, { noIndex, showFiles, out: process.stderr });
   process.stderr.write(`${green('✓ Consumed')}: ${repoPath}\n`);
 }