dotmd-cli 0.1.0

package/src/lifecycle.mjs

@@ -0,0 +1,224 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, die } from './util.mjs';
+import { gitMv } from './git.mjs';
+import { buildIndex, collectDocFiles } from './index.mjs';
+import { renderIndexFile, writeIndex } from './index-file.mjs';
+import { green, dim } from './color.mjs';
+
+export function runStatus(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const input = argv[0];
+  const newStatus = argv[1];
+
+  if (!input || !newStatus) { die('Usage: dotmd status <file> <new-status>'); return; }
+  if (!config.validStatuses.has(newStatus)) { die(`Invalid status: ${newStatus}\nValid: ${[...config.validStatuses].join(', ')}`); return; }
+
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) { die(`File not found: ${input}`); return; }
+
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter } = extractFrontmatter(raw);
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  const oldStatus = asString(parsed.status);
+
+  if (oldStatus === newStatus) {
+    process.stdout.write(`${toRepoPath(filePath, config.repoRoot)}: already ${newStatus}, no changes made.\n`);
+    return;
+  }
+
+  const today = new Date().toISOString().slice(0, 10);
+  const archiveDir = path.join(config.docsRoot, config.archiveDir);
+  const isArchiving = config.lifecycle.archiveStatuses.has(newStatus) && !filePath.includes(`/${config.archiveDir}/`);
+  const isUnarchiving = !config.lifecycle.archiveStatuses.has(newStatus) && filePath.includes(`/${config.archiveDir}/`);
+  let finalPath = filePath;
+
+  if (dryRun) {
+    const prefix = dim('[dry-run]');
+    process.stdout.write(`${prefix} Would update frontmatter: status: ${oldStatus ?? 'unknown'} → ${newStatus}, updated: ${today}\n`);
+    if (isArchiving) {
+      const targetPath = path.join(archiveDir, path.basename(filePath));
+      process.stdout.write(`${prefix} Would move: ${toRepoPath(filePath, config.repoRoot)} → ${toRepoPath(targetPath, config.repoRoot)}\n`);
+      finalPath = targetPath;
+    }
+    if (isUnarchiving) {
+      const targetPath = path.join(config.docsRoot, path.basename(filePath));
+      process.stdout.write(`${prefix} Would move: ${toRepoPath(filePath, config.repoRoot)} → ${toRepoPath(targetPath, config.repoRoot)}\n`);
+      finalPath = targetPath;
+    }
+    if ((isArchiving || isUnarchiving) && config.indexPath) {
+      process.stdout.write(`${prefix} Would regenerate index\n`);
+    }
+    process.stdout.write(`${prefix} ${toRepoPath(finalPath, config.repoRoot)}: ${oldStatus ?? 'unknown'} → ${newStatus}\n`);
+    return;
+  }
+
+  updateFrontmatter(filePath, { status: newStatus, updated: today });
+
+  if (isArchiving) {
+    const targetPath = path.join(archiveDir, path.basename(filePath));
+    if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); return; }
+    const result = gitMv(filePath, targetPath, config.repoRoot);
+    if (result.status !== 0) { die(result.stderr || 'git mv failed.'); return; }
+    finalPath = targetPath;
+  }
+
+  if (isUnarchiving) {
+    const targetPath = path.join(config.docsRoot, path.basename(filePath));
+    if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); return; }
+    const result = gitMv(filePath, targetPath, config.repoRoot);
+    if (result.status !== 0) { die(result.stderr || 'git mv failed.'); return; }
+    finalPath = targetPath;
+  }
+
+  if ((isArchiving || isUnarchiving) && config.indexPath) {
+    const index = buildIndex(config);
+    writeIndex(renderIndexFile(index, config), config);
+  }
+
+  process.stdout.write(`${green(toRepoPath(finalPath, config.repoRoot))}: ${oldStatus ?? 'unknown'} → ${newStatus}\n`);
+
+  config.hooks.onStatusChange?.({ path: toRepoPath(finalPath, config.repoRoot), oldStatus, newStatus }, {
+    oldPath: toRepoPath(filePath, config.repoRoot),
+    newPath: toRepoPath(finalPath, config.repoRoot),
+  });
+}
+
+export function runArchive(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const input = argv[0];
+
+  if (!input) { die('Usage: dotmd archive <file>'); return; }
+
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) { die(`File not found: ${input}`); return; }
+  if (filePath.includes(`/${config.archiveDir}/`)) { die(`Already archived: ${toRepoPath(filePath, config.repoRoot)}`); return; }
+
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter } = extractFrontmatter(raw);
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  const oldStatus = asString(parsed.status) ?? 'unknown';
+
+  const today = new Date().toISOString().slice(0, 10);
+  const targetDir = path.join(config.docsRoot, config.archiveDir);
+  const targetPath = path.join(targetDir, path.basename(filePath));
+  const oldRepoPath = toRepoPath(filePath, config.repoRoot);
+  const newRepoPath = toRepoPath(targetPath, config.repoRoot);
+
+  if (dryRun) {
+    const prefix = dim('[dry-run]');
+    process.stdout.write(`${prefix} Would update frontmatter: status: ${oldStatus} → archived, updated: ${today}\n`);
+    if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); return; }
+    process.stdout.write(`${prefix} Would move: ${oldRepoPath} → ${newRepoPath}\n`);
+    if (config.indexPath) process.stdout.write(`${prefix} Would regenerate index\n`);
+
+    // Reference scan is read-only, still useful in dry-run
+    const basename = path.basename(filePath);
+    const references = [];
+    for (const docFile of collectDocFiles(config)) {
+      if (docFile === targetPath) continue;
+      const docRaw = readFileSync(docFile, 'utf8');
+      const { frontmatter: docFm } = extractFrontmatter(docRaw);
+      if (docFm.includes(basename)) {
+        references.push(toRepoPath(docFile, config.repoRoot));
+      }
+    }
+    if (references.length > 0) {
+      process.stdout.write('\nThese docs reference the old path — would need updating:\n');
+      for (const ref of references) process.stdout.write(`- ${ref}\n`);
+    }
+    return;
+  }
+
+  updateFrontmatter(filePath, { status: 'archived', updated: today });
+
+  if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); return; }
+
+  const result = gitMv(filePath, targetPath, config.repoRoot);
+  if (result.status !== 0) { die(result.stderr || 'git mv failed.'); return; }
+
+  if (config.indexPath) {
+    const index = buildIndex(config);
+    writeIndex(renderIndexFile(index, config), config);
+  }
+
+  process.stdout.write(`${green('Archived')}: ${oldRepoPath} → ${newRepoPath}\n`);
+  if (config.indexPath) process.stdout.write('Index regenerated.\n');
+
+  const basename = path.basename(filePath);
+  const references = [];
+  for (const docFile of collectDocFiles(config)) {
+    if (docFile === targetPath) continue;
+    const docRaw = readFileSync(docFile, 'utf8');
+    const { frontmatter: docFm } = extractFrontmatter(docRaw);
+    if (docFm.includes(basename)) {
+      references.push(toRepoPath(docFile, config.repoRoot));
+    }
+  }
+
+  if (references.length > 0) {
+    process.stdout.write('\nThese docs reference the old path — update reference entries:\n');
+    for (const ref of references) process.stdout.write(`- ${ref}\n`);
+  }
+
+  process.stdout.write('\nNext: commit, then update references if needed.\n');
+  config.hooks.onArchive?.({ path: newRepoPath, oldStatus }, { oldPath: oldRepoPath, newPath: newRepoPath });
+}
+
+export function runTouch(argv, config, opts = {}) {
+  const { dryRun } = opts;
+  const input = argv[0];
+
+  if (!input) { die('Usage: dotmd touch <file>'); return; }
+
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) { die(`File not found: ${input}`); return; }
+
+  const today = new Date().toISOString().slice(0, 10);
+
+  if (dryRun) {
+    process.stdout.write(`${dim('[dry-run]')} Would touch: ${toRepoPath(filePath, config.repoRoot)} (updated → ${today})\n`);
+    return;
+  }
+
+  updateFrontmatter(filePath, { updated: today });
+  process.stdout.write(`${green('Touched')}: ${toRepoPath(filePath, config.repoRoot)} (updated → ${today})\n`);
+
+  config.hooks.onTouch?.({ path: toRepoPath(filePath, config.repoRoot) }, { path: toRepoPath(filePath, config.repoRoot), date: today });
+}
+
+function resolveDocPath(input, config) {
+  if (!input) return null;
+  if (path.isAbsolute(input)) return existsSync(input) ? input : null;
+
+  let candidate = path.resolve(config.repoRoot, input);
+  if (existsSync(candidate)) return candidate;
+
+  candidate = path.resolve(config.docsRoot, input);
+  if (existsSync(candidate)) return candidate;
+
+  return null;
+}
+
+export function updateFrontmatter(filePath, updates) {
+  const raw = readFileSync(filePath, 'utf8');
+  if (!raw.startsWith('---\n')) throw new Error(`${filePath} has no frontmatter block.`);
+
+  const endMarker = raw.indexOf('\n---\n', 4);
+  if (endMarker === -1) throw new Error(`${filePath} has unclosed frontmatter block.`);
+
+  let frontmatter = raw.slice(4, endMarker);
+  const body = raw.slice(endMarker + 5);
+
+  for (const [key, value] of Object.entries(updates)) {
+    const regex = new RegExp(`^${key}:.*$`, 'm');
+    if (regex.test(frontmatter)) {
+      frontmatter = frontmatter.replace(regex, `${key}: ${value}`);
+    } else {
+      frontmatter += `\n${key}: ${value}`;
+    }
+  }
+
+  writeFileSync(filePath, `---\n${frontmatter}\n---\n${body}`, 'utf8');
+}

