forgedock 1.26.0 → 1.28.0

package/bin/lean/depcache.mjs

@@ -0,0 +1,312 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/**
+ * Shared dependency cache (#4220): lanes on one lock hash share one install. Layout under the root
+ * (`FORGE_DEPCACHE_ROOT` or `~/.forge/depcache`):
+ *   <repoKey>/<eco>-<key>/            published snapshot: the trees (node_modules dirs at their relative paths, or .venv)
+ *                                     + manifest.json {eco,key,prefix,trees,created} + last-used. Files are read-only and
+ *                                     never written again; lanes get hardlinks, so an in-place write fails instead of
+ *                                     corrupting it.
+ *   <repoKey>/<eco>-<key>.lock        per-key lock {host,pid,created} (open "wx"; a dead or expired holder is stale)
+ *   <repoKey>/<eco>-<key>.tmp-<pid>   snapshot being published (atomic rename into place)
+ *   stores/{pnpm-store,npm-cache,uv-cache,poetry-cache,pip-cache}   the package managers' own shared stores
+ * The repo's own package manager does every install (frozen lockfile). Every effect is injected; nothing here throws:
+ * a missing tool, another filesystem (EXDEV) or a failed install leaves the lane as it was before.
+ */
+import * as nodeFs from "node:fs";
+import { createHash } from "node:crypto";
+import { homedir, hostname } from "node:os";
+import { join, dirname } from "node:path";
+import { safeSegment } from "./ledger.mjs";
+
+export const depcacheRoot = (env = process.env) => String(env.FORGE_DEPCACHE_ROOT ?? "").trim() || join(homedir(), ".forge", "depcache");
+export const DEPCACHE_INSTALL_TIMEOUT_MS = 15 * 60000;
+export const DEPCACHE_MAX_AGE_MS = 7 * 24 * 3600 * 1000;
+const STORES = "stores";
+const SNAP_RE = /^(pnpm|npm|yarn|uv|poetry)-[0-9a-f]{16}$/;
+const TMP_RE = /^(pnpm|npm|yarn|uv|poetry)-[0-9a-f]{16}\.tmp-(\d+)$/;
+const LOCK_RE = /^(pnpm|npm|yarn|uv|poetry)-[0-9a-f]{16}\.lock$/;
+
+const pidAlive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e?.code === "EPERM"; } };
+const msg = (e) => String(e?.stderr || e?.message || e).trim().split("\n").slice(-3).join(" ").slice(0, 300);
+
+/** Lockfile -> ecosystem, in priority order: at most one JS and one Python ecosystem per repo. */
+function detect(fs, wt) {
+  const has = (f) => fs.existsSync(join(wt, f));
+  const out = [];
+  if (has("pnpm-lock.yaml")) out.push({ eco: "pnpm", lock: "pnpm-lock.yaml" });
+  else if (has("package-lock.json")) out.push({ eco: "npm", lock: "package-lock.json" });
+  else if (has("npm-shrinkwrap.json")) out.push({ eco: "npm", lock: "npm-shrinkwrap.json" });
+  else if (has("yarn.lock")) {
+    const rc = has(".yarnrc.yml") ? String(fs.readFileSync(join(wt, ".yarnrc.yml"))) : null;
+    // Yarn berry defaults to Plug'n'Play (no node_modules): only cache it with an explicit node-modules linker.
+    const pnp = has(".pnp.cjs") || (rc !== null && !/^\s*nodeLinker:\s*["']?(node-modules|pnpm)/m.test(rc));
+    out.push(pnp ? { eco: "yarn", lock: "yarn.lock", skip: "yarn Plug'n'Play has no node_modules" } : { eco: "yarn", lock: "yarn.lock", berry: rc !== null });
+  }
+  if (has("uv.lock")) out.push({ eco: "uv", lock: "uv.lock" });
+  else if (has("poetry.lock")) out.push({ eco: "poetry", lock: "poetry.lock" });
+  return out;
+}
+
+const JS = new Set(["pnpm", "npm", "yarn"]);
+/** Full frozen install on a miss, and the warm no-op repair pass on a hit (null: nothing path-dependent to repair). */
+function commands(d) {
+  switch (d.eco) {
+    case "pnpm": return { install: [["pnpm", ["install", "--frozen-lockfile"]]], repair: [["pnpm", ["install", "--frozen-lockfile", "--offline"]]] };
+    // npm/yarn node_modules hold only relative links; npm's hidden lockfile is rewritten in place, which the read-only
+    // snapshot (correctly) refuses, so they get no repair pass.
+    case "npm": return { install: [["npm", ["ci", "--no-audit", "--no-fund"]]], repair: null };
+    case "yarn": return { install: [["yarn", ["install", d.berry ? "--immutable" : "--frozen-lockfile"]]], repair: null };
+    case "uv": return { install: [["uv", ["venv", "--relocatable", ".venv"]], ["uv", ["sync", "--frozen"]]], repair: [["uv", ["sync", "--frozen"]]] };
+    case "poetry": return { install: [["poetry", ["install", "--sync"]]], repair: [["poetry", ["install", "--sync"]]] };
+    default: return null;
+  }
+}
+
+/**
+ * @param {object} [o]
+ * @param {string} [o.root]   cache root (default FORGE_DEPCACHE_ROOT or ~/.forge/depcache)
+ * @param {Function} o.exec   (cmd, args, {cwd, env, timeoutMs}) => Promise<stdout>; rejects on failure
+ */
+export function makeDepCache({ root = depcacheRoot(), exec, fs = nodeFs, now = () => Date.now(), alive = pidAlive, host = hostname(), pid = process.pid,
+  env: procEnv = process.env, installTimeoutMs = DEPCACHE_INSTALL_TIMEOUT_MS, lockWaitMs = DEPCACHE_INSTALL_TIMEOUT_MS, pollMs = 1000,
+  sleep = (ms) => new Promise((r) => setTimeout(r, ms)) } = {}) {
+  const disabled = () => String(procEnv.FORGE_DEPCACHE ?? "").trim() === "0";
+  const store = (n) => join(root, STORES, n);
+
+  /** Shared package-manager stores for every runner call, so the builder's own installs reuse them too. */
+  function env() {
+    if (disabled()) return {};
+    return { npm_config_store_dir: store("pnpm-store"), npm_config_cache: store("npm-cache"), UV_CACHE_DIR: store("uv-cache"), UV_LINK_MODE: "hardlink",
+      POETRY_CACHE_DIR: store("poetry-cache"), PIP_CACHE_DIR: store("pip-cache"), POETRY_VIRTUALENVS_IN_PROJECT: "true" };
+  }
+  const run = (cmd, args, cwd) => exec(cmd, args, { cwd, env: env(), timeoutMs: installTimeoutMs });
+  const runtime = async (cmd) => { try { return String(await exec(cmd, ["--version"], { timeoutMs: 30000 })).trim(); } catch { return "unknown"; } };
+
+  /** Tracked package.json files (workspace members), relative; root only when git cannot list them. */
+  async function manifests(wt) {
+    try {
+      const out = String(await exec("git", ["ls-files", "-z", "--", "package.json", ":(glob)**/package.json"], { cwd: wt, timeoutMs: 60000 }));
+      const l = [...new Set(out.split("\0").map((s) => s.trim()).filter((s) => s && !s.split("/").includes("node_modules")))].sort();
+      if (l.length) return l;
+    } catch { /* not a git checkout */ }
+    return ["package.json"];
+  }
+
+  async function keyOf(wt, d, pkgs) {
+    const h = createHash("sha256").update(`v1\0${d.eco}\0${process.platform}-${process.arch}\0`);
+    h.update(await runtime(JS.has(d.eco) ? "node" : "python3")).update("\0");
+    const files = JS.has(d.eco) ? [d.lock, ...pkgs, "pnpm-workspace.yaml", ".npmrc", ".yarnrc.yml"] : [d.lock, "pyproject.toml", ".python-version"];
+    for (const f of files) {
+      h.update(`${f}\0`);
+      try { h.update(fs.readFileSync(join(wt, f))); } catch { h.update("<absent>"); }
+      h.update("\0");
+    }
+    return h.digest("hex").slice(0, 16);
+  }
+
+  // ---- per-key lock ----
+  function tryLock(path) {
+    try {
+      const fd = fs.openSync(path, "wx");
+      try { fs.writeSync(fd, JSON.stringify({ host, pid, created: now() })); } finally { fs.closeSync(fd); }
+      return true;
+    } catch (e) { if (e?.code !== "EEXIST") throw e; }
+    let held = null;
+    try { held = JSON.parse(String(fs.readFileSync(path))); } catch { /* being written or garbage: stale only when old */ }
+    let mtime = now();
+    try { mtime = fs.statSync(path).mtimeMs; } catch { return false; }
+    const stale = held ? ((held.host === host && !alive(held.pid)) || now() - Number(held.created) > installTimeoutMs * 2) : now() - mtime > 60000;
+    if (!stale) return false;
+    try { fs.rmSync(path, { force: true }); } catch { return false; }
+    return tryLock(path);
+  }
+  async function withLock(path, fn, { wait = true } = {}) {
+    const t0 = now();
+    for (;;) {
+      if (tryLock(path)) break;
+      if (!wait || now() - t0 >= lockWaitMs) return { locked: false };
+      await sleep(pollMs);
+    }
+    try { return { locked: true, value: await fn() }; } finally { try { fs.rmSync(path, { force: true }); } catch { /* best effort */ } }
+  }
+
+  // ---- trees ----
+  const boundary = (p) => new RegExp(p.replace(/[.*+?^${}()|[\]\\]/g, "\\$&") + "(?=$|[/\\\\'\"\\s:;])", "g");
+  /** Hardlink `src` into `dst`; symlinks recreated; files in bin dirs that name `from` are copied with `to` instead. */
+  function linkTree(src, dst, { from = null, to = null, binDir = () => false } = {}) {
+    const re = from && to && from !== to ? boundary(from) : null;
+    const walk = (s, d, rel) => {
+      fs.mkdirSync(d, { recursive: true });
+      for (const ent of fs.readdirSync(s, { withFileTypes: true })) {
+        const sp = join(s, ent.name), dp = join(d, ent.name), r = rel ? `${rel}/${ent.name}` : ent.name;
+        if (ent.isSymbolicLink()) {
+          const t = String(fs.readlinkSync(sp));
+          fs.symlinkSync(re ? t.replace(re, to) : t, dp);
+        } else if (ent.isDirectory()) walk(sp, dp, r);
+        else if (ent.isFile()) {
+          if (re && binDir(rel)) {
+            const buf = fs.readFileSync(sp);
+            if (!buf.includes(0) && buf.includes(from)) {
+              fs.writeFileSync(dp, String(buf).replace(re, to), { mode: (fs.statSync(sp).mode & 0o7777) | 0o200 });
+              continue;
+            }
+          }
+          fs.linkSync(sp, dp);
+        }
+      }
+    };
+    walk(src, dst, "");
+  }
+  function readOnly(dir) {
+    for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = join(dir, ent.name);
+      if (ent.isDirectory()) readOnly(p);
+      else if (ent.isFile()) fs.chmodSync(p, fs.statSync(p).mode & 0o7555);
+    }
+  }
+  /** Trees an ecosystem installs: every existing node_modules next to a tracked package.json, or the project .venv. */
+  const treesOf = (wt, d, pkgs) => (JS.has(d.eco) ? pkgs.map((p) => (dirname(p) === "." ? "node_modules" : `${dirname(p)}/node_modules`)) : [".venv"])
+    .filter((t, i, a) => a.indexOf(t) === i && fs.existsSync(join(wt, t)));
+  const binDirFor = (d) => (JS.has(d.eco) ? (rel) => rel.split("/").includes(".bin") : (rel) => rel === "bin");
+  const rmTrees = (wt, trees) => { for (const t of trees) { try { fs.rmSync(join(wt, t), { recursive: true, force: true }); } catch { /* best effort */ } } };
+
+  function publish(wt, d, key, trees, snap) {
+    const tmp = `${snap}.tmp-${pid}`;
+    try {
+      fs.rmSync(tmp, { recursive: true, force: true });
+      for (const t of trees) linkTree(join(wt, t), join(tmp, t));
+      readOnly(tmp);
+      fs.writeFileSync(join(tmp, "manifest.json"), JSON.stringify({ v: 1, eco: d.eco, key, prefix: wt, trees, created: now() }) + "\n");
+      fs.writeFileSync(join(tmp, "last-used"), String(now()));
+      try { fs.renameSync(tmp, snap); } catch (e) {
+        if (!fs.existsSync(join(snap, "manifest.json"))) throw e;
+        fs.rmSync(tmp, { recursive: true, force: true }); // another lane published first: never write into its snapshot
+      }
+      return null;
+    } catch (e) {
+      try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* best effort */ }
+      return e?.code === "EXDEV" ? "cache is on another filesystem than the worktree (EXDEV)" : `publish failed: ${msg(e)}`;
+    }
+  }
+
+  async function prepareOne(wt, keyRoot, d) {
+    const t0 = now();
+    const done = (status, extra = {}) => ({ status, eco: d.eco, key: extra.key ?? null, ms: now() - t0, reason: extra.reason ?? null, ...(extra.published === undefined ? {} : { published: extra.published }) });
+    if (d.skip) return done("skipped", { reason: d.skip });
+    const pkgs = JS.has(d.eco) ? await manifests(wt) : [];
+    const key = await keyOf(wt, d, pkgs);
+    const snap = join(keyRoot, `${d.eco}-${key}`);
+    const cmds = commands(d);
+    const expected = JS.has(d.eco) ? [...new Set(pkgs.map((p) => (dirname(p) === "." ? "node_modules" : `${dirname(p)}/node_modules`)))] : [".venv"];
+    const existing = expected.filter((t) => fs.existsSync(join(wt, t)));
+    if (existing.length) return done("skipped", { key, reason: `${existing[0]} already exists in the worktree` });
+    fs.mkdirSync(keyRoot, { recursive: true, mode: 0o700 });
+
+    const materialize = async () => {
+      let man;
+      try { man = JSON.parse(String(fs.readFileSync(join(snap, "manifest.json")))); } catch { return null; }
+      const created = [];
+      try {
+        for (const t of man.trees ?? []) { created.push(t); linkTree(join(snap, t), join(wt, t), { from: man.prefix, to: wt, binDir: binDirFor(d) }); }
+        for (const [c, a] of cmds.repair ?? []) await run(c, a, wt);
+        try { fs.writeFileSync(join(snap, "last-used"), String(now())); } catch { /* best effort */ }
+        return done("hit", { key });
+      } catch (e) {
+        rmTrees(wt, created);
+        return done(e?.code === "EXDEV" ? "skipped" : "failed", { key, reason: e?.code === "EXDEV" ? "cache is on another filesystem than the worktree (EXDEV)" : `materialize failed: ${msg(e)}` });
+      }
+    };
+    const install = async () => {
+      try { for (const [c, a] of cmds.install) await run(c, a, wt); } catch (e) {
+        rmTrees(wt, expected);
+        return { failed: done("failed", { key, reason: `${e?.code === "ENOENT" ? "tool not found" : "install failed"}: ${msg(e)}` }) };
+      }
+      return { trees: treesOf(wt, d, pkgs) };
+    };
+
+    const lockPath = `${snap}.lock`;
+    const r = await withLock(lockPath, async () => {
+      if (fs.existsSync(join(snap, "manifest.json"))) return materialize(); // hit, or another lane published while we waited
+      const ins = await install();
+      if (ins.failed) return ins.failed;
+      if (!ins.trees.length) return done("miss-installed", { key, published: false, reason: "the install produced no node_modules/.venv" });
+      const why = publish(wt, d, key, ins.trees, snap);
+      return done("miss-installed", { key, published: !why, reason: why });
+    });
+    if (r.locked) return r.value ?? done("failed", { key, reason: "snapshot manifest unreadable" });
+    // The lock stayed busy past the wait: install in this lane without touching the cache.
+    const ins = await install();
+    return ins.failed ?? done("miss-installed", { key, published: false, reason: "cache lock busy" });
+  }
+
+  /** Materialize or build node_modules/.venv for `wt`; one result per detected ecosystem. Never throws. */
+  async function prepare({ wt, repoKey } = {}) {
+    if (disabled()) return [{ status: "skipped", eco: null, key: null, ms: 0, reason: "FORGE_DEPCACHE=0" }];
+    let found;
+    try { found = detect(fs, wt); } catch (e) { return [{ status: "failed", eco: null, key: null, ms: 0, reason: msg(e) }]; }
+    if (!found.length) return [{ status: "skipped", eco: null, key: null, ms: 0, reason: "no lockfile" }];
+    const keyRoot = join(root, safeSegment(repoKey ?? "repo"));
+    const out = [];
+    for (const d of found) {
+      try { out.push(await prepareOne(wt, keyRoot, d)); } catch (e) { out.push({ status: "failed", eco: d.eco, key: null, ms: 0, reason: msg(e) }); }
+    }
+    return out;
+  }
+
+  /**
+   * Read-only scan for the reaper: snapshots unused for maxAgeMs, tmp dirs of dead publishers, locks of dead holders on
+   * this host. Only names this module creates are listed. Each entry: {name, path, kind: snapshot|tmp|lock, ageMs, locked?, reason};
+   * a snapshot whose lock a live (or other-host) holder owns is listed with locked: true and is never removed.
+   */
+  function scan({ maxAgeMs = DEPCACHE_MAX_AGE_MS } = {}) {
+    const out = [];
+    let repos = [];
+    try { repos = fs.readdirSync(root).filter((n) => n !== STORES); } catch { return out; }
+    for (const rk of repos) {
+      const dir = join(root, rk);
+      let names = [];
+      try { if (!fs.lstatSync(dir).isDirectory()) continue; names = fs.readdirSync(dir); } catch { continue; }
+      for (const n of names) {
+        const p = join(dir, n), name = `${rk}/${n}`;
+        try {
+          const tm = TMP_RE.exec(n);
+          if (tm) { if (!alive(Number(tm[2]))) out.push({ name, path: p, kind: "tmp", ageMs: null, reason: "publisher dead" }); continue; }
+          if (LOCK_RE.test(n)) {
+            const held = JSON.parse(String(fs.readFileSync(p)));
+            if (held.host === host && !alive(held.pid)) out.push({ name, path: p, kind: "lock", ageMs: now() - Number(held.created), reason: "lock holder dead" });
+            continue;
+          }
+          if (!SNAP_RE.test(n) || !fs.existsSync(join(p, "manifest.json"))) continue;
+          let last = 0;
+          try { last = Number(String(fs.readFileSync(join(p, "last-used")))); } catch { /* fall back to created */ }
+          if (!Number.isFinite(last) || last <= 0) last = Number(JSON.parse(String(fs.readFileSync(join(p, "manifest.json")))).created) || 0;
+          if (now() - last < maxAgeMs) continue;
+          let locked = false;
+          try { const h = JSON.parse(String(fs.readFileSync(`${p}.lock`))); locked = !(h.host === host && !alive(h.pid)); } catch { /* no lock */ }
+          out.push({ name, path: p, kind: "snapshot", ageMs: now() - last, locked, reason: locked ? "locked by a live lane" : "snapshot unused" });
+        } catch { /* unreadable or not ours: leave it */ }
+      }
+    }
+    return out;
+  }
+
+  /** Remove one scanned entry; a snapshot only while holding its lock. Returns false when it is locked or not ours. */
+  async function remove(entry) {
+    const p = String(entry?.path ?? "");
+    if (!p.startsWith(root + "/") || p.slice(root.length + 1).split("/").length !== 2) return false;
+    if (entry.kind === "snapshot") return (await withLock(`${p}.lock`, async () => { fs.rmSync(p, { recursive: true, force: true }); return true; }, { wait: false })).locked;
+    fs.rmSync(p, { recursive: true, force: true });
+    return true;
+  }
+
+  /** scan + remove: snapshots unused for maxAgeMs (taking their lock), dead publishers' tmp dirs, stale locks. Returns names. */
+  async function prune({ maxAgeMs = DEPCACHE_MAX_AGE_MS } = {}) {
+    const removed = [];
+    for (const e of scan({ maxAgeMs })) { if (e.locked) continue; try { if (await remove(e)) removed.push(e.name); } catch { /* leave it */ } }
+    return removed;
+  }
+
+  return { env, prepare, prune, scan, remove, root };
+}
+

