npm - dotmd-cli - Versions diffs - 0.24.1 → 0.26.0 - Mend

dotmd-cli 0.24.1 → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/bin/dotmd.mjs CHANGED Viewed

@@ -56,7 +56,7 @@ Lifecycle:
   migrate <field> <old> <new> [f...]Batch update a frontmatter field value (optional file filter)
 Create & Export:
-  new <type> <name> [body]          Create doc of given type (plan, doc, prompt, research)
+  new <type> <name> [body]          Create doc of given type (plan, doc, prompt)
   index [--write]                   Generate/update docs.md index block
   export [--format md|html|json]    Export docs as markdown, HTML, or JSON
   notion import|export|sync [db-id] Notion database integration
@@ -396,9 +396,8 @@ Use --dry-run (-n) with --write to preview without writing.`,
 Types and their default destinations:
   plan        docs/plans/<slug>.md     (build-up template: Problem → Phases → Closeout)
-  doc         docs/<slug>.md           (minimal reference doc)
+  doc         docs/<slug>.md           (build-up lite: Overview → Version History → Related)
   prompt      docs/prompts/<slug>.md   (saved prompt to seed a future session — body required)
-  research    docs/<slug>.md           (audit / investigation)
 \`<type>\` can be omitted; defaults to \`doc\`.
 \`<name>\` is slugified for the filename.

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.24.1",
+  "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/claude-commands.mjs CHANGED Viewed

@@ -119,7 +119,6 @@ function generateDocsCommand(config) {
   lines.push('- `dotmd new plan <name>` — scaffold new plan');
   lines.push('- `dotmd new doc <name>` — scaffold reference doc');
   lines.push('- `dotmd new prompt <name> "<body>"` — save a resume-prompt');
-  lines.push('- `dotmd new research <name>` — scaffold an audit/investigation');
   lines.push('- `dotmd status <file> <status>` — transition status');
   lines.push('- `dotmd archive <file>` — archive with auto ref-fixing');
   lines.push('- `dotmd bulk archive <files>` — archive multiple at once');

package/src/config.mjs CHANGED Viewed

@@ -35,11 +35,6 @@ const DEFAULTS = {
       context: { expanded: ['active'], listed: ['draft', 'review'], counted: ['reference', 'deprecated', 'archived'] },
       staleDays: { draft: 30, active: 14, review: 14 },
     },
-    research: {
-      statuses: ['active', 'reference', 'archived'],
-      context: { expanded: ['active'], listed: [], counted: ['reference', 'archived'] },
-      staleDays: { active: 30 },
-    },
     prompt: {
       statuses: ['pending', 'claimed', 'archived'],
       context: { expanded: ['pending'], listed: [], counted: ['claimed', 'archived'] },

package/src/frontmatter.mjs CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/new.mjs CHANGED Viewed

@@ -10,10 +10,36 @@ const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'),
 const BUILTIN_TEMPLATES = {
   doc: {
-    description: 'Reference doc, design note, glossary entry, etc.',
+    description: 'Reference doc, design note, module overview — build-up shape lite',
     defaultStatus: 'active',
-    frontmatter: (s, d) => `type: doc\nstatus: ${s}\ncreated: ${d}\nupdated: ${d}`,
-    body: (t) => `\n# ${t}\n`,
+    frontmatter: (s, d) => [
+      'type: doc',
+      `status: ${s}`,
+      `created: ${d}`,
+      `updated: ${d}`,
+      'modules: []',
+      'surfaces: []',
+      'domain:',
+      'audience: internal',
+      'related_plans: []',
+      'related_docs: []',
+    ].join('\n'),
+    body: (t, ctx) => `
+# ${t}
+> One-line summary of what this doc covers.
+## Overview
+## Version History
+- **${ctx?.today ?? ''}** Created.
+## Related Documentation
+`,
   },
   plan: {
     description: 'Execution plan — build-up shape (Problem → Phases → Closeout) with phase status markers and Version History',
@@ -95,22 +121,6 @@ Status markers (put in heading text):
 <!-- Filled on archive: what shipped, key commits, deferrals dispositioned. -->
 `,
   },
-  research: {
-    description: 'Codebase audit or research investigation',
-    defaultStatus: 'active',
-    frontmatter: (s, d) => [
-      'type: research',
-      `status: ${s}`,
-      `created: ${d}`,
-      `updated: ${d}`,
-      `audited: ${d}`,
-      'audit_level: pass1',
-      'module:',
-      'source_of_truth: code',
-      'supports_plans: []',
-    ].join('\n'),
-    body: (t) => `\n# ${t}\n\n## Scope\n\n\n\n## Findings\n\n\n\n## Recommendations\n\n\n`,
-  },
   prompt: {
     description: 'Saved prompt to seed a future Claude session — body is required',
     dir: 'prompts',

package/src/validate.mjs CHANGED Viewed

@@ -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);