package/src/query.mjs

@@ -0,0 +1,178 @@
+import { capitalize, toSlug } from './util.mjs';
+import { renderProgressBar } from './render.mjs';
+import { computeDaysSinceUpdate, computeIsStale } from './validate.mjs';
+import { getGitLastModified } from './git.mjs';
+
+export function runFocus(index, argv, config) {
+  const statusFilter = argv[0] ?? 'active';
+  const docs = index.docs.filter(doc => doc.status === statusFilter);
+
+  if (docs.length === 0) {
+    process.stdout.write(`No docs found for status: ${statusFilter}\n`);
+    return;
+  }
+
+  process.stdout.write(`${statusFilter.toUpperCase()} Focus\n\n`);
+
+  for (const doc of docs) {
+    process.stdout.write(`- ${doc.title}\n`);
+    process.stdout.write(`  path: ${doc.path}\n`);
+    process.stdout.write(`  state: ${doc.currentState}\n`);
+    if (doc.nextStep) {
+      process.stdout.write(`  next: ${doc.nextStep}\n`);
+    }
+    if (doc.blockers?.length) {
+      process.stdout.write(`  blockers: ${doc.blockers.join('; ')}\n`);
+    }
+    if (doc.checklist?.total) {
+      process.stdout.write(`  checklist: ${doc.checklist.completed}/${doc.checklist.total} complete\n`);
+    }
+    process.stdout.write('\n');
+  }
+}
+
+export function runQuery(index, argv, config) {
+  const filters = parseQueryArgs(argv);
+  const docs = filterDocs(index.docs, filters, config);
+
+  if (filters.json) {
+    process.stdout.write(`${JSON.stringify({ filters, count: docs.length, docs }, null, 2)}\n`);
+    return;
+  }
+
+  renderQueryResults(docs, filters);
+}
+
+export function parseQueryArgs(argv) {
+  const filters = {
+    statuses: null, keyword: null, owner: null, surface: null,
+    module: null, domain: null, audience: null, executionMode: null,
+    updatedSince: null, limit: 20, all: false, sort: 'updated',
+    stale: false, hasNextStep: false, hasBlockers: false,
+    checklistOpen: false, json: false, git: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    const next = argv[i + 1];
+
+    if (arg === '--status' && next) { filters.statuses = next.split(',').map(v => v.trim()).filter(Boolean); i += 1; continue; }
+    if (arg === '--keyword' && next) { filters.keyword = next; i += 1; continue; }
+    if (arg === '--owner' && next) { filters.owner = next; i += 1; continue; }
+    if (arg === '--surface' && next) { filters.surface = next; i += 1; continue; }
+    if (arg === '--module' && next) { filters.module = next; i += 1; continue; }
+    if (arg === '--domain' && next) { filters.domain = next; i += 1; continue; }
+    if (arg === '--audience' && next) { filters.audience = next; i += 1; continue; }
+    if (arg === '--execution-mode' && next) { filters.executionMode = next; i += 1; continue; }
+    if (arg === '--updated-since' && next) { filters.updatedSince = next; i += 1; continue; }
+    if (arg === '--limit' && next) { filters.limit = Number.parseInt(next, 10) || 20; i += 1; continue; }
+    if (arg === '--sort' && next) { filters.sort = next; i += 1; continue; }
+    if (arg === '--all') { filters.all = true; continue; }
+    if (arg === '--stale') { filters.stale = true; continue; }
+    if (arg === '--has-next-step') { filters.hasNextStep = true; continue; }
+    if (arg === '--has-blockers') { filters.hasBlockers = true; continue; }
+    if (arg === '--checklist-open') { filters.checklistOpen = true; continue; }
+    if (arg === '--json') { filters.json = true; continue; }
+    if (arg === '--git') { filters.git = true; continue; }
+  }
+
+  return filters;
+}
+
+export function filterDocs(docs, filters, config) {
+  let result = [...docs];
+
+  if (filters.statuses?.length) result = result.filter(d => filters.statuses.includes(d.status));
+
+  if (filters.keyword) {
+    const needle = filters.keyword.toLowerCase();
+    result = result.filter(d => [d.title, d.summary, d.currentState, d.nextStep, d.path, ...(d.blockers ?? [])].filter(Boolean).join(' ').toLowerCase().includes(needle));
+  }
+
+  if (filters.owner) { const n = filters.owner.toLowerCase(); result = result.filter(d => (d.owner ?? '').toLowerCase().includes(n)); }
+  if (filters.surface) { const n = filters.surface.toLowerCase(); result = result.filter(d => (d.surfaces ?? []).some(s => s.toLowerCase() === n)); }
+  if (filters.module) { const n = filters.module.toLowerCase(); result = result.filter(d => (d.modules ?? []).some(m => m.toLowerCase() === n)); }
+  if (filters.domain) { const n = filters.domain.toLowerCase(); result = result.filter(d => (d.domain ?? '').toLowerCase() === n); }
+  if (filters.audience) { const n = filters.audience.toLowerCase(); result = result.filter(d => (d.audience ?? '').toLowerCase() === n); }
+  if (filters.executionMode) { const n = filters.executionMode.toLowerCase(); result = result.filter(d => (d.executionMode ?? '').toLowerCase() === n); }
+  if (filters.updatedSince) result = result.filter(d => d.updated && d.updated >= filters.updatedSince);
+
+  if (filters.git) {
+    for (const doc of result) {
+      const gitDate = getGitLastModified(doc.path, config.repoRoot);
+      if (gitDate) {
+        doc.daysSinceUpdate = computeDaysSinceUpdate(gitDate);
+        doc.isStale = computeIsStale(doc.status, gitDate, config);
+      }
+    }
+  }
+
+  if (filters.stale) result = result.filter(d => d.isStale);
+  if (filters.hasNextStep) result = result.filter(d => d.hasNextStep);
+  if (filters.hasBlockers) result = result.filter(d => d.hasBlockers);
+  if (filters.checklistOpen) result = result.filter(d => (d.checklist?.open ?? 0) > 0);
+
+  result.sort(buildSorter(filters.sort, config));
+  return filters.all ? result : result.slice(0, filters.limit);
+}
+
+function renderQueryResults(docs, filters) {
+  process.stdout.write('Query\n\n');
+  process.stdout.write(`- results: ${docs.length}\n`);
+  if (filters.statuses?.length) process.stdout.write(`- status: ${filters.statuses.join(', ')}\n`);
+  if (filters.keyword) process.stdout.write(`- keyword: ${filters.keyword}\n`);
+  if (filters.owner) process.stdout.write(`- owner: ${filters.owner}\n`);
+  if (filters.surface) process.stdout.write(`- surface: ${filters.surface}\n`);
+  if (filters.module) process.stdout.write(`- module: ${filters.module}\n`);
+  if (filters.domain) process.stdout.write(`- domain: ${filters.domain}\n`);
+  if (filters.audience) process.stdout.write(`- audience: ${filters.audience}\n`);
+  if (filters.executionMode) process.stdout.write(`- execution-mode: ${filters.executionMode}\n`);
+  if (filters.updatedSince) process.stdout.write(`- updated-since: ${filters.updatedSince}\n`);
+  process.stdout.write(`- sort: ${filters.sort}\n`);
+  if (filters.stale) process.stdout.write('- stale-only: true\n');
+  if (filters.git) process.stdout.write('- using: git dates\n');
+  if (filters.hasNextStep) process.stdout.write('- has-next-step: true\n');
+  if (filters.hasBlockers) process.stdout.write('- has-blockers: true\n');
+  if (filters.checklistOpen) process.stdout.write('- checklist-open: true\n');
+  process.stdout.write('\n');
+
+  if (docs.length === 0) { process.stdout.write('No matching docs.\n'); return; }
+
+  for (const doc of docs) {
+    process.stdout.write(`- ${doc.title}\n`);
+    process.stdout.write(`  status: ${doc.status}\n`);
+    process.stdout.write(`  updated: ${doc.updated ?? 'n/a'}\n`);
+    if (doc.daysSinceUpdate != null) process.stdout.write(`  days-since-update: ${doc.daysSinceUpdate}\n`);
+    process.stdout.write(`  stale: ${doc.isStale ? 'yes' : 'no'}\n`);
+    process.stdout.write(`  path: ${doc.path}\n`);
+    process.stdout.write(`  state: ${doc.currentState}\n`);
+    if (doc.nextStep) process.stdout.write(`  next: ${doc.nextStep}\n`);
+    if (doc.owner) process.stdout.write(`  owner: ${doc.owner}\n`);
+    if (doc.surfaces?.length) process.stdout.write(`  surfaces: ${doc.surfaces.join(', ')}\n`);
+    if (doc.modules?.length) process.stdout.write(`  modules: ${doc.modules.join(', ')}\n`);
+    if (doc.domain) process.stdout.write(`  domain: ${doc.domain}\n`);
+    if (doc.audience) process.stdout.write(`  audience: ${doc.audience}\n`);
+    if (doc.executionMode) process.stdout.write(`  execution-mode: ${doc.executionMode}\n`);
+    if (doc.blockers?.length) process.stdout.write(`  blockers: ${doc.blockers.join('; ')}\n`);
+    if (doc.checklist?.total) process.stdout.write(`  checklist: ${doc.checklist.completed}/${doc.checklist.total} complete\n`);
+    process.stdout.write('\n');
+  }
+}
+
+function buildSorter(sort, config) {
+  if (sort === 'title') return (a, b) => a.title.localeCompare(b.title);
+  if (sort === 'status') {
+    return (a, b) => {
+      const ai = config.statusOrder.indexOf(a.status); const bi = config.statusOrder.indexOf(b.status);
+      const aIdx = ai === -1 ? Number.MAX_SAFE_INTEGER : ai; const bIdx = bi === -1 ? Number.MAX_SAFE_INTEGER : bi;
+      if (aIdx !== bIdx) return aIdx - bIdx;
+      return compareUpdatedDesc(a, b) || a.title.localeCompare(b.title);
+    };
+  }
+  return (a, b) => compareUpdatedDesc(a, b) || a.title.localeCompare(b.title);
+}
+
+function compareUpdatedDesc(a, b) {
+  const au = a.updated ?? ''; const bu = b.updated ?? '';
+  return au !== bu ? bu.localeCompare(au) : 0;
+}