package/bin/lean/depcache.test.mjs

@@ -0,0 +1,298 @@
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+/** #4220 shared dependency cache: JS (pnpm/npm) and Python (uv/poetry) fixture repos, fake installers (no real tools). */
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import { mkdirSync, writeFileSync, readFileSync, existsSync, statSync, lstatSync, readlinkSync, readdirSync, symlinkSync, rmSync, renameSync } from "node:fs";
+import { tmpDir } from "../tests/_tmp.mjs";
+import { join, dirname, relative } from "node:path";
+import { makeDepCache } from "./depcache.mjs";
+
+const scratch = () => tmpDir("fd-depcache-");
+const put = (p, text, mode) => { mkdirSync(dirname(p), { recursive: true }); writeFileSync(p, text, mode ? { mode } : undefined); };
+/** Replace a file the way package managers do (tmp + rename), never writing into the existing inode. */
+const replace = (p, text) => { put(`${p}.new`, text); renameSync(`${p}.new`, p); };
+
+const FIXTURES = {
+  pnpm(wt, lock = "lockfileVersion: 9\nlodash: 4.17.21\n") {
+    put(join(wt, "package.json"), '{"name":"web","private":true}');
+    put(join(wt, "pnpm-workspace.yaml"), "packages:\n  - packages/*\n");
+    put(join(wt, "packages/a/package.json"), '{"name":"a"}');
+    put(join(wt, "pnpm-lock.yaml"), lock);
+  },
+  npm(wt, lock = '{"lockfileVersion":3,"packages":{"node_modules/left-pad":{"version":"1.3.0"}}}') {
+    put(join(wt, "package.json"), '{"name":"app"}');
+    put(join(wt, "package-lock.json"), lock);
+  },
+  uv(wt, lock = 'version = 1\n[[package]]\nname = "requests"\nversion = "2.32.0"\n') {
+    put(join(wt, "pyproject.toml"), '[project]\nname = "proj"\nversion = "0.1.0"\n');
+    put(join(wt, "uv.lock"), lock);
+  },
+  poetry(wt, lock = '[[package]]\nname = "requests"\nversion = "2.32.0"\n') {
+    put(join(wt, "pyproject.toml"), '[tool.poetry]\nname = "proj"\nversion = "0.1.0"\n');
+    put(join(wt, "poetry.lock"), lock);
+  },
+};
+const LOCKFILE = { pnpm: "pnpm-lock.yaml", npm: "package-lock.json", uv: "uv.lock", poetry: "poetry.lock" };
+
+/** Fake package managers: write what a real install leaves behind, including the absolute paths that need rewriting. */
+function fakeExec({ failInstall = false, installDelayMs = 0 } = {}) {
+  const calls = [];
+  const venv = (cwd, lock) => {
+    const v = join(cwd, ".venv");
+    if (!existsSync(join(v, "pyvenv.cfg"))) put(join(v, "pyvenv.cfg"), "home = /usr/bin\n");
+    // Satisfied dependencies are left alone (a warm sync over a complete venv); only missing files are written.
+    const once = (p, text, mode) => { if (!existsSync(p)) put(p, text, mode); };
+    once(join(v, "lib/python3.12/site-packages/requests/__init__.py"), `# ${lock.length}\n`);
+    once(join(v, "bin/pytest"), `#!${v}/bin/python\nimport pytest\n`, 0o755);
+    once(join(v, "bin/activate"), `VIRTUAL_ENV='${v}'\n`);
+    if (!existsSync(join(v, "bin/python"))) symlinkSync("/usr/bin/python3", join(v, "bin/python"));
+    replace(join(v, "lib/python3.12/site-packages/_proj.pth"), `${cwd}/src\n`); // editable project: per worktree
+  };
+  const exec = async (cmd, args, { cwd } = {}) => {
+    calls.push({ cmd, args: [...args], cwd });
+    if (cmd === "git" && args[0] === "ls-files") {
+      const out = [];
+      const walk = (d) => { for (const e of readdirSync(d, { withFileTypes: true })) { if (e.name === "node_modules" || e.name.startsWith(".")) continue; const p = join(d, e.name); if (e.isDirectory()) walk(p); else if (e.name === "package.json") out.push(relative(cwd, p)); } };
+      walk(cwd);
+      return out.join("\0");
+    }
+    if (args[0] === "--version") return cmd === "node" ? "v22.1.0\n" : "Python 3.12.3\n";
+    const full = (cmd === "pnpm" && args.includes("--frozen-lockfile") && !args.includes("--offline")) || (cmd === "npm" && args[0] === "ci")
+      || (cmd === "uv" && args[0] === "venv") || (cmd === "poetry" && !existsSync(join(cwd, ".venv")));
+    if (full && installDelayMs) await new Promise((r) => setTimeout(r, installDelayMs));
+    if (full && failInstall) { put(join(cwd, cmd === "uv" || cmd === "poetry" ? ".venv/partial" : "node_modules/partial"), "x"); throw Object.assign(new Error("install failed"), { stderr: "ERR_PNPM_FROZEN_LOCKFILE" }); }
+    if (cmd === "pnpm") {
+      if (args.includes("--offline")) return ""; // warm repair pass: nothing to do
+      const lock = readFileSync(join(cwd, "pnpm-lock.yaml"), "utf8");
+      put(join(cwd, "node_modules/.pnpm/lodash@4/node_modules/lodash/index.js"), `module.exports = ${JSON.stringify(lock)};\n`);
+      symlinkSync(".pnpm/lodash@4/node_modules/lodash", join(cwd, "node_modules/lodash"));
+      put(join(cwd, "node_modules/.bin/lodash"), `#!/bin/sh\nexport NODE_PATH="${cwd}/node_modules/.pnpm/node_modules"\nexec node "$basedir/../lodash/cli.js"\n`, 0o755);
+      put(join(cwd, "node_modules/.modules.yaml"), "layoutVersion: 5\n");
+      mkdirSync(join(cwd, "packages/a/node_modules"), { recursive: true });
+      symlinkSync("../../../node_modules/.pnpm/lodash@4/node_modules/lodash", join(cwd, "packages/a/node_modules/lodash"));
+      return "";
+    }
+    if (cmd === "npm") {
+      put(join(cwd, "node_modules/left-pad/index.js"), `// ${readFileSync(join(cwd, "package-lock.json"), "utf8").length}\n`);
+      put(join(cwd, "node_modules/left-pad/cli.js"), "#!/usr/bin/env node\n", 0o755);
+      mkdirSync(join(cwd, "node_modules/.bin"), { recursive: true });
+      symlinkSync("../left-pad/cli.js", join(cwd, "node_modules/.bin/left-pad"));
+      return "";
+    }
+    if (cmd === "uv" && args[0] === "venv") { put(join(cwd, ".venv/pyvenv.cfg"), "home = /usr/bin\nrelocatable = true\n"); return ""; }
+    if (cmd === "uv" || cmd === "poetry") { venv(cwd, readFileSync(join(cwd, cmd === "uv" ? "uv.lock" : "poetry.lock"), "utf8")); return ""; }
+    throw Object.assign(new Error(`spawn ${cmd} ENOENT`), { code: "ENOENT" });
+  };
+  return { exec, calls, installs: () => calls.filter((c) => c.cmd !== "git" && c.args[0] !== "--version") };
+}
+
+/** path -> {ino, content} for every regular file, symlink target for links: a byte- and inode-exact picture of a tree. */
+function snapshotOf(dir) {
+  const out = {};
+  const walk = (d) => {
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      const p = join(d, e.name), r = relative(dir, p);
+      if (e.isSymbolicLink()) out[r] = `-> ${readlinkSync(p)}`;
+      else if (e.isDirectory()) walk(p);
+      else { const s = statSync(p); out[r] = `${s.ino}:${s.mode.toString(8)}:${readFileSync(p, "utf8")}`; }
+    }
+  };
+  walk(dir);
+  return out;
+}
+const snapDirs = (root, eco) => {
+  const out = [];
+  for (const rk of existsSync(root) ? readdirSync(root) : []) {
+    if (rk === "stores") continue;
+    for (const n of readdirSync(join(root, rk))) if (new RegExp(`^${eco}-[0-9a-f]{16}$`).test(n)) out.push(join(root, rk, n));
+  }
+  return out;
+};
+const isRoot = typeof process.getuid === "function" && process.getuid() === 0;
+const setup = (eco, o = {}) => {
+  const base = scratch(), root = join(base, "cache");
+  const f = fakeExec(o);
+  const cache = makeDepCache({ root, exec: f.exec, env: {}, pollMs: 5, lockWaitMs: o.lockWaitMs ?? 5000, ...(o.cache ?? {}) });
+  const lane = (name, lock) => { const wt = join(base, "wt", name); mkdirSync(wt, { recursive: true }); FIXTURES[eco](wt, lock); return wt; };
+  return { base, root, f, cache, lane };
+};
+
+describe("depcache (#4220): shared dependency installs keyed by lock hash", () => {
+  for (const eco of ["pnpm", "npm", "uv", "poetry"]) {
+    it(`${eco}: a miss installs once and publishes; a lane on the same lock hardlinks it and runs no install`, async () => {
+      const { root, f, cache, lane } = setup(eco);
+      const a = lane("lean-1");
+      const [ra] = await cache.prepare({ wt: a, repoKey: "repo-1" });
+      assert.equal(ra.status, "miss-installed", JSON.stringify(ra));
+      assert.equal(ra.published, true);
+      assert.equal(ra.eco, eco);
+      const [snap] = snapDirs(root, eco);
+      assert.ok(snap && existsSync(join(snap, "manifest.json")));
+      const fullInstalls = f.installs().length;
+      assert.ok(fullInstalls >= 1);
+
+      const b = lane("lean-2");
+      const [rb] = await cache.prepare({ wt: b, repoKey: "repo-1" });
+      assert.equal(rb.status, "hit", JSON.stringify(rb));
+      assert.equal(rb.key, ra.key);
+      const after = f.installs().slice(fullInstalls);
+      // ≈ 0 install: only the warm repair pass (pnpm --offline / uv sync / poetry install over a complete venv), never a full install.
+      for (const c of after) assert.ok(!(c.cmd === "npm" && c.args[0] === "ci") && !(c.cmd === "pnpm" && !c.args.includes("--offline")) && !(c.cmd === "uv" && c.args[0] === "venv"), `full install on a hit: ${c.cmd} ${c.args.join(" ")}`);
+      if (eco === "npm") assert.equal(after.length, 0, "npm has no repair pass");
+
+      if (eco === "pnpm" || eco === "npm") {
+        const file = eco === "pnpm" ? "node_modules/.pnpm/lodash@4/node_modules/lodash/index.js" : "node_modules/left-pad/index.js";
+        assert.equal(statSync(join(b, file)).ino, statSync(join(snap, file)).ino, "node_modules files are hardlinks of the snapshot");
+        assert.equal(statSync(join(b, file)).ino, statSync(join(a, file)).ino);
+        if (eco === "pnpm") {
+          assert.equal(readlinkSync(join(b, "node_modules/lodash")), ".pnpm/lodash@4/node_modules/lodash");
+          assert.ok(lstatSync(join(b, "packages/a/node_modules/lodash")).isSymbolicLink(), "workspace member node_modules are materialized too");
+          const shim = readFileSync(join(b, "node_modules/.bin/lodash"), "utf8");
+          assert.ok(shim.includes(`${b}/node_modules/.pnpm`) && !shim.includes(`${a}/`), ".bin shims point at this lane");
+          assert.notEqual(statSync(join(b, "node_modules/.bin/lodash")).ino, statSync(join(snap, "node_modules/.bin/lodash")).ino);
+        }
+      } else {
+        const sp = ".venv/lib/python3.12/site-packages/requests/__init__.py";
+        assert.equal(statSync(join(b, sp)).ino, statSync(join(snap, sp)).ino, "venv files are hardlinks of the snapshot");
+        assert.equal(readFileSync(join(b, ".venv/bin/pytest"), "utf8").split("\n")[0], `#!${b}/.venv/bin/python`, "console scripts point at this lane's venv");
+        assert.ok(readFileSync(join(b, ".venv/bin/activate"), "utf8").includes(`'${b}/.venv'`));
+        assert.equal(readlinkSync(join(b, ".venv/bin/python")), "/usr/bin/python3");
+        assert.equal(readFileSync(join(b, ".venv/lib/python3.12/site-packages/_proj.pth"), "utf8"), `${b}/src\n`, "the repair pass reinstalls the project for this lane");
+        assert.ok(after.length >= 1, "repair pass ran");
+      }
+    });
+  }
+
+  it("REGRESSION: a lane whose lockfile changed gets its own install and never corrupts the shared snapshot", async () => {
+    for (const eco of ["pnpm", "uv"]) {
+      const { root, f, cache, lane } = setup(eco);
+      const a = lane("lean-1");
+      const [ra] = await cache.prepare({ wt: a, repoKey: "r" });
+      const b = lane("lean-2");
+      assert.equal((await cache.prepare({ wt: b, repoKey: "r" }))[0].status, "hit");
+      const [snapA] = snapDirs(root, eco);
+      const before = snapshotOf(snapA);
+
+      const n = f.installs().length;
+      const c = lane("lean-3", eco === "pnpm" ? "lockfileVersion: 9\nlodash: 4.17.22\n" : 'version = 1\n[[package]]\nname = "requests"\nversion = "2.33.0"\n');
+      const [rc] = await cache.prepare({ wt: c, repoKey: "r" });
+      assert.equal(rc.status, "miss-installed", JSON.stringify(rc));
+      assert.notEqual(rc.key, ra.key, "a changed lockfile is a different key");
+      assert.ok(f.installs().slice(n).some((x) => (x.cmd === "pnpm" && !x.args.includes("--offline")) || (x.cmd === "uv" && x.args[0] === "venv")), "own full install");
+      assert.equal(snapDirs(root, eco).length, 2);
+
+      // A lane writing in place into a linked file fails instead of changing the shared inode.
+      const linked = eco === "pnpm" ? join(b, "node_modules/.pnpm/lodash@4/node_modules/lodash/index.js") : join(b, ".venv/lib/python3.12/site-packages/requests/__init__.py");
+      if (!isRoot) assert.throws(() => writeFileSync(linked, "corrupted"), (e) => e.code === "EACCES");
+      // Package-manager style replacement and deleting a lane's tree only unlink that lane's links.
+      replace(linked, "lane B's own copy");
+      rmSync(join(b, eco === "pnpm" ? "node_modules" : ".venv"), { recursive: true, force: true });
+      rmSync(join(a, eco === "pnpm" ? "node_modules" : ".venv"), { recursive: true, force: true });
+      assert.deepEqual(snapshotOf(snapA), before, "snapshot A is byte- and inode-identical");
+
+      const d = lane("lean-4");
+      assert.equal((await cache.prepare({ wt: d, repoKey: "r" }))[0].status, "hit", "the original lock still hits");
+    }
+  });
+
+  it("concurrent lanes on one key: one install, one snapshot, no tmp left; a dead holder's lock is taken over", async () => {
+    const { root, f, cache, lane } = setup("npm", { installDelayMs: 60 });
+    const lanes = ["l1", "l2", "l3"].map((n) => lane(n));
+    const rs = (await Promise.all(lanes.map((wt) => cache.prepare({ wt, repoKey: "r" })))).map((x) => x[0]);
+    assert.equal(f.calls.filter((c) => c.cmd === "npm" && c.args[0] === "ci").length, 1);
+    assert.deepEqual(rs.map((r) => r.status).sort(), ["hit", "hit", "miss-installed"]);
+    for (const wt of lanes) assert.ok(existsSync(join(wt, "node_modules/left-pad/index.js")));
+    const names = readdirSync(join(root, "r"));
+    assert.equal(names.filter((n) => /^npm-[0-9a-f]{16}$/.test(n)).length, 1);
+    assert.equal(names.filter((n) => /\.tmp-|\.lock$/.test(n)).length, 0, names.join(","));
+
+    const s2 = setup("npm", { cache: { alive: () => false } });
+    const wt = s2.lane("x");
+    const key = (await makeDepCache({ root: join(s2.base, "probe"), exec: s2.f.exec, env: {} }).prepare({ wt: s2.lane("probe"), repoKey: "r" }))[0].key;
+    put(join(s2.root, "r", `npm-${key}.lock`), JSON.stringify({ host: (await import("node:os")).hostname(), pid: 999999, created: Date.now() }));
+    const [r] = await s2.cache.prepare({ wt, repoKey: "r" });
+    assert.equal(r.status, "miss-installed");
+    assert.equal(r.published, true, "the stale lock was replaced");
+  });
+
+  it("a failed install, a missing tool or another filesystem leaves no snapshot and no partial tree", async () => {
+    const s = setup("pnpm", { failInstall: true });
+    const wt = s.lane("x");
+    const [r] = await s.cache.prepare({ wt, repoKey: "r" });
+    assert.equal(r.status, "failed");
+    assert.match(r.reason, /install failed/);
+    assert.ok(!existsSync(join(wt, "node_modules")));
+    assert.equal(snapDirs(s.root, "pnpm").length, 0);
+
+    const s2 = setup("npm");
+    const exdev = { ...fs, linkSync: () => { throw Object.assign(new Error("EXDEV: cross-device link"), { code: "EXDEV" }); } };
+    const c2 = makeDepCache({ root: s2.root, exec: s2.f.exec, env: {}, fs: exdev });
+    const wt2 = s2.lane("y");
+    const [r2] = await c2.prepare({ wt: wt2, repoKey: "r" });
+    assert.equal(r2.status, "miss-installed");
+    assert.equal(r2.published, false);
+    assert.match(r2.reason, /EXDEV/);
+    assert.ok(existsSync(join(wt2, "node_modules/left-pad/index.js")), "the lane keeps its own install");
+    assert.equal(snapDirs(s2.root, "npm").length, 0);
+    assert.deepEqual(readdirSync(join(s2.root, "r")), [], "no tmp or lock left");
+    // A published snapshot that cannot be linked (EXDEV) is skipped and leaves nothing half-linked.
+    await s2.cache.prepare({ wt: s2.lane("z"), repoKey: "r" });
+    const wt3 = s2.lane("w");
+    const [r3] = await c2.prepare({ wt: wt3, repoKey: "r" });
+    assert.equal(r3.status, "skipped");
+    assert.ok(!existsSync(join(wt3, "node_modules")));
+
+    const s4 = setup("npm");
+    const c4 = makeDepCache({ root: s4.root, exec: async (cmd, args) => { if (cmd === "git" || args[0] === "--version") return s4.f.exec(cmd, args, { cwd: s4.base }); throw Object.assign(new Error("spawn npm ENOENT"), { code: "ENOENT" }); }, env: {} });
+    const [r4] = await c4.prepare({ wt: s4.lane("v"), repoKey: "r" });
+    assert.equal(r4.status, "failed");
+    assert.match(r4.reason, /tool not found/);
+  });
+
+  it("no lockfile, yarn Plug'n'Play, an existing node_modules and FORGE_DEPCACHE=0 are skipped untouched", async () => {
+    const s = setup("npm");
+    const empty = join(s.base, "empty"); mkdirSync(empty);
+    assert.deepEqual((await s.cache.prepare({ wt: empty, repoKey: "r" })).map((r) => [r.status, r.reason]), [["skipped", "no lockfile"]]);
+    const y = join(s.base, "yarn"); put(join(y, "package.json"), "{}"); put(join(y, "yarn.lock"), "# yarn"); put(join(y, ".yarnrc.yml"), "yarnPath: x\n");
+    assert.equal((await s.cache.prepare({ wt: y, repoKey: "r" }))[0].status, "skipped");
+    const pre = s.lane("pre"); put(join(pre, "node_modules/keep.js"), "mine");
+    const [r] = await s.cache.prepare({ wt: pre, repoKey: "r" });
+    assert.equal(r.status, "skipped");
+    assert.equal(readFileSync(join(pre, "node_modules/keep.js"), "utf8"), "mine");
+    const off = makeDepCache({ root: s.root, exec: s.f.exec, env: { FORGE_DEPCACHE: "0" } });
+    assert.equal((await off.prepare({ wt: s.lane("off"), repoKey: "r" }))[0].status, "skipped");
+    assert.deepEqual(off.env(), {});
+    assert.equal(s.f.installs().length, 0);
+    const e = s.cache.env();
+    for (const k of ["npm_config_store_dir", "npm_config_cache", "UV_CACHE_DIR", "POETRY_CACHE_DIR", "PIP_CACHE_DIR"]) assert.ok(e[k].startsWith(join(s.root, "stores")), k);
+  });
+
+  it("prune removes unused unlocked snapshots, dead publishers' tmp dirs and dead locks; keeps fresh or locked ones", async () => {
+    let clock = Date.now();
+    const s = setup("npm", { cache: { now: () => clock } });
+    await s.cache.prepare({ wt: s.lane("a"), repoKey: "r" });
+    await s.cache.prepare({ wt: s.lane("b", '{"lockfileVersion":3,"other":1}'), repoKey: "r" });
+    const [old, fresh] = snapDirs(s.root, "npm");
+    clock += 8 * 24 * 3600 * 1000;
+    writeFileSync(join(fresh, "last-used"), String(clock));
+    put(`${old}.tmp-999999`, "x");
+    const alive = (pid) => pid === process.pid;
+    const pruner = makeDepCache({ root: s.root, exec: s.f.exec, env: {}, now: () => clock, alive });
+    writeFileSync(`${fresh}.lock`, JSON.stringify({ host: (await import("node:os")).hostname(), pid: process.pid, created: clock }));
+    const removed = await pruner.prune();
+    assert.ok(!existsSync(old), "old snapshot removed (read-only files and all)");
+    assert.ok(existsSync(fresh), "recently used snapshot kept");
+    assert.ok(!existsSync(`${old}.tmp-999999`));
+    assert.equal(removed.length, 2);
+    // A locked old snapshot is kept: someone is materializing or publishing it.
+    clock += 8 * 24 * 3600 * 1000;
+    writeFileSync(`${fresh}.lock`, JSON.stringify({ host: (await import("node:os")).hostname(), pid: process.pid, created: clock }));
+    assert.deepEqual(await pruner.prune(), []);
+    assert.ok(existsSync(fresh));
+    rmSync(`${fresh}.lock`);
+    assert.equal((await pruner.prune()).length, 1);
+    assert.ok(!existsSync(fresh));
+  });
+});