wyvrnpm 2.10.2 → 2.12.2

package/src/build/cache.js

@@ -1,344 +1,344 @@
-'use strict';
-
-const fs   = require('fs');
-const path = require('path');
-const os   = require('os');
-
-/**
- * Root directory for the wyvrnpm source-build cache.
- *   Windows: %LOCALAPPDATA%\wyvrnpm\bc\           (short name — Windows 260-char path limits bite nested CMake builds)
- *   Unix   : ~/.cache/wyvrnpm/bc/
- *
- * @returns {string}
- */
-function getBuildCacheRoot() {
-  const base = process.env.LOCALAPPDATA
-    ? path.join(process.env.LOCALAPPDATA, 'wyvrnpm')
-    : path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'wyvrnpm');
-  return path.join(base, 'bc');
-}
-
-/**
- * Per-build cache directory, keyed by `(name, version, profileHash)`. Each
- * consumer profile gets its own cache line because the toolchain's output
- * differs per profile.
- *
- * Layout inside this dir:
- *   src/               git clone
- *   wyvrn_internal/    package's own deps + generated toolchain
- *   build/             cmake -B
- *   build/install/     cmake install prefix → zipped as the artefact
- *   wyvrn.zip          final artefact (treated as if downloaded)
- *
- * @param {{ name: string, version: string, profileHash: string }} args
- * @returns {string}
- */
-function getPackageBuildDir({ name, version, profileHash }) {
-  // Sanitise — names should be filesystem-safe already, but guard against
-  // accidental path traversal.
-  const safeName    = name.replace(/[^\w.-]/g, '_');
-  const safeVersion = version.replace(/[^\w.-]/g, '_');
-  const safeHash    = profileHash.replace(/[^\w.-]/g, '_');
-  return path.join(getBuildCacheRoot(), `${safeName}-${safeVersion}-${safeHash}`);
-}
-
-/**
- * Names of the artefacts inside a package build dir.
- */
-const LAYOUT = Object.freeze({
-  srcDir:        'src',
-  internalDir:   'wyvrn_internal',
-  buildDir:      'build',
-  installSubdir: 'install', // relative to buildDir — can be overridden by recipe.installDir
-  artefactZip:   'wyvrn.zip',
-  uploadSidecar: '.uploaded-to.json',
-});
-
-/**
- * Resolve the standard sub-paths within a package build dir.
- */
-function getBuildPaths({ name, version, profileHash }) {
-  const root = getPackageBuildDir({ name, version, profileHash });
-  return {
-    root,
-    src:        path.join(root, LAYOUT.srcDir),
-    internal:   path.join(root, LAYOUT.internalDir),
-    build:      path.join(root, LAYOUT.buildDir),
-    install:    path.join(root, LAYOUT.buildDir, LAYOUT.installSubdir),
-    artefact:   path.join(root, LAYOUT.artefactZip),
-  };
-}
-
-/**
- * Remove the entire build cache root. Used by `wyvrnpm clean --build-cache`.
- * @returns {string|null}  the path removed, or null if nothing was there.
- */
-function clearBuildCache() {
-  const root = getBuildCacheRoot();
-  if (!fs.existsSync(root)) return null;
-  fs.rmSync(root, { recursive: true, force: true });
-  return root;
-}
-
-/**
- * Check whether a valid cached artefact exists for this `(name, version, profileHash)`
- * — used to short-circuit re-builds on re-run.
- *
- * @param {{ name, version, profileHash }} args
- * @returns {boolean}
- */
-function hasValidArtefact(args) {
-  const { artefact } = getBuildPaths(args);
-  return fs.existsSync(artefact);
-}
-
-/**
- * Find every `.uploaded-to.json` sidecar under the build cache. Each file
- * records the destinations that a cached artefact has been pushed to via
- * `wyvrnpm install --build=missing --upload-built`.
- *
- * Used by `wyvrnpm clean --uploaded-built` and for audit tooling.
- *
- * @returns {Array<{ cacheDir: string, sidecarPath: string, uploads: Array<object> }>}
- */
-function listUploadSidecars() {
-  const root = getBuildCacheRoot();
-  if (!fs.existsSync(root)) return [];
-  const out = [];
-  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-    const cacheDir    = path.join(root, entry.name);
-    const sidecarPath = path.join(cacheDir, LAYOUT.uploadSidecar);
-    if (!fs.existsSync(sidecarPath)) continue;
-    let uploads = [];
-    try {
-      const raw = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
-      if (Array.isArray(raw?.uploads)) uploads = raw.uploads;
-    } catch { /* corrupt — surface as empty uploads */ }
-    out.push({ cacheDir, sidecarPath, uploads });
-  }
-  return out;
-}
-
-/**
- * Remove every `.uploaded-to.json` sidecar under the build cache. Used by
- * `wyvrnpm clean --uploaded-built`. Leaves all other cache content intact
- * (the artefact zips, source clones, and build dirs stay put).
- *
- * @returns {number}  count of sidecar files removed
- */
-function clearUploadSidecars() {
-  const entries = listUploadSidecars();
-  let removed = 0;
-  for (const { sidecarPath } of entries) {
-    try { fs.unlinkSync(sidecarPath); removed++; } catch { /* ignore */ }
-  }
-  return removed;
-}
-
-// ---------------------------------------------------------------------------
-// Cache inspection (F12)
-// ---------------------------------------------------------------------------
-
-/**
- * Dotted-version + 16+ hex-hash suffix. The hash tail is unambiguous
- * (always hex, always 16 chars per src/profile.js) so parsing from the
- * end avoids ambiguity when package names contain dashes
- * (`boost-filesystem-1.80.0.0-abc1234567890def`).
- */
-const CACHE_DIR_RE = /^(.+)-(\d+(?:\.\d+)+)-([a-f0-9]{16,})$/;
-
-/**
- * Recursively compute total size of a directory in bytes. Skips symlinks
- * to avoid accidental cycles through user-linked packages.
- *
- * @param {string} dir
- * @returns {number}
- */
-function dirSizeBytes(dir) {
-  let total = 0;
-  let entries;
-  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
-  catch { return 0; }
-  for (const e of entries) {
-    if (e.isSymbolicLink()) continue;
-    const p = path.join(dir, e.name);
-    try {
-      if (e.isDirectory()) {
-        total += dirSizeBytes(p);
-      } else if (e.isFile()) {
-        total += fs.statSync(p).size;
-      }
-    } catch { /* concurrent deletion — ignore */ }
-  }
-  return total;
-}
-
-/**
- * List every entry in the source-build cache, enriched with metadata.
- * Unparseable directory names are skipped (corrupt / manual cruft).
- *
- * @returns {Array<{
- *   name:        string,
- *   version:     string,
- *   profileHash: string,
- *   cacheDir:    string,
- *   sizeBytes:   number,
- *   mtimeMs:     number,
- *   hasArtefact: boolean,
- *   uploads:     Array<object>,
- * }>}
- */
-function listCacheEntries() {
-  const root = getBuildCacheRoot();
-  if (!fs.existsSync(root)) return [];
-
-  const out = [];
-  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
-    if (!entry.isDirectory()) continue;
-
-    const m = entry.name.match(CACHE_DIR_RE);
-    if (!m) continue;   // corrupt / unknown — skip silently
-    const [, name, version, profileHash] = m;
-
-    const cacheDir    = path.join(root, entry.name);
-    const artefact    = path.join(cacheDir, LAYOUT.artefactZip);
-    const sidecarPath = path.join(cacheDir, LAYOUT.uploadSidecar);
-
-    let mtimeMs = 0;
-    try { mtimeMs = fs.statSync(cacheDir).mtimeMs; } catch { /* skip */ }
-
-    let uploads = [];
-    if (fs.existsSync(sidecarPath)) {
-      try {
-        const raw = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
-        if (Array.isArray(raw?.uploads)) uploads = raw.uploads;
-      } catch { /* corrupt sidecar — surface empty */ }
-    }
-
-    out.push({
-      name, version, profileHash, cacheDir,
-      sizeBytes:   dirSizeBytes(cacheDir),
-      mtimeMs,
-      hasArtefact: fs.existsSync(artefact),
-      uploads,
-    });
-  }
-  return out;
-}
-
-/**
- * Parse `--older-than` duration strings (`7d`, `24h`, `30m`, `3600s`).
- * Returns the cutoff timestamp in ms-since-epoch: entries with
- * `mtimeMs < cutoff` are older than the threshold.
- *
- * @param {string} spec
- * @param {number} [now=Date.now()]
- * @returns {number}
- */
-function parseDurationToCutoff(spec, now = Date.now()) {
-  if (typeof spec !== 'string') {
-    throw new Error(`--older-than expects a string like "30d", got ${JSON.stringify(spec)}`);
-  }
-  const m = spec.trim().match(/^(\d+)\s*([smhd])$/i);
-  if (!m) {
-    throw new Error(
-      `--older-than ${JSON.stringify(spec)} must be <number><unit> where unit is s/m/h/d`,
-    );
-  }
-  const n = parseInt(m[1], 10);
-  const unit = m[2].toLowerCase();
-  const ms = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[unit];
-  return now - n * ms;
-}
-
-/**
- * Compute which cache entries would be pruned under the given policy.
- * Pure — does no I/O of its own. Caller passes in `entries` (from
- * `listCacheEntries()`) so tests can synthesise them.
- *
- * Policy semantics:
- *  - `keepLast` is **per (name, version) group** — preserves the N most
- *    recent profileHash variants for each version so multi-profile
- *    dev rigs don't lose every profile on a single prune.
- *  - `olderThanMs` applies after `keepLast`; it only widens the set
- *    of eligible-for-pruning entries; never adds entries back.
- *  - `patternRegex` filters entries by name at the very start.
- *
- * Returns the prune set in descending mtime order (newest-of-the-
- * doomed first) — handy for human-friendly "about to remove" output.
- *
- * @param {ReturnType<typeof listCacheEntries>} entries
- * @param {{ keepLast?: number, olderThanMs?: number, patternRegex?: RegExp }} policy
- * @returns {ReturnType<typeof listCacheEntries>}
- */
-function computePruneSet(entries, { keepLast, olderThanMs, patternRegex } = {}) {
-  let candidates = entries;
-  if (patternRegex) candidates = candidates.filter((e) => patternRegex.test(e.name));
-
-  // Group by (name, version); within each group, sort by mtime desc,
-  // mark the top N as keepers when keepLast is set.
-  const keep = new Set();
-  if (typeof keepLast === 'number' && keepLast >= 0) {
-    const groups = new Map();
-    for (const e of candidates) {
-      const k = `${e.name}\x1f${e.version}`;
-      if (!groups.has(k)) groups.set(k, []);
-      groups.get(k).push(e);
-    }
-    for (const group of groups.values()) {
-      group.sort((a, b) => b.mtimeMs - a.mtimeMs);
-      for (let i = 0; i < Math.min(keepLast, group.length); i++) {
-        keep.add(group[i].cacheDir);
-      }
-    }
-  } else {
-    // No keepLast → every candidate is eligible for pruning subject to
-    // the other filters.
-  }
-
-  const toPrune = candidates.filter((e) => !keep.has(e.cacheDir));
-
-  const filtered = typeof olderThanMs === 'number'
-    ? toPrune.filter((e) => e.mtimeMs < olderThanMs)
-    : toPrune;
-
-  filtered.sort((a, b) => b.mtimeMs - a.mtimeMs);
-  return filtered;
-}
-
-/**
- * Delete a list of cache entries. Returns the subset that was actually
- * removed (permissions failures surface as misses). Caller should have
- * already computed the set via `computePruneSet`.
- *
- * @param {ReturnType<typeof listCacheEntries>} entries
- * @returns {ReturnType<typeof listCacheEntries>}
- */
-function removeCacheEntries(entries) {
-  const removed = [];
-  for (const e of entries) {
-    try {
-      fs.rmSync(e.cacheDir, { recursive: true, force: true });
-      removed.push(e);
-    } catch { /* skip failures — caller reports the delta */ }
-  }
-  return removed;
-}
-
-module.exports = {
-  getBuildCacheRoot,
-  getPackageBuildDir,
-  getBuildPaths,
-  clearBuildCache,
-  hasValidArtefact,
-  listUploadSidecars,
-  clearUploadSidecars,
-  LAYOUT,
-  // Cache inspection (F12)
-  listCacheEntries,
-  computePruneSet,
-  removeCacheEntries,
-  parseDurationToCutoff,
-  CACHE_DIR_RE,
-};
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+/**
+ * Root directory for the wyvrnpm source-build cache.
+ *   Windows: %LOCALAPPDATA%\wyvrnpm\bc\           (short name — Windows 260-char path limits bite nested CMake builds)
+ *   Unix   : ~/.cache/wyvrnpm/bc/
+ *
+ * @returns {string}
+ */
+function getBuildCacheRoot() {
+  const base = process.env.LOCALAPPDATA
+    ? path.join(process.env.LOCALAPPDATA, 'wyvrnpm')
+    : path.join(process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'), 'wyvrnpm');
+  return path.join(base, 'bc');
+}
+
+/**
+ * Per-build cache directory, keyed by `(name, version, profileHash)`. Each
+ * consumer profile gets its own cache line because the toolchain's output
+ * differs per profile.
+ *
+ * Layout inside this dir:
+ *   src/               git clone
+ *   wyvrn_internal/    package's own deps + generated toolchain
+ *   build/             cmake -B
+ *   build/install/     cmake install prefix → zipped as the artefact
+ *   wyvrn.zip          final artefact (treated as if downloaded)
+ *
+ * @param {{ name: string, version: string, profileHash: string }} args
+ * @returns {string}
+ */
+function getPackageBuildDir({ name, version, profileHash }) {
+  // Sanitise — names should be filesystem-safe already, but guard against
+  // accidental path traversal.
+  const safeName    = name.replace(/[^\w.-]/g, '_');
+  const safeVersion = version.replace(/[^\w.-]/g, '_');
+  const safeHash    = profileHash.replace(/[^\w.-]/g, '_');
+  return path.join(getBuildCacheRoot(), `${safeName}-${safeVersion}-${safeHash}`);
+}
+
+/**
+ * Names of the artefacts inside a package build dir.
+ */
+const LAYOUT = Object.freeze({
+  srcDir:        'src',
+  internalDir:   'wyvrn_internal',
+  buildDir:      'build',
+  installSubdir: 'install', // relative to buildDir — can be overridden by recipe.installDir
+  artefactZip:   'wyvrn.zip',
+  uploadSidecar: '.uploaded-to.json',
+});
+
+/**
+ * Resolve the standard sub-paths within a package build dir.
+ */
+function getBuildPaths({ name, version, profileHash }) {
+  const root = getPackageBuildDir({ name, version, profileHash });
+  return {
+    root,
+    src:        path.join(root, LAYOUT.srcDir),
+    internal:   path.join(root, LAYOUT.internalDir),
+    build:      path.join(root, LAYOUT.buildDir),
+    install:    path.join(root, LAYOUT.buildDir, LAYOUT.installSubdir),
+    artefact:   path.join(root, LAYOUT.artefactZip),
+  };
+}
+
+/**
+ * Remove the entire build cache root. Used by `wyvrnpm clean --build-cache`.
+ * @returns {string|null}  the path removed, or null if nothing was there.
+ */
+function clearBuildCache() {
+  const root = getBuildCacheRoot();
+  if (!fs.existsSync(root)) return null;
+  fs.rmSync(root, { recursive: true, force: true });
+  return root;
+}
+
+/**
+ * Check whether a valid cached artefact exists for this `(name, version, profileHash)`
+ * — used to short-circuit re-builds on re-run.
+ *
+ * @param {{ name, version, profileHash }} args
+ * @returns {boolean}
+ */
+function hasValidArtefact(args) {
+  const { artefact } = getBuildPaths(args);
+  return fs.existsSync(artefact);
+}
+
+/**
+ * Find every `.uploaded-to.json` sidecar under the build cache. Each file
+ * records the destinations that a cached artefact has been pushed to via
+ * `wyvrnpm install --build=missing --upload-built`.
+ *
+ * Used by `wyvrnpm clean --uploaded-built` and for audit tooling.
+ *
+ * @returns {Array<{ cacheDir: string, sidecarPath: string, uploads: Array<object> }>}
+ */
+function listUploadSidecars() {
+  const root = getBuildCacheRoot();
+  if (!fs.existsSync(root)) return [];
+  const out = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const cacheDir    = path.join(root, entry.name);
+    const sidecarPath = path.join(cacheDir, LAYOUT.uploadSidecar);
+    if (!fs.existsSync(sidecarPath)) continue;
+    let uploads = [];
+    try {
+      const raw = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
+      if (Array.isArray(raw?.uploads)) uploads = raw.uploads;
+    } catch { /* corrupt — surface as empty uploads */ }
+    out.push({ cacheDir, sidecarPath, uploads });
+  }
+  return out;
+}
+
+/**
+ * Remove every `.uploaded-to.json` sidecar under the build cache. Used by
+ * `wyvrnpm clean --uploaded-built`. Leaves all other cache content intact
+ * (the artefact zips, source clones, and build dirs stay put).
+ *
+ * @returns {number}  count of sidecar files removed
+ */
+function clearUploadSidecars() {
+  const entries = listUploadSidecars();
+  let removed = 0;
+  for (const { sidecarPath } of entries) {
+    try { fs.unlinkSync(sidecarPath); removed++; } catch { /* ignore */ }
+  }
+  return removed;
+}
+
+// ---------------------------------------------------------------------------
+// Cache inspection (F12)
+// ---------------------------------------------------------------------------
+
+/**
+ * Dotted-version + 16+ hex-hash suffix. The hash tail is unambiguous
+ * (always hex, always 16 chars per src/profile.js) so parsing from the
+ * end avoids ambiguity when package names contain dashes
+ * (`boost-filesystem-1.80.0.0-abc1234567890def`).
+ */
+const CACHE_DIR_RE = /^(.+)-(\d+(?:\.\d+)+)-([a-f0-9]{16,})$/;
+
+/**
+ * Recursively compute total size of a directory in bytes. Skips symlinks
+ * to avoid accidental cycles through user-linked packages.
+ *
+ * @param {string} dir
+ * @returns {number}
+ */
+function dirSizeBytes(dir) {
+  let total = 0;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return 0; }
+  for (const e of entries) {
+    if (e.isSymbolicLink()) continue;
+    const p = path.join(dir, e.name);
+    try {
+      if (e.isDirectory()) {
+        total += dirSizeBytes(p);
+      } else if (e.isFile()) {
+        total += fs.statSync(p).size;
+      }
+    } catch { /* concurrent deletion — ignore */ }
+  }
+  return total;
+}
+
+/**
+ * List every entry in the source-build cache, enriched with metadata.
+ * Unparseable directory names are skipped (corrupt / manual cruft).
+ *
+ * @returns {Array<{
+ *   name:        string,
+ *   version:     string,
+ *   profileHash: string,
+ *   cacheDir:    string,
+ *   sizeBytes:   number,
+ *   mtimeMs:     number,
+ *   hasArtefact: boolean,
+ *   uploads:     Array<object>,
+ * }>}
+ */
+function listCacheEntries() {
+  const root = getBuildCacheRoot();
+  if (!fs.existsSync(root)) return [];
+
+  const out = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+
+    const m = entry.name.match(CACHE_DIR_RE);
+    if (!m) continue;   // corrupt / unknown — skip silently
+    const [, name, version, profileHash] = m;
+
+    const cacheDir    = path.join(root, entry.name);
+    const artefact    = path.join(cacheDir, LAYOUT.artefactZip);
+    const sidecarPath = path.join(cacheDir, LAYOUT.uploadSidecar);
+
+    let mtimeMs = 0;
+    try { mtimeMs = fs.statSync(cacheDir).mtimeMs; } catch { /* skip */ }
+
+    let uploads = [];
+    if (fs.existsSync(sidecarPath)) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
+        if (Array.isArray(raw?.uploads)) uploads = raw.uploads;
+      } catch { /* corrupt sidecar — surface empty */ }
+    }
+
+    out.push({
+      name, version, profileHash, cacheDir,
+      sizeBytes:   dirSizeBytes(cacheDir),
+      mtimeMs,
+      hasArtefact: fs.existsSync(artefact),
+      uploads,
+    });
+  }
+  return out;
+}
+
+/**
+ * Parse `--older-than` duration strings (`7d`, `24h`, `30m`, `3600s`).
+ * Returns the cutoff timestamp in ms-since-epoch: entries with
+ * `mtimeMs < cutoff` are older than the threshold.
+ *
+ * @param {string} spec
+ * @param {number} [now=Date.now()]
+ * @returns {number}
+ */
+function parseDurationToCutoff(spec, now = Date.now()) {
+  if (typeof spec !== 'string') {
+    throw new Error(`--older-than expects a string like "30d", got ${JSON.stringify(spec)}`);
+  }
+  const m = spec.trim().match(/^(\d+)\s*([smhd])$/i);
+  if (!m) {
+    throw new Error(
+      `--older-than ${JSON.stringify(spec)} must be <number><unit> where unit is s/m/h/d`,
+    );
+  }
+  const n = parseInt(m[1], 10);
+  const unit = m[2].toLowerCase();
+  const ms = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[unit];
+  return now - n * ms;
+}
+
+/**
+ * Compute which cache entries would be pruned under the given policy.
+ * Pure — does no I/O of its own. Caller passes in `entries` (from
+ * `listCacheEntries()`) so tests can synthesise them.
+ *
+ * Policy semantics:
+ *  - `keepLast` is **per (name, version) group** — preserves the N most
+ *    recent profileHash variants for each version so multi-profile
+ *    dev rigs don't lose every profile on a single prune.
+ *  - `olderThanMs` applies after `keepLast`; it only widens the set
+ *    of eligible-for-pruning entries; never adds entries back.
+ *  - `patternRegex` filters entries by name at the very start.
+ *
+ * Returns the prune set in descending mtime order (newest-of-the-
+ * doomed first) — handy for human-friendly "about to remove" output.
+ *
+ * @param {ReturnType<typeof listCacheEntries>} entries
+ * @param {{ keepLast?: number, olderThanMs?: number, patternRegex?: RegExp }} policy
+ * @returns {ReturnType<typeof listCacheEntries>}
+ */
+function computePruneSet(entries, { keepLast, olderThanMs, patternRegex } = {}) {
+  let candidates = entries;
+  if (patternRegex) candidates = candidates.filter((e) => patternRegex.test(e.name));
+
+  // Group by (name, version); within each group, sort by mtime desc,
+  // mark the top N as keepers when keepLast is set.
+  const keep = new Set();
+  if (typeof keepLast === 'number' && keepLast >= 0) {
+    const groups = new Map();
+    for (const e of candidates) {
+      const k = `${e.name}\x1f${e.version}`;
+      if (!groups.has(k)) groups.set(k, []);
+      groups.get(k).push(e);
+    }
+    for (const group of groups.values()) {
+      group.sort((a, b) => b.mtimeMs - a.mtimeMs);
+      for (let i = 0; i < Math.min(keepLast, group.length); i++) {
+        keep.add(group[i].cacheDir);
+      }
+    }
+  } else {
+    // No keepLast → every candidate is eligible for pruning subject to
+    // the other filters.
+  }
+
+  const toPrune = candidates.filter((e) => !keep.has(e.cacheDir));
+
+  const filtered = typeof olderThanMs === 'number'
+    ? toPrune.filter((e) => e.mtimeMs < olderThanMs)
+    : toPrune;
+
+  filtered.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return filtered;
+}
+
+/**
+ * Delete a list of cache entries. Returns the subset that was actually
+ * removed (permissions failures surface as misses). Caller should have
+ * already computed the set via `computePruneSet`.
+ *
+ * @param {ReturnType<typeof listCacheEntries>} entries
+ * @returns {ReturnType<typeof listCacheEntries>}
+ */
+function removeCacheEntries(entries) {
+  const removed = [];
+  for (const e of entries) {
+    try {
+      fs.rmSync(e.cacheDir, { recursive: true, force: true });
+      removed.push(e);
+    } catch { /* skip failures — caller reports the delta */ }
+  }
+  return removed;
+}
+
+module.exports = {
+  getBuildCacheRoot,
+  getPackageBuildDir,
+  getBuildPaths,
+  clearBuildCache,
+  hasValidArtefact,
+  listUploadSidecars,
+  clearUploadSidecars,
+  LAYOUT,
+  // Cache inspection (F12)
+  listCacheEntries,
+  computePruneSet,
+  removeCacheEntries,
+  parseDurationToCutoff,
+  CACHE_DIR_RE,
+};