package/src/render.mjs

@@ -0,0 +1,248 @@
+import { capitalize, toSlug, truncate } from './util.mjs';
+import { bold, red, yellow, green } from './color.mjs';
+
+export function renderCompactList(index, config) {
+  const defaultRenderer = (idx) => _renderCompactList(idx, config);
+  if (config.hooks.renderCompactList) {
+    return config.hooks.renderCompactList(index, defaultRenderer);
+  }
+  return defaultRenderer(index);
+}
+
+function _renderCompactList(index, config) {
+  const lines = ['Index', ''];
+  const maxWidth = config.display.lineWidth || process.stdout.columns || 120;
+
+  for (const status of config.statusOrder) {
+    const docs = index.docs.filter(d => d.status === status);
+    if (!docs.length) continue;
+
+    lines.push(bold(`${capitalize(status)} (${docs.length})`));
+    const maxTitle = Math.min(config.display.truncateTitle || 30, Math.max(...docs.map(d => d.title.length)));
+
+    for (const doc of docs) {
+      const title = doc.title.length > maxTitle
+        ? doc.title.slice(0, maxTitle - 3) + '...'
+        : doc.title.padEnd(maxTitle);
+      const days = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : '';
+      const progress = renderProgressBar(doc.checklist);
+      const next = doc.nextStep ? `next: ${doc.nextStep}` : '';
+      const parts = [`  ${title}  ${days.padStart(4)}`];
+      if (progress) parts.push(progress);
+      if (next) parts.push(next);
+      const line = parts.join('  ');
+      lines.push(line.length > maxWidth ? line.slice(0, maxWidth - 3) + '...' : line);
+    }
+    lines.push('');
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+export function renderVerboseList(index, config) {
+  const lines = ['Index', ''];
+
+  for (const status of config.statusOrder) {
+    const docs = index.docs.filter(doc => doc.status === status);
+    if (docs.length === 0) continue;
+
+    lines.push(`${capitalize(status)} (${docs.length})`);
+    for (const doc of docs) {
+      const parts = [`- ${doc.title}`, `${capitalize(status)}: ${doc.currentState}`, `(${doc.path})`];
+      if (doc.nextStep) {
+        parts.push(`next: ${doc.nextStep}`);
+      }
+      lines.push(parts.join(' — '));
+    }
+    lines.push('');
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+export function renderContext(index, config) {
+  const defaultRenderer = (idx) => _renderContext(idx, config);
+  if (config.hooks.renderContext) {
+    return config.hooks.renderContext(index, defaultRenderer);
+  }
+  return defaultRenderer(index);
+}
+
+function _renderContext(index, config) {
+  const today = new Date().toISOString().slice(0, 10);
+  const lines = [`BRIEFING (${today})`, ''];
+  const ctx = config.context;
+
+  const byStatus = {};
+  for (const status of config.statusOrder) {
+    byStatus[status] = index.docs.filter(d => d.status === status);
+  }
+
+  for (const status of (ctx.expanded || [])) {
+    const docs = byStatus[status];
+    if (!docs?.length) continue;
+    lines.push(bold(`${capitalize(status)} (${docs.length}):`));
+    const maxSlug = Math.min(24, Math.max(...docs.map(d => toSlug(d).length)));
+    for (const doc of docs) {
+      const slug = toSlug(doc).padEnd(maxSlug);
+      const next = doc.nextStep
+        ? truncate(doc.nextStep, ctx.truncateNextStep || 80)
+        : '(no next step)';
+      lines.push(`  ${slug}  next: ${next}`);
+    }
+    lines.push('');
+  }
+
+  for (const status of (ctx.listed || [])) {
+    const docs = byStatus[status];
+    if (!docs?.length) continue;
+    lines.push(`${capitalize(status)} (${docs.length}): ${docs.map(toSlug).join(', ')}`);
+  }
+
+  const counts = (ctx.counted || [])
+    .filter(s => byStatus[s]?.length)
+    .map(s => `${capitalize(s)} (${byStatus[s].length})`);
+  if (counts.length) {
+    lines.push(counts.join('  |  '));
+  }
+  lines.push('');
+
+  const stale = index.docs.filter(d => d.isStale && !config.lifecycle.skipStaleFor.has(d.status));
+  if (stale.length) {
+    lines.push(`Stale: ${stale.map(d => `${toSlug(d)} (${d.daysSinceUpdate}d)`).join(', ')}`);
+  } else {
+    lines.push('Stale: none');
+  }
+
+  const withErrors = index.docs.filter(d => d.errors.length > 0 && !config.lifecycle.skipWarningsFor.has(d.status));
+  const withWarnings = index.docs.filter(d => d.warnings.length > 0 && !config.lifecycle.skipWarningsFor.has(d.status));
+  if (withErrors.length || withWarnings.length) {
+    const parts = [];
+    if (withErrors.length) parts.push(`${withErrors.length} with errors`);
+    if (withWarnings.length) parts.push(`${withWarnings.length} with warnings`);
+    lines.push(`Non-compliant: ${parts.join(', ')} (run \`dotmd check\` for details)`);
+  }
+
+  const recentStatuses = new Set(ctx.recentStatuses || ['active', 'ready', 'planned']);
+  const recentDays = ctx.recentDays ?? 3;
+  const recentLimit = ctx.recentLimit ?? 10;
+  const recent = index.docs
+    .filter(d => d.daysSinceUpdate != null && d.daysSinceUpdate <= recentDays && recentStatuses.has(d.status))
+    .sort((a, b) => (a.daysSinceUpdate ?? 99) - (b.daysSinceUpdate ?? 99))
+    .slice(0, recentLimit);
+  if (recent.length) {
+    const items = recent.map(d => {
+      const label = d.daysSinceUpdate === 0 ? 'today' : `${d.daysSinceUpdate}d ago`;
+      return `${toSlug(d)} (${label})`;
+    });
+    lines.push(`Recently updated: ${items.join(', ')}`);
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+export function renderCheck(index, config) {
+  const defaultRenderer = (idx) => _renderCheck(idx);
+  if (config.hooks.renderCheck) {
+    return config.hooks.renderCheck(index, defaultRenderer);
+  }
+  return defaultRenderer(index);
+}
+
+function _renderCheck(index) {
+  const lines = ['Check', ''];
+  lines.push(`- docs scanned: ${index.docs.length}`);
+  lines.push(`- errors: ${index.errors.length}`);
+  lines.push(`- warnings: ${index.warnings.length}`);
+  lines.push('');
+
+  if (index.errors.length > 0) {
+    lines.push(red('Errors'));
+    for (const issue of index.errors) {
+      lines.push(`- ${issue.path}: ${issue.message}`);
+    }
+    lines.push('');
+  }
+
+  if (index.warnings.length > 0) {
+    lines.push(yellow('Warnings'));
+    for (const issue of index.warnings) {
+      lines.push(`- ${issue.path}: ${issue.message}`);
+    }
+    lines.push('');
+  }
+
+  if (index.errors.length === 0 && index.warnings.length === 0) {
+    lines.push(green('No issues found.'));
+  } else if (index.errors.length === 0) {
+    lines.push(green('Check passed with warnings.'));
+  } else {
+    lines.push(red('Check failed.'));
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+export function renderCoverage(index, config) {
+  const coverage = buildCoverage(index, config);
+  const lines = ['Coverage', ''];
+  lines.push(`- scoped docs: ${coverage.totals.scopedDocs}`);
+  lines.push(`- missing surface: ${coverage.totals.missingSurface}`);
+  lines.push(`- missing module: ${coverage.totals.missingModule}`);
+  lines.push(`- module:platform: ${coverage.totals.modulePlatform}`);
+  lines.push(`- module:none: ${coverage.totals.moduleNone}`);
+  lines.push(`- audit_level:none: ${coverage.totals.auditLevelNone}`);
+  lines.push(`- audited (pass1/pass2/deep): ${coverage.totals.audited}`);
+  lines.push('');
+
+  for (const [label, list] of [['Missing surface', coverage.missingSurface], ['Missing module', coverage.missingModule], ['module:platform', coverage.modulePlatform], ['module:none', coverage.moduleNone], ['audit_level:none', coverage.auditLevelNone]]) {
+    if (list.length) {
+      lines.push(label);
+      for (const doc of list) lines.push(`- ${doc.path}`);
+      lines.push('');
+    }
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+export function buildCoverage(index, config) {
+  const scope = ['active', 'ready', 'planned', 'blocked'];
+  const scoped = index.docs.filter(doc => scope.includes(doc.status));
+  const missingSurface = scoped.filter(doc => !doc.surface);
+  const missingModule = scoped.filter(doc => !doc.module);
+  const modulePlatform = scoped.filter(doc => doc.module === 'platform');
+  const moduleNone = scoped.filter(doc => doc.module === 'none');
+  const auditLevelNone = scoped.filter(doc => doc.auditLevel === 'none');
+  const audited = scoped.filter(doc => ['pass1', 'pass2', 'deep'].includes(doc.auditLevel));
+
+  return {
+    generatedAt: index.generatedAt, scope,
+    totals: { scopedDocs: scoped.length, missingSurface: missingSurface.length, missingModule: missingModule.length, modulePlatform: modulePlatform.length, moduleNone: moduleNone.length, auditLevelNone: auditLevelNone.length, audited: audited.length },
+    missingSurface, missingModule, modulePlatform, moduleNone, auditLevelNone, audited,
+  };
+}
+
+export function renderProgressBar(checklist) {
+  if (!checklist?.total) return '';
+  const ratio = checklist.completed / checklist.total;
+  const filled = Math.round(ratio * 10);
+  const bar = '█'.repeat(filled) + '░'.repeat(10 - filled);
+  return `${bar} ${checklist.completed}/${checklist.total}`;
+}
+
+export function formatSnapshot(doc, config) {
+  const defaultFormatter = (d) => _formatSnapshot(d);
+  if (config.hooks.formatSnapshot) {
+    return config.hooks.formatSnapshot(doc, defaultFormatter);
+  }
+  return defaultFormatter(doc);
+}
+
+function _formatSnapshot(doc) {
+  const state = doc.currentState ?? 'No current_state set';
+  if (/^active:|^ready:|^planned:|^research:|^blocked:|^archived:/i.test(state)) {
+    return state;
+  }
+  return `${capitalize(doc.status ?? 'unknown')}: ${state}`;
+}