llmnav 0.7.0 → 0.7.1

package/CHANGELOG.md

@@ -6,6 +6,12 @@ The npm package follows Semantic Versioning. The `llmnav/N` source protocol is v
 
 ## [Unreleased]
 
+## [0.7.1] — 2026-08-13
+
+### Fixed
+
+* Revalidated managed-write parent identity and symbolic-link traversal immediately before atomic replacement, preventing a concurrent directory swap from redirecting source formatting or control-file writes outside the repository.
+
 ## [0.7.0] — 2026-08-13
 
 ### Added

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "llmnav",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "A deterministic semantic navigation layer for LLM coding agents.",
   "type": "module",
   "bin": {

package/src/agents.js

@@ -42,19 +42,19 @@ export async function installAgentInstructions(root, adapters = ["agents"]) {
     if (adapter === "agents") {
       const target = path.join(root, "AGENTS.md");
       await assertNoSymlinkTraversal(root, target, "AGENTS.md");
-      if (await upsertMarkdown(target, "# Repository instructions", AGENT_PROTOCOL)) {
+      if (await upsertMarkdown(root, target, "# Repository instructions", AGENT_PROTOCOL)) {
         changed.push("AGENTS.md");
       }
     } else if (adapter === "claude") {
       const target = path.join(root, "CLAUDE.md");
       await assertNoSymlinkTraversal(root, target, "CLAUDE.md");
-      if (await upsertMarkdown(target, "# Claude Code instructions", AGENT_PROTOCOL)) {
+      if (await upsertMarkdown(root, target, "# Claude Code instructions", AGENT_PROTOCOL)) {
         changed.push("CLAUDE.md");
       }
     } else if (adapter === "copilot") {
       const target = path.join(root, ".github", "copilot-instructions.md");
       await assertNoSymlinkTraversal(root, target, ".github/copilot-instructions.md");
-      if (await upsertMarkdown(target, "# GitHub Copilot instructions", AGENT_PROTOCOL)) {
+      if (await upsertMarkdown(root, target, "# GitHub Copilot instructions", AGENT_PROTOCOL)) {
         changed.push(".github/copilot-instructions.md");
       }
     } else if (adapter === "cursor") {
@@ -63,7 +63,7 @@ export async function installAgentInstructions(root, adapters = ["agents"]) {
       const content = `---\ndescription: Use LLMNav before broad codebase exploration\nalwaysApply: true\n---\n\n${AGENT_PROTOCOL}\n`;
       const existing = await readText(target, "");
       if (existing !== content) {
-        await atomicWrite(target, content);
+        await atomicWrite(root, target, content);
         changed.push(".cursor/rules/llmnav.mdc");
       }
     }
@@ -73,7 +73,7 @@ export async function installAgentInstructions(root, adapters = ["agents"]) {
   await assertNoSymlinkTraversal(root, canonicalPath, ".llmnav/AGENT_INSTRUCTIONS.md");
   const canonical = `# LLMNav agent protocol\n\n${AGENT_PROTOCOL}\n`;
   if ((await readText(canonicalPath, "")) !== canonical) {
-    await atomicWrite(canonicalPath, canonical);
+    await atomicWrite(root, canonicalPath, canonical);
     changed.push(".llmnav/AGENT_INSTRUCTIONS.md");
   }
   return changed;
@@ -102,7 +102,7 @@ function adapterUsageError(message) {
   return error;
 }
 
-async function upsertMarkdown(filePath, title, block) {
+async function upsertMarkdown(root, filePath, title, block) {
   await mkdir(path.dirname(filePath), { recursive: true });
   const existing = await readText(filePath, "");
   let next;
@@ -124,6 +124,6 @@ async function upsertMarkdown(filePath, title, block) {
     next = `${existing.trimEnd()}\n\n${block}\n`;
   }
   if (next === existing) return false;
-  await atomicWrite(filePath, next);
+  await atomicWrite(root, filePath, next);
   return true;
 }

package/src/cli.js

@@ -339,7 +339,7 @@ async function runAudit(root, args, json) {
     ? { schemaVersion: result.schemaVersion, repositoryId: result.repositoryId, summary: result.summary, failOn }
     : report;
   if (outputPath) {
-    await atomicWrite(outputPath, `${JSON.stringify(selectedReport, null, 2)}\n`);
+    await atomicWrite(root, outputPath, `${JSON.stringify(selectedReport, null, 2)}\n`);
   }
   if (json) {
     console.log(JSON.stringify(outputPath

package/src/formatter.js

@@ -27,7 +27,7 @@ export async function formatProject(root, options = {}) {
     errors.push(...result.errors.map((error) => ({ file: relativePath, ...error })));
     if (!result.changed) continue;
     changedFiles.push(relativePath);
-    if (!options.check) await atomicWrite(filePath, result.source);
+    if (!options.check) await atomicWrite(root, filePath, result.source, options.atomicWriteOptions);
   }
   const ok = errors.length === 0 && (options.check ? changedFiles.length === 0 : true);
   return { ok, changedFiles, errors };

package/src/incremental.js

@@ -165,7 +165,7 @@ export function buildFileStateFromProject(project) {
 
 export async function persistStatHints(root, hintsPath, statHints) {
   await assertNoSymlinkTraversal(root, hintsPath, relativePosix(root, hintsPath));
-  await atomicWrite(hintsPath, stableStringify(statHints));
+  await atomicWrite(root, hintsPath, stableStringify(statHints));
 }
 
 export function renderFileState(fileState) {

package/src/initializer.js

@@ -123,7 +123,7 @@ async function writeIfMissingOrForced(root, filePath, content, force, changed, d
   const existing = await readText(filePath, null);
   if (existing !== null && !force) return;
   if (existing === content) return;
-  await atomicWrite(filePath, content);
+  await atomicWrite(root, filePath, content);
   changed.push(displayPath);
 }
 
@@ -147,6 +147,6 @@ async function addPackageScripts(root) {
     parsed.scripts[name] = command;
     changed = true;
   }
-  if (changed) await atomicWrite(packagePath, `${JSON.stringify(parsed, null, 2)}\n`);
+  if (changed) await atomicWrite(root, packagePath, `${JSON.stringify(parsed, null, 2)}\n`);
   return changed;
 }

package/src/registry.js

@@ -79,7 +79,7 @@ export async function ensureActiveIds(root, registry, ids) {
   }
   await assertNoSymlinkTraversal(root, registryPath, ".llmnav/ids.jsonl");
   const { records, changed } = mergeActiveIds(registry, ids);
-  if (changed) await atomicWrite(registryPath, renderRegistryRecords(records));
+  if (changed) await atomicWrite(root, registryPath, renderRegistryRecords(records));
   return { records, changed };
 }
 

package/src/spec.js

@@ -10,7 +10,7 @@ rel=workflow>llmnav.rules.validate
 stability=contract
 */
 
-export const PACKAGE_VERSION = "0.7.0";
+export const PACKAGE_VERSION = "0.7.1";
 export const SPEC_VERSION = "1";
 
 export const SCOPES = Object.freeze(["file", "module", "symbol"]);

package/src/transaction.js

@@ -152,7 +152,7 @@ export async function commitGeneratedCache(root, cacheDirectory, artifacts, opti
       controlArtifacts: controlRecords,
       phase: "prepared",
     };
-    await atomicWrite(journalPath, stableStringify(journal));
+    await atomicWrite(root, journalPath, stableStringify(journal));
     await invokeFailpoint("after-journal", options);
 
     if (hadExistingCache) {
@@ -160,19 +160,19 @@ export async function commitGeneratedCache(root, cacheDirectory, artifacts, opti
     }
     await moveControlArtifactsToBackup(root, controlRecords, options.renameOptions);
     journal = { ...journal, phase: "old-moved" };
-    await atomicWrite(journalPath, stableStringify(journal));
+    await atomicWrite(root, journalPath, stableStringify(journal));
     await invokeFailpoint("after-cache-moved", options);
 
     await renameWithRetry(stagePath, cachePath, options.renameOptions);
     await installControlArtifacts(root, controlRecords, options.renameOptions);
     journal = { ...journal, phase: "new-installed" };
-    await atomicWrite(journalPath, stableStringify(journal));
+    await atomicWrite(root, journalPath, stableStringify(journal));
     await verifyCommittedCache(cachePath, cacheRelative);
     await verifyControlArtifacts(root, controlRecords);
     await invokeFailpoint("after-new-installed", options);
 
     journal = { ...journal, phase: "committed" };
-    await atomicWrite(journalPath, stableStringify(journal));
+    await atomicWrite(root, journalPath, stableStringify(journal));
     if (hadExistingCache) await removeWithRetry(backupPath, options.renameOptions);
     await removeWithRetry(transactionPath, options.renameOptions);
     await removeWithRetry(journalPath, options.renameOptions);

package/src/util.js

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { lstat, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
 
 export function normalizeNewlines(value) {
@@ -137,18 +137,41 @@ export async function readJsonSafe(filePath, fallback = null) {
   }
 }
 
-export async function atomicWrite(filePath, content) {
-  await mkdir(path.dirname(filePath), { recursive: true });
+export async function atomicWrite(root, filePath, content, options = {}) {
+  const parent = path.dirname(filePath);
+  const label = options.label ?? relativePosix(root, filePath);
+  await assertNoSymlinkTraversal(root, filePath, label);
+  await mkdir(parent, { recursive: true });
+  const parentIdentity = await directoryIdentity(root, parent, label);
   const temporaryPath = `${filePath}.tmp-${process.pid}-${Math.random().toString(16).slice(2)}`;
-  await writeFile(temporaryPath, content, "utf8");
+  await writeFile(temporaryPath, content, { encoding: "utf8", flag: "wx" });
   try {
+    await options.beforeCommit?.({ filePath, temporaryPath });
+    await assertNoSymlinkTraversal(root, filePath, label);
+    const currentIdentity = await directoryIdentity(root, parent, label);
+    if (currentIdentity !== parentIdentity) throw new Error(`${label} parent directory changed during atomic write.`);
     await rename(temporaryPath, filePath);
   } catch (error) {
-    await rm(temporaryPath, { force: true });
+    if (await parentHasIdentity(root, parent, parentIdentity)) await rm(temporaryPath, { force: true });
     throw error;
   }
 }
 
+async function directoryIdentity(root, directory, label) {
+  await assertNoSymlinkTraversal(root, directory, label);
+  const [details, canonical] = await Promise.all([lstat(directory), realpath(directory)]);
+  if (!details.isDirectory()) throw new Error(`${label} parent is not a directory.`);
+  return `${details.dev}:${details.ino}:${path.normalize(canonical)}`;
+}
+
+async function parentHasIdentity(root, parent, expected) {
+  try {
+    return (await directoryIdentity(root, parent, parent)) === expected;
+  } catch {
+    return false;
+  }
+}
+
 export async function assertNoSymlinkTraversal(root, targetPath, label = targetPath) {
   const rootPath = path.resolve(root);
   const target = path.resolve(targetPath);