@pi-archimedes/core 2.10.1 → 2.10.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/core",
-  "version": "2.10.1",
+  "version": "2.10.3",
   "repository": {
     "type": "git",
     "url": "https://github.com/danielcherubini/pi-archimedes.git"

package/src/settings-io.test.ts

@@ -353,3 +353,118 @@ describe("updateConfig", () => {
     expect(data["concurrent.ns"]).toBeDefined(); // siblings survived
   });
 });
+
+describe("symlink preservation", () => {
+  const settingsLink = () => join(tempDir, "settings.json");
+  const target = () => join(tempDir, "dotfiles-settings.json");
+
+  /**
+   * Per-case setup: wipe settings.json (and any stale link/target/tmp), then
+   * create a fresh target file pre-seeded with `{ preexisting: "keep-me" }`
+   * (plus optional extra keys) and a settings.json **symlink** to it.
+   * For dangling cases, `targetName` points the link at a non-existent path
+   * instead of the seeded target.
+   */
+  function setupSymlink(targetName?: string, extraTargetKeys?: Record<string, unknown>) {
+    const link = settingsLink();
+    const t = target();
+    for (const p of [link, link + ".tmp", t, join(tempDir, "nope.json"), join(tempDir, "nope2.json")]) {
+      try { fs.unlinkSync(p); } catch { /* ignore */ }
+    }
+    if (targetName) {
+      fs.symlinkSync(join(tempDir, targetName), link);
+      return join(tempDir, targetName);
+    }
+    fs.writeFileSync(t, JSON.stringify({ preexisting: "keep-me", ...extraTargetKeys }), "utf-8");
+    fs.symlinkSync(t, link);
+    return t;
+  }
+
+  afterEach(() => {
+    for (const p of [settingsLink(), settingsLink() + ".tmp", target(), join(tempDir, "nope.json"), join(tempDir, "nope2.json")]) {
+      try { fs.unlinkSync(p); } catch { /* ignore */ }
+    }
+  });
+
+  it("saveConfig through symlink preserves the link and updates the destination", () => {
+    const t = setupSymlink();
+    saveConfig("archimedes.test", { a: 1 });
+    expect(fs.lstatSync(settingsLink()).isSymbolicLink()).toBe(true);
+    const data = JSON.parse(fs.readFileSync(t, "utf-8"));
+    expect(data["archimedes.test"]).toEqual({ a: 1 });
+    expect(data["preexisting"]).toBe("keep-me");
+  });
+
+  it("removeConfig through symlink preserves the link", () => {
+    const t = setupSymlink();
+    saveConfig("archimedes.test", { a: 1 });
+    removeConfig("archimedes.test");
+    expect(fs.lstatSync(settingsLink()).isSymbolicLink()).toBe(true);
+    const data = JSON.parse(fs.readFileSync(t, "utf-8"));
+    expect(data["archimedes.test"]).toBeUndefined();
+    expect(data["preexisting"]).toBe("keep-me");
+  });
+
+  it("regular file behavior unchanged (no symlink)", () => {
+    const link = settingsLink();
+    setupSymlink();
+    fs.unlinkSync(link);
+    fs.writeFileSync(link, "{}", "utf-8");
+    saveConfig("archimedes.test", { b: 2 });
+    expect(fs.lstatSync(link).isSymbolicLink()).toBe(false);
+    const data = JSON.parse(fs.readFileSync(link, "utf-8"));
+    expect(data["archimedes.test"]).toEqual({ b: 2 });
+    expect(fs.existsSync(link + ".tmp")).toBe(false);
+  });
+
+  it("removeConfig with missing file creates nothing", () => {
+    const link = settingsLink();
+    setupSymlink();
+    fs.unlinkSync(link);
+    removeConfig("archimedes.test");
+    expect(fs.existsSync(link)).toBe(false);
+  });
+
+  it("dangling symlink: saveConfig recreates the destination, link live again", () => {
+    const t = setupSymlink("nope.json");
+    saveConfig("archimedes.test", { c: 3 });
+    expect(fs.existsSync(t)).toBe(true);
+    const data = JSON.parse(fs.readFileSync(t, "utf-8"));
+    expect(data["archimedes.test"]).toEqual({ c: 3 });
+    expect(fs.lstatSync(settingsLink()).isSymbolicLink()).toBe(true);
+  });
+
+  it("dangling symlink: removeConfig is a no-op, link untouched", () => {
+    const t = setupSymlink("nope2.json");
+    removeConfig("archimedes.test");
+    expect(fs.lstatSync(settingsLink()).isSymbolicLink()).toBe(true);
+    expect(fs.existsSync(t)).toBe(false);
+  });
+
+  it("temp-write failure leaves the original file untouched", () => {
+    const t = setupSymlink();
+    const beforeRaw = fs.readFileSync(t, "utf-8");
+    // The temp file is written beside the target (inside tempDir), so make the
+    // parent directory read-only: the temp write fails (EACCES), the rename is
+    // never attempted, and the live file must survive untouched.
+    const mode = fs.statSync(tempDir).mode;
+    fs.chmodSync(tempDir, 0o555);
+    try {
+      expect(() => saveConfig("archimedes.test", { e: 5 })).toThrow();
+      expect(fs.readFileSync(t, "utf-8")).toBe(beforeRaw);
+      expect(fs.existsSync(t + ".tmp")).toBe(false);
+      expect(fs.existsSync(settingsLink() + ".tmp")).toBe(false);
+      expect(fs.lstatSync(settingsLink()).isSymbolicLink()).toBe(true);
+    } finally {
+      fs.chmodSync(tempDir, mode);
+    }
+  });
+
+  it("sibling namespaces survive a save", () => {
+    const t = setupSymlink(undefined, { "archimedes.other": { keep: true } });
+    saveConfig("archimedes.test", { d: 4 });
+    const data = JSON.parse(fs.readFileSync(t, "utf-8"));
+    expect(data["archimedes.other"]).toEqual({ keep: true });
+    expect(data["archimedes.test"]).toEqual({ d: 4 });
+  });
+});

