dotmd-cli 0.70.2 → 0.70.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.70.2",
+  "version": "0.70.4",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, lifecycle, and AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/atomic-mutation.mjs

@@ -23,10 +23,15 @@ import os from 'node:os';
 import path from 'node:path';
 import { captureGitIndexGeneration, reclaimPreparedGitIndex, restoreGitIndexCas, sameGitIndexGeneration, stageMovePathsCas } from './git.mjs';
 import { authorizeManagedDestination, authorizeManagedSource, authorizeRepoGeneratedPath } from './managed-path.mjs';
+import { commitRename } from './durable-rename.mjs';
 
 const sleepBuffer = new Int32Array(new SharedArrayBuffer(4));
 let tempSequence = 0;
 
+// How long a peer waits to acquire a path lock before MutationLockError. Any
+// retry budget spent while the lock is held has to fit well inside this.
+export const MUTATION_LOCK_TIMEOUT_MS = 2000;
+
 export function processStartIdentity(pid) {
   try {
     const stat = readFileSync(`/proc/${pid}/stat`, 'utf8');
@@ -111,7 +116,7 @@ function transactionRoot(repoRoot, options = {}) {
 function durableJson(filePath, value, options = {}) {
   const content = JSON.stringify(value, null, 2) + '\n';
   const temp = writeCompleteTemp(filePath, content, 0o600);
-  renameSync(temp.path, filePath);
+  commitRename(temp.path, filePath, options.testHooks);
   fsyncDirectory(path.dirname(filePath), options, 'transaction-manifest');
 }
 
@@ -841,7 +846,7 @@ function reclaimLock(lockPath, lockRoot) {
 }
 
 export function withPathLocks(filePaths, options, callback) {
-  const { repoRoot, timeoutMs = 2000, retryMs = 20 } = options;
+  const { repoRoot, timeoutMs = MUTATION_LOCK_TIMEOUT_MS, retryMs = 20 } = options;
   if (!repoRoot) throw new Error('withPathLocks requires repoRoot.');
   const canonicals = [...new Set(filePaths.map(canonicalPath))].sort();
   const lockRoot = safeGeneratedPath(path.join(path.resolve(repoRoot), '.dotmd', 'locks'), repoRoot, options, 'Lock root');
@@ -1036,7 +1041,7 @@ export function replaceSnapshot(snapshot, newContent, options = {}) {
     try {
       options.testHooks?.beforeReplacePublish?.({ snapshot, tempPath: prepared.path });
       assertSnapshotCurrent(snapshot);
-      renameSync(prepared.path, snapshot.path);
+      commitRename(prepared.path, snapshot.path, options.testHooks);
       committed = committedGeneration(prepared, snapshot.path);
       options.testHooks?.afterPublicationBeforePathOpen?.('replace', snapshot.path);
       try { fsyncDirectory(path.dirname(snapshot.path), options, 'replace-publish'); }
@@ -1097,7 +1102,7 @@ export function createFileExclusive(filePath, content, options) {
           options.testHooks?.afterReservationAcquired?.(filePath);
           options.testHooks?.afterCreateReservation?.(filePath);
           assertSnapshotCurrent(reservation);
-          renameSync(prepared.path, filePath);
+          commitRename(prepared.path, filePath, options.testHooks);
           tempPublished = true;
           committed = committedGeneration(prepared, filePath);
           options.testHooks?.afterPublicationBeforePathOpen?.('create-rename', filePath);
@@ -1210,7 +1215,7 @@ export function moveFileAtomic(sourcePath, targetPath, render, options) {
       // step that can permit an injected or external source edit.
       assertSnapshotCurrent(source);
       for (const item of preparedUpdates) assertSnapshotCurrent(item.snapshot);
-      renameSync(sourcePath, backup);
+      commitRename(sourcePath, backup, testHooks);
       moved = true;
       backupSnapshot = { ...source, path: backup, identityKind: 'inode-content' };
       fsyncDirectory(path.dirname(sourcePath));
@@ -1218,7 +1223,7 @@ export function moveFileAtomic(sourcePath, targetPath, render, options) {
 
       testHooks?.afterSourceMove?.({ backup, sourcePath, targetPath });
       assertSnapshotCurrent(reservation);
-      renameSync(stagedPath, targetPath);
+      commitRename(stagedPath, targetPath, testHooks);
       published = true;
       reserved = false;
       publishedSnapshot = committedGeneration(prepared, targetPath);

package/src/config-edit.mjs

@@ -7,7 +7,7 @@
 //   2. fs.writeFileSync(<path>.tmp, new)
 //   3. import the tmp via file:// + cache-bust query — must parse
 //   4. resolveConfig(tmp) — must not surface new warnings
-//   5. fs.renameSync(tmp, real) only on full success
+//   5. commitRename(tmp, real) only on full success
 //   6. on any failure: unlink tmp, surface error, real file untouched
 //
 // Pulling in @babel/parser would force a heavy dep on a project with two
@@ -15,9 +15,10 @@
 // `templates` section is 264 lines of arrow functions with multi-line
 // template literals). Line surgery is the conservative choice.
 
-import { existsSync, readFileSync, writeFileSync, unlinkSync, renameSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'node:fs';
 import { pathToFileURL } from 'node:url';
 import { resolveConfig } from './config.mjs';
+import { commitRename } from './durable-rename.mjs';
 
 const STATUS_NAME_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
 const RESERVED_NAMES = new Set([
@@ -595,7 +596,9 @@ export async function writeConfigAtomic(configPath, newContent, cwd) {
       throw new ConfigEditError(`Generated config surfaces new warnings:\n  - ${novel.join('\n  - ')}`);
     }
 
-    renameSync(tmpPath, configPath);
+    // The live config is very likely open in the user's editor; on Windows that
+    // makes the rename fail transiently, so publish through the retrying helper.
+    commitRename(tmpPath, configPath);
   } catch (err) {
     try { unlinkSync(tmpPath); } catch { /* ignore */ }
     throw err;

package/src/durable-rename.mjs

@@ -0,0 +1,55 @@
+// Retrying rename for publishing a prepared temp over a live path.
+//
+// Lives in its own leaf module rather than in atomic-mutation.mjs because
+// atomic-mutation.mjs already imports git.mjs, and git.mjs needs this helper for
+// its .git/index publish — exporting it from atomic-mutation.mjs would close an
+// import cycle.
+import { renameSync } from 'node:fs';
+
+const sleepBuffer = new Int32Array(new SharedArrayBuffer(4));
+
+const RENAME_RETRY_CODES = ['EPERM', 'EBUSY', 'EACCES'];
+const RENAME_RETRY_ATTEMPTS = 10;
+const RENAME_RETRY_BACKOFF_MS = 10;
+
+// Total the backoff can sleep across a fully exhausted retry — the sum of
+// RENAME_RETRY_BACKOFF_MS × (1 … attempts-1). Exported so the budget can be
+// checked against MUTATION_LOCK_TIMEOUT_MS deterministically, rather than by
+// timing a run on a shared CI runner.
+export const RENAME_RETRY_SLEEP_BUDGET_MS =
+  (RENAME_RETRY_BACKOFF_MS * (RENAME_RETRY_ATTEMPTS - 1) * RENAME_RETRY_ATTEMPTS) / 2;
+
+// Windows refuses to rename onto — or away from — a path another process holds
+// open, surfacing EPERM/EBUSY/EACCES. That holder is by construction a
+// non-cooperating one (editor, AV, Search Indexer, `git`): dotmd's path lock is
+// advisory and only excludes other dotmd processes, so a retry here is never
+// waiting on a peer we would have serialized against anyway. POSIX never fails a
+// rename this way, so retrying there would mask a genuinely different fault.
+//
+// The budget is bounded by withPathLocks' timeoutMs (2000ms default): these
+// renames run while the lock is held, so a longer budget would trade a rare
+// transient EPERM for common peer MutationLockErrors. 10 attempts with a 10ms
+// linear backoff is ~450ms of sleep — comfortable headroom under 2s. Do not
+// raise it past ~1s without also raising timeoutMs.
+export function commitRename(from, to, testHooks) {
+  // Single seam for the platform check so the retry is reachable in tests on the
+  // POSIX machines that actually run them.
+  const windowsRenameSemantics = testHooks?.forceWindowsRenameSemantics ?? process.platform === 'win32';
+  for (let attempt = 0; ; attempt++) {
+    try {
+      const injected = testHooks?.forceRenameError?.(attempt);
+      if (injected) {
+        const error = new Error(`injected rename ${injected}`);
+        error.code = injected;
+        throw error;
+      }
+      renameSync(from, to);
+      return;
+    } catch (err) {
+      if (!windowsRenameSemantics) throw err;
+      if (!RENAME_RETRY_CODES.includes(err?.code)) throw err;
+      if (attempt >= RENAME_RETRY_ATTEMPTS - 1) throw err;
+      Atomics.wait(sleepBuffer, 0, 0, RENAME_RETRY_BACKOFF_MS * (attempt + 1));
+    }
+  }
+}

package/src/git.mjs

@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process';
 import { chmodSync, closeSync, existsSync, fsyncSync, linkSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
+import { commitRename } from './durable-rename.mjs';
 
 // Best-effort `git check-ignore` for a path. Returns true only when git
 // definitively reports the path is ignored; any failure (not a repo, git
@@ -675,7 +676,9 @@ function publishIndexGeneration(repoRoot, expected, desired, prepared, testHooks
     if (!sameGitIndexGeneration(current, expected)) throw new Error('Git index changed before transaction publication; current staging was preserved.');
     testHooks.afterGitIndexCompare?.({ lockPath, current, desired });
     if (desired.exists) {
-      renameSync(lockPath, indexPath);
+      // .git/index is routinely held open by concurrent git processes and IDE git
+      // extensions, so on Windows this publish needs the retry.
+      commitRename(lockPath, indexPath, testHooks);
       lockOwned = false;
     } else {
       if (existsSync(indexPath)) unlinkSync(indexPath);

package/src/lifecycle.mjs

@@ -80,10 +80,20 @@ function commitLifecycleMutation(filePath, targetPath, config, updates, historyF
     const tracked = isTracked(filePath, config.repoRoot);
     const gitIndex = tracked ? captureGitIndexGeneration(config.repoRoot) : null;
     const companionPaths = new Set((options.additionalUpdates ?? []).map(item => path.resolve(item.path)));
-    const allFiles = collectDocFiles(config).filter(candidate => candidate !== filePath && candidate !== targetPath && !companionPaths.has(path.resolve(candidate)));
+    const allFiles = options.skipInboundRefs
+      ? []
+      : collectDocFiles(config).filter(candidate => candidate !== filePath && candidate !== targetPath && !companionPaths.has(path.resolve(candidate)));
     authorizeManagedSweep(allFiles, config, { kind: 'Reference rewrite source' });
     const identities = createReferenceIdentitySet([filePath, ...allFiles]);
     const referenceFields = configuredReferenceFields(config);
+    const additionalUpdates = options.skipInboundRefs
+      ? (options.additionalUpdates ?? [])
+      : (options.additionalUpdates ?? []).map(item => ({
+          ...item,
+          content: item.content === undefined ? undefined : rewriteDocumentReferences(item.content, {
+            sourcePath: item.path, repoRoot: config.repoRoot, identities, oldPath: filePath, newPath: targetPath, referenceFields,
+          }),
+        }));
     const moveResult = moveFileAtomic(filePath, targetPath, sourceContent => {
       result = render(sourceContent);
       return result.content;
@@ -95,12 +105,7 @@ function commitLifecycleMutation(filePath, targetPath, config, updates, historyF
         render: raw => rewriteDocumentReferences(raw, {
           sourcePath: docFile, repoRoot: config.repoRoot, identities, oldPath: filePath, newPath: targetPath, referenceFields,
         }),
-      })), ...(options.additionalUpdates ?? []).map(item => ({
-        ...item,
-        content: item.content === undefined ? undefined : rewriteDocumentReferences(item.content, {
-          sourcePath: item.path, repoRoot: config.repoRoot, identities, oldPath: filePath, newPath: targetPath, referenceFields,
-        }),
-      }))],
+      })), ...additionalUpdates],
       creations: options.creations ?? [],
       gitMove: tracked,
       gitIndex,
@@ -806,10 +811,13 @@ export function runArchive(argv, config, opts = {}) {
     if (config.indexPath && !noIndex && !opts.deferIndex) out.write(`${prefix} Would regenerate index\n`);
     if (config.indexPath && noIndex) out.write(`${prefix} Would skip index regen (--no-index)\n`);
 
-    // Preview reference updates
-    const refCount = countRefsToUpdate(filePath, targetPath, config);
-    if (refCount > 0) {
-      out.write(`${prefix} Would update references in ${refCount} file(s)\n`);
+    // Preview reference updates unless the caller owns a non-referenceable,
+    // session-local document such as a saved prompt.
+    if (!opts.skipInboundRefs) {
+      const refCount = countRefsToUpdate(filePath, targetPath, config);
+      if (refCount > 0) {
+        out.write(`${prefix} Would update references in ${refCount} file(s)\n`);
+      }
     }
 
     // Preview onArchive hook fire
@@ -825,6 +833,7 @@ export function runArchive(argv, config, opts = {}) {
       testHooks: opts.testHooks,
       additionalUpdates: [...(opts.additionalUpdates ?? []), ...(releaseUpdate ? [releaseUpdate] : [])],
       creations: opts.creations,
+      skipInboundRefs: opts.skipInboundRefs,
       bodyTransform: closeoutTemplate ? currentBody => {
         committedCloseoutAction = planCloseoutInjection(currentBody);
         return committedCloseoutAction.action === 'inject' ? committedCloseoutAction.newBody : currentBody;

package/src/prompts.mjs

@@ -270,7 +270,7 @@ export async function consumePrompt(filePath, config, opts) {
     process.stderr.write(body);
     if (!body.endsWith('\n')) process.stderr.write('\n');
     process.stderr.write(`${dim('--->8---')}\n`);
-    runArchive([filePath], config, { dryRun: true, noIndex, out: process.stderr });
+    runArchive([filePath], config, { dryRun: true, noIndex, out: process.stderr, skipInboundRefs: true });
     return;
   }
 
@@ -284,6 +284,9 @@ export async function consumePrompt(filePath, config, opts) {
     out: process.stderr,
     testHooks: opts.testHooks,
     deferIndex: Boolean(linkedClaim),
+    // Saved prompts are gitignored session state, never durable reference
+    // targets. Avoid locking and replanning the entire corpus on consumption.
+    skipInboundRefs: true,
     additionalUpdates: linkedClaim?.prepared?.updates,
     creations: linkedClaim?.prepared?.creations,
   });