wyvrnpm 2.3.2 → 2.8.1

package/bin/wyvrn.js

@@ -4,6 +4,7 @@
 
 const yargs     = require('yargs');
 const init         = require('../src/commands/init');
+const add          = require('../src/commands/add');
 const install      = require('../src/commands/install');
 const clean        = require('../src/commands/clean');
 const publish      = require('../src/commands/publish');
@@ -12,6 +13,7 @@ const profile      = require('../src/commands/profile');
 const build        = require('../src/commands/build');
 const show         = require('../src/commands/show');
 const installSkill = require('../src/commands/install-skill');
+const cache        = require('../src/commands/cache');
 const { link, unlink } = require('../src/commands/link');
 
 yargs
@@ -35,6 +37,34 @@ yargs
     (argv) => init(argv),
   )
 
+  // ── add ───────────────────────────────────────────────────────────────────
+  .command(
+    'add <packages...>',
+    'Add dependencies to wyvrn.json. Without @version, resolves latest and writes "^<latest>"; ' +
+    'with @version, writes the given string verbatim. Does not run install.',
+    (y) => {
+      y
+        .positional('packages', {
+          type: 'string',
+          array: true,
+          describe: 'One or more <name>[@<version>] specs',
+        })
+        .option('source', {
+          alias: 's',
+          type: 'string',
+          description: 'Base URL of a package source for `latest` lookup (can be repeated)',
+          array: true,
+        })
+        .option('platform', {
+          type: 'string',
+          description: 'v1 legacy platform path (used as fallback when looking up latest)',
+          choices: ['win_x64', 'win_x86', 'linux_x64', 'linux_x86', 'osx_x64', 'osx_arm64'],
+          default: 'win_x64',
+        });
+    },
+    (argv) => add(argv),
+  )
+
   // ── install ───────────────────────────────────────────────────────────────
   .command(
     'install',
@@ -57,8 +87,8 @@ yargs
           choices: ['never', 'missing', 'always'],
           default: 'never',
           description:
-            'Resolution mode when no exact profile match exists. ' +
-            'never=fail; missing=build from source (pending phase 3); always=rebuild (pending phase 3)',
+            'Resolution strategy. never=fail when no exact match; ' +
+            'missing=source-build only when no match; always=ignore registry binaries and rebuild every dep from source (debug/verification).',
         })
         .option('option', {
           alias: 'o',
@@ -68,6 +98,25 @@ yargs
             'Override a package option. Repeatable. Format: <pkg>:<name>=<value>. ' +
             'Example: -o zlib:minizip=false -o OpenSSL:fips=true',
         })
+        .option('dry-run', {
+          type: 'boolean',
+          default: false,
+          description:
+            'Run the resolver + profile-hash math and print the install plan (every ' +
+            'dep, its pinned version, effective profileHash, per-dep option overrides) ' +
+            'without downloading, extracting, writing wyvrn.lock, or emitting the ' +
+            'toolchain. Combine with --format=json for CI-friendly output.',
+        })
+        .option('conf', {
+          type: 'string',
+          array: true,
+          description:
+            'Non-ABI build-time override. Repeatable. Format: ' +
+            '<namespace.leaf>=<value> — e.g. --conf cmake.cache.CHROMA_ENABLE_TEST=ON. ' +
+            'Bare KEY is sugar for KEY=ON (CMake -D convention); KEY= (empty RHS) ' +
+            'clears an inherited value. Does NOT fold into profileHash — see ' +
+            'claude/PLAN-CONF.md for layering rules.',
+        })
         .option('upload-built', {
           type: 'boolean',
           default: false,
@@ -88,7 +137,11 @@ yargs
         })
         .option('token', {
           type: 'string',
-          description: 'Bearer token for --upload-built when uploading to HTTP',
+          description: 'Bearer token for --upload-built when uploading to HTTP. Prefer --token-env in CI so the literal value never lands in argv.',
+        })
+        .option('token-env', {
+          type: 'string',
+          description: 'Name of an env var whose value is the bearer token for --upload-built. Preferred over --token in CI.',
         })
         .option('platform', {
           type: 'string',
@@ -113,6 +166,8 @@ yargs
       uploadBuilt:  argv['upload-built'],
       uploadSource: argv['upload-source'],
       awsProfile:   argv['aws-profile'],
+      tokenEnv:     argv['token-env'],
+      dryRun:       argv['dry-run'],
     }),
   )
 
