dotmd-cli 0.70.3 → 0.70.4

package/package.json

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