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

dotmd-cli 0.26.0 → 0.27.1

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

package/bin/dotmd.mjs CHANGED Viewed

@@ -21,7 +21,8 @@ View & Query:
   focus [status] [--json]           Detailed view for one status group
   query [filters] [--json]          Filtered search (--status, --keyword, --stale, etc.)
   plans                             Live plans (excludes archived; --include-archived for all)
-  prompts                           Pending prompts in docs/prompts/
+  prompts [list|next|use|archive|new]
+                                    Manage saved prompts (default: list pending)
   stale                             Stale docs (preset)
   actionable                        Docs with next steps (preset)
@@ -260,24 +261,29 @@ Shows detailed info for all docs matching the given status (default: active).
 Options:
   --json                 Output as JSON`,
-  hud: `dotmd hud — three-line actionable triage
+  hud: `dotmd hud — actionable triage for session start
-Prints up to three lines, in order:
+Prints up to four lines, in order:
   ▶ You hold N plans: <slugs>       (leases owned by current session)
   ▶ N handoffs queued: <slugs>      (resume-prompt sidecars waiting)
+  ▶ N pending prompts: <slugs>      (saved prompts in docs/prompts/)
   ⚠ N stuck leases >24h             (suggest \`dotmd release --stale\`)
-Silent when all three are empty — designed for SessionStart hooks where
+Silent when all four are empty — designed for SessionStart hooks where
 zero noise is the right default. Distinct from \`dotmd briefing\`, which
 dumps the full plan-status pipeline and per-plan next_step bodies (kilobytes
 on large repos). Use hud for ergonomic session boot; use briefing for
 explicit "give me the full picture."
+The pending-prompts line tells Claude to consume them via
+\`dotmd prompts use <file>\` rather than reading/cat'ing — that atomically
+prints the body and archives the prompt so it cannot be double-consumed.
 Recommended SessionStart hook (in ~/.claude/settings.json):
   "SessionStart": [{ "hooks": [{ "type": "command", "command": "dotmd hud", "timeout": 5 }] }]
 Options:
-  --json                 Output as JSON ({ owned, queued, stale })`,
+  --json                 Output as JSON ({ owned, queued, prompts, stale })`,
   briefing: `dotmd briefing — compact summary for session start
@@ -555,19 +561,36 @@ Examples:
   dotmd plans --group module           # plans grouped by module
   dotmd plans --json                   # JSON output`,
-  prompts: `dotmd prompts — list saved prompts (excludes archived by default)
+  prompts: `dotmd prompts — manage saved prompts (subcommand namespace)
+Prompts are documents with \`type: prompt\`, typically saved under
+docs/prompts/. They seed future Claude sessions; consuming a prompt
+prints its body to stdout and atomically archives it (one-shot).
-Shows documents with type: prompt, typically saved under docs/prompts/.
-Prompts are created with \`dotmd new prompt <name> "<body>"\` and seed
-future Claude sessions via \`claude "$(cat docs/prompts/<name>.md)"\`.
+Subcommands:
+  list                       List pending prompts (default)
+  next                       Consume the oldest pending prompt:
+                             print body to stdout, flip status to archived
+  use <file>                 Consume a specific prompt (same as next, but
+                             targets <file> instead of picking oldest)
+  archive <file>             Archive a prompt without printing its body
+  new <slug> [body]          Create a new prompt (alias for
+                             \`dotmd new prompt <slug> [body]\`)
 Default prompt statuses: pending, claimed, archived.
 Examples:
   dotmd prompts                        # pending prompts (default)
-  dotmd prompts --include-archived     # all prompts including archived
-  dotmd prompts --status claimed       # already-consumed prompts
-  dotmd prompts --json                 # JSON output`,
+  dotmd prompts list --include-archived # all prompts including archived
+  dotmd prompts list --status claimed   # already-consumed prompts
+  dotmd prompts --json                 # JSON output
+  claude "$(dotmd prompts next)"       # consume oldest pending + run claude
+  claude "$(dotmd prompts use docs/prompts/foo.md)"
+  dotmd prompts next --dry-run         # preview without consuming
+  dotmd prompts archive docs/prompts/old.md
+  dotmd prompts new my-prompt "Body text here"`,
   stale: `dotmd stale — list stale documents
@@ -769,19 +792,8 @@ async function main() {
     return;
   }
   if (command === 'prompts') {
-    const { buildIndex } = await import('../src/index.mjs');
-    const { runQuery } = await import('../src/query.mjs');
-    const index = buildIndex(config);
-    const sub = restArgs[0];
-    let defaults;
-    let extras = restArgs;
-    if (sub === 'status') {
-      defaults = ['--type', 'prompt', '--exclude-archived', '--sort', 'status', '--all'];
-      extras = restArgs.slice(1);
-    } else {
-      defaults = ['--type', 'prompt', '--exclude-archived', '--sort', 'updated', '--limit', '10'];
-    }
-    runQuery(index, [...defaults, ...extras], config, { preset: 'prompts' });
+    const { runPrompts } = await import('../src/prompts.mjs');
+    await runPrompts(restArgs, config, { dryRun });
     return;
   }

