dotmd-cli 0.19.0 → 0.21.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.19.0",
+  "version": "0.21.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/index.mjs

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
 import { extractFirstHeading, extractSummary, extractStatusSnapshot, extractNextStep, extractChecklistCounts, extractBodyLinks } from './extractors.mjs';
 import { asString, normalizeStringList, normalizeBlockers, mergeUniqueStrings, toRepoPath, warn } from './util.mjs';
-import { validateDoc, checkBidirectionalReferences, checkGitStaleness, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate } from './validate.mjs';
+import { validateDoc, validatePlanShape, checkBidirectionalReferences, checkGitStaleness, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
 
@@ -193,5 +193,6 @@ export function parseDocFile(filePath, config) {
   }
 
   validateDoc(doc, parsedFrontmatter, headingTitle, config);
+  validatePlanShape(doc, body, parsedFrontmatter, config);
   return doc;
 }

package/src/lifecycle.mjs

@@ -17,6 +17,7 @@ import {
   migrateLease,
 } from './lease.mjs';
 import { hasHandoff, consumeHandoff, appendHandoff, handoffPath, listQueuedHandoffs } from './handoff.mjs';
+import { buildCard, renderCard } from './pickup-card.mjs';
 
 function findFileRoot(filePath, config) {
   const roots = config.docsRoots || [config.docsRoot];
@@ -135,6 +136,7 @@ export async function runPickup(argv, config, opts = {}) {
   const { dryRun } = opts;
   const json = argv.includes('--json');
   const takeover = argv.includes('--takeover');
+  const fullBody = argv.includes('--full');
   let input = argv.find(a => !a.startsWith('-'));
 
   // Interactive: pick from active/planned plans + anything with a queued handoff
@@ -217,12 +219,14 @@ export async function runPickup(argv, config, opts = {}) {
   }
 
   if (json) {
+    const card = handoffBody ? null : buildCard(filePath, raw, config);
     process.stdout.write(JSON.stringify({
       path: repoPath, oldStatus, newStatus: 'in-session', title,
       reattached: leaseOutcome === 'reattached',
       takenOver: leaseOutcome === 'taken-over',
       handoffConsumed: handoffBody !== null,
       body: (handoffBody ?? body)?.trim() ?? '',
+      card,
     }, null, 2) + '\n');
   } else {
     if (leaseOutcome === 'reattached') {
@@ -232,12 +236,21 @@ export async function runPickup(argv, config, opts = {}) {
     } else {
       process.stderr.write(`${green('▶ Picked up')}: ${repoPath} (${oldStatus ?? 'unset'} → in-session)\n\n`);
     }
-    const header = handoffBody
-      ? `[dotmd] holding ${repoPath} — consumed handoff. Release with: dotmd release ${repoPath}\n---\n`
-      : `[dotmd] holding ${repoPath} — release with: dotmd release ${repoPath}\n---\n`;
-    process.stdout.write(header);
-    const content = (handoffBody ?? body ?? '').trim();
-    if (content) process.stdout.write(content + '\n');
+    if (handoffBody) {
+      const header = `[dotmd] holding ${repoPath} — consumed handoff. Release with: dotmd release ${repoPath}\n---\n`;
+      process.stdout.write(header);
+      const content = handoffBody.trim();
+      if (content) process.stdout.write(content + '\n');
+    } else if (fullBody) {
+      const header = `[dotmd] holding ${repoPath} — release with: dotmd release ${repoPath}\n---\n`;
+      process.stdout.write(header);
+      const content = (body ?? '').trim();
+      if (content) process.stdout.write(content + '\n');
+    } else {
+      // Default: card view
+      const card = buildCard(filePath, raw, config);
+      process.stdout.write(renderCard(card));
+    }
   }
 
   try { config.hooks.onPickup?.({ path: repoPath, oldStatus, newStatus: 'in-session' }); } catch (err) { warn(`Hook 'onPickup' threw: ${err.message}`); }

package/src/pickup-card.mjs

@@ -0,0 +1,250 @@
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, resolveDocPath } from './util.mjs';
+import { walkSections, findSection, findActivePhase, summarizePhases, isPhaseHeading, detectMarker } from './section.mjs';
+import { dim, green } from './color.mjs';
+
+const CAPS = {
+  blurb: 200,
+  currentState: 500,
+  nextStep: 300,
+  versionHistoryEntry: 200,
+};
+
+function countBullets(body) {
+  if (!body) return 0;
+  return body.split('\n').filter(l => /^[-*]\s+\S/.test(l)).length;
+}
+
+function truncate(s, cap) {
+  if (!s) return '';
+  if (s.length <= cap) return s;
+  return s.slice(0, cap - 3).trimEnd() + '...';
+}
+
+function statusSummary(counts) {
+  const order = ['shipped', 'skipped', 'in-progress', 'blocked', 'todo'];
+  const icons = { shipped: '✅', skipped: '⏭', 'in-progress': '🟡', blocked: '🚧', todo: '⬜' };
+  return order.filter(k => counts[k]).map(k => `${counts[k]}${icons[k]}`).join(' ');
+}
+
+function readRelatedSummary(rawList, config) {
+  const list = Array.isArray(rawList) ? rawList : (typeof rawList === 'string' && rawList.trim() ? [rawList] : []);
+  const out = [];
+  for (const ref of list) {
+    if (!ref) continue;
+    const refStr = String(ref).trim();
+    if (!refStr) continue;
+    let abs = null;
+    try { abs = resolveDocPath(refStr, config); } catch { abs = null; }
+    if (!abs || !existsSync(abs)) {
+      out.push({ ref: refStr, status: null, missing: true });
+      continue;
+    }
+    try {
+      const raw = readFileSync(abs, 'utf8');
+      const { frontmatter } = extractFrontmatter(raw);
+      const fm = parseSimpleFrontmatter(frontmatter);
+      out.push({
+        ref: toRepoPath(abs, config.repoRoot),
+        status: asString(fm.status) ?? null,
+        missing: false,
+      });
+    } catch {
+      out.push({ ref: refStr, status: null, missing: true });
+    }
+  }
+  return out;
+}
+
+// Build the structured card object. Pure: no IO beyond what's passed in.
+export function buildCard(filePath, raw, config) {
+  const { frontmatter: fmRaw, body } = extractFrontmatter(raw);
+  const fm = parseSimpleFrontmatter(fmRaw);
+  const sections = walkSections(body);
+
+  // Title + blurb
+  const titleSection = sections.find(s => s.level === 1) ?? null;
+  const title = titleSection ? titleSection.heading : path.basename(filePath, '.md');
+  // Blurb = first blockquote line(s) after the H1, or first paragraph
+  const lines = body.split('\n');
+  let blurb = '';
+  if (titleSection) {
+    for (let i = titleSection.bodyLineStart - 1; i < lines.length; i++) {
+      const ln = lines[i];
+      if (!ln.trim()) {
+        if (blurb) break;
+        else continue;
+      }
+      if (ln.startsWith('## ') || ln.startsWith('# ')) break;
+      blurb += (blurb ? '\n' : '') + ln;
+    }
+  }
+  blurb = truncate(blurb.replace(/^> ?/gm, '').trim(), CAPS.blurb);
+
+  // Frontmatter pointers. The simple parser doesn't handle YAML multiline blocks
+  // (`>`, `|`); when only the marker char survives, treat as empty.
+  const cleanInline = (v) => {
+    const s = asString(v);
+    if (!s) return '';
+    if (/^[>|][+-]?$/.test(s.trim())) return '';
+    return s;
+  };
+  const status = asString(fm.status) ?? null;
+  const updated = asString(fm.updated) ?? null;
+  const currentState = truncate(cleanInline(fm.current_state), CAPS.currentState);
+  const nextStep = truncate(cleanInline(fm.next_step), CAPS.nextStep);
+
+  // Related plans (compressed: slug + status only — show all, don't cap count)
+  const related = [
+    ...readRelatedSummary(fm.parent_plan, config).map(r => ({ ...r, kind: 'parent' })),
+    ...readRelatedSummary(fm.related_plans, config).map(r => ({ ...r, kind: 'related' })),
+  ];
+
+  // Phases summary + active phase (pointer only, no body)
+  const phaseSummary = summarizePhases(sections);
+  const activePhase = findActivePhase(sections);
+  let activePhasePointer = null;
+  if (activePhase) {
+    activePhasePointer = {
+      heading: activePhase.heading,
+      lineStart: activePhase.lineStart,
+      lineEnd: activePhase.lineEnd,
+      marker: detectMarker(activePhase.heading),
+    };
+  }
+
+  // Old-plan fallback: no ## Phases section → point to last H2 as "active content"
+  let fallbackPointer = null;
+  if (!findSection(sections, 'Phases') && !activePhase) {
+    const h2s = sections.filter(s => s.level === 2);
+    const lastH2 = h2s[h2s.length - 1] ?? null;
+    if (lastH2) {
+      fallbackPointer = {
+        heading: lastH2.heading,
+        lineStart: lastH2.lineStart,
+        lineEnd: lastH2.lineEnd,
+      };
+    }
+  }
+
+  // Open Questions — count + pointer only, no body
+  const oqSection = findSection(sections, 'Open Questions') ?? findSection(sections, 'Open questions');
+  let openQuestions = null;
+  if (oqSection && oqSection.body.trim()) {
+    openQuestions = {
+      heading: oqSection.heading,
+      lineStart: oqSection.lineStart,
+      lineEnd: oqSection.lineEnd,
+      count: countBullets(oqSection.body),
+    };
+  }
+
+  // Last Version History entry (newest = first bullet under the heading)
+  const vhSection = findSection(sections, 'Version History');
+  let lastVersion = null;
+  if (vhSection && vhSection.body.trim()) {
+    const firstBullet = vhSection.body.split('\n').find(l => /^[-*]\s/.test(l));
+    if (firstBullet) lastVersion = truncate(firstBullet.replace(/^[-*]\s+/, ''), CAPS.versionHistoryEntry);
+  }
+
+  // Outline = all H2 headings with line ranges; phase summary inline if Phases present
+  const outline = sections.filter(s => s.level === 2).map(s => {
+    const isPhases = /^phases?$/i.test(s.heading.replace(/[^\w\s]+$/, '').trim());
+    let suffix = `lines ${s.lineStart}-${s.lineEnd}`;
+    if (isPhases && phaseSummary.total > 0) {
+      suffix = `(${phaseSummary.total}: ${statusSummary(phaseSummary.counts)})  ${suffix}`;
+    }
+    return { heading: s.heading, lineStart: s.lineStart, lineEnd: s.lineEnd, suffix };
+  });
+
+  return {
+    path: toRepoPath(filePath, config.repoRoot),
+    title,
+    status,
+    updated,
+    blurb,
+    currentState,
+    nextStep,
+    related,
+    phases: phaseSummary,
+    activePhase: activePhasePointer,
+    fallbackContent: fallbackPointer,
+    openQuestions,
+    lastVersion,
+    outline,
+    bodyBytes: body.length,
+  };
+}
+
+// Render the card to human-format string.
+export function renderCard(card) {
+  const lines = [];
+  lines.push(`[dotmd] holding ${card.path} — release with: dotmd release ${card.path}`);
+  lines.push('---');
+  lines.push(`# ${card.title}`);
+  const meta = [card.status, card.updated && `updated ${card.updated}`].filter(Boolean).join(' · ');
+  if (meta) lines.push(dim(meta));
+  if (card.blurb) {
+    lines.push('');
+    lines.push(`> ${card.blurb.replace(/\n/g, '\n> ')}`);
+  }
+
+  if (card.currentState || card.nextStep) {
+    lines.push('');
+    if (card.currentState) lines.push(`${green('Current:')} ${card.currentState}`);
+    if (card.nextStep) lines.push(`${green('Next:')}    ${card.nextStep}`);
+  }
+
+  if (card.related.length > 0) {
+    lines.push('');
+    lines.push(green('Related:'));
+    for (const r of card.related) {
+      const tag = r.kind === 'parent' ? '↑ parent' : '↔';
+      if (r.missing) {
+        lines.push(`  ${tag} ${r.ref} ${dim('(missing)')}`);
+      } else {
+        lines.push(`  ${tag} ${r.ref}${r.status ? ` ${dim(`(${r.status})`)}` : ''}`);
+      }
+    }
+  }
+
+  if (card.activePhase) {
+    lines.push('');
+    lines.push(`${green('Active phase:')} ${card.activePhase.heading}  ${dim(`(lines ${card.activePhase.lineStart}-${card.activePhase.lineEnd})`)}`);
+  } else if (card.fallbackContent) {
+    lines.push('');
+    lines.push(`${green('Active section:')} ${card.fallbackContent.heading}  ${dim(`(lines ${card.fallbackContent.lineStart}-${card.fallbackContent.lineEnd})`)}`);
+  } else if (card.phases.total > 0) {
+    lines.push('');
+    lines.push(dim(`All ${card.phases.total} phases shipped/skipped — ready for archive?`));
+  }
+
+  if (card.openQuestions) {
+    lines.push(`${green('Open Questions:')} ${card.openQuestions.count}  ${dim(`(lines ${card.openQuestions.lineStart}-${card.openQuestions.lineEnd})`)}`);
+  }
+
+  if (card.lastVersion) {
+    lines.push('');
+    lines.push(`${green('Last change:')} ${card.lastVersion}`);
+  }
+
+  if (card.outline.length > 0) {
+    lines.push('');
+    lines.push(green('Outline:'));
+    for (const o of card.outline) {
+      lines.push(`  ## ${o.heading}  ${dim(o.suffix)}`);
+    }
+  }
+
+  lines.push('');
+  lines.push(dim(`Body: ${formatBytes(card.bodyBytes)}. \`dotmd pickup ${card.path} --full\` for everything, or Read the file with offset/limit to target a section by line number.`));
+  return lines.join('\n') + '\n';
+}
+
+function formatBytes(n) {
+  if (n < 1024) return `${n}B`;
+  if (n < 1024 * 1024) return `${(n / 1024).toFixed(1)}KB`;
+  return `${(n / 1024 / 1024).toFixed(2)}MB`;
+}

package/src/section.mjs

@@ -0,0 +1,96 @@
+// Pure markdown section walker. Regex-walks H1-H6 headings respecting fenced
+// code blocks (``` and ~~~). Returns flat list of sections with body content
+// and absolute line numbers (1-indexed, matches Read tool's `offset`).
+
+export function walkSections(body) {
+  const lines = body.split('\n');
+  const fenceRe = /^(`{3,}|~{3,})/;
+  const headingRe = /^(#{1,6})\s+(.+?)\s*$/;
+  const sections = [];
+  let fenceChar = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fence = line.match(fenceRe);
+    if (fence) {
+      const tok = fence[1][0]; // ` or ~
+      if (fenceChar === null) fenceChar = tok;
+      else if (fenceChar === tok) fenceChar = null;
+      continue;
+    }
+    if (fenceChar !== null) continue;
+    const h = line.match(headingRe);
+    if (!h) continue;
+    sections.push({
+      level: h[1].length,
+      heading: h[2],
+      lineStart: i + 1, // 1-indexed
+      lineEnd: lines.length, // patched below
+      bodyLineStart: i + 2,
+    });
+  }
+
+  for (let i = 0; i < sections.length; i++) {
+    const next = sections.find((s, j) => j > i && s.level <= sections[i].level);
+    sections[i].lineEnd = next ? next.lineStart - 1 : lines.length;
+  }
+
+  for (const s of sections) {
+    s.body = lines.slice(s.bodyLineStart - 1, s.lineEnd).join('\n').trim();
+  }
+
+  return sections;
+}
+
+// Find a section by heading text, case-insensitive, trims trailing markers.
+// Returns the matching section or null.
+export function findSection(sections, name) {
+  const norm = (s) => s.toLowerCase().replace(/[^\w\s]+$/, '').trim();
+  const target = norm(name);
+  return sections.find(s => norm(s.heading) === target) ?? null;
+}
+
+// Status marker detection for phase headings. Returns one of:
+//   'shipped' | 'skipped' | 'in-progress' | 'blocked' | 'todo' | null
+const MARKER_PATTERNS = [
+  { kind: 'shipped',     re: /(✅|☑|✔|\bshipped\b|\bdone\b|\bcomplete\b)/i },
+  { kind: 'skipped',     re: /(⏭|\bskip(?:ped)?\b)/i },
+  { kind: 'in-progress', re: /(🟡|🔄|\bin[-_ ]?(?:progress|flight)\b|\bwip\b)/i },
+  { kind: 'blocked',     re: /(🚧|🔴|\bblocked\b)/i },
+  { kind: 'todo',        re: /(⬜|⬛|◻|☐|\btodo\b|\bnot[-_ ]?started\b)/i },
+];
+
+export function detectMarker(heading) {
+  for (const { kind, re } of MARKER_PATTERNS) {
+    if (re.test(heading)) return kind;
+  }
+  return null;
+}
+
+export function isPhaseHeading(section) {
+  return section.level === 3 && /^phase\b/i.test(section.heading);
+}
+
+// Summarize a phase set: { 'shipped': 2, 'in-progress': 1, 'todo': 2 }
+export function summarizePhases(sections) {
+  const phases = sections.filter(isPhaseHeading);
+  const counts = {};
+  for (const p of phases) {
+    const k = detectMarker(p.heading) ?? 'todo';
+    counts[k] = (counts[k] ?? 0) + 1;
+  }
+  return { total: phases.length, counts, phases };
+}
+
+// Active phase = first phase whose marker is NOT shipped/skipped.
+// Priority within active: in-progress > blocked > todo.
+export function findActivePhase(sections) {
+  const phases = sections.filter(isPhaseHeading);
+  const active = phases.filter(p => {
+    const m = detectMarker(p.heading);
+    return m !== 'shipped' && m !== 'skipped';
+  });
+  if (active.length === 0) return null;
+  const rank = (m) => ({ 'in-progress': 0, 'blocked': 1, 'todo': 2, [null]: 3 })[m] ?? 3;
+  return active.sort((a, b) => rank(detectMarker(a.heading)) - rank(detectMarker(b.heading)))[0];
+}

package/src/validate.mjs

@@ -174,6 +174,91 @@ export function checkGitStaleness(docs, config) {
   return warnings;
 }
 
+// Plan-shape lint: soft warnings on convention drift. Plan-only.
+// Body is the unparsed plan body (everything after the closing `---`).
+export function validatePlanShape(doc, body, frontmatter, config) {
+  if (doc.type !== 'plan') return;
+  // Skip plans in terminal/archive statuses (closed work shouldn't generate noise)
+  if (config.lifecycle.terminalStatuses.has(doc.status) || config.lifecycle.archiveStatuses.has(doc.status)) return;
+  if (config.lifecycle.skipWarningsFor.has(doc.status)) return;
+
+  // 1. next_step length cap (300 chars)
+  const nextStep = typeof frontmatter.next_step === 'string' ? frontmatter.next_step : '';
+  if (nextStep.length > 300) {
+    doc.warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: `\`next_step\` is ${nextStep.length} chars (cap: 300). Long prose belongs in the body — keep next_step as a 1-2 line pointer.`,
+    });
+  }
+
+  // 2. current_state length cap (500 chars)
+  const currentState = typeof frontmatter.current_state === 'string' ? frontmatter.current_state : '';
+  if (currentState.length > 500) {
+    doc.warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: `\`current_state\` is ${currentState.length} chars (cap: 500). Long prose belongs in the body.`,
+    });
+  }
+
+  // 3. surface AND surfaces both populated
+  if (frontmatter.surface && Array.isArray(frontmatter.surfaces) && frontmatter.surfaces.length > 0) {
+    doc.warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: 'Both `surface` (singular) and `surfaces` (array) are set. Pick one — prefer `surfaces` array form.',
+    });
+  }
+  if (frontmatter.module && Array.isArray(frontmatter.modules) && frontmatter.modules.length > 0) {
+    doc.warnings.push({
+      path: doc.path,
+      level: 'warning',
+      message: 'Both `module` (singular) and `modules` (array) are set. Pick one — prefer `modules` array form.',
+    });
+  }
+
+  if (!body) return;
+
+  // 4. Heading drift: case + name variants
+  const headingDrift = [
+    { wrong: /^##\s+Open questions\s*$/m, right: '## Open Questions' },
+    { wrong: /^##\s+(Non-goals|Out of scope|Out of Scope|out of scope)\s*$/m, right: '## Non-Goals' },
+    { wrong: /^##\s+open questions\s*$/m, right: '## Open Questions' },
+  ];
+  for (const { wrong, right } of headingDrift) {
+    const m = body.match(wrong);
+    if (m) {
+      doc.warnings.push({
+        path: doc.path,
+        level: 'warning',
+        message: `Heading drift: \`${m[0].trim()}\` → suggest \`${right}\`.`,
+      });
+    }
+  }
+
+  // 5. Phases section exists but no phase H3 has a status marker
+  const phasesIdx = body.search(/^## Phases\s*$/m);
+  if (phasesIdx >= 0) {
+    // Find the section's body (until next H2 or EOF)
+    const after = body.slice(phasesIdx);
+    const nextH2 = after.slice(8).search(/^## /m);
+    const phasesBody = nextH2 >= 0 ? after.slice(8, 8 + nextH2) : after.slice(8);
+    const phaseHeadings = [...phasesBody.matchAll(/^###\s+(.+?)\s*$/gm)].map(m => m[1]);
+    if (phaseHeadings.length > 0) {
+      const markerRe = /(✅|⏭|🟡|⬜|🚧|☑|✔|◻|☐|⬛|\bshipped\b|\bskip(?:ped)?\b|\bin[-_ ]?(?:progress|flight)\b|\bblocked\b|\btodo\b|\bnot[-_ ]?started\b|\bwip\b|\bdone\b|\bcomplete\b)/i;
+      const unmarked = phaseHeadings.filter(h => !markerRe.test(h));
+      if (unmarked.length > 0) {
+        doc.warnings.push({
+          path: doc.path,
+          level: 'warning',
+          message: `${unmarked.length} of ${phaseHeadings.length} phase heading(s) lack a status marker. Use one of ✅ shipped, ⏭ skipped, 🟡 in-progress, ⬜ todo, 🚧 blocked.`,
+        });
+      }
+    }
+  }
+}
+
 export function computeDaysSinceUpdate(updated) {
   if (!updated) return null;
   const parsed = new Date(updated);