@pi-archimedes/core 2.7.0 → 2.7.1

package/package.json

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

package/src/settings-io.test.ts

@@ -17,7 +17,7 @@ vi.mock("@earendil-works/pi-coding-agent", () => ({
 }));
 
 // Import after mocks are set up
-const { loadConfig, saveConfig, removeConfig, isConfigEnabled, setConfigEnabled } = await import("./settings-io.js");
+const { loadConfig, saveConfig, removeConfig, isConfigEnabled, setConfigEnabled, updateConfig } = await import("./settings-io.js");
 
 describe("removeConfig", () => {
   beforeEach(() => {
@@ -242,3 +242,114 @@ describe("saveConfig", () => {
     expect(fs.existsSync(settingsPath + ".tmp")).toBe(false);
   });
 });
+
+describe("updateConfig", () => {
+  const settingsPath = () => join(tempDir, "settings.json");
+
+  beforeEach(() => {
+    const p = settingsPath();
+    if (fs.existsSync(p)) fs.unlinkSync(p);
+  });
+
+  afterEach(() => {
+    const p = settingsPath();
+    const tmpP = p + ".tmp";
+    try { fs.unlinkSync(p); } catch { /* ignore */ }
+    try { fs.unlinkSync(tmpP); } catch { /* ignore */ }
+  });
+
+  it("applies mutation onto defaults when settings.json does not exist", () => {
+    const result = updateConfig(
+      "test.ns",
+      { done: false, count: 0 },
+      (cfg) => ({ ...cfg, done: true }),
+    );
+    expect(result).toEqual({ done: true, count: 0 });
+    const data = JSON.parse(fs.readFileSync(settingsPath(), "utf-8"));
+    expect(data["test.ns"]).toEqual({ done: true, count: 0 });
+  });
+
+  it("preserves sibling namespaces AND other keys of the target namespace", () => {
+    fs.writeFileSync(
+      settingsPath(),
+      JSON.stringify({
+        "test.ns": { done: false, extra: 99 },
+        "other.ns": { sibling: "value" },
+      }),
+      "utf-8",
+    );
+    const result = updateConfig(
+      "test.ns",
+      { done: false, extra: 0 },
+      (cfg) => ({ ...cfg, done: true }),
+    );
+    expect(result).toEqual({ done: true, extra: 99 });
+    const data = JSON.parse(fs.readFileSync(settingsPath(), "utf-8"));
+    expect(data["test.ns"]).toEqual({ done: true, extra: 99 });
+    expect(data["other.ns"]).toEqual({ sibling: "value" });
+  });
+
+  it("concurrent-change detection: detects a mid-mutation external write and retries; final file contains both the external key and the mutated value", () => {
+    fs.writeFileSync(
+      settingsPath(),
+      JSON.stringify({ "test.ns": { done: false } }),
+      "utf-8",
+    );
+
+    let mutateCallCount = 0;
+    const result = updateConfig(
+      "test.ns",
+      { done: false },
+      (cfg) => {
+        mutateCallCount += 1;
+        // On the first call, simulate a concurrent process writing an external key
+        // between the `before` read and the `after` read. This change must be
+        // detected by the optimistic re-read check, triggering a retry.
+        if (mutateCallCount === 1) {
+          const raw = JSON.parse(fs.readFileSync(settingsPath(), "utf-8"));
+          raw["concurrent.ns"] = { injected: true };
+          fs.writeFileSync(settingsPath(), JSON.stringify(raw), "utf-8");
+        }
+        return { ...cfg, done: true };
+      },
+    );
+
+    expect(mutateCallCount).toBeGreaterThan(1);
+    expect(result).toEqual({ done: true });
+    const data = JSON.parse(fs.readFileSync(settingsPath(), "utf-8"));
+    // Retry recomputed from fresh state — both the external key AND the mutated value survive
+    expect(data["test.ns"]).toEqual({ done: true });
+    expect(data["concurrent.ns"]).toEqual({ injected: true });
+  });
+
+  it("persistent concurrent writer: after maxAttempts the update still completes (last-writer-wins, no crash)", () => {
+    fs.writeFileSync(
+      settingsPath(),
+      JSON.stringify({ "test.ns": { done: false } }),
+      "utf-8",
+    );
+
+    let mutateCallCount = 0;
+    // mutate always writes the external key — simulates a persistent concurrent writer
+    const result = updateConfig(
+      "test.ns",
+      { done: false },
+      (cfg) => {
+        mutateCallCount += 1;
+        // Always write a concurrent change to force re-read on every attempt
+        const raw = JSON.parse(fs.readFileSync(settingsPath(), "utf-8"));
+        raw["concurrent.ns"] = { injected: mutateCallCount };
+        fs.writeFileSync(settingsPath(), JSON.stringify(raw), "utf-8");
+        return { ...cfg, done: true };
+      },
+      3, // maxAttempts
+    );
+
+    // Must complete (not loop forever or throw)
+    expect(mutateCallCount).toBe(3); // saturated at maxAttempts
+    expect(result).toEqual({ done: true }); // flag value persisted
+    const data = JSON.parse(fs.readFileSync(settingsPath(), "utf-8"));
+    expect(data["test.ns"]).toEqual({ done: true }); // flag survived
+    expect(data["concurrent.ns"]).toBeDefined(); // siblings survived
+  });
+});

package/src/settings-io.ts

@@ -4,16 +4,35 @@ import { getAgentDir } from "@earendil-works/pi-coding-agent";
 
 const SETTINGS_PATH = join(getAgentDir(), "settings.json");
 
-/** Read the full settings.json, returning empty object if missing/corrupt. */
-function readSettings(): Record<string, unknown> {
-  if (!existsSync(SETTINGS_PATH)) return {};
+/**
+ * Read settings.json as a raw string. Returns null when the file is absent or
+ * unreadable (EISDIR, EACCES, etc.) — callers treat null the same as an empty
+ * file (i.e. no prior settings).
+ */
+function readRawSettings(): string | null {
+  if (!existsSync(SETTINGS_PATH)) return null;
   try {
-    return JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
+    return readFileSync(SETTINGS_PATH, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/** Parse a raw settings string, returning empty object on null/corrupt input. */
+function parseSettings(raw: string | null): Record<string, unknown> {
+  if (raw === null) return {};
+  try {
+    return JSON.parse(raw) as Record<string, unknown>;
   } catch {
     return {};
   }
 }
 
+/** Read the full settings.json, returning empty object if missing/corrupt. */
+function readSettings(): Record<string, unknown> {
+  return parseSettings(readRawSettings());
+}
+
 /**
  * Load a config section from settings.json, merged with defaults.
  */
@@ -97,3 +116,47 @@ export function setConfigEnabled(namespace: string, enabled: boolean): void {
     saveConfig(namespace, cfg);
   }
 }
+
+/**
+ * Concurrency-safe read-modify-write for one settings namespace.
+ *
+ * Uses an optimistic re-read check: the settings file is read before and after
+ * the `mutate` callback runs. If the file changed during that window (indicating
+ * a concurrent writer, e.g. another TUI session running /plugins toggle), the
+ * attempt is discarded and the loop restarts from a fresh read — up to
+ * `maxAttempts` times.
+ *
+ * Sibling namespaces always benefit from `saveConfig`’s own fresh read inside
+ * the atomic write, so they are never clobbered regardless of retries.
+ *
+ * The residual window between the final `after` check and `saveConfig`’s
+ * internal read is last-writer-wins; the optimistic check handles all
+ * detectable races (changes that happen during the `mutate` call itself).
+ *
+ * When the maximum attempt count is reached without a clean window (persistent
+ * concurrent writer), the last computed value is still written — no crash, no
+ * unbounded loop.
+ */
+export function updateConfig<T extends object>(
+  namespace: string,
+  defaults: T,
+  mutate: (cfg: T) => T,
+  maxAttempts = 3,
+): T {
+  let last = { ...defaults } as T;
+  for (let attempt = 1; ; attempt++) {
+    const before = readRawSettings();
+    const parsed = parseSettings(before);
+    const current = { ...defaults, ...(parsed[namespace] ?? {}) } as T;
+    const next = mutate(current);
+    const after = readRawSettings();
+    if (before !== after && attempt < maxAttempts) {
+      // Settings file changed during our update window (concurrent writer) —
+      // recompute from the fresh state on the next iteration.
+      continue;
+    }
+    last = next;
+    saveConfig(namespace, next);
+    return last;
+  }
+}