package/src/settings-io.ts

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, existsSync, renameSync, unlinkSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, renameSync, unlinkSync, lstatSync, realpathSync } from "node:fs";
 import { join } from "node:path";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
@@ -45,21 +45,66 @@ export function loadConfig<T>(
 }
 
 /**
- * Save a config section to settings.json (atomic: write to .tmp then rename).
+ * Atomic write that preserves symlinks: if `path` is a symlink to an
+ * existing file, the temp file is created beside the resolved destination
+ * and the rename targets the destination — leaving the link intact.
+ * Regular files and missing files behave exactly as a plain tmp-then-rename
+ * would (temp beside `path`, rename onto `path`).
+ *
+ * Dangling symlink: `realpathSync` throws (ENOENT) — the fallback writes
+ * directly through the link, recreating the destination so the link is
+ * live again.
+ *
+ * Failure-mode note (deliberate, differs from the old clobber behavior):
+ * a failed temp write (e.g. ENOSPC) cleans up the temp file and re-throws —
+ * the live file is left untouched, so no data loss. A failed rename falls
+ * back to a direct write-through, since the temp already holds the full
+ * content; writeFileSync follows links, so even that non-atomic path never
+ * clobbers a link to an existing file. A symlink loop (ELOOP) or an
+ * unwritable destination (EACCES) still throw out of this function, where
+ * the old code would have "succeeded" by replacing the link with a regular
+ * file in the writable agent dir.
  */
-export function saveConfig(namespace: string, config: object): void {
-  const full = readSettings();
-  full[namespace] = config;
-  const tmpPath = SETTINGS_PATH + ".tmp";
-  writeFileSync(tmpPath, JSON.stringify(full, null, 2), "utf-8");
+export function writeAtomicPreservingSymlinks(path: string, data: string): void {
+  let isLink = false;
+  try { isLink = lstatSync(path).isSymbolicLink(); } catch { /* missing → plain path */ }
+  let target = path;
+  if (isLink) {
+    try {
+      target = realpathSync(path);
+    } catch {
+      // Dangling symlink: write through the link, recreating the destination.
+      writeFileSync(path, data, "utf-8");
+      return;
+    }
+  }
+  const tmpPath = target + ".tmp";
   try {
-    renameSync(tmpPath, SETTINGS_PATH);
+    writeFileSync(tmpPath, data, "utf-8");
+  } catch (err) {
+    // Temp write failed (e.g. ENOSPC) — the live file must survive untouched.
+    try { unlinkSync(tmpPath); } catch { /* ignore */ }
+    throw err;
+  }
+  try {
+    renameSync(tmpPath, target);
   } catch {
+    // Rename failed — the temp already holds the full content, so a direct
+    // write-through (which follows symlinks) is the fallback.
     try { unlinkSync(tmpPath); } catch { /* ignore */ }
-    writeFileSync(SETTINGS_PATH, JSON.stringify(full, null, 2), "utf-8");
+    writeFileSync(target, data, "utf-8");
   }
 }
 
+/**
+ * Save a config section to settings.json (atomic, symlink-preserving — delegates to writeAtomicPreservingSymlinks).
+ */
+export function saveConfig(namespace: string, config: object): void {
+  const full = readSettings();
+  full[namespace] = config;
+  writeAtomicPreservingSymlinks(SETTINGS_PATH, JSON.stringify(full, null, 2));
+}
+
 /**
  * Delete a namespace section from settings.json entirely.
  * No-op if the key is absent (including when the file doesn't exist — the file
@@ -72,14 +117,7 @@ export function removeConfig(namespace: string): void {
   if (!existsSync(SETTINGS_PATH)) return;
   if (!(namespace in full)) return;
   delete full[namespace];
-  const tmpPath = SETTINGS_PATH + ".tmp";
-  writeFileSync(tmpPath, JSON.stringify(full, null, 2), "utf-8");
-  try {
-    renameSync(tmpPath, SETTINGS_PATH);
-  } catch {
-    try { unlinkSync(tmpPath); } catch { /* ignore */ }
-    writeFileSync(SETTINGS_PATH, JSON.stringify(full, null, 2), "utf-8");
-  }
+  writeAtomicPreservingSymlinks(SETTINGS_PATH, JSON.stringify(full, null, 2));
 }
 
 /**