@@ -156,6 +211,13 @@ yargs
           default: false,
           description: 'Remove the build directory before configuring',
         })
+        .option('generator', {
+          alias: 'G',
+          type: 'string',
+          description:
+            'Override the preset\'s CMake generator (e.g. "Visual Studio 17 2022", "Ninja", "Ninja Multi-Config"). ' +
+            'CMake locks the generator into the build-dir cache, so pair this with --clean when switching generators.',
+        })
         .option('install', {
           type: 'boolean',
           default: false,
@@ -184,6 +246,16 @@ yargs
         .option('timeout', {
           type: 'number',
           default: 300,
+        })
+        .option('conf', {
+          type: 'string',
+          array: true,
+          description:
+            'Non-ABI build-time override forwarded to cmake --preset as -D / -U. ' +
+            'Repeatable. Format: <namespace.leaf>=<value> — e.g. ' +
+            '--conf cmake.cache.CHROMA_ENABLE_TEST=ON. CLI --conf does NOT ' +
+            'regenerate CMakePresets.json; edit wyvrn.local.json and re-run ' +
+            '`wyvrnpm install` for persistent overrides. See claude/PLAN-CONF.md.',
         });
     },
     (argv) => build({
@@ -193,6 +265,74 @@ yargs
     }),
   )
 
+  // ── cache ─────────────────────────────────────────────────────────────────
+  .command(
+    'cache',
+    'Inspect and selectively prune the machine-wide source-build cache (F12). Use `clean --build-cache` to wipe everything.',
+    (y) => {
+      y
+        .command(
+          'list [pattern]',
+          'List cache entries. Optional glob pattern filters by package name.',
+          (y2) => {
+            y2
+              .positional('pattern', {
+                type:        'string',
+                description: 'Glob over package names, e.g. "boost*" (alias for --pattern)',
+              })
+              .option('pattern', {
+                type:        'string',
+                description: 'Glob over package names; overrides the positional',
+              })
+              .option('format', {
+                type:        'string',
+                choices:     ['text', 'json'],
+                default:     'text',
+                description: 'Output format',
+              });
+          },
+          (argv) => cache.list(argv),
+        )
+        .command(
+          'prune',
+          'Remove cache entries per policy. Requires at least one of --keep-last / --older-than.',
+          (y2) => {
+            y2
+              .option('keep-last', {
+                type:        'number',
+                description:
+                  'Retain the N most recently-touched entries per (name, version). ' +
+                  'Older variants beyond N are pruned.',
+              })
+              .option('older-than', {
+                type:        'string',
+                description:
+                  'Remove entries whose mtime is older than this threshold. ' +
+                  'Format: <number><unit>, unit ∈ s/m/h/d (e.g. 30d, 72h).',
+              })
+              .option('pattern', {
+                type:        'string',
+                description: 'Limit scope to package names matching this glob (e.g. "boost*")',
+              })
+              .option('dry-run', {
+                type:        'boolean',
+                default:     false,
+                description: 'Print what would be removed without actually deleting',
+              });
+          },
+          (argv) => cache.prune({
+            ...argv,
+            keepLast:  argv['keep-last'],
+            olderThan: argv['older-than'],
+            dryRun:    argv['dry-run'],
+          }),
+        )
+        .demandCommand(1)
+        .help();
+    },
+    () => {},
+  )
+
   // ── clean ─────────────────────────────────────────────────────────────────
   .command(
     'clean',
@@ -242,7 +382,11 @@ yargs
         })
         .option('token', {
           type: 'string',
-          description: 'Bearer token for HTTP sources',
+          description: 'Bearer token for HTTP sources. Prefer --token-env in CI so the literal value never lands in argv.',
+        })
+        .option('token-env', {
+          type: 'string',
+          description: 'Name of an env var whose value is the bearer token for HTTP sources.',
         })
         .option('format', {
           type: 'string',
@@ -251,7 +395,7 @@ yargs
           description: 'Output format. "json" emits a single JSON object on stdout; log lines go to stderr.',
         });
     },
