dotmd-cli 0.69.0 → 0.70.1

package/src/new.mjs

@@ -1,4 +1,4 @@
-import { existsSync, readFileSync, writeFileSync, mkdirSync, fstatSync } from 'node:fs';
+import { existsSync, readFileSync, mkdirSync, fstatSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { toRepoPath, die, warn, nowIso, emitFilesFooter } from './util.mjs';
@@ -6,6 +6,8 @@ import { green, dim, bold } from './color.mjs';
 import { isInteractive, promptText } from './prompt.mjs';
 import { regenIndex } from './lifecycle.mjs';
 import { extractFrontmatter, parseSimpleFrontmatter, normalizeEol } from './frontmatter.mjs';
+import { authorizeManagedDestination } from './managed-path.mjs';
+import { createFileExclusive, mutateFileSet, MutationConflictError } from './atomic-mutation.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
@@ -281,6 +283,18 @@ export function readBodyInput(source) {
   return source;
 }
 
+export function readPipedBodyInput() {
+  try {
+    const stat = fstatSync(0);
+    const isWindowsPipe = process.platform === 'win32' && !process.stdin.isTTY;
+    if (stat.isFIFO() || stat.isFile() || stat.isSocket() || isWindowsPipe) {
+      const piped = readFileSync(0, 'utf8');
+      return piped.length > 0 ? piped : null;
+    }
+  } catch { /* stdin not introspectable */ }
+  return null;
+}
+
 // Slug/title helpers shared by name resolution and runlist child generation.
 export function slugify(s) {
   return s.toLowerCase().replace(/[\s_]+/g, '-').replace(/[^a-z0-9-]/g, '').replace(/-+/g, '-').replace(/^-|-$/g, '');
@@ -289,6 +303,48 @@ export function titleize(s) {
   return s.replace(/[-_]/g, ' ').replace(/\b\w/g, c => c.toUpperCase());
 }
 
+export function preparePromptDocument(name, bodyInput, config, { plan = null, dryRun = false } = {}) {
+  const template = resolveTemplate('prompt', config);
+  const typeStatuses = config.typeStatuses?.get('prompt');
+  const status = template.defaultStatus && (!typeStatuses || typeStatuses.has(template.defaultStatus))
+    ? template.defaultStatus
+    : ([...(typeStatuses ?? [])][0] ?? 'pending');
+  if (!bodyInput?.trim()) die('`prompt` template requires a body.');
+  const slug = slugify(path.basename(name, '.md'));
+  const title = titleize(path.basename(name, '.md'));
+  let targetRoot = config.docsRoot;
+  let routed = false;
+  if (template.targetRoot) {
+    const match = (config.docsRoots || [config.docsRoot]).find(root => root.endsWith(template.targetRoot) || path.basename(root) === template.targetRoot);
+    if (match) { targetRoot = match; routed = true; }
+  }
+  const baseDir = template.dir && !routed ? path.join(targetRoot, template.dir) : targetRoot;
+  const filePath = path.join(baseDir, `${slug}.md`);
+  authorizeManagedDestination(filePath, config, { kind: 'Baton prompt destination' });
+  if (dryRun) return { slug, filePath, repoPath: toRepoPath(filePath, config.repoRoot), content: null };
+
+  const today = nowIso();
+  const split = splitBodyFrontmatter(bodyInput);
+  const body = split.frontmatter ? split.body : bodyInput;
+  const ctx = { status, title, today, bodyInput: body };
+  let content;
+  if (typeof template === 'function') {
+    content = template(name, ctx);
+    if (plan) {
+      const end = content.indexOf('\n---\n', 4);
+      if (!content.startsWith('---\n') || end === -1) throw new Error('Custom prompt template must return frontmatter for baton plan binding.');
+      const fm = mergeBodyFrontmatter(content.slice(4, end), { plan }, 'prompt');
+      content = `---\n${fm}${content.slice(end)}`;
+    }
+  } else {
+    let fm = template.frontmatter(status, today, ctx);
+    if (split.frontmatter) fm = mergeBodyFrontmatter(fm, split.frontmatter, 'prompt');
+    if (plan) fm = mergeBodyFrontmatter(fm, { plan }, 'prompt');
+    content = `---\n${fm}\n---\n${template.body(title, ctx)}`;
+  }
+  return { slug, filePath, repoPath: toRepoPath(filePath, config.repoRoot), content };
+}
+
 // Resolve one `--runlist` token to a scaffolded child plan: a bare slug becomes
 // `<hub>-NN-<slug>.md` (the documented runlist naming convention). `pos` is the
 // 1-based position used for the zero-padded NN prefix. Tokens must be bare slugs
@@ -642,16 +698,11 @@ export async function runNew(argv, config, opts = {}) {
     // delivers stdin as an AF_UNIX socket). Probe this even for templates that
     // don't accept bodies so the fail-fast guard below can reject accidental
     // heredoc/input instead of silently scaffolding without it.
-    try {
-      const stat = fstatSync(0);
-      if (stat.isFIFO() || stat.isFile() || stat.isSocket()) {
-        const piped = readFileSync(0, 'utf8');
-        if (piped.length > 0) {
-          bodyInput = piped;
-          bodyInputSource = 'piped stdin';
-        }
-      }
-    } catch { /* stdin not introspectable — skip auto-consume */ }
+    const piped = readPipedBodyInput();
+    if (piped !== null) {
+      bodyInput = piped;
+      bodyInputSource = 'piped stdin';
+    }
   }
 
   // If the body input has a leading `---…---` frontmatter block, lift its keys
@@ -757,6 +808,7 @@ export async function runNew(argv, config, opts = {}) {
   const baseDir = nameDir ? path.resolve(config.repoRoot, nameDir) : targetRoot;
   const filePath = path.join(baseDir, slug + '.md');
   const repoPath = toRepoPath(filePath, config.repoRoot);
+  const destinationAuthorization = authorizeManagedDestination(filePath, config, { kind: 'New document destination' });
 
   if (existsSync(filePath)) {
     die(`File already exists: ${repoPath}`);
@@ -766,40 +818,13 @@ export async function runNew(argv, config, opts = {}) {
 
   // Resolve runlist children from the hub slug (e.g. `extract` → hub-01-extract.md).
   const runlistChildren = runlistTokens.map((tok, i) => planChildFromToken(slug, tok, i + 1));
-  const childStatus = effective.has('planned') ? 'planned' : status;
-
-  // Generate content
-  let content;
-  const validSurfaces = config.raw?.taxonomy?.surfaces ?? (config.validSurfaces ? [...config.validSurfaces] : null);
-  const validModules = config.raw?.taxonomy?.modules ?? (config.validModules ? [...config.validModules] : null);
-  const tmplCtx = { status, title: docTitle, today, bodyInput, validSurfaces, validModules };
-  if (typeof template === 'function') {
-    content = template(name, tmplCtx);
-  } else {
-    let fm = template.frontmatter(status, today, tmplCtx);
-    if (bodyFrontmatter) fm = mergeBodyFrontmatter(fm, bodyFrontmatter, typeName);
-    // Inject the hub-shape frontmatter (runlist array / coordination marker)
-    // on top of the standard plan scaffold, then swap in a purpose-built body.
-    if (isRunlistHub) fm = mergeBodyFrontmatter(fm, { runlist: runlistChildren.map(c => c.file) }, typeName);
-    if (isCoordinationHub) fm = mergeBodyFrontmatter(fm, { execution_mode: 'coordination' }, typeName);
-    if (isRoadmap) fm = mergeBodyFrontmatter(fm, { execution_mode: 'roadmap' }, typeName);
-    let body;
-    // A full authored body (own `## Section` headings) wins over every variant
-    // skeleton too — otherwise the whole document gets nested in the builder's
-    // single slot and the skeleton is appended below it (duplicate Scope /
-    // Ranked queue / Version History). The default plan body applies the same
-    // shortcut inside template.body, so only the variant branches need it here.
-    const variantBody = isRunlistHub || isCoordinationHub || isRoadmap || isLite || isAudit;
-    const authored = variantBody ? fullBodyShortcut(docTitle, bodyInput) : null;
-    if (authored !== null) body = authored;
-    else if (isRunlistHub) body = runlistHubBody(docTitle, slug, runlistChildren, bodyInput, today);
-    else if (isCoordinationHub) body = coordinationHubBody(docTitle, bodyInput, today);
-    else if (isRoadmap) body = roadmapHubBody(docTitle, slug, bodyInput, today);
-    else if (isLite) body = litePlanBody(docTitle, bodyInput, today);
-    else if (isAudit) body = auditPlanBody(docTitle, bodyInput, today);
-    else body = template.body(docTitle, tmplCtx);
-    content = `---\n${fm}\n---\n${body}`;
+  for (const child of runlistChildren) {
+    authorizeManagedDestination(path.join(baseDir, child.file), config, {
+      root: destinationAuthorization.root,
+      kind: 'Runlist child destination',
+    });
   }
+  const childStatus = effective.has('planned') ? 'planned' : status;
 
   // When the project has >1 root and `--root` was omitted, surface the choice
   // so agents can see that an alternative root was available. Cheap visibility
@@ -820,34 +845,81 @@ export async function runNew(argv, config, opts = {}) {
     : isLite ? ' (lite plan)'
     : isAudit ? ' (audit plan)'
     : '';
+  const isCustomTemplate = Object.prototype.hasOwnProperty.call(config.raw?.templates ?? {}, typeName);
 
   if (dryRun) {
-    process.stdout.write(`${dim('[dry-run]')} Would create: ${repoPath}\n`);
+    if (isCustomTemplate) {
+      process.stdout.write(`${dim('[dry-run]')} Target: ${repoPath}\n`);
+      process.stdout.write(`${dim('[dry-run]')} Custom template rendering skipped; preview cannot confirm creation will succeed.\n`);
+    } else {
+      process.stdout.write(`${dim('[dry-run]')} Would create: ${repoPath}\n`);
+    }
     process.stdout.write(`${dim('[dry-run]')} Type: ${typeName}${hubKind}\n`);
     for (const c of runlistChildren) {
-      process.stdout.write(`${dim('[dry-run]')} Would create child: ${toRepoPath(path.join(baseDir, c.file), config.repoRoot)}\n`);
+      const childPath = path.join(baseDir, c.file);
+      const action = existsSync(childPath) ? 'Would leave existing child unchanged' : 'Would create child';
+      process.stdout.write(`${dim('[dry-run]')} ${action}: ${toRepoPath(childPath, config.repoRoot)}\n`);
     }
     if (rootHint) process.stdout.write(`${dim('[dry-run]')} ${rootHint}`);
     return;
   }
 
+  // Generate content only for a real create. Custom template functions are
+  // user code and may have side effects, so previews stop before invoking them.
+  let content;
+  const validSurfaces = config.raw?.taxonomy?.surfaces ?? (config.validSurfaces ? [...config.validSurfaces] : null);
+  const validModules = config.raw?.taxonomy?.modules ?? (config.validModules ? [...config.validModules] : null);
+  const tmplCtx = { status, title: docTitle, today, bodyInput, validSurfaces, validModules };
+  if (typeof template === 'function') {
+    content = template(name, tmplCtx);
+  } else {
+    let fm = template.frontmatter(status, today, tmplCtx);
+    if (bodyFrontmatter) fm = mergeBodyFrontmatter(fm, bodyFrontmatter, typeName);
+    if (isRunlistHub) fm = mergeBodyFrontmatter(fm, { runlist: runlistChildren.map(c => c.file) }, typeName);
+    if (isCoordinationHub) fm = mergeBodyFrontmatter(fm, { execution_mode: 'coordination' }, typeName);
+    if (isRoadmap) fm = mergeBodyFrontmatter(fm, { execution_mode: 'roadmap' }, typeName);
+    let body;
+    const variantBody = isRunlistHub || isCoordinationHub || isRoadmap || isLite || isAudit;
+    const authored = variantBody ? fullBodyShortcut(docTitle, bodyInput) : null;
+    if (authored !== null) body = authored;
+    else if (isRunlistHub) body = runlistHubBody(docTitle, slug, runlistChildren, bodyInput, today);
+    else if (isCoordinationHub) body = coordinationHubBody(docTitle, bodyInput, today);
+    else if (isRoadmap) body = roadmapHubBody(docTitle, slug, bodyInput, today);
+    else if (isLite) body = litePlanBody(docTitle, bodyInput, today);
+    else if (isAudit) body = auditPlanBody(docTitle, bodyInput, today);
+    else body = template.body(docTitle, tmplCtx);
+    content = `---\n${fm}\n---\n${body}`;
+  }
+
   // Ensure parent dir exists (templates with `dir:` may target a new subdirectory)
   mkdirSync(path.dirname(filePath), { recursive: true });
 
-  writeFileSync(filePath, content, 'utf8');
-  process.stdout.write(`${green('Created')}: ${repoPath} ${dim(`(${typeName}${hubKind})`)}\n`);
-  if (rootHint) process.stdout.write(dim(rootHint));
-
-  // Scaffold runlist child stubs. An existing child file is never clobbered.
   const childPaths = [];
+  const creations = [{ path: filePath, content }];
   for (const c of runlistChildren) {
     const childPath = path.join(baseDir, c.file);
     if (existsSync(childPath)) {
       warn(`Runlist child already exists, left as-is: ${toRepoPath(childPath, config.repoRoot)}`);
       continue;
     }
-    writeFileSync(childPath, runlistChildContent(c.title, slug, docTitle, childStatus, today), 'utf8');
+    creations.push({ path: childPath, content: runlistChildContent(c.title, slug, docTitle, childStatus, today) });
     childPaths.push(childPath);
+  }
+  try {
+    if (runlistChildren.length > 0) mutateFileSet({ creations }, { repoRoot: config.repoRoot, testHooks: opts.testHooks });
+    else createFileExclusive(filePath, content, { repoRoot: config.repoRoot, testHooks: opts.testHooks });
+  } catch (err) {
+    if (err instanceof MutationConflictError) die(`Could not create runlist atomically because a destination already exists: ${err.message}`);
+    throw err;
+  }
+  process.stdout.write(`${green('Created')}: ${repoPath} ${dim(`(${typeName}${hubKind})`)}\n`);
+  if (rootHint) process.stdout.write(dim(rootHint));
+
+  // Existing children discovered before the transaction are consistently left
+  // unchanged; absent children and the hub publish or roll back together.
+  for (const c of runlistChildren) {
+    const childPath = path.join(baseDir, c.file);
+    if (!childPaths.includes(childPath)) continue;
     process.stdout.write(`${green('Created')}: ${toRepoPath(childPath, config.repoRoot)} ${dim(`(plan · runlist child, ${childStatus})`)}\n`);
   }
 
@@ -873,15 +945,24 @@ export async function runNew(argv, config, opts = {}) {
     }
   } catch { /* git absent / not a repo — skip the note */ }
 
-  regenIndex(config);
+  const indexRegenerated = !opts.deferIndex ? regenIndex(config) : false;
 
   if (showFiles) {
     const touched = [filePath, ...childPaths];
-    if (config.indexPath) touched.push(config.indexPath);
+    if (config.indexPath && !opts.deferIndex) touched.push(config.indexPath);
     emitFilesFooter(touched, config);
   }
 
   try { config.hooks.onNew?.({ path: repoPath, status, title: docTitle, type: typeName }); } catch (err) { warn(`Hook 'onNew' threw: ${err.message}`); }
+  const sessionLocal = typeName === 'prompt';
+  return {
+    operation: 'new',
+    repositoryFiles: sessionLocal ? [] : [repoPath, ...childPaths.map(item => toRepoPath(item, config.repoRoot))],
+    sessionFiles: sessionLocal ? [repoPath] : [],
+    generatedFiles: config.indexPath && indexRegenerated ? [toRepoPath(config.indexPath, config.repoRoot)] : [],
+    deferredGeneratedFiles: config.indexPath && opts.deferIndex ? [toRepoPath(config.indexPath, config.repoRoot)] : [],
+    path: repoPath,
+  };
 }
 
 function resolveTemplate(name, config) {

package/src/output-identity.mjs

@@ -0,0 +1,106 @@
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+
+export const HTML_FALLBACK_DIR = '__dotmd';
+
+function normalizeRelative(value, kind) {
+  if (typeof value !== 'string' || value.includes('\0')) {
+    throw new Error(`${kind} must be a string without NUL bytes`);
+  }
+  const normalized = path.posix.normalize(value || '.');
+  if (path.posix.isAbsolute(normalized)) throw new Error(`${kind} must be relative: ${value}`);
+  return normalized;
+}
+
+function isTraversal(value) {
+  return value === '..' || value.startsWith('../');
+}
+
+function pathsConflict(a, b) {
+  const left = a.toLowerCase();
+  const right = b.toLowerCase();
+  return left === right || left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+
+function validateHtmlPath(value) {
+  const normalized = normalizeRelative(value, 'HTML output path');
+  if (normalized === '.' || isTraversal(normalized) || normalized !== value) {
+    throw new Error(`Unsafe HTML output path: ${value}`);
+  }
+  return normalized;
+}
+
+export function outputPathToUrl(value) {
+  return validateHtmlPath(value).split('/').map(encodeURIComponent).join('/');
+}
+
+export function allocateOutputIdentities(docs) {
+  const entries = [];
+  const logicalIds = new Set();
+
+  for (const doc of docs) {
+    const logicalId = normalizeRelative(doc.path, 'Document path');
+    if (logicalIds.has(logicalId)) throw new Error(`Duplicate document path: ${logicalId}`);
+    logicalIds.add(logicalId);
+
+    const root = normalizeRelative(doc.root || '.', 'Document root');
+    const relativeSource = path.posix.relative(root, logicalId);
+    if (!relativeSource || isTraversal(relativeSource) || path.posix.isAbsolute(relativeSource)) {
+      throw new Error(`Document path is not owned by its root: ${logicalId} (root: ${root})`);
+    }
+    if (!relativeSource.toLowerCase().endsWith('.md')) {
+      throw new Error(`Document path must end in .md: ${logicalId}`);
+    }
+
+    const preferred = validateHtmlPath(relativeSource.slice(0, -3) + '.html');
+    entries.push({
+      logicalId,
+      label: path.posix.basename(logicalId, path.posix.extname(logicalId)),
+      preferred,
+      conflict: preferred.toLowerCase() === 'index.html'
+        || preferred.toLowerCase().startsWith('index.html/')
+        || preferred.toLowerCase().startsWith(`${HTML_FALLBACK_DIR.toLowerCase()}/`),
+    });
+  }
+
+  entries.sort((a, b) => a.logicalId.localeCompare(b.logicalId));
+  for (let i = 0; i < entries.length; i++) {
+    for (let j = i + 1; j < entries.length; j++) {
+      if (!pathsConflict(entries[i].preferred, entries[j].preferred)) continue;
+      entries[i].conflict = true;
+      entries[j].conflict = true;
+    }
+  }
+
+  const digestOwners = new Map();
+  for (const entry of entries) {
+    if (!entry.conflict) {
+      entry.htmlPath = entry.preferred;
+      continue;
+    }
+    const digest = createHash('sha256').update(entry.logicalId).digest('hex');
+    const owner = digestOwners.get(digest);
+    if (owner && owner !== entry.logicalId) {
+      throw new Error(`Output identity hash collision: ${owner} and ${entry.logicalId}`);
+    }
+    digestOwners.set(digest, entry.logicalId);
+    entry.htmlPath = `${HTML_FALLBACK_DIR}/${digest}.html`;
+  }
+
+  const finalEntries = [...entries].sort((a, b) => a.htmlPath.localeCompare(b.htmlPath));
+  for (let i = 0; i < finalEntries.length; i++) {
+    validateHtmlPath(finalEntries[i].htmlPath);
+    for (let j = i + 1; j < finalEntries.length; j++) {
+      if (pathsConflict(finalEntries[i].htmlPath, finalEntries[j].htmlPath)) {
+        throw new Error(`Conflicting HTML output paths: ${finalEntries[i].htmlPath} and ${finalEntries[j].htmlPath}`);
+      }
+    }
+  }
+
+  return new Map(entries.map(entry => [entry.logicalId, {
+    logicalId: entry.logicalId,
+    label: entry.label,
+    htmlPath: entry.htmlPath,
+    htmlUrl: outputPathToUrl(entry.htmlPath),
+  }]));
+}

package/src/pickup-card.mjs

@@ -70,7 +70,7 @@ function readRelatedSummary(rawList, config, docDir) {
 
 // Build the structured card object. Pure: no IO beyond what's passed in.
 export function buildCard(filePath, raw, config) {
-  const { frontmatter: fmRaw, body } = extractFrontmatter(raw);
+  const { frontmatter: fmRaw, body, bodyLineOffset } = extractFrontmatter(raw);
   const fm = parseSimpleFrontmatter(fmRaw);
   const sections = walkSections(body);
 
@@ -117,13 +117,23 @@ export function buildCard(filePath, raw, config) {
 
   // Phases summary + active phase (pointer only, no body)
   const phaseSummary = summarizePhases(sections);
+  const toFileLine = line => line + bodyLineOffset;
+  const phaseSummaryForCard = {
+    ...phaseSummary,
+    phases: phaseSummary.phases.map(phase => ({
+      ...phase,
+      lineStart: toFileLine(phase.lineStart),
+      lineEnd: toFileLine(phase.lineEnd),
+      bodyLineStart: toFileLine(phase.bodyLineStart),
+    })),
+  };
   const activePhase = findActivePhase(sections);
   let activePhasePointer = null;
   if (activePhase) {
     activePhasePointer = {
       heading: activePhase.heading,
-      lineStart: activePhase.lineStart,
-      lineEnd: activePhase.lineEnd,
+      lineStart: toFileLine(activePhase.lineStart),
+      lineEnd: toFileLine(activePhase.lineEnd),
       marker: detectMarker(activePhase.heading),
     };
   }
@@ -136,8 +146,8 @@ export function buildCard(filePath, raw, config) {
     if (lastH2) {
       fallbackPointer = {
         heading: lastH2.heading,
-        lineStart: lastH2.lineStart,
-        lineEnd: lastH2.lineEnd,
+        lineStart: toFileLine(lastH2.lineStart),
+        lineEnd: toFileLine(lastH2.lineEnd),
       };
     }
   }
@@ -148,8 +158,8 @@ export function buildCard(filePath, raw, config) {
   if (oqSection && oqSection.body.trim()) {
     openQuestions = {
       heading: oqSection.heading,
-      lineStart: oqSection.lineStart,
-      lineEnd: oqSection.lineEnd,
+      lineStart: toFileLine(oqSection.lineStart),
+      lineEnd: toFileLine(oqSection.lineEnd),
       count: countBullets(oqSection.body),
     };
   }
@@ -165,11 +175,13 @@ export function buildCard(filePath, raw, config) {
   // Outline = all H2 headings with line ranges; phase summary inline if Phases present
   const outline = sections.filter(s => s.level === 2).map(s => {
     const isPhases = /^phases?$/i.test(s.heading.replace(/[^\w\s]+$/, '').trim());
-    let suffix = `lines ${s.lineStart}-${s.lineEnd}`;
+    const lineStart = toFileLine(s.lineStart);
+    const lineEnd = toFileLine(s.lineEnd);
+    let suffix = `lines ${lineStart}-${lineEnd}`;
     if (isPhases && phaseSummary.total > 0) {
       suffix = `(${phaseSummary.total}: ${statusSummary(phaseSummary.counts)})  ${suffix}`;
     }
-    return { heading: s.heading, lineStart: s.lineStart, lineEnd: s.lineEnd, suffix };
+    return { heading: s.heading, lineStart, lineEnd, suffix };
   });
 
   return {
@@ -181,13 +193,15 @@ export function buildCard(filePath, raw, config) {
     currentState,
     nextStep,
     related,
-    phases: phaseSummary,
+    phases: phaseSummaryForCard,
     activePhase: activePhasePointer,
     fallbackContent: fallbackPointer,
     openQuestions,
     lastVersion,
     outline,
     bodyBytes: body.length,
+    bodyLineOffset,
+    coordinateSpace: 'file',
   };
 }