@holmes-lab/holmes-kit 0.23.3 → 0.24.1

package/dist/holmes/update/workspaces.js

@@ -34,12 +34,33 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.EMPTY_REGISTRY = void 0;
+exports.holmesHome = holmesHome;
 exports.readRegistry = readRegistry;
 exports.mergeWorkspaceEntry = mergeWorkspaceEntry;
+exports.isTempTarget = isTempTarget;
+exports.pruneRegistry = pruneRegistry;
 exports.recordWorkspace = recordWorkspace;
 // @implements A-SPEC-543.1
 const fs = __importStar(require("node:fs"));
+const os = __importStar(require("node:os"));
 const path = __importStar(require("node:path"));
+/**
+ * @implements A-SPEC-678
+ * Where the registry lives — with one seam a test can reach.
+ *
+ * Measured 2026-09-18: inside jest, `process.env` is a plain object copy in the sandbox, so
+ * assigning `HOME` never reaches `setenv` and `os.homedir()` keeps answering the developer's real
+ * home. Plain node follows `$HOME`; jest does not. An in-process test therefore cannot isolate a
+ * module that calls `os.homedir()` directly — which is how 599 of this machine's 603 registry
+ * entries came to be test temp directories.
+ *
+ * jest DOES control `process.env`, so one lookup there is the smallest seam that works. Consumers
+ * set nothing and get `os.homedir()`; an empty value is not a setting.
+ */
+function holmesHome(env, fallback) {
+    const override = env.HOLMES_HOME;
+    return typeof override === 'string' && override.trim() !== '' ? override : fallback;
+}
 exports.EMPTY_REGISTRY = { version: 1, workspaces: [] };
 /**
  * @implements A-SPEC-543.1
@@ -79,16 +100,59 @@ function mergeWorkspaceEntry(reg, entry) {
     };
 }
 /**
- * @implements A-SPEC-543.1
- * Thin best-effort recorder: read → merge → write `~/.holmes/workspaces.json`. Every failure is
- * swallowed (returns false) — a registry problem must never fail the init that feeds it.
+ * @implements A-SPEC-677
+ * Whether a target lives under the OS temp root — and therefore is ephemeral by construction.
+ *
+ * macOS spells that root two ways: `os.tmpdir()` answers `/var/folders/...` while a realpath gives
+ * `/private/var/folders/...`. Both appear in this machine's registry, so both are judged. A `/tmp`
+ * literal would have missed all 599 of them.
+ *
+ * An empty root filters NOTHING. When the judgement cannot be made, keeping an entry costs a line
+ * and dropping one the user wanted costs them something they cannot get back.
  */
+function isTempTarget(target, tmpdir) {
+    if (typeof target !== 'string' || typeof tmpdir !== 'string' || tmpdir.trim() === '')
+        return false;
+    const roots = new Set([tmpdir, tmpdir.startsWith('/private') ? tmpdir.slice('/private'.length) : `/private${tmpdir}`]);
+    return [...roots].some((r) => r !== '' && (target === r || target.startsWith(r.endsWith('/') ? r : `${r}/`)));
+}
+/**
+ * @implements A-SPEC-677
+ * Drop what has certainly gone; COUNT what merely cannot be seen.
+ *
+ * The asymmetry is the whole judgement. A vanished temp path is gone by construction — nothing
+ * re-creates a `mkdtemp` directory. A vanished normal path may be an unmounted volume, an external
+ * disk or a network share, and `upgrade` already skips it harmlessly with one line. Deleting it is
+ * the one outcome the user cannot undo, so absence outside the temp root is reported, never acted on.
+ */
+function pruneRegistry(reg, p) {
+    let dropped = 0, absent = 0;
+    const workspaces = reg.workspaces.filter((w) => {
+        if (p.exists(w.target))
+            return true;
+        if (p.isTemp(w.target)) {
+            dropped += 1;
+            return false;
+        }
+        absent += 1;
+        return true;
+    });
+    return { registry: { version: 1, workspaces }, dropped, absent };
+}
 function recordWorkspace(home, entry, io = {
     read: (p) => fs.readFileSync(p, 'utf8'),
     write: (p, c) => fs.writeFileSync(p, c),
     mkdir: (p) => { fs.mkdirSync(p, { recursive: true }); },
+    exists: (p) => fs.existsSync(p),
+    tmpdir: () => os.tmpdir(),
 }) {
     try {
+        // @implements A-SPEC-677 — an ephemeral target is not recorded at all. What never enters cannot
+        // pile up, and 599 of this machine's 603 entries entered exactly this way. Returning true is
+        // honest: nothing failed, there was simply nothing worth remembering.
+        const tmpdir = io.tmpdir?.() ?? '';
+        if (isTempTarget(entry.target, tmpdir))
+            return true;
         const dir = path.join(home, '.holmes');
         const file = path.join(dir, 'workspaces.json');
         let raw = null;
@@ -98,9 +162,18 @@ function recordWorkspace(home, entry, io = {
         catch {
             raw = null;
         }
-        const merged = mergeWorkspaceEntry(readRegistry(raw), entry);
+        const exists = io.exists;
+        // @implements A-SPEC-677 — prune while we are already here. Without an `exists` probe there is
+        // no way to tell gone from present, so the registry is merged unpruned rather than guessed at.
+        const base = exists
+            ? pruneRegistry(readRegistry(raw), { exists, isTemp: (t) => isTempTarget(t, tmpdir) })
+            : { registry: readRegistry(raw), dropped: 0, absent: 0 };
+        const merged = mergeWorkspaceEntry(base.registry, entry);
         io.mkdir(dir);
         io.write(file, `${JSON.stringify(merged, null, 2)}\n`);
+        // Never a silent deletion: whoever asked can learn how many entries went.
+        if (base.dropped > 0)
+            io.onPrune?.(base.dropped);
         return true;
     }
     catch {

package/package.json

@@ -1,7 +1,7 @@
 {
   "//": "@implements A-SPEC-209",
   "name": "@holmes-lab/holmes-kit",
-  "version": "0.23.3",
+  "version": "0.24.1",
   "description": "Holmes-Kit — deterministic Agentic Software Engineering (ASE) harness with causal traceability (spec chain + D-CPG + RTM + phase guardrail)",
   "main": "dist/holmes/mcp/server.js",
   "types": "dist/holmes/mcp/server.d.ts",