-    (argv) => show({ ...argv, awsProfile: argv['aws-profile'] }),
+    (argv) => show({ ...argv, awsProfile: argv['aws-profile'], tokenEnv: argv['token-env'] }),
   )
 
   // ── publish ───────────────────────────────────────────────────────────────
@@ -282,7 +426,11 @@ yargs
         })
         .option('token', {
           type: 'string',
-          description: 'Bearer token for HTTP server authentication',
+          description: 'Bearer token for HTTP server authentication. Prefer --token-env in CI so the literal value never lands in argv.',
+        })
+        .option('token-env', {
+          type: 'string',
+          description: 'Name of an env var whose value is the bearer token for HTTP authentication.',
         })
         .option('force', {
           alias: 'f',
@@ -298,6 +446,15 @@ yargs
             'Override an option value at publish time. Repeatable. ' +
             'Format: <pkg>:<name>=<value> (pkg must match the package being published).',
         })
+        .option('conf', {
+          type: 'string',
+          array: true,
+          description:
+            'Non-ABI build-time override recorded as `publishedConf` on the ' +
+            'uploaded manifest (informational — does not affect profileHash). ' +
+            'Reads recipe conf + CLI only; wyvrn.local.json is intentionally ' +
+            'ignored for publish.',
+        })
         .option('format', {
           type: 'string',
           choices: ['text', 'json'],
@@ -306,7 +463,7 @@ yargs
         })
         ;
     },
-    (argv) => publish({ ...argv, awsProfile: argv['aws-profile'] }),
+    (argv) => publish({ ...argv, awsProfile: argv['aws-profile'], tokenEnv: argv['token-env'] }),
   )
 
   // ── configure ─────────────────────────────────────────────────────────────
@@ -328,7 +485,8 @@ yargs
               .option('name',    { type: 'string', demandOption: true })
               .option('url',     { type: 'string', demandOption: true })
               .option('profile', { type: 'string', description: 'AWS SSO profile (S3 only)' })
-              .option('token',   { type: 'string', description: 'Bearer token (HTTP only)' });
+              .option('token',   { type: 'string', description: 'Bearer token (HTTP only). Persists in plaintext in config.json — prefer --token-env for CI/shared setups.' })
+              .option('token-env', { type: 'string', description: 'Name of an env var whose value is the bearer token (HTTP only). Only the name is persisted; the value is resolved at runtime.' });
           },
           (argv) => configure.addSource(argv),
         )
@@ -402,7 +560,15 @@ yargs
                     .option('compiler',         { type: 'string', description: 'Compiler (msvc | gcc | clang | apple-clang)' })
                     .option('compiler-version', { type: 'string', description: 'Compiler version (193 | 11 | 14 | ...)' })
                     .option('cppstd',           { type: 'string', description: 'C++ standard (14 | 17 | 20 | 23)' })
-                    .option('runtime',          { type: 'string', description: 'Runtime linkage (static | dynamic)' });
+                    .option('runtime',          { type: 'string', description: 'Runtime linkage (static | dynamic)' })
+                    .option('conf', {
+                      type:         'string',
+                      array:        true,
+                      description:
+                        'Profile-level non-ABI build knob — <namespace.leaf>=<value> ' +
+                        '(repeatable). `KEY` alone means `KEY=ON`; `KEY=` removes the ' +
+                        'leaf. Phase 1 allow-list: cmake.cache.*. See PLAN-CONF.md §4.',
+                    });
                 },
                 (argv) => profile.set({ ...argv, compilerVersion: argv['compiler-version'] }),
               )

package/cmake/macros.cmake

@@ -25,6 +25,44 @@ macro(WYVRN_CONFIGURE_VERSION_HEADER)
     )
 endmacro()
 
