dotmd-cli 0.69.0 → 0.70.0

package/src/prompts.mjs

@@ -1,17 +1,20 @@
-import { readFileSync, statSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync } from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 import { extractFrontmatter, parseSimpleFrontmatter } from './frontmatter.mjs';
-import { asString, toRepoPath, die, resolveDocPath, isArchivedPath, currentSessionId } from './util.mjs';
+import { asString, toRepoPath, die, resolveDocPath, isArchivedPath } from './util.mjs';
 import { buildIndex, resolveDocArg } from './index.mjs';
 import { runQuery } from './query.mjs';
-import { runArchive, runStatus, updateFrontmatter } from './lifecycle.mjs';
-import { appendJournalEntry } from './journal.mjs';
+import { completePlanClaim, regenIndex, renderLifecycleMutation, runArchive, runStatus } from './lifecycle.mjs';
 import { runNew } from './new.mjs';
 import { green, dim } from './color.mjs';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
+import { authorizeManagedSource } from './managed-path.mjs';
+import {
+  authoritativeSessionId,
+  classifyPlanPickup,
+  preparePlanClaim,
+  readPlanOwnership,
+} from './pickup.mjs';
+import { actionablePromptStatuses, comparePromptDocs } from './status-metadata.mjs';
 
 // `resume` is an alias for `use` — agents reach for "resume" when continuing a
 // session; `use` reads as internal mechanics. Both names stay valid; the
@@ -130,10 +133,10 @@ function slugToPlanPath(s, config) {
 // Resolve a markdown body link relative to the prompt's location so e.g.
 // `../plans/foo.md` from docs/prompts/x.md → docs/plans/foo.md.
 function resolveBodyLink(link, promptRepoPath) {
-  const cleaned = link.replace(/#.*$/, '');
+  const cleaned = link.replace(/#.*$/, '').replaceAll('\\', '/');
   if (cleaned.startsWith('/')) return cleaned.replace(/^\/+/, '');
-  const promptDir = path.dirname(promptRepoPath);
-  return path.normalize(path.join(promptDir, cleaned));
+  const promptDir = path.posix.dirname(promptRepoPath.replaceAll('\\', '/'));
+  return path.posix.normalize(path.posix.join(promptDir, cleaned));
 }
 
 function renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived }) {
@@ -163,36 +166,27 @@ function renderPromptsVerbose(index, config, { hasStatusFlag, includeArchived })
 }
 
 export function pendingPromptsOldestFirst(config) {
-  const index = buildIndex(config);
+  const index = buildIndex(config, { fast: true, invokeHooks: false });
+  const actionable = actionablePromptStatuses(config);
   const prompts = index.docs.filter(d =>
     d.type === 'prompt'
-    && d.status === 'pending'
+    && actionable.has(d.status)
     && !isArchivedPath(d.path, config),
   );
 
   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;
-    });
+    .sort(comparePromptDocs)
+    .map(d => ({ doc: d, abs: resolveDocPath(d.path, config), created: d.created ?? '' }));
 }
 
-function runPromptsNext(argv, config, opts = {}) {
+async 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);
+  return consumePrompt(head.abs, config, opts);
 }
 
 // Resolve user input to a prompt path. Tries (in order): exact path,
@@ -209,7 +203,7 @@ export function resolvePromptInput(input, config, options = {}) {
     if (withExt) return withExt;
   }
 
