npm - dotmd-cli - Versions diffs - 0.31.1 → 0.31.2 - Mend

dotmd-cli 0.31.1 → 0.31.2

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 (10) hide show

package/bin/dotmd.mjs CHANGED Viewed

@@ -693,7 +693,7 @@ async function main() {
   // Init — now has access to config for Claude command generation
   if (command === 'init') {
     const { runInit } = await import('../src/init.mjs');
-    runInit(process.cwd(), config.configFound ? config : null);
+    runInit(process.cwd(), config.configFound ? config : null, { dryRun });
     return;
   }
@@ -1036,14 +1036,8 @@ async function main() {
   }
   // Unknown command — suggest closest match
-  const allCommands = [
-    'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'hud',
-    'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor',
-    'unblocks', 'health', 'glossary',
-    'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
-    'watch', 'diff', 'new', 'init', 'completions', 'statuses',
-  ];
-  const matches = allCommands
+  const { KNOWN_COMMANDS } = await import('../src/commands.mjs');
+  const matches = KNOWN_COMMANDS
     .map(c => ({ cmd: c, dist: levenshtein(command, c) }))
     .sort((a, b) => a.dist - b.dist);
   if (matches[0] && matches[0].dist <= 3) {

package/package.json CHANGED Viewed

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

@@ -20,7 +20,7 @@ function generatePlansCommand(config) {
   lines.push('- `dotmd release` — release current session\'s leases (alias: unpickup)');
   lines.push('- `dotmd health` — plan velocity, aging, checklist progress, pipeline view');
   lines.push('- `dotmd unblocks <file>` — what depends on / is blocked by a plan');
-  lines.push('- `dotmd next` — ready plans with next steps (what to promote)');
+  lines.push('- `dotmd actionable` — ready plans with next steps (what to promote)');
   lines.push('- `dotmd new plan <name>` — scaffold with full phase structure');
   lines.push('- `dotmd prompts new <name> "<body>"` — save a resume-prompt to docs/prompts/');
   lines.push('- `dotmd prompts next` — consume oldest pending prompt (prints body, auto-archives)');
@@ -107,7 +107,8 @@ function getInstalledVersion(filePath) {
   return match ? match[1] : null;
 }
-export function scaffoldClaudeCommands(cwd, config) {
+export function scaffoldClaudeCommands(cwd, config, opts = {}) {
+  const { dryRun = false } = opts;
   const claudeDir = path.join(cwd, '.claude');
   if (!existsSync(claudeDir)) return [];
@@ -127,13 +128,17 @@ export function scaffoldClaudeCommands(cwd, config) {
       results.push({ name, action: 'current' });
     } else if (installedVersion) {
       // Outdated — regenerate
-      mkdirSync(commandsDir, { recursive: true });
-      writeFileSync(filePath, generate(), 'utf8');
+      if (!dryRun) {
+        mkdirSync(commandsDir, { recursive: true });
+        writeFileSync(filePath, generate(), 'utf8');
+      }
       results.push({ name, action: 'updated', from: installedVersion, to: pkg.version });
     } else if (!existsSync(filePath)) {
       // New — create
-      mkdirSync(commandsDir, { recursive: true });
-      writeFileSync(filePath, generate(), 'utf8');
+      if (!dryRun) {
+        mkdirSync(commandsDir, { recursive: true });
+        writeFileSync(filePath, generate(), 'utf8');
+      }
       results.push({ name, action: 'created' });
     } else {
       // File exists but no version marker — user-managed, don't touch

package/src/commands.mjs ADDED Viewed

@@ -0,0 +1,11 @@
+// Canonical list of CLI verbs the dispatcher in bin/dotmd.mjs handles.
+// Source of truth for both the unknown-command suggester and the self-check
+// that asserts every `dotmd <verb>` reference in generated slash-command
+// templates points at a real command.
+export const KNOWN_COMMANDS = [
+  'list', 'json', 'check', 'coverage', 'stats', 'graph', 'deps', 'briefing', 'context', 'hud',
+  'focus', 'query', 'plans', 'prompts', 'stale', 'actionable', 'index', 'pickup', 'release', 'finish', 'status', 'archive', 'bulk', 'touch', 'doctor',
+  'unblocks', 'health', 'glossary',
+  'fix-refs', 'lint', 'rename', 'migrate', 'notion', 'export', 'summary',
+  'watch', 'diff', 'new', 'init', 'completions', 'statuses',
+];

package/src/config.mjs CHANGED Viewed

@@ -84,8 +84,12 @@ const DEFAULTS = {
   },
   referenceFields: {
-    bidirectional: [],
-    unidirectional: [],
+    // Defaults match the fields the built-in `plan`, `doc`, and `prompt`
+    // templates scaffold, so graph / deps / unblocks / pickup's Related:
+    // resolver work without config. Override by setting `referenceFields`
+    // in your config — your value fully replaces (no per-field merge).
+    bidirectional: ['related_plans', 'related_docs'],
+    unidirectional: ['parent_plan'],
   },
   templates: {},

package/src/init.mjs CHANGED Viewed

@@ -21,6 +21,14 @@ export const index = {
   endMarker: '<!-- GENERATED:dotmd:end -->',
   archivedLimit: 8,
 };
+// Frontmatter fields graph / deps / unblocks / pickup's Related: resolver
+// traverse. Defaults match what the built-in plan/doc/prompt templates scaffold.
+// Add field names here (and to your templates) to track more relationships.
+export const referenceFields = {
+  bidirectional: ['related_plans', 'related_docs'],
+  unidirectional: ['parent_plan'],
+};
 `;
 const STARTER_INDEX = `# Docs
@@ -143,32 +151,38 @@ function generateDetectedConfig(scan, rootPath) {
   return lines.join('\n');
 }
-export function runInit(cwd, config) {
+export function runInit(cwd, config, opts = {}) {
+  const { dryRun = false } = opts;
   const configPath = path.join(cwd, 'dotmd.config.mjs');
   const docsDir = path.join(cwd, 'docs');
   const indexPath = path.join(docsDir, 'docs.md');
+  // Prefix every reported line during dry-run so the user can't mistake the
+  // preview for a real run. Without this, every write below would silently
+  // execute — runInit previously ignored the `--dry-run` flag entirely.
+  const dryTag = dryRun ? `${dim('[dry-run]')} ` : '';
   process.stdout.write('\n');
   const scan = existsSync(docsDir) ? scanExistingDocs(docsDir) : null;
   if (existsSync(configPath)) {
-    process.stdout.write(`  ${dim('exists')}  dotmd.config.mjs\n`);
+    process.stdout.write(`  ${dryTag}${dim('exists')}  dotmd.config.mjs\n`);
   } else {
     if (scan && scan.docCount > 0) {
-      writeFileSync(configPath, generateDetectedConfig(scan, 'docs'), 'utf8');
-      process.stdout.write(`  ${green('create')}  dotmd.config.mjs (detected ${scan.docCount} docs)\n`);
+      if (!dryRun) writeFileSync(configPath, generateDetectedConfig(scan, 'docs'), 'utf8');
+      process.stdout.write(`  ${dryTag}${green('create')}  dotmd.config.mjs (detected ${scan.docCount} docs)\n`);
     } else {
-      writeFileSync(configPath, STARTER_CONFIG, 'utf8');
-      process.stdout.write(`  ${green('create')}  dotmd.config.mjs\n`);
+      if (!dryRun) writeFileSync(configPath, STARTER_CONFIG, 'utf8');
+      process.stdout.write(`  ${dryTag}${green('create')}  dotmd.config.mjs\n`);
     }
   }
   if (existsSync(docsDir)) {
-    process.stdout.write(`  ${dim('exists')}  docs/\n`);
+    process.stdout.write(`  ${dryTag}${dim('exists')}  docs/\n`);
   } else {
-    mkdirSync(docsDir, { recursive: true });
-    process.stdout.write(`  ${green('create')}  docs/\n`);
+    if (!dryRun) mkdirSync(docsDir, { recursive: true });
+    process.stdout.write(`  ${dryTag}${green('create')}  docs/\n`);
   }
   // Inspect root-level siblings (e.g. ./plans/, ./prompts/) before scaffolding.
@@ -192,25 +206,25 @@ export function runInit(cwd, config) {
     const counts = scan?.subdirCounts?.[sub];
     const total = counts ? counts.withFrontmatter + counts.withoutFrontmatter : 0;
     if (siblingSet.has(sub) && !existsSync(subPath)) {
-      process.stdout.write(`  ${yellow('skip')}    docs/${sub}/ (root-level ./${sub}/ already holds content)\n`);
+      process.stdout.write(`  ${dryTag}${yellow('skip')}    docs/${sub}/ (root-level ./${sub}/ already holds content)\n`);
       continue;
     }
     if (existsSync(subPath)) {
       const detail = total > 0
         ? ` (${counts.withFrontmatter} dotmd-tracked, ${counts.withoutFrontmatter} plain .md)`
         : '';
-      process.stdout.write(`  ${dim('exists')}  docs/${sub}/${detail}\n`);
+      process.stdout.write(`  ${dryTag}${dim('exists')}  docs/${sub}/${detail}\n`);
     } else {
-      mkdirSync(subPath, { recursive: true });
-      process.stdout.write(`  ${green('create')}  docs/${sub}/\n`);
+      if (!dryRun) mkdirSync(subPath, { recursive: true });
+      process.stdout.write(`  ${dryTag}${green('create')}  docs/${sub}/\n`);
     }
   }
   if (existsSync(indexPath)) {
-    process.stdout.write(`  ${dim('exists')}  docs/docs.md\n`);
+    process.stdout.write(`  ${dryTag}${dim('exists')}  docs/docs.md\n`);
   } else {
-    writeFileSync(indexPath, STARTER_INDEX, 'utf8');
-    process.stdout.write(`  ${green('create')}  docs/docs.md\n`);
+    if (!dryRun) writeFileSync(indexPath, STARTER_INDEX, 'utf8');
+    process.stdout.write(`  ${dryTag}${green('create')}  docs/docs.md\n`);
   }
   if (siblingsWithContent.length > 0) {
@@ -235,24 +249,32 @@ export function runInit(cwd, config) {
     const has = current.split('\n').some(l => l.trim() === ignoreLine || l.trim() === '.dotmd');
     if (!has) {
       const sep = current.endsWith('\n') ? '' : '\n';
-      writeFileSync(gitignorePath, `${current}${sep}${ignoreLine}\n`, 'utf8');
-      process.stdout.write(`  ${green('update')}  .gitignore (+${ignoreLine})\n`);
+      if (!dryRun) writeFileSync(gitignorePath, `${current}${sep}${ignoreLine}\n`, 'utf8');
+      process.stdout.write(`  ${dryTag}${green('update')}  .gitignore (+${ignoreLine})\n`);
     } else {
-      process.stdout.write(`  ${dim('exists')}  .gitignore\n`);
+      process.stdout.write(`  ${dryTag}${dim('exists')}  .gitignore\n`);
     }
   } else {
-    writeFileSync(gitignorePath, `${ignoreLine}\n`, 'utf8');
-    process.stdout.write(`  ${green('create')}  .gitignore\n`);
+    if (!dryRun) writeFileSync(gitignorePath, `${ignoreLine}\n`, 'utf8');
+    process.stdout.write(`  ${dryTag}${green('create')}  .gitignore\n`);
   }
-  // Claude Code integration — auto-detect .claude/ directory
+  // Claude Code integration — auto-detect .claude/ directory.
+  // Reports all four scaffold outcomes so the user can't be surprised by
+  // either a silent regenerate (pre-fix: `updated` was unreported) or by
+  // dotmd skipping a user-managed file (pre-fix: `skipped` was unreported).
   if (config) {
-    const results = scaffoldClaudeCommands(cwd, config);
+    const results = scaffoldClaudeCommands(cwd, config, { dryRun });
     for (const r of results) {
+      const filename = `.claude/commands/${r.name}`;
       if (r.action === 'created') {
-        process.stdout.write(`  ${green('create')}  .claude/commands/${r.name}\n`);
+        process.stdout.write(`  ${dryTag}${green('create')}  ${filename}\n`);
+      } else if (r.action === 'updated') {
+        process.stdout.write(`  ${dryTag}${green('update')}  ${filename} (v${r.from} → v${r.to})\n`);
       } else if (r.action === 'current') {
-        process.stdout.write(`  ${dim('current')} .claude/commands/${r.name}\n`);
+        process.stdout.write(`  ${dryTag}${dim('exists')}  ${filename}\n`);
+      } else if (r.action === 'skipped') {
+        process.stdout.write(`  ${dryTag}${yellow('skip')}    ${filename} (no version marker — user-managed)\n`);
       }
     }
   }

package/src/lifecycle.mjs CHANGED Viewed

@@ -24,6 +24,21 @@ function findFileRoot(filePath, config) {
   return roots.find(r => filePath.startsWith(r + '/')) ?? config.docsRoot;
 }
+// Best-effort index regen for any doc-set or doc-status mutation. The
+// generated block groups by status and embeds per-doc snapshots, so any
+// change that affects what would render leaves the index stale. Wrapped
+// in try/catch — a regen failure shouldn't undo the successful mutation,
+// only warn with the recovery command.
+export function regenIndex(config) {
+  if (!config.indexPath) return;
+  try {
+    const index = buildIndex(config);
+    writeIndex(renderIndexFile(index, config), config);
+  } catch (err) {
+    warn(`Could not regenerate index (run \`dotmd index --write\`): ${err.message}`);
+  }
+}
 // Pick an archive destination that won't clobber an existing record. If
 // `<dir>/<basename>` is free, returns it unchanged; otherwise appends a UTC
 // timestamp (and a counter on the vanishingly rare same-second collision) so
@@ -142,10 +157,10 @@ export async function runStatus(argv, config, opts = {}) {
     finalPath = targetPath;
   }
-  if ((isArchiving || isUnarchiving) && config.indexPath) {
-    const index = buildIndex(config);
-    writeIndex(renderIndexFile(index, config), config);
-  }
+  // Regen the index on every status change — `active → planned` etc. drift
+  // the per-status sections just as much as archive crossings. Archive paths
+  // also benefit (replaces the previously-gated regen).
+  regenIndex(config);
   process.stdout.write(`${green(toRepoPath(finalPath, config.repoRoot))}: ${oldStatus ?? 'unknown'} → ${newStatus}\n`);
@@ -230,6 +245,7 @@ export async function runPickup(argv, config, opts = {}) {
     }
     if (oldStatus !== 'in-session') {
       updateFrontmatter(filePath, { status: 'in-session', updated: today });
+      regenIndex(config);
     }
     // VH append per lease outcome:
     //   acquired   → `Picked up (<old> → in-session).`
@@ -336,6 +352,7 @@ export async function runUnpickup(argv, config, opts = {}) {
         const today = nowIso();
         updateFrontmatter(filePath, { status: newStatus, updated: today });
         appendVersionHistory(filePath, `Released (in-session → ${newStatus}).`);
+        regenIndex(config);
       }
       // If frontmatter is no longer in-session (manual flip), leave it alone.
     } catch (err) {
@@ -450,6 +467,7 @@ export async function runFinish(argv, config, opts = {}) {
     process.stderr.write(`${dim('[dry-run]')} Would update: status: in-session → ${targetStatus}, updated: ${today}\n`);
   } else {
     updateFrontmatter(filePath, { status: targetStatus, updated: today });
+    regenIndex(config);
   }
   if (json) {
@@ -517,10 +535,7 @@ export function runArchive(argv, config, opts = {}) {
   // Auto-update references in other docs
   const updatedRefCount = updateRefsAfterMove(filePath, targetPath, config);
-  if (config.indexPath) {
-    const index = buildIndex(config);
-    writeIndex(renderIndexFile(index, config), config);
-  }
+  regenIndex(config);
   out.write(`${green('Archived')}: ${oldRepoPath} → ${newRepoPath}\n`);
   if (selfRefsFixed) out.write('Updated references in archived file.\n');

package/src/new.mjs CHANGED Viewed

@@ -4,6 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { toRepoPath, die, warn, nowIso } from './util.mjs';
 import { green, dim, bold } from './color.mjs';
 import { isInteractive, promptText } from './prompt.mjs';
+import { regenIndex } from './lifecycle.mjs';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
@@ -133,6 +134,7 @@ Status markers (put in heading text):
       'type: prompt',
       `status: ${s}`,
       `created: ${d}`,
+      `updated: ${d}`,
       `dotmd_version: ${pkg.version}`,
       `context: ${ctx?.title ? `"${ctx.title.replace(/"/g, '\\"')}"` : ''}`,
       'related_plans:',
@@ -328,6 +330,8 @@ export async function runNew(argv, config, opts = {}) {
   writeFileSync(filePath, content, 'utf8');
   process.stdout.write(`${green('Created')}: ${repoPath} ${dim(`(${typeName})`)}\n`);
+  regenIndex(config);
   try { config.hooks.onNew?.({ path: repoPath, status, title: docTitle, type: typeName }); } catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
 }

package/src/rename.mjs CHANGED Viewed

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { toRepoPath, resolveDocPath, die, warn } from './util.mjs';
 import { migrateLease } from './lease.mjs';
 import { collectDocFiles } from './index.mjs';
+import { regenIndex } from './lifecycle.mjs';
 import { gitMv } from './git.mjs';
 import { green, dim } from './color.mjs';
 import { isInteractive, promptText } from './prompt.mjs';
@@ -101,6 +102,8 @@ export async function runRename(argv, config, opts = {}) {
   try { migrateLease(config, oldRepoPath, newRepoPath); } catch (err) { warn(`Could not migrate lease ${oldRepoPath} → ${newRepoPath}: ${err.message}`); }
+  regenIndex(config);
   process.stdout.write(`${green('Renamed')}: ${oldRepoPath} → ${newRepoPath}\n`);
   if (updatedCount > 0) {
     process.stdout.write(`Updated references in ${updatedCount} file(s).\n`);

package/src/validate.mjs CHANGED Viewed

@@ -114,11 +114,16 @@ export function validateDoc(doc, frontmatter, headingTitle, config) {
     }
   }
-  if (!headingTitle && !asString(frontmatter.title)) {
+  // Prompts are intentionally body-only one-shot artifacts: the slug names the
+  // prompt, the body IS the payload. Forcing a `title` or blockquote `summary`
+  // is friction the prompt format was designed around.
+  const skipTitleSummary = doc.type === 'prompt';
+  if (!skipTitleSummary && !headingTitle && !asString(frontmatter.title)) {
     doc.warnings.push({ path: doc.path, level: 'warning', message: 'Missing `title` and no H1 found for fallback.' });
   }
-  if (!config.lifecycle.skipWarningsFor.has(doc.status) && !asString(frontmatter.summary) && !doc.summary) {
+  if (!skipTitleSummary && !config.lifecycle.skipWarningsFor.has(doc.status) && !asString(frontmatter.summary) && !doc.summary) {
     doc.warnings.push({ path: doc.path, level: 'warning', message: 'Missing `summary` and no blockquote fallback found.' });
   }