dotmd-cli 0.25.0 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.25.0",
+  "version": "0.26.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/frontmatter.mjs

@@ -26,15 +26,22 @@ export function replaceFrontmatter(raw, newFrontmatter) {
 // structural issues (e.g. duplicate keys) — caller decides whether to surface
 // them. Default behavior is unchanged: keep first occurrence of a duplicate
 // key, ignore subsequent ones.
+//
+// Supports:
+//   inline scalars         `key: value`
+//   arrays                 `key:\n  - item\n  - item`
+//   folded block scalar    `key: >\n  one line\n  continues`         → "one line continues"
+//   literal block scalar   `key: |\n  one\n  two`                    → "one\ntwo"
+//   chomping indicators    `>-`, `|-` (strip), `>+`, `|+` (keep), default (clip to one trailing \n)
 export function parseSimpleFrontmatter(text, warnings) {
   const data = {};
   const seenDupKeys = new Set();
   let currentArrayKey = null;
-  let lineNum = 0;
+  const lines = text.split('\n');
 
-  for (const rawLine of text.split('\n')) {
-    lineNum++;
-    const line = rawLine.replace(/\r$/, '');
+  for (let i = 0; i < lines.length; i++) {
+    const lineNum = i + 1;
+    const line = lines[i].replace(/\r$/, '');
     if (!line.trim()) continue;
 
     const keyMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
@@ -49,11 +56,25 @@ export function parseSimpleFrontmatter(text, warnings) {
         }
         continue;
       }
-      if (!rawValue.trim()) {
+
+      const trimmedValue = rawValue.trim();
+
+      // Block scalar marker: > or | with optional chomping indicator (-/+).
+      const blockMatch = trimmedValue.match(/^([>|])([-+])?\s*$/);
+      if (blockMatch) {
+        const [, style, chomp] = blockMatch;
+        const { value, consumed } = collectBlockScalar(lines, i + 1, style, chomp);
+        data[key] = value;
+        i += consumed;
+        currentArrayKey = null;
+        continue;
+      }
+
+      if (!trimmedValue) {
         data[key] = [];
         currentArrayKey = key;
       } else {
-        data[key] = parseScalar(rawValue.trim());
+        data[key] = parseScalar(trimmedValue);
         currentArrayKey = null;
       }
       continue;
@@ -71,6 +92,83 @@ export function parseSimpleFrontmatter(text, warnings) {
   return data;
 }
 
+// Reads lines starting at startIdx and collects them as a YAML block scalar
+// body. Stops when a line is encountered that is dedented to (or past) the
+// key's indent level (zero in our frontmatter context). Returns the joined
+// string and the number of lines consumed (for the caller to advance `i`).
+function collectBlockScalar(lines, startIdx, style, chomp) {
+  // Determine content indent from the first non-blank line.
+  let contentIndent = null;
+  const collected = [];
+  let i = startIdx;
+  for (; i < lines.length; i++) {
+    const line = lines[i].replace(/\r$/, '');
+    if (line.trim() === '') {
+      collected.push(''); // preserve as blank for folding/literal rules
+      continue;
+    }
+    const indent = line.match(/^(\s*)/)[1].length;
+    if (contentIndent === null) {
+      // First non-blank content line establishes the indent.
+      // If it's at column 0, that's a sibling key — block was empty.
+      if (indent === 0) break;
+      contentIndent = indent;
+      collected.push(line.slice(contentIndent));
+      continue;
+    }
+    if (indent < contentIndent) {
+      // Dedented past content level — end of block scalar.
+      break;
+    }
+    collected.push(line.slice(contentIndent));
+  }
+
+  // Strip trailing blank lines we accidentally captured before the dedent
+  // (they belong to the document, not the scalar's chomping window).
+  while (collected.length > 0 && collected[collected.length - 1] === '') {
+    collected.pop();
+  }
+
+  // Join according to style.
+  let value;
+  if (style === '|') {
+    // Literal: each line preserved as-is, joined with \n.
+    value = collected.join('\n');
+  } else {
+    // Folded: single newline between non-blank lines folds to space;
+    // a blank-line run between content becomes a single \n (paragraph break).
+    value = '';
+    let hasContent = false;
+    let prevWasBlank = false;
+    for (const line of collected) {
+      if (line === '') {
+        if (hasContent && !prevWasBlank) value += '\n';
+        prevWasBlank = true;
+      } else {
+        if (hasContent && !prevWasBlank) value += ' ';
+        value += line;
+        hasContent = true;
+        prevWasBlank = false;
+      }
+    }
+  }
+
+  // Apply chomping: default = clip (single trailing \n if any content),
+  // '-' = strip (no trailing \n), '+' = keep (preserve all).
+  if (chomp === '-') {
+    value = value.replace(/\n+$/, '');
+  } else if (chomp === '+') {
+    if (!value.endsWith('\n')) value = value + '\n';
+  } else {
+    // Clip: strip multiple trailing newlines down to none for inline content
+    // (matches the practical expectation that `key: >` yields a string without
+    // trailing whitespace artifacts when used inline).
+    value = value.replace(/\n+$/, '');
+  }
+
+  return { value, consumed: i - startIdx };
+}
+
 function parseScalar(value) {
   let unquoted = value;
   if (value.length > 1 &&

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, validatePlanShape, checkBidirectionalReferences, checkGitStaleness, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate } from './validate.mjs';
+import { validateDoc, validatePlanShape, validateDocShape, checkBidirectionalReferences, checkGitStaleness, computeDaysSinceUpdate, computeIsStale, computeChecklistCompletionRate } from './validate.mjs';
 import { checkIndex } from './index-file.mjs';
 import { checkClaudeCommands } from './claude-commands.mjs';
 
@@ -194,5 +194,6 @@ export function parseDocFile(filePath, config) {
 
   validateDoc(doc, parsedFrontmatter, headingTitle, config);
   validatePlanShape(doc, body, parsedFrontmatter, config);
+  validateDocShape(doc, body, parsedFrontmatter, config);
   return doc;
 }

package/src/lifecycle.mjs

@@ -18,6 +18,7 @@ import {
 } from './lease.mjs';
 import { hasHandoff, consumeHandoff, appendHandoff, handoffPath, listQueuedHandoffs } from './handoff.mjs';
 import { buildCard, renderCard } from './pickup-card.mjs';
+import { walkSections, findSection } from './section.mjs';
 
 function findFileRoot(filePath, config) {
   const roots = config.docsRoots || [config.docsRoot];
@@ -101,6 +102,7 @@ export async function runStatus(argv, config, opts = {}) {
   }
 
   updateFrontmatter(filePath, { status: newStatus, updated: today });
+  appendVersionHistory(filePath, `Status: ${oldStatus ?? 'unknown'} → ${newStatus}.`);
 
   if (isArchiving) {
     mkdirSync(archiveDir, { recursive: true });
@@ -211,6 +213,16 @@ export async function runPickup(argv, config, opts = {}) {
     if (oldStatus !== 'in-session') {
       updateFrontmatter(filePath, { status: 'in-session', updated: today });
     }
+    // VH append per lease outcome:
+    //   acquired   → `Picked up (<old> → in-session).`
+    //   taken-over → `Took over from <session>.`
+    //   reattached → no entry (same-session noise)
+    if (leaseOutcome === 'acquired') {
+      appendVersionHistory(filePath, `Picked up (${oldStatus ?? 'unknown'} → in-session).`);
+    } else if (leaseOutcome === 'taken-over') {
+      const fromSession = result.conflict?.session ?? 'unknown';
+      appendVersionHistory(filePath, `Took over from ${fromSession}.`);
+    }
   }
 
   let handoffBody = null;
@@ -317,6 +329,7 @@ export async function runUnpickup(argv, config, opts = {}) {
       if (cur === 'in-session') {
         const today = nowIso();
         updateFrontmatter(filePath, { status: newStatus, updated: today });
+        appendVersionHistory(filePath, `Released (in-session → ${newStatus}).`);
       }
       // If frontmatter is no longer in-session (manual flip), leave it alone.
     } catch (err) {
@@ -486,6 +499,7 @@ export function runArchive(argv, config, opts = {}) {
   }
 
   updateFrontmatter(filePath, { status: 'archived', updated: today });
+  appendVersionHistory(filePath, 'Archived.');
 
   mkdirSync(targetDir, { recursive: true });
   if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); }
@@ -821,6 +835,7 @@ export async function runHandoff(argv, config, opts = {}) {
   if (oldStatus === 'in-session') {
     updateFrontmatter(filePath, { status: targetStatus, updated: today });
   }
+  appendVersionHistory(filePath, `Handoff queued (in-session → ${targetStatus}).`);
   releaseLease(config, repoPath, { force: true });
 
   if (json) {
@@ -839,6 +854,47 @@ export async function runHandoff(argv, config, opts = {}) {
   try { config.hooks.onUnpickup?.({ path: repoPath, oldStatus: 'in-session', newStatus: targetStatus }); } catch (err) { warn(`Hook 'onUnpickup' threw: ${err.message}`); }
 }
 
+// Append a one-line dated bullet to the file's `## Version History` section.
+// Newest-first ordering: inserted at the top of the section, right after the
+// heading + blank-line gap. If the section is missing, this is a silent no-op
+// — never auto-creates the section (don't surprise users on old plans/docs).
+export function appendVersionHistory(filePath, entry) {
+  let raw;
+  try { raw = readFileSync(filePath, 'utf8'); } catch { return false; }
+  if (!raw.startsWith('---\n')) return false;
+
+  const endMarker = raw.indexOf('\n---\n', 4);
+  if (endMarker === -1) return false;
+  const frontmatter = raw.slice(4, endMarker);
+  const body = raw.slice(endMarker + 5);
+
+  const vh = findSection(walkSections(body), 'Version History');
+  if (!vh) return false;
+
+  const bullet = `- **${nowIso()}** ${entry}`;
+  const lines = body.split('\n');
+
+  // vh.lineStart is 1-indexed for the heading line. The line immediately
+  // after the heading is at 0-indexed `vh.lineStart`. Skip leading blanks
+  // to find the first content line (existing bullet or next heading).
+  let insertAt = vh.lineStart;
+  while (insertAt < lines.length && lines[insertAt].trim() === '') {
+    insertAt++;
+  }
+
+  // If we're inserting just before another heading (next H2), pad with a
+  // blank line after our bullet for readability. Otherwise just splice in.
+  const atSectionBoundary = insertAt >= lines.length || lines[insertAt].startsWith('#');
+  if (atSectionBoundary) {
+    lines.splice(insertAt, 0, bullet, '');
+  } else {
+    lines.splice(insertAt, 0, bullet);
+  }
+
+  writeFileSync(filePath, `---\n${frontmatter}\n---\n${lines.join('\n')}`, 'utf8');
+  return true;
+}
+
 export function updateFrontmatter(filePath, updates) {
   const raw = readFileSync(filePath, 'utf8');
   if (!raw.startsWith('---\n')) throw new Error(`${filePath} has no frontmatter block.`);

package/src/validate.mjs

@@ -259,6 +259,31 @@ export function validatePlanShape(doc, body, frontmatter, config) {
   }
 }
 
+// Doc-shape lint: soft warnings on convention drift. Doc-only.
+// Mirrors validatePlanShape's structure.
+export function validateDocShape(doc, body, frontmatter, config) {
+  if (doc.type !== 'doc') return;
+  if (config.lifecycle.terminalStatuses.has(doc.status) || config.lifecycle.archiveStatuses.has(doc.status)) return;
+  if (config.lifecycle.skipWarningsFor.has(doc.status)) return;
+
+  if (!body) return;
+
+  // Heading drift for docs.
+  const headingDrift = [
+    { wrong: /^##\s+Related Documents\s*$/m, right: '## Related Documentation' },
+  ];
+  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}\`.`,
+      });
+    }
+  }
+}
+
 export function computeDaysSinceUpdate(updated) {
   if (!updated) return null;
   const parsed = new Date(updated);