-  const index = buildIndex(config);
+  const index = buildIndex(config, { fast: true, invokeHooks: false });
   const prompts = index.docs.filter(d => d.type === 'prompt');
   if (prompts.length === 0) {
     if (dieOnMiss) die(`No prompts in the index.`);
@@ -236,17 +230,18 @@ export function resolvePromptInput(input, config, options = {}) {
   return null;
 }
 
-function runPromptsUse(argv, config, opts = {}) {
+async function runPromptsUse(argv, config, opts = {}) {
   const input = argv.find(a => !a.startsWith('-'));
   if (!input) die('Usage: dotmd prompts use <file-or-slug>');
   const noIndex = argv.includes('--no-index') || opts.noIndex;
   const showFiles = argv.includes('--show-files') || opts.showFiles;
   const filePath = resolvePromptInput(input, config);
-  consumePrompt(filePath, config, { ...opts, noIndex, showFiles });
+  return consumePrompt(filePath, config, { ...opts, noIndex, showFiles });
 }
 
-export function consumePrompt(filePath, config, opts) {
+export async function consumePrompt(filePath, config, opts) {
   const { dryRun, noIndex, showFiles } = opts;
+  filePath = authorizeManagedSource(filePath, config, { kind: 'Prompt consumption source' }).path;
   const raw = readFileSync(filePath, 'utf8');
   const { frontmatter, body } = extractFrontmatter(raw);
   const parsed = parseSimpleFrontmatter(frontmatter);
@@ -261,6 +256,10 @@ export function consumePrompt(filePath, config, opts) {
     die(`Already consumed: ${repoPath}`);
   }
 
+  const planRef = asString(parsed.plan);
+  let linkedClaim = null;
+  if (planRef) linkedClaim = prepareLinkedPromptClaim(planRef, config);
+
   if (dryRun) {
     const prefix = dim('[dry-run]');
     process.stderr.write(`${prefix} Would emit body and archive: ${repoPath} (${status ?? 'unknown'} → archived)\n`);
@@ -279,57 +278,117 @@ export function consumePrompt(filePath, config, opts) {
   // hook crash, anything), the body must not have already gone to stdout —
   // otherwise `claude "$(dotmd prompts next)"` consumes the prompt without it
   // ever being archived, and the next session sees the same prompt as pending.
-  // Body is already in memory from extractFrontmatter, so the source file
-  // can move out from under us safely.
-  const archiveResult = runArchive([filePath], config, { noIndex, showFiles, out: process.stderr });
-
-  process.stdout.write(body);
-  if (!body.endsWith('\n')) process.stdout.write('\n');
+  const archiveResult = runArchive([filePath], config, {
+    noIndex,
+    showFiles,
+    out: process.stderr,
+    testHooks: opts.testHooks,
+    deferIndex: Boolean(linkedClaim),
+    additionalUpdates: linkedClaim?.prepared?.updates,
+    creations: linkedClaim?.prepared?.creations,
+  });
+  const consumedBody = archiveResult?.consumedBody ?? body;
 
   const consumedPath = archiveResult?.newRepoPath ?? repoPath;
+  // Consume output is at-most-once: archive/claim commits before stdout. A
+  // downstream failure cannot roll the transaction back or make it consumable
+  // again; the archived path remains available through `prompts show`.
+  await writeConsumedBody(consumedBody, consumedPath, opts.writeBody, linkedClaim?.repoPath);
+  let completion = { indexRegenerated: false, ownershipChanged: false, hook: 'none', pending: false };
+  if (linkedClaim) {
+    try {
+      completion = completePlanClaim(linkedClaim.repoPath, config, opts);
+      if (!noIndex && config.indexPath && !completion.indexRegenerated) {
+        regenIndex(config, { throwOnError: true, testHooks: opts.testHooks });
+        completion.indexRegenerated = true;
+      }
+    } catch (err) {
+      throw new Error(`Prompt consumed and body delivered; linked claim completion remains pending for ${linkedClaim.repoPath}: ${err.message}`);
+    }
+    process.stderr.write(`${green('→ Claimed')}: ${linkedClaim.repoPath} (in-session)\n`);
+  }
   process.stderr.write(`${green('✓ Consumed')}: ${consumedPath}\n`);
-
-  // Consume = claim: a baton-created resume prompt carries `plan: <path>`.
-  // Adopt that plan for THIS session so the next `dotmd baton` (with no arg)
-  // hands it off — closing the cross-session ownership loop that otherwise dies
-  // at the prompt boundary.
-  claimPromptPlan(asString(parsed.plan), config);
+  const ownershipRecordPath = linkedClaim?.prepared?.recordPath ?? (linkedClaim ? readPlanOwnership(linkedClaim.repoPath, config)?.recordPath : null);
+  const ownershipPath = ownershipRecordPath ? toRepoPath(ownershipRecordPath, config.repoRoot) : null;
+  const normalize = candidate => path.isAbsolute(candidate) ? toRepoPath(candidate, config.repoRoot) : candidate.split(path.sep).join('/');
+  const resultPaths = [
+    ...(linkedClaim?.planChanged ? [linkedClaim.repoPath] : []),
+    ...(archiveResult?.referencePaths ?? []),
+  ].filter(Boolean).map(normalize);
+  const ownershipResultPaths = resultPaths.filter(candidate => candidate.startsWith('.dotmd/ownership/'));
+  const repositoryFiles = [...new Set(resultPaths.filter(candidate => !candidate.startsWith('.dotmd/ownership/')))];
+  const sessionFiles = [...new Set([
+    repoPath,
+    consumedPath,
+    (linkedClaim?.prepared || completion.ownershipChanged) ? ownershipPath : null,
+    ...ownershipResultPaths,
+  ].filter(Boolean).map(normalize))];
+  return {
+    operation: 'consume',
+    status: { from: status ?? null, to: 'archived', changed: true },
+    repositoryFiles,
+    sessionFiles,
+    generatedFiles: config.indexPath && !noIndex && (completion.indexRegenerated || archiveResult?.indexRegenerated) ? [toRepoPath(config.indexPath, config.repoRoot)] : [],
+    deferredGeneratedFiles: config.indexPath && noIndex ? [toRepoPath(config.indexPath, config.repoRoot)] : [],
+    claim: linkedClaim ? { plan: linkedClaim.repoPath, changed: linkedClaim.planChanged, pendingCompletion: completion.pending, hook: completion.hook } : null,
+  };
 }
 
-// Flip the resume prompt's linked plan to in-session for this session and
-// record the ownership in the journal. The journal entry matters: baton's
-// `findOwnedPlan` reconstructs ownership from journaled `set in-session <plan>`
-// commands, and the outer `use <prompt>` argv can't tie a prompt ref to a plan
-// — so without this synthetic entry the claim would be invisible to baton (and,
-// with the misfire gate, would even make the next baton refuse).
-function claimPromptPlan(planRef, config) {
-  if (!planRef) return;
-  let planPath = null;
-  try { planPath = resolveDocPath(planRef, config) ?? resolveDocArg(planRef, config, { dieOnMiss: false }); }
-  catch { planPath = null; }
-  if (!planPath || !existsSync(planPath)) return; // link went stale (plan renamed/removed) — the resume body already printed, so stay quiet
-
-  let planFm;
-  try { planFm = parseSimpleFrontmatter(extractFrontmatter(readFileSync(planPath, 'utf8')).frontmatter); }
-  catch { return; }
-  const cur = asString(planFm.status);
-  // Only claim a startable plan. Already in-session → someone's on it (don't
-  // steal); archived/terminal → the link is stale. Either way, leave it be.
-  if (!cur || cur === 'in-session' || cur === 'archived') return;
+export async function writeConsumedBody(body, archivedPath, write = null, linkedPlan = null) {
+  const content = body.endsWith('\n') ? body : `${body}\n`;
+  try {
+    if (write) {
+      const accepted = await write(content);
+      if (accepted === false) throw Object.assign(new Error('writer reported unresolved backpressure'), { code: 'BACKPRESSURE' });
+    } else {
+      await new Promise((resolve, reject) => process.stdout.write(content, err => err ? reject(err) : resolve()));
+    }
+  }
+  catch (err) {
+    const completion = linkedPlan ? ` Then complete the linked claim with \`dotmd use ${linkedPlan}\`.` : '';
+    throw new Error(`Prompt was consumed but body output failed (${err.code ?? err.message}). It will not be emitted again; recover it with \`dotmd prompts show ${archivedPath}\`.${completion}`);
+  }
+}
 
+function prepareLinkedPromptClaim(planRef, config) {
+  let planPath = resolveDocPath(planRef, config) ?? resolveDocArg(planRef, config, { dieOnMiss: false });
+  if (!planPath || !existsSync(planPath)) die(`Linked plan is missing; prompt was not consumed: ${planRef}`);
+  planPath = authorizeManagedSource(planPath, config, { kind: 'Prompt linked plan source' }).path;
+  const raw = readFileSync(planPath, 'utf8');
+  let parsed;
+  try { parsed = parseSimpleFrontmatter(extractFrontmatter(raw).frontmatter); }
+  catch { die(`Linked plan is malformed; prompt was not consumed: ${planRef}`); }
   const repoPath = toRepoPath(planPath, config.repoRoot);
-  try { updateFrontmatter(planPath, { status: 'in-session' }); }
-  catch { return; }
-  try {
-    // `v` MUST be the real CLI version: the journal rotates when a new entry's
-    // version differs from the file's first entry, so a sentinel here would shove
-    // our just-written claim into the backup file where findOwnedPlan can't see it.
-    appendJournalEntry(config, {
-      ts: new Date().toISOString(), sid: currentSessionId(), pid: process.pid,
-      argv: ['set', 'in-session', repoPath], exit: 0, ms: 0, v: pkg.version,
-    });
-  } catch { /* journal is best-effort — the status flip already landed */ }
-  process.stderr.write(`${green('→ Claimed')}: ${repoPath} (in-session)\n`);
+  const sessionId = authoritativeSessionId();
+  const ownership = readPlanOwnership(repoPath, config);
+  const oldStatus = asString(parsed.status);
+  const disposition = classifyPlanPickup({
+    type: asString(parsed.type),
+    status: oldStatus,
+    validStatuses: config.typeStatuses?.get('plan') ?? config.validStatuses,
+    startableStatuses: config.lifecycle.startableStatuses,
+    terminalStatuses: config.lifecycle.terminalStatuses,
+    archiveStatuses: config.lifecycle.archiveStatuses,
+    physicallyArchived: isArchivedPath(repoPath, config),
+    ownership,
+    sessionId,
+    malformed: false,
+  });
+  if (!disposition.pickupable) die(`Linked plan cannot be claimed (${disposition.kind}); prompt was not consumed: ${repoPath}`);
+  if (disposition.kind === 'resume') return { planPath, repoPath, prepared: null, planChanged: false, disposition: disposition.kind };
+  const now = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+  const rendered = disposition.kind === 'start'
+    ? renderLifecycleMutation(raw, { status: 'in-session', updated: now }, `Started (${oldStatus} → in-session).`, { createSection: true })
+    : null;
+  const prepared = preparePlanClaim({ filePath: planPath, sourceContent: raw, renderedContent: rendered,
+    ownership, sessionId, now, config });
+  return {
+    planPath,
+    repoPath,
+    prepared,
+    planChanged: prepared.updates.some(item => path.resolve(item.path) === path.resolve(planPath)),
+    disposition: disposition.kind,
+  };
 }
 
 // Read-only peek: print the body WITHOUT consuming. The sanctioned triage path

package/src/query.mjs

@@ -85,15 +85,21 @@ export function runQuery(index, argv, config, opts = {}) {
   if (filters.body && !filters.keyword) {
     die('`--body` extends a keyword search into document bodies — pass `--keyword <term>` (or use `dotmd grep <term>`).');
   }
-  const docs = filterDocs(index.docs, filters, config);
+  const docs = filterDocs(index.docs, filters, config, opts.gitMetadataOptions);
+  const summaryPreviewSkipped = filters.summarize && config._execution?.suppressSideEffects;
 
   if (filters.json) {
-    if (filters.summarize) {
+    if (filters.summarize && !summaryPreviewSkipped) {
       for (let i = 0; i < docs.length && i < filters.summarizeLimit; i++) {
         docs[i].aiSummary = getDocSummary(docs[i], config);
       }
     }
-    process.stdout.write(`${JSON.stringify({ filters, count: docs.length, docs }, null, 2)}\n`);
+    process.stdout.write(`${JSON.stringify({
+      filters,
+      count: docs.length,
+      docs,
+      ...(summaryPreviewSkipped ? { summaryPreview: { status: 'skipped-preview', reason: 'side-effect-free preview' } } : {}),
+    }, null, 2)}\n`);
     return;
   }
 
@@ -279,7 +285,7 @@ export function parseQueryArgs(argv) {
   return filters;
 }
 
-export function filterDocs(docs, filters, config) {
+export function filterDocs(docs, filters, config, gitMetadataOptions) {
   let result = [...docs];
 
   if (filters.types?.length) result = result.filter(d => filters.types.includes(d.type));
@@ -320,14 +326,18 @@ export function filterDocs(docs, filters, config) {
   if (filters.updatedSince) result = result.filter(d => d.updated && d.updated >= filters.updatedSince);
 
   if (filters.git) {
-    const gitDates = getGitLastModifiedBatch(config.repoRoot);
+    const gitMetadata = getGitLastModifiedBatch(config.repoRoot, result.map(doc => doc.path), gitMetadataOptions);
+    const gitDates = gitMetadata.dates;
     for (const doc of result) {
       const gitDate = gitDates.get(doc.path) ?? null;
       if (gitDate) {
         doc.daysSinceUpdate = computeDaysSinceUpdate(gitDate);
-        doc.isStale = computeIsStale(doc.status, gitDate, config);
+        doc.isStale = computeIsStale(doc.status, gitDate, config, doc.type);
       }
     }
+    if (!gitMetadata.complete) {
+      warn(`Git metadata is incomplete (${gitMetadata.reason}); query results use known dates only.`);
+    }
   }
 
   if (filters.stale) result = result.filter(d => d.isStale);
@@ -380,18 +390,16 @@ function scanBodyForKeyword(doc, needle, config) {
     warn(`Could not read ${doc.path}: ${err.message}`);
     return [];
   }
-  const { body } = extractFrontmatter(raw);
+  const { body, bodyLineOffset } = extractFrontmatter(raw);
   if (!body || !body.toLowerCase().includes(needle)) return [];
 
-  // body is a suffix of raw — the slice before it is the frontmatter block.
-  const bodyStartLine = raw.slice(0, raw.length - body.length).split('\n').length;
   const lines = body.split('\n');
   const matches = [];
   for (let i = 0; i < lines.length && matches.length < MAX_BODY_MATCHES; i++) {
     const text = lines[i].trim();
     const at = text.toLowerCase().indexOf(needle);
     if (at === -1) continue;
-    matches.push({ line: bodyStartLine + i, text: excerptAround(text, at, needle.length) });
+    matches.push({ line: bodyLineOffset + i + 1, text: excerptAround(text, at, needle.length) });
   }
   return matches;
 }
@@ -411,6 +419,7 @@ function getDocSummary(doc, config) {
     const { body } = extractFrontmatter(raw);
     if (!body?.trim()) return null;
     const meta = { title: doc.title, status: doc.status, path: doc.path };
+    if (config._execution?.suppressSideEffects) return null;
     return config.hooks.summarizeDoc
       ? config.hooks.summarizeDoc(body, meta)
       : summarizeDocBody(body, meta);
@@ -442,6 +451,9 @@ function renderQueryResults(docs, filters, config) {
   if (filters.hasNextStep) process.stdout.write('- has-next-step: true\n');
   if (filters.hasBlockers) process.stdout.write('- has-blockers: true\n');
   if (filters.checklistOpen) process.stdout.write('- checklist-open: true\n');
+  if (filters.summarize && config._execution?.suppressSideEffects) {
+    process.stdout.write('- summaries: skipped in side-effect-free preview\n');
+  }
   process.stdout.write('\n');
 
   if (docs.length === 0) { process.stdout.write('No matching docs.\n'); return; }