dotmd-cli 0.14.10 → 0.14.12

package/bin/dotmd.mjs

@@ -103,6 +103,7 @@ Filters:
   --has-blockers         Only docs with blockers
   --checklist-open       Only docs with open checklist items
   --sort <field>         Sort by: updated (default), title, status
+  --group <field>        Group by: module, surface, owner (plans view)
   --limit <n>            Max results (default: 20)
   --all                  Show all results (no limit)
   --git                  Use git dates instead of frontmatter
@@ -365,11 +366,13 @@ modules, and reference fields to pre-populate the config.`,
   plans: `dotmd plans — list all plans
 
 Shows all documents with type: plan, sorted by status.
-Supports all query flags (--status, --json, --sort, etc.)
+Supports all query flags (--status, --module, --json, --sort, --group, etc.)
 
 Examples:
   dotmd plans                       # all plans
   dotmd plans --status active       # active plans only
+  dotmd plans --module auth         # plans for the auth module
+  dotmd plans --group module        # all plans grouped by module
   dotmd plans --json                # JSON output`,
 
   stale: `dotmd stale — list stale documents

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.14.10",
+  "version": "0.14.12",
   "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

@@ -22,11 +22,18 @@ export function replaceFrontmatter(raw, newFrontmatter) {
   return `---\n${newFrontmatter}\n---\n${body}`;
 }
 
-export function parseSimpleFrontmatter(text) {
+// Parses our YAML subset. Optional `warnings` array receives non-fatal
+// 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.
+export function parseSimpleFrontmatter(text, warnings) {
   const data = {};
+  const seenDupKeys = new Set();
   let currentArrayKey = null;
+  let lineNum = 0;
 
   for (const rawLine of text.split('\n')) {
+    lineNum++;
     const line = rawLine.replace(/\r$/, '');
     if (!line.trim()) continue;
 
@@ -35,6 +42,11 @@ export function parseSimpleFrontmatter(text) {
       const [, key, rawValue] = keyMatch;
       if (Object.prototype.hasOwnProperty.call(data, key)) {
         currentArrayKey = null;
+        if (warnings && !seenDupKeys.has(key)) {
+          seenDupKeys.add(key);
+          warnings.push({ key, line: lineNum,
+            message: `Duplicate frontmatter key \`${key}\` at line ${lineNum}; keeping first occurrence, ignoring later values.` });
+        }
         continue;
       }
       if (!rawValue.trim()) {

package/src/index.mjs

@@ -120,7 +120,8 @@ export function parseDocFile(filePath, config) {
   const relativePath = toRepoPath(filePath, config.repoRoot);
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter, body } = extractFrontmatter(raw);
-  const parsedFrontmatter = parseSimpleFrontmatter(frontmatter);
+  const fmWarnings = [];
+  const parsedFrontmatter = parseSimpleFrontmatter(frontmatter, fmWarnings);
   const headingTitle = extractFirstHeading(body);
   const title = asString(parsedFrontmatter.title) ?? headingTitle ?? path.basename(filePath, '.md');
   const summary = asString(parsedFrontmatter.summary) ?? extractSummary(body) ?? null;
@@ -146,7 +147,7 @@ export function parseDocFile(filePath, config) {
 
   // Tag doc with its root
   const roots = config.docsRoots || [config.docsRoot];
-  const docRoot = roots.find(r => filePath.startsWith(r)) ?? config.docsRoot;
+  const docRoot = roots.find(r => filePath.startsWith(r + '/')) ?? config.docsRoot;
   const rootLabel = path.relative(config.repoRoot, docRoot).split(path.sep).join('/');
 
   const docType = asString(parsedFrontmatter.type) ?? null;
@@ -187,6 +188,10 @@ export function parseDocFile(filePath, config) {
     errors: [],
   };
 
+  for (const w of fmWarnings) {
+    doc.warnings.push({ path: relativePath, level: 'warning', message: w.message });
+  }
+
   validateDoc(doc, parsedFrontmatter, headingTitle, config);
   return doc;
 }

package/src/query.mjs

@@ -77,6 +77,7 @@ export function parseQueryArgs(argv) {
     types: null, statuses: null, keyword: null, owner: null, surface: null,
     module: null, domain: null, audience: null, executionMode: null,
     updatedSince: null, limit: 20, all: false, sort: 'updated',
+    group: null,
     stale: false, hasNextStep: false, hasBlockers: false,
     checklistOpen: false, json: false, git: false,
     summarize: false, summarizeLimit: 5, model: undefined,
@@ -98,6 +99,7 @@ export function parseQueryArgs(argv) {
     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 === '--group' && next) { filters.group = 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; }
@@ -248,50 +250,85 @@ function renderPlansOutput(docs, filters, config) {
   // Active filter note (only if user applied extra filters beyond the preset defaults)
   const activeFilters = [];
   if (filters.statuses?.length) activeFilters.push(`status: ${filters.statuses.join(', ')}`);
+  if (filters.module) activeFilters.push(`module: ${filters.module}`);
+  if (filters.surface) activeFilters.push(`surface: ${filters.surface}`);
+  if (filters.owner) activeFilters.push(`owner: ${filters.owner}`);
   if (filters.keyword) activeFilters.push(`keyword: ${filters.keyword}`);
   if (filters.stale) activeFilters.push('stale only');
   if (filters.hasNextStep) activeFilters.push('has next step');
   if (filters.hasBlockers) activeFilters.push('has blockers');
   if (activeFilters.length) process.stdout.write(dim(`  filtered: ${activeFilters.join(' | ')}`) + '\n');
 
-  // Group by status, ordered by config.statusOrder
-  const statusGroups = new Map();
-  for (const d of docs) {
-    const s = d.status ?? 'unknown';
-    if (!statusGroups.has(s)) statusGroups.set(s, []);
-    statusGroups.get(s).push(d);
-  }
-
-  const orderedStatuses = [...config.statusOrder.filter(s => statusGroups.has(s)), ...([...statusGroups.keys()].filter(s => !config.statusOrder.includes(s)))];
   const maxWidth = process.stdout.columns || 100;
 
-  for (const status of orderedStatuses) {
-    const group = statusGroups.get(status);
-    process.stdout.write(`\n${bold(`${capitalize(status)} (${group.length})`)}\n`);
-
-    const maxSlug = Math.min(30, Math.max(...group.map(d => toSlug(d).length)));
+  // Group by module or status
+  if (filters.group === 'module') {
+    renderPlansByGroup(docs, d => d.modules?.length ? d.modules : ['(none)'], filters, maxWidth);
+  } else if (filters.group === 'surface') {
+    renderPlansByGroup(docs, d => d.surfaces?.length ? d.surfaces : ['(none)'], filters, maxWidth);
+  } else if (filters.group === 'owner') {
+    renderPlansByGroup(docs, d => [d.owner ?? '(none)'], filters, maxWidth);
+  } else {
+    // Default: group by status, ordered by config.statusOrder
+    const statusGroups = new Map();
+    for (const d of docs) {
+      const s = d.status ?? 'unknown';
+      if (!statusGroups.has(s)) statusGroups.set(s, []);
+      statusGroups.get(s).push(d);
+    }
 
-    for (const doc of group) {
-      const slug = toSlug(doc).padEnd(maxSlug);
-      const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : ' —';
-      const ageStr = doc.daysSinceUpdate != null && doc.isStale ? red(age.padStart(4)) : dim(age.padStart(4));
-      const progress = renderProgressBar(doc.checklist);
+    const orderedStatuses = [...config.statusOrder.filter(s => statusGroups.has(s)), ...([...statusGroups.keys()].filter(s => !config.statusOrder.includes(s)))];
 
-      const parts = [`  ${slug}  ${ageStr}`];
-      if (progress) parts.push(progress);
+    for (const status of orderedStatuses) {
+      const group = statusGroups.get(status);
+      process.stdout.write(`\n${bold(`${capitalize(status)} (${group.length})`)}\n`);
+      renderPlanRows(group, filters, maxWidth);
+    }
+  }
 
-      if (doc.blockers?.length && (status === 'blocked')) {
-        parts.push(yellow(`blockers: ${doc.blockers.join('; ')}`));
-      } else if (doc.nextStep) {
-        parts.push(`next: ${doc.nextStep}`);
-      } else {
-        parts.push(dim('(no next step)'));
-      }
+  process.stdout.write('\n');
+}
 
-      const line = parts.join('  ');
-      process.stdout.write((line.length > maxWidth ? line.slice(0, maxWidth - 3) + '...' : line) + '\n');
+function renderPlansByGroup(docs, keyFn, filters, maxWidth) {
+  const groups = new Map();
+  for (const d of docs) {
+    for (const key of keyFn(d)) {
+      if (!groups.has(key)) groups.set(key, []);
+      groups.get(key).push(d);
     }
   }
 
-  process.stdout.write('\n');
+  const ordered = [...groups.keys()].sort((a, b) => a === '(none)' ? 1 : b === '(none)' ? -1 : a.localeCompare(b));
+  for (const key of ordered) {
+    const group = groups.get(key);
+    process.stdout.write(`\n${bold(`${key} (${group.length})`)}\n`);
+    renderPlanRows(group, filters, maxWidth);
+  }
+}
+
+function renderPlanRows(group, filters, maxWidth) {
+  const maxSlug = Math.min(30, Math.max(...group.map(d => toSlug(d).length)));
+  const showModule = !filters.module && filters.group !== 'module';
+
+  for (const doc of group) {
+    const slug = toSlug(doc).padEnd(maxSlug);
+    const age = doc.daysSinceUpdate != null ? `${doc.daysSinceUpdate}d` : ' —';
+    const ageStr = doc.daysSinceUpdate != null && doc.isStale ? red(age.padStart(4)) : dim(age.padStart(4));
+    const progress = renderProgressBar(doc.checklist);
+
+    const parts = [`  ${slug}  ${ageStr}`];
+    if (progress) parts.push(progress);
+    if (showModule && doc.modules?.length) parts.push(dim(`[${doc.modules.join(',')}]`));
+
+    if (doc.blockers?.length && (doc.status === 'blocked')) {
+      parts.push(yellow(`blockers: ${doc.blockers.join('; ')}`));
+    } else if (doc.nextStep) {
+      parts.push(`next: ${doc.nextStep}`);
+    } else {
+      parts.push(dim('(no next step)'));
+    }
+
+    const line = parts.join('  ');
+    process.stdout.write((line.length > maxWidth ? line.slice(0, maxWidth - 3) + '...' : line) + '\n');
+  }
 }

package/src/util.mjs

@@ -100,3 +100,17 @@ export function resolveDocPath(input, config) {
 
   return null;
 }
+
+// Resolve a reference path written in frontmatter or a body link.
+// Tries doc-relative first (the historical convention), then falls back to
+// repo-root-relative — so paths like `docs/foo/bar.md` written from any nesting
+// level resolve correctly. Returns the absolute path if either form exists,
+// else null.
+export function resolveRefPath(relPath, docDir, repoRoot) {
+  if (!relPath) return null;
+  const docRelative = path.resolve(docDir, relPath);
+  if (existsSync(docRelative)) return docRelative;
+  const repoRelative = path.resolve(repoRoot, relPath);
+  if (existsSync(repoRelative)) return repoRelative;
+  return null;
+}

package/src/validate.mjs

@@ -1,6 +1,5 @@
-import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { asString } from './util.mjs';
+import { asString, resolveRefPath } from './util.mjs';
 import { getGitLastModified, getGitLastModifiedBatch } from './git.mjs';
 import { toRepoPath } from './util.mjs';
 
@@ -101,8 +100,7 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
   const allRefFields = [...(config.referenceFields.bidirectional || []), ...(config.referenceFields.unidirectional || [])];
   for (const field of allRefFields) {
     for (const relPath of (doc.refFields[field] || [])) {
-      const resolved = path.resolve(docDir, relPath);
-      if (!existsSync(resolved)) {
+      if (!resolveRefPath(relPath, docDir, config.repoRoot)) {
         doc.errors.push({ path: doc.path, level: 'error', message: `${field} entry \`${relPath}\` does not resolve to an existing file.` });
       }
     }
@@ -110,8 +108,7 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
 
   // Validate body links resolve to existing files
   for (const link of (doc.bodyLinks || [])) {
-    const resolved = path.resolve(docDir, link.href);
-    if (!existsSync(resolved)) {
+    if (!resolveRefPath(link.href, docDir, config.repoRoot)) {
       doc.warnings.push({ path: doc.path, level: 'warning', message: `body link \`${link.href}\` does not resolve to an existing file.` });
     }
   }
@@ -128,7 +125,12 @@ export function checkBidirectionalReferences(docs, config) {
     const refs = new Set();
     for (const field of biFields) {
       for (const relPath of (doc.refFields[field] || [])) {
-        const resolved = path.resolve(docDir, relPath);
+        // Use the same doc-relative-then-repo-root fallback as validateDoc so
+        // both styles produce identical refMap keys; otherwise an entry like
+        // `docs/foo.md` (repo-root style) gets keyed as
+        // `<doc-parent>/docs/foo.md` and never matches the target's repo path.
+        const resolved = resolveRefPath(relPath, docDir, config.repoRoot)
+          ?? path.resolve(docDir, relPath);
         refs.add(toRepoPath(resolved, config.repoRoot));
       }
     }