+# Apply WYVRN_ARCH_SUFFIX to a target's OUTPUT_NAME so the produced artefact
+# carries an unambiguous arch marker. Opt-in — call it from your CMakeLists
+# only if you want the suffixing:
+#
+#   WYVRN_APPLY_ARCH_SUFFIX(String)                       # String64.lib / String32.lib
+#   WYVRN_APPLY_ARCH_SUFFIX(String BASE_NAME my-string)   # my-string64.lib / my-string32.lib
+#
+# BASE_NAME defaults to the target name. The target linkage name (what
+# consumers pass to target_link_libraries) is untouched — only the on-disk
+# output file changes. Safe to call for any target type; does nothing if
+# WYVRN_ARCH_SUFFIX is empty (unknown / unmapped arch).
+function(WYVRN_APPLY_ARCH_SUFFIX _wyvrn_target)
+    set(options)
+    set(oneValueArgs BASE_NAME)
+    set(multiValueArgs)
+    cmake_parse_arguments(_WYVRN_ARG "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
+
+    if(NOT TARGET ${_wyvrn_target})
+        message(FATAL_ERROR "WYVRN_APPLY_ARCH_SUFFIX: '${_wyvrn_target}' is not a target")
+    endif()
+
+    if("${WYVRN_ARCH_SUFFIX}" STREQUAL "")
+        # Unknown arch — leave the output name alone rather than stamping a
+        # misleading value. The caller can still set OUTPUT_NAME manually.
+        return()
+    endif()
+
+    if(_WYVRN_ARG_BASE_NAME)
+        set(_wyvrn_base "${_WYVRN_ARG_BASE_NAME}")
+    else()
+        set(_wyvrn_base "${_wyvrn_target}")
+    endif()
+
+    set_target_properties(${_wyvrn_target} PROPERTIES
+        OUTPUT_NAME "${_wyvrn_base}${WYVRN_ARCH_SUFFIX}"
+    )
+endfunction()
+
 function(WYVRN_INSTALL_PACKAGE_EXPORT)
     set(options)
     set(oneValueArgs
@@ -84,10 +122,23 @@ function(WYVRN_INSTALL_PACKAGE_EXPORT)
         INSTALL_DESTINATION "${WYVRN_EXPORT_INSTALL_CMAKEDIR}"
     )
 
+    # INTERFACE libraries (header-only) have no compiled binary, so the arch
+    # stamped by `write_basic_package_version_file()` by default makes CMake
+    # reject the package when the consumer's CMAKE_SIZEOF_VOID_P differs —
+    # even though the headers themselves are arch-portable. Pass
+    # ARCH_INDEPENDENT so a HeaderOnlyLib published from x86_64 is consumable
+    # from x86 (and vice versa). Binary kinds keep the arch check.
+    set(_wyvrn_version_args)
+    get_target_property(_wyvrn_target_type ${WYVRN_EXPORT_TARGET} TYPE)
+    if(_wyvrn_target_type STREQUAL "INTERFACE_LIBRARY")
+        list(APPEND _wyvrn_version_args ARCH_INDEPENDENT)
+    endif()
+
     write_basic_package_version_file(
         "${WYVRN_EXPORT_VERSION_OUTPUT}"
         VERSION "${WYVRN_EXPORT_PACKAGE_VERSION}"
         COMPATIBILITY SameMajorVersion
+        ${_wyvrn_version_args}
     )
 
     install(FILES

package/cmake/variables.cmake

@@ -161,9 +161,19 @@ else()
     message(STATUS "Unknown architecture")
 endif()
 
-set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_SOURCE_DIR}/output/lib/")
-set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_SOURCE_DIR}/output/lib/")
-set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_SOURCE_DIR}/output/bin")
+# Output dirs are suffixed with WYVRN_ARCH_SUFFIX ("64" / "32" / "") so
+# multi-arch builds from the same source tree don't clobber each other
+# (e.g. building x64 then x86 used to silently overwrite the x64 DLLs
+# in output/bin/<CONFIG>/). Single-arch consumers see no path change on
+# x86 or unmapped arches — the suffix is empty there. Set defensively:
+# if wyvrn_toolchain.cmake hasn't been included (standalone cmake runs),
+# WYVRN_ARCH_SUFFIX is undefined and we fall back to the legacy layout.
+if(NOT DEFINED WYVRN_ARCH_SUFFIX)
+    set(WYVRN_ARCH_SUFFIX "")
+endif()
+set(CMAKE_ARCHIVE_OUTPUT_DIRECTORY "${CMAKE_SOURCE_DIR}/output/lib${WYVRN_ARCH_SUFFIX}/")
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_SOURCE_DIR}/output/lib${WYVRN_ARCH_SUFFIX}/")
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_SOURCE_DIR}/output/bin${WYVRN_ARCH_SUFFIX}")
 
 add_compile_definitions(
     $<$<CONFIG:Debug>:WYVRN_DEBUG>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wyvrnpm",
-  "version": "2.3.2",
+  "version": "2.8.1",
   "description": "A simple, static-hosting-compatible C++ package manager",
   "keywords": [
     "c++",

package/src/auth.js

@@ -0,0 +1,66 @@
+'use strict';
+
+/**
+ * Resolve an authentication token for HTTP-source reads/writes.
+ *
+ * Closes EVALUATION.md S8 — passing `--token <value>` on the command line
+ * leaks the token into any shell history, process table, or CI job log
+ * that captures argv. `--token-env <VAR>` and the config equivalent
+ * `tokenEnv` let users keep the literal value in env only.
+ *
+ * Resolution order (first match wins):
+ *   1. `token`     — literal string from CLI or config (explicit beats env).
+ *   2. `tokenEnv`  — name of an env var; its value becomes the token.
+ *
+ * Returns `undefined` when nothing is configured (valid — not every source
+ * needs auth). Throws when `tokenEnv` names a var that is unset or empty.
+ *
+ * @param {{ token?: string, tokenEnv?: string }} opts
+ * @returns {string|undefined}
+ */
+function resolveToken(opts = {}) {
+  const { token, tokenEnv } = opts;
+
+  if (typeof token === 'string' && token.length > 0) {
+    return token;
+  }
+
+  if (typeof tokenEnv === 'string' && tokenEnv.length > 0) {
+    const value = process.env[tokenEnv];
+    if (typeof value !== 'string' || value.length === 0) {
+      throw new Error(
+        `--token-env ${tokenEnv} (or config tokenEnv=${tokenEnv}) is set, ` +
+        `but the environment variable is unset or empty.`,
+      );
+    }
+    return value;
+  }
+
+  return undefined;
+}
+
+/**
+ * Merge CLI auth args + a source-config entry into a final `{ token }`
+ * object ready for passing to a provider. Centralises the "CLI wins,
+ * then env-backed CLI, then config literal, then config env-backed"
+ * precedence so call sites don't each re-implement it.
+ *
+ * @param {{ token?: string, tokenEnv?: string }} cli
+ * @param {{ token?: string, tokenEnv?: string } | null | undefined} source
+ * @returns {{ token: string|undefined }}
+ */
+function resolveSourceAuth(cli, source) {
+  // Try CLI first; if it produced nothing, fall back to the source's
+  // own stored auth. Each call to resolveToken handles its own
+  // precedence (literal > env) and throws on invalid tokenEnv.
+  const fromCli    = resolveToken(cli);
+  if (fromCli !== undefined) return { token: fromCli };
+
+  const fromSource = source ? resolveToken(source) : undefined;
+  return { token: fromSource };
+}
+
+module.exports = {
+  resolveToken,
+  resolveSourceAuth,
+};

package/src/build/cache.js

@@ -136,6 +136,196 @@ function clearUploadSidecars() {
   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,
@@ -145,4 +335,10 @@ module.exports = {
   listUploadSidecars,
   clearUploadSidecars,
   LAYOUT,
+  // Cache inspection (F12)
+  listCacheEntries,
+  computePruneSet,
+  removeCacheEntries,
+  parseDurationToCutoff,
+  CACHE_DIR_RE,
 };