package/package.json CHANGED Viewed

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

@@ -23,7 +23,9 @@ function generatePlansCommand(config) {
   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 new plan <name>` — scaffold with full phase structure');
-  lines.push('- `dotmd new prompt <name> "<body>"` — save a resume-prompt to docs/prompts/');
+  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)');
+  lines.push('- `dotmd prompts use <file>` — consume a specific prompt (prints body, auto-archives)');
   lines.push('- `dotmd archive <file>` — archive with auto ref-fixing (both directions)');
   lines.push('- `dotmd bulk archive <files>` — archive multiple at once');
   lines.push('- `dotmd status <file> <status>` — transition status');
@@ -39,6 +41,8 @@ function generatePlansCommand(config) {
   lines.push('If the user asks to change a plan\'s status, use `dotmd status <file> <status>`.');
   lines.push('If the user asks to archive a plan, use `dotmd archive <file>`.');
   lines.push('');
+  lines.push('**Saved prompts (`docs/prompts/*.md`):** if the user references a file under `docs/prompts/` — e.g. "resume via docs/prompts/foo.md", "use this prompt", "load that one" — consume it with `dotmd prompts use <file>` (atomically prints the body and archives the prompt so it cannot be double-consumed). Do NOT `cat` it, read it with the file-reading tool, or copy its body into chat. To pick the oldest pending prompt without naming a file, use `dotmd prompts next`.');
+  lines.push('');
   return lines.join('\n');
 }
@@ -118,7 +122,9 @@ function generateDocsCommand(config) {
   lines.push('Lifecycle:');
   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 prompts new <name> "<body>"` — save a resume-prompt');
+  lines.push('- `dotmd prompts next` — consume oldest pending prompt (prints body, auto-archives)');
+  lines.push('- `dotmd prompts use <file>` — consume a specific prompt (prints body, auto-archives)');
   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');
@@ -127,6 +133,8 @@ function generateDocsCommand(config) {
   lines.push('- `dotmd fix-refs` — repair broken references and body links');
   lines.push('- `dotmd rename <old> <new>` — rename doc + update all references');
   lines.push('');
+  lines.push('**Saved prompts (`docs/prompts/*.md`):** if the user references a file under `docs/prompts/` — e.g. "resume via docs/prompts/foo.md", "use this prompt" — consume it with `dotmd prompts use <file>` (prints the body and archives atomically). Do NOT `cat` it or read it with the file-reading tool. To pick the oldest pending prompt without naming a file, use `dotmd prompts next`.');
+  lines.push('');
   return lines.join('\n');
 }

package/src/hud.mjs CHANGED Viewed

@@ -1,6 +1,9 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { readLeases, findStaleLeases, currentSessionId } from './lease.mjs';
 import { listQueuedHandoffs } from './handoff.mjs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath } from './util.mjs';
 import { green, yellow, dim } from './color.mjs';
 const MAX_PREVIEW = 5;
@@ -13,14 +16,50 @@ function previewList(items, max = MAX_PREVIEW) {
   return slugs.join(', ') + more;
 }
+function findPendingPrompts(config) {
+  const roots = config.docsRoots || (config.docsRoot ? [config.docsRoot] : []);
+  const archiveDir = config.archiveDir || 'archived';
+  const found = [];
+  const seen = new Set();
+  for (const root of roots) {
+    // A root may either contain a prompts/ subdir (the common case, e.g. root=docs)
+    // or be the prompts/ dir itself (e.g. root=docs/prompts — see #6).
+    const dir = path.basename(root) === 'prompts' ? root : path.join(root, 'prompts');
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    if (!existsSync(dir)) continue;
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const entry of entries) {
+      if (entry.isDirectory()) continue;
+      if (!entry.name.endsWith('.md')) continue;
+      const filePath = path.join(dir, entry.name);
+      // Skip any nested archived/ collisions just in case
+      if (filePath.includes(`/${archiveDir}/`)) continue;
+      let raw;
+      try { raw = readFileSync(filePath, 'utf8'); } catch { continue; }
+      const { frontmatter } = extractFrontmatter(raw);
+      if (!frontmatter) continue;
+      const fm = parseSimpleFrontmatter(frontmatter);
+      if (asString(fm.type) !== 'prompt') continue;
+      if (asString(fm.status) !== 'pending') continue;
+      found.push(toRepoPath(filePath, config.repoRoot));
+    }
+  }
+  return found.sort();
+}
 export function buildHud(config) {
   const session = currentSessionId();
   const leases = readLeases(config);
   const owned = Object.values(leases).filter(l => l.session === session).map(l => l.path);
   const queued = listQueuedHandoffs(config).map(h => h.repoPath);
   const stale = findStaleLeases(config).map(l => l.path);
+  const prompts = findPendingPrompts(config);
-  return { owned, queued, stale };
+  return { owned, queued, stale, prompts };
 }
 export function runHud(argv, config) {
@@ -39,6 +78,9 @@ export function runHud(argv, config) {
   if (hud.queued.length > 0) {
     lines.push(green(`▶ ${hud.queued.length} handoff${hud.queued.length === 1 ? '' : 's'} queued: ${previewList(hud.queued)}  ${dim('(resume: dotmd pickup)')}`));
   }
+  if (hud.prompts.length > 0) {
+    lines.push(green(`▶ ${hud.prompts.length} pending prompt${hud.prompts.length === 1 ? '' : 's'}: ${previewList(hud.prompts)}  ${dim('(consume: `dotmd prompts use <file>` — do not cat/read)')}`));
+  }
   if (hud.stale.length > 0) {
     lines.push(yellow(`⚠ ${hud.stale.length} stuck lease${hud.stale.length === 1 ? '' : 's'} >24h  ${dim('(run: dotmd release --stale)')}`));
   }

package/src/lifecycle.mjs CHANGED Viewed

@@ -460,7 +460,7 @@ export async function runFinish(argv, config, opts = {}) {
 }
 export function runArchive(argv, config, opts = {}) {
-  const { dryRun } = opts;
+  const { dryRun, out = process.stdout } = opts;
   const input = argv[0];
   if (!input) { die('Usage: dotmd archive <file>'); }
@@ -485,15 +485,15 @@ export function runArchive(argv, config, opts = {}) {
   if (dryRun) {
     const prefix = dim('[dry-run]');
-    process.stdout.write(`${prefix} Would update frontmatter: status: ${oldStatus} → archived, updated: ${today}\n`);
+    out.write(`${prefix} Would update frontmatter: status: ${oldStatus} → archived, updated: ${today}\n`);
     if (existsSync(targetPath)) { die(`Target already exists: ${toRepoPath(targetPath, config.repoRoot)}`); }
-    process.stdout.write(`${prefix} Would move: ${oldRepoPath} → ${newRepoPath}\n`);
-    if (config.indexPath) process.stdout.write(`${prefix} Would regenerate index\n`);
+    out.write(`${prefix} Would move: ${oldRepoPath} → ${newRepoPath}\n`);
+    if (config.indexPath) out.write(`${prefix} Would regenerate index\n`);
     // Preview reference updates
     const refCount = countRefsToUpdate(filePath, targetPath, config);
     if (refCount > 0) {
-      process.stdout.write(`${prefix} Would update references in ${refCount} file(s)\n`);
+      out.write(`${prefix} Would update references in ${refCount} file(s)\n`);
     }
     return;
   }
@@ -518,10 +518,10 @@ export function runArchive(argv, config, opts = {}) {
     writeIndex(renderIndexFile(index, config), config);
   }
-  process.stdout.write(`${green('Archived')}: ${oldRepoPath} → ${newRepoPath}\n`);
-  if (selfRefsFixed) process.stdout.write('Updated references in archived file.\n');
-  if (updatedRefCount > 0) process.stdout.write(`Updated references in ${updatedRefCount} file(s).\n`);
-  if (config.indexPath) process.stdout.write('Index regenerated.\n');
+  out.write(`${green('Archived')}: ${oldRepoPath} → ${newRepoPath}\n`);
+  if (selfRefsFixed) out.write('Updated references in archived file.\n');
+  if (updatedRefCount > 0) out.write(`Updated references in ${updatedRefCount} file(s).\n`);
+  if (config.indexPath) out.write('Index regenerated.\n');
   try { releaseLease(config, oldRepoPath, { force: true }); } catch (err) { warn(`Could not release lease for ${oldRepoPath}: ${err.message}`); }

package/src/prompts.mjs ADDED Viewed

@@ -0,0 +1,135 @@
+import { readFileSync, statSync } from 'node:fs';
+import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
+import { asString, toRepoPath, die, resolveDocPath } from './util.mjs';
+import { buildIndex } from './index.mjs';
+import { runQuery } from './query.mjs';
+import { runArchive } from './lifecycle.mjs';
+import { runNew } from './new.mjs';
+import { green, dim } from './color.mjs';
+const SUBCOMMANDS = new Set(['list', 'next', 'use', 'archive', 'new']);
+export async function runPrompts(argv, config, opts = {}) {
+  const sub = argv[0];
+  if (!sub || !SUBCOMMANDS.has(sub)) {
+    return runPromptsList(argv, config, opts);
+  }
+  const rest = argv.slice(1);
+  switch (sub) {
+    case 'list':   return runPromptsList(rest, config, opts);
+    case 'next':   return runPromptsNext(rest, config, opts);
+    case 'use':    return runPromptsUse(rest, config, opts);
+    case 'archive': return runPromptsArchive(rest, config, opts);
+    case 'new':    return runPromptsNew(rest, config, opts);
+  }
+}
+function runPromptsList(argv, config) {
+  const index = buildIndex(config);
+  const hasStatusFlag = argv.includes('--status');
+  const includeArchived = argv.includes('--include-archived');
+  const sub = argv[0];
+  let defaults;
+  let extras = argv;
+  if (sub === 'status') {
+    defaults = ['--type', 'prompt', '--exclude-archived', '--sort', 'status', '--all'];
+    extras = argv.slice(1);
+  } else if (hasStatusFlag || includeArchived) {
+    defaults = ['--type', 'prompt', '--sort', 'updated', '--limit', '10'];
+  } else {
+    defaults = ['--type', 'prompt', '--exclude-archived', '--sort', 'updated', '--limit', '10'];
+  }
+  runQuery(index, [...defaults, ...extras], config, { preset: 'prompts' });
+}
+function pendingPromptsOldestFirst(config) {
+  const index = buildIndex(config);
+  const prompts = index.docs.filter(d => d.type === 'prompt' && d.status === 'pending');
+  return prompts
+    .map(d => {
+      const abs = resolveDocPath(d.path, config);
+      let mtime = 0;
+      try { mtime = abs ? statSync(abs).mtimeMs : 0; } catch { mtime = 0; }
+      return { doc: d, abs, created: d.created ?? '', mtime };
+    })
+    .sort((a, b) => {
+      if (a.created && b.created && a.created !== b.created) return a.created.localeCompare(b.created);
+      if (a.created && !b.created) return -1;
+      if (!a.created && b.created) return 1;
+      return a.mtime - b.mtime;
+    });
+}
+function runPromptsNext(argv, config, opts = {}) {
+  const queue = pendingPromptsOldestFirst(config);
+  if (queue.length === 0) {
+    die('No pending prompts.');
+  }
+  const head = queue[0];
+  if (!head.abs) die(`Could not resolve path: ${head.doc.path}`);
+  consumePrompt(head.abs, config, opts);
+}
+function runPromptsUse(argv, config, opts = {}) {
+  const input = argv.find(a => !a.startsWith('-'));
+  if (!input) die('Usage: dotmd prompts use <file>');
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) die(`File not found: ${input}`);
+  consumePrompt(filePath, config, opts);
+}
+function consumePrompt(filePath, config, opts) {
+  const { dryRun } = opts;
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter, body } = extractFrontmatter(raw);
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  const docType = asString(parsed.type);
+  const status = asString(parsed.status);
+  const repoPath = toRepoPath(filePath, config.repoRoot);
+  if (docType !== 'prompt') {
+    die(`Not a prompt (type: ${docType ?? 'unknown'}): ${repoPath}`);
+  }
+  if (status === 'archived') {
+    die(`Already consumed: ${repoPath}`);
+  }
+  if (dryRun) {
+    process.stderr.write(`${dim('[dry-run]')} Would emit body and archive: ${repoPath} (${status ?? 'unknown'} → archived)\n`);
+    runArchive([filePath], config, { dryRun: true, out: process.stderr });
+    return;
+  }
+  process.stdout.write(body);
+  if (!body.endsWith('\n')) process.stdout.write('\n');
+  runArchive([filePath], config, { out: process.stderr });
+  process.stderr.write(`${green('✓ Consumed')}: ${repoPath}\n`);
+}
+function runPromptsArchive(argv, config, opts = {}) {
+  const input = argv.find(a => !a.startsWith('-'));
+  if (!input) die('Usage: dotmd prompts archive <file>');
+  const filePath = resolveDocPath(input, config);
+  if (!filePath) die(`File not found: ${input}`);
+  const raw = readFileSync(filePath, 'utf8');
+  const { frontmatter } = extractFrontmatter(raw);
+  const parsed = parseSimpleFrontmatter(frontmatter);
+  if (asString(parsed.type) !== 'prompt') {
+    die(`Not a prompt: ${toRepoPath(filePath, config.repoRoot)}`);
+  }
+  runArchive([filePath], config, opts);
+}
+async function runPromptsNew(argv, config, opts = {}) {
+  if (!argv[0] || argv[0].startsWith('-')) {
+    die('Usage: dotmd prompts new <slug> [body]\n       body: inline text | "-" (stdin) | "@path" (file) | --message "..."');
+  }
+  return runNew(['prompt', ...argv], config, opts);
+}