wyvrnpm 2.18.0 → 2.20.0

package/bin/wyvrnpm.js

@@ -543,7 +543,7 @@ yargs
   // ── cache ─────────────────────────────────────────────────────────────────
   .command(
     'cache',
-    'Inspect and selectively prune the machine-wide source-build cache (F12). Use `clean --build-cache` to wipe everything.',
+    'Inspect and selectively prune the machine-wide caches. Use `clean --build-cache` / `clean --pkg-cache` to wipe everything.',
     (y) => {
       y
         .command(
@@ -559,6 +559,12 @@ yargs
                 type:        'string',
                 description: 'Glob over package names; overrides the positional',
               })
+              .option('type', {
+                type:        'string',
+                choices:     ['src', 'pkg', 'all'],
+                default:     'all',
+                description: 'Which cache to inspect: src (source-build), pkg (binary downloads), or all',
+              })
               .option('format', {
                 type:        'string',
                 choices:     ['text', 'json'],
@@ -573,6 +579,12 @@ yargs
           'Remove cache entries per policy. Requires at least one of --keep-last / --older-than.',
           (y2) => {
             y2
+              .option('type', {
+                type:        'string',
+                choices:     ['src', 'pkg', 'all'],
+                default:     'all',
+                description: 'Which cache to prune: src (source-build), pkg (binary downloads), or all',
+              })
               .option('keep-last', {
                 type:        'number',
                 description:
@@ -644,6 +656,11 @@ yargs
           default: false,
           description: 'Also remove the source-build cache under %LOCALAPPDATA%\\wyvrnpm\\bc\\',
         })
+        .option('pkg-cache', {
+          type: 'boolean',
+          default: false,
+          description: 'Also remove the binary package cache under %LOCALAPPDATA%\\wyvrnpm\\pkg\\ (14-day TTL download cache)',
+        })
         .option('uploaded-built', {
           type: 'boolean',
           default: false,
@@ -662,6 +679,7 @@ yargs
       ...argv,
       buildDir:       argv['build-dir'],
       buildCache:     argv['build-cache'],
+      pkgCache:       argv['pkg-cache'],
       uploadedBuilt:  argv['uploaded-built'],
       dryRun:         argv['dry-run'],
     }),

package/package.json

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

package/src/build/cmake.js

@@ -5,6 +5,8 @@ const path = require('path');
 const { spawn } = require('child_process');
 
 const { loadMsvcEnv } = require('./msvc-env');
+const { archToVsPlatform, isVisualStudioGenerator } = require('../toolchain');
+const { detectDefaultGenerator } = require('./default-generator');
 const log = require('../logger');
 
 /**
@@ -190,15 +192,21 @@ function isMultiConfigGenerator(generatorName) {
  *   configureExtra:  string[],
  *   buildType?:      string|null,   // single-config only
  *   configurations?: string[]|null, // multi-config only, pins CMAKE_CONFIGURATION_TYPES
+ *   vsPlatform?:     string|null,   // VS generators only — emits -A <platform>
  * }} args
  * @returns {string[]}
  */
 function buildConfigureArgs({
   sourceDir, buildDir, installDir, toolchainFile, generator, configureExtra,
-  buildType, configurations,
+  buildType, configurations, vsPlatform = null,
 }) {
   const args = ['-S', sourceDir, '-B', buildDir];
   if (generator) args.push('-G', generator);
+  // Visual Studio generators default to host x64 unless the target platform is
+  // pinned with -A. Without this, an x86/ARM profile silently produces x64
+  // binaries (PLAN-VS-ARCH-PIN gate 3). Mapped from the profile arch by the
+  // caller; null for non-VS generators.
+  if (vsPlatform) args.push('-A', vsPlatform);
   args.push(`-DCMAKE_TOOLCHAIN_FILE=${toolchainFile}`);
   args.push(`-DCMAKE_INSTALL_PREFIX=${installDir}`);
   // Single-config generators bake CMAKE_BUILD_TYPE into the cache.
@@ -257,7 +265,22 @@ async function configureBuildInstall({ recipe, srcRoot, buildPaths, toolchainFil
 
   // Resolve generator from the fallback chain (probes each candidate's
   // backing tool). `null` → omit `-G`, let CMake pick its default.
-  const generator = await pickGenerator(recipe.generators);
+  let generator = await pickGenerator(recipe.generators);
+
+  // No recipe generator → CMake's Windows default is the newest VS, which
+  // builds host x64 unless `-A` is pinned. Resolve it to a concrete VS
+  // generator so the -A below applies (PLAN-VS-ARCH-PIN gate 3). Non-Windows /
+  // non-MSVC leaves `generator` null → CMake default, no -A (target arch is
+  // the compiler's job there).
+  if (!generator && profile && profile.os === 'Windows' && profile.compiler === 'msvc') {
+    generator = await detectDefaultGenerator();
+  }
+
+  // VS generators need -A <platform> to honour the profile arch — recipe-pinned
+  // VS generators get it too, not just the detected default.
+  const vsPlatform = isVisualStudioGenerator(generator)
+    ? archToVsPlatform(profile && profile.arch)
+    : null;
 
   // On Windows with an MSVC profile + non-VS generator (Ninja, Make, ...),
   // auto-enter a Developer Command Prompt-equivalent env so `cl.exe` is on
@@ -281,6 +304,7 @@ async function configureBuildInstall({ recipe, srcRoot, buildPaths, toolchainFil
       installDir:     buildPaths.install,
       toolchainFile,
       generator,
+      vsPlatform,
       configureExtra: recipe.configure,
       buildType:      null,        // multi-config picks at build time
       configurations: configList,  // pin CMAKE_CONFIGURATION_TYPES so all 4 build-<Config>.ninja files get generated
@@ -313,6 +337,7 @@ async function configureBuildInstall({ recipe, srcRoot, buildPaths, toolchainFil
       installDir:     buildPaths.install,
       toolchainFile,
       generator,
+      vsPlatform,
       configureExtra: recipe.configure,
       buildType:      cfg,
     });

package/src/build/default-generator.js

@@ -0,0 +1,124 @@
+'use strict';
+
+const { spawn } = require('child_process');
+
+const { isVisualStudioGenerator } = require('../toolchain');
+
+/**
+ * Parse `cmake --help` output for the platform's default generator. CMake
+ * marks the default with a leading `* ` in the "Generators" section, e.g.:
+ *
+ *   The following generators are available on this platform (* marks default):
+ *   * Visual Studio 17 2022 [arch] = Generates Visual Studio 2022 project files.
+ *     Visual Studio 16 2019 [arch] = Generates Visual Studio 2019 project files.
+ *     Ninja                        = Generates build.ninja files.
+ *
+ * Returns the default generator's name verbatim (with any trailing ` [arch]`
+ * annotation stripped), or null when no default marker is present. The name is
+ * returned as-is — deciding whether it's a Visual Studio generator is the
+ * caller's job.
+ *
+ * @param {string} helpText
+ * @returns {string|null}
+ */
+function parseDefaultGenerator(helpText) {
+  if (typeof helpText !== 'string') return null;
+  for (const line of helpText.split(/\r?\n/)) {
+    const m = line.match(/^\*\s+(.+?)\s*=/);
+    if (!m) continue;
+    return m[1].replace(/\s*\[arch\]\s*$/, '').trim();
+  }
+  return null;
+}
+
+/**
+ * Spawn `cmake --help` and resolve its stdout. Resolves null (never rejects)
+ * when cmake is absent from PATH or exits non-zero — generator detection is
+ * best-effort, and an unavailable cmake simply means the caller falls back to
+ * leaving the generator unpinned, exactly as before this feature.
+ *
+ * @returns {Promise<string|null>}
+ */
+function runCmakeHelp() {
+  return new Promise((resolve) => {
+    let out = '';
+    const proc = spawn('cmake', ['--help'], {
+      shell: process.platform === 'win32',
+    });
+    proc.stdout.on('data', (chunk) => { out += chunk.toString(); });
+    // cmake not on PATH → detection unavailable; recoverable, fall back to null.
+    proc.on('error', () => resolve(null));
+    proc.on('close', (code) => resolve(code === 0 ? out : null));
+  });
+}
+
+// Per-process memo of the production (no-injection) probe result. The default
+// generator can't change mid-run, so a single `cmake --help` spawn is enough
+// for the whole process — important when one process drives many installs
+// (e.g. a source-build that resolves several deps, or the test suite). Calls
+// that inject `platform`/`runHelp` (tests) bypass this cache to stay hermetic.
+let cachedDefault; // undefined = unprobed; string|null = probed result
+
+/**
+ * Detect the Visual Studio generator CMake would use by default on this
+ * machine. On Windows with VS installed, CMake's implicit default is the
+ * newest installed VS — which builds host x64 unless `-A`/architecture is
+ * pinned. Returns that VS generator name so callers can pin it (and the
+ * matching `-A`), or null when the default is not a VS generator
+ * (non-Windows, or VS not installed → today's behaviour, no pin).
+ *
+ * `platform` and `runHelp` are injectable for tests; the defaults probe the
+ * real machine and memoise the result per-process.
+ *
+ * @param {{ platform?: string, runHelp?: () => Promise<string|null> }} [opts]
+ * @returns {Promise<string|null>}
+ */
+async function detectDefaultGenerator({ platform, runHelp } = {}) {
+  const injected = platform !== undefined || runHelp !== undefined;
+  if (!injected && cachedDefault !== undefined) return cachedDefault;
+
+  const plat = platform ?? process.platform;
+  let result = null;
+  if (plat === 'win32') {
+    const helpText = await (runHelp ?? runCmakeHelp)();
+    const name = helpText ? parseDefaultGenerator(helpText) : null;
+    // Only VS generators need an arch pin; everything else (Ninja, NMake, …)
+    // already honours the active vcvarsall env for target arch.
+    result = isVisualStudioGenerator(name) ? name : null;
+  }
+
+  if (!injected) cachedDefault = result;
+  return result;
+}
+
+/**
+ * Resolve the generator a CMake invocation will actually use, given an
+ * optional explicit choice (CLI `--generator` or a recipe `build.generator`)
+ * and the active profile.
+ *
+ *   - An explicit non-empty generator always wins, verbatim.
+ *   - Otherwise, on a Windows/MSVC profile, fall back to the detected default
+ *     VS generator so callers can pin `-A`/architecture against it.
+ *   - Otherwise null — the caller leaves the generator unpinned (CMake picks
+ *     its default), exactly as before this feature. On non-Windows toolchains
+ *     target arch is the compiler's job, not the generator's.
+ *
+ * @param {{ explicit?: string|null,
+ *           profile?: { os?: string, compiler?: string }|null,
+ *           detect?: () => Promise<string|null> }} [args]
+ * @returns {Promise<string|null>}
+ */
+async function resolveEffectiveGenerator({ explicit = null, profile = null, detect = detectDefaultGenerator } = {}) {
+  if (typeof explicit === 'string' && explicit.trim()) return explicit;
+  if (profile && profile.os === 'Windows' && profile.compiler === 'msvc') {
+    return detect();
+  }
+  return null;
+}
+
+module.exports = {
+  resolveEffectiveGenerator,
+  detectDefaultGenerator,
+  // Exported for unit tests
+  parseDefaultGenerator,
+};

package/src/commands/build.js

@@ -7,6 +7,7 @@ const { spawn } = require('child_process');
 const { normalizeRecipe, hasBuildRecipe, VALID_CMAKE_CONFIGS, DEFAULT_RECIPE } = require('../build/recipe');
 const { loadMsvcEnv }  = require('../build/msvc-env');
 const { archToVsPlatform, isVisualStudioGenerator } = require('../toolchain');
+const { resolveEffectiveGenerator } = require('../build/default-generator');
 const { LOCAL_OVERLAY_FILENAME, readLocalOverlay } = require('../conf');
 const { resolveBinaryDirRoot, DEFAULT_BINARY_DIR_ROOT } = require('../binary-dir');
 const { buildContext } = require('../context');
@@ -384,9 +385,17 @@ async function build(argv) {
         if (recipe.generators.length > 0) [presetGenerator] = recipe.generators;
       } catch { /* templates need options → skip env activation */ }
     }
-    // CLI --generator wins — that is the generator CMake will actually use,
-    // so it is the one that determines whether vcvarsall must be activated.
-    if (!effectiveGenerator) effectiveGenerator = presetGenerator;
+    // CLI --generator wins, then the recipe's generator, then — on a
+    // Windows/MSVC profile with neither — CMake's detected default VS
+    // generator. Resolving the default here keeps the `-A` pin below and the
+    // vcvarsall-skip decision consistent with the generator `cmake --preset`
+    // will actually use (install pins the same generator into the preset).
+    // Non-Windows / non-MSVC → null, unchanged from before.
+    // See claude/PLAN-VS-ARCH-PIN.md.
+    effectiveGenerator = await resolveEffectiveGenerator({
+      explicit: effectiveGenerator ?? presetGenerator,
+      profile:  activeProfile,
+    });
     cmakeEnv = await loadMsvcEnv({
       profile:          activeProfile,
       skipForGenerator: effectiveGenerator,

package/src/commands/cache.js

@@ -1,189 +1,265 @@
-'use strict';
-
-// F12: source-build cache inspection + targeted pruning.
-//
-// `wyvrnpm cache list [pattern]` prints a human-readable table (or JSON
-// with --format json) of everything in the machine-wide source-build
-// cache at `%LOCALAPPDATA%\wyvrnpm\bc\`.
-//
-// `wyvrnpm cache prune` removes cache entries per a policy:
-//   --keep-last N      retain N most-recently-touched per (name,version)
-//   --older-than 30d   also remove entries older than the threshold
-//   --pattern <glob>   restrict to matching package names
-//   --dry-run          print what would go, remove nothing
-//
-// The existing `wyvrnpm clean --build-cache` nukes everything; this is
-// the targeted alternative for teams whose `--upload-built` cache has
-// ballooned.
-
-const {
-  listCacheEntries,
-  computePruneSet,
-  removeCacheEntries,
-  parseDurationToCutoff,
-  getBuildCacheRoot,
-} = require('../build/cache');
-const log = require('../logger');
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function formatBytes(n) {
-  if (n < 1024) return `${n} B`;
-  const units = ['KB', 'MB', 'GB', 'TB'];
-  let size = n / 1024, i = 0;
-  while (size >= 1024 && i < units.length - 1) { size /= 1024; i++; }
-  return `${size.toFixed(size >= 100 ? 0 : 1)} ${units[i]}`;
-}
-
-function formatMtime(ms) {
-  if (!ms) return '<unknown>';
-  return new Date(ms).toISOString().replace('T', ' ').slice(0, 16);
-}
-
-function globToRegExp(glob) {
-  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&');
-  return new RegExp(`^${escaped.replace(/\*/g, '.*').replace(/\?/g, '.')}$`);
-}
-
-function patternFor(argPattern, positional) {
-  const src = argPattern ?? positional ?? null;
-  return src ? globToRegExp(src) : null;
-}
-
-// ---------------------------------------------------------------------------
-// list
-// ---------------------------------------------------------------------------
-
-/**
- * wyvrnpm cache list [pattern] [--format json|text]
- *
- * @param {object} argv
- */
-function list(argv) {
-  const entries = listCacheEntries();
-  const regex   = patternFor(argv.pattern, argv._?.[1]);
-  const filtered = regex ? entries.filter((e) => regex.test(e.name)) : entries;
-
-  // Newest first — matches what `ls -lt` users expect.
-  filtered.sort((a, b) => b.mtimeMs - a.mtimeMs);
-
-  if (argv.format === 'json') {
-    process.stdout.write(JSON.stringify({
-      command:       'cache-list',
-      cacheRoot:     getBuildCacheRoot(),
-      totalEntries:  filtered.length,
-      totalBytes:    filtered.reduce((s, e) => s + e.sizeBytes, 0),
-      entries:       filtered.map((e) => ({
-        name:        e.name,
-        version:     e.version,
-        profileHash: e.profileHash,
-        sizeBytes:   e.sizeBytes,
-        mtime:       new Date(e.mtimeMs).toISOString(),
-        hasArtefact: e.hasArtefact,
-        uploadCount: e.uploads.length,
-      })),
-    }, null, 2) + '\n');
-    return;
-  }
-
-  log.info(`Cache root : ${getBuildCacheRoot()}`);
-  if (filtered.length === 0) {
-    log.info('  (empty)');
-    return;
-  }
-
-  const rows = filtered.map((e) => [
-    e.name,
-    e.version,
-    e.profileHash,
-    formatBytes(e.sizeBytes),
-    formatMtime(e.mtimeMs),
-    e.uploads.length > 0 ? `${e.uploads.length}` : '-',
-  ]);
-  const header = ['NAME', 'VERSION', 'PROFILE HASH', 'SIZE', 'MTIME', 'UPLOADS'];
-  const widths = header.map((h, i) =>
-    Math.max(h.length, ...rows.map((r) => String(r[i]).length)),
-  );
-
-  const format = (cells) => cells.map((c, i) => String(c).padEnd(widths[i])).join('  ');
-  console.log('');
-  console.log('  ' + format(header));
-  console.log('  ' + widths.map((w) => '-'.repeat(w)).join('  '));
-  for (const r of rows) console.log('  ' + format(r));
-  console.log('');
-
-  const totalBytes = filtered.reduce((s, e) => s + e.sizeBytes, 0);
-  log.info(`${filtered.length} entries, ${formatBytes(totalBytes)} total`);
-}
-
-// ---------------------------------------------------------------------------
-// prune
-// ---------------------------------------------------------------------------
-
-/**
- * wyvrnpm cache prune [--keep-last N] [--older-than 30d] [--pattern X] [--dry-run]
- *
- * Requires at least one of --keep-last / --older-than to avoid footgun
- * (use `wyvrnpm clean --build-cache` to wipe everything).
- *
- * @param {object} argv
- */
-function prune(argv) {
-  const hasKeep  = argv.keepLast !== undefined && argv.keepLast !== null;
-  const hasOlder = typeof argv.olderThan === 'string' && argv.olderThan.length > 0;
-
-  if (!hasKeep && !hasOlder) {
-    log.error(
-      'cache prune: specify --keep-last <N> and/or --older-than <duration>.\n' +
-      '  To wipe the entire build cache, use `wyvrnpm clean --build-cache`.',
-    );
-    process.exit(1);
-  }
-
-  const policy = {};
-  if (hasKeep) {
-    const n = Number(argv.keepLast);
-    if (!Number.isInteger(n) || n < 0) {
-      log.error(`--keep-last must be a non-negative integer, got ${argv.keepLast}`);
-      process.exit(1);
-    }
-    policy.keepLast = n;
-  }
-  if (hasOlder) {
-    try { policy.olderThanMs = parseDurationToCutoff(argv.olderThan); }
-    catch (err) { log.error(err.message); process.exit(1); }
-  }
-  if (argv.pattern) {
-    policy.patternRegex = globToRegExp(argv.pattern);
-  }
-
-  const entries  = listCacheEntries();
-  const pruneSet = computePruneSet(entries, policy);
-
-  if (pruneSet.length === 0) {
-    log.info('Nothing to prune under that policy.');
-    return;
-  }
-
-  const totalBytes = pruneSet.reduce((s, e) => s + e.sizeBytes, 0);
-  const verb = argv.dryRun ? 'Would remove' : 'Removing';
-  log.info(`${verb} ${pruneSet.length} cache entr${pruneSet.length === 1 ? 'y' : 'ies'}, ${formatBytes(totalBytes)}:`);
-  for (const e of pruneSet) {
-    console.log(`  - ${e.name}@${e.version} [${e.profileHash}]  ${formatBytes(e.sizeBytes)}  ${formatMtime(e.mtimeMs)}`);
-  }
-
-  if (argv.dryRun) {
-    log.info('(dry-run — nothing deleted)');
-    return;
-  }
-
-  const removed = removeCacheEntries(pruneSet);
-  log.info(`Removed ${removed.length} of ${pruneSet.length} cache entr${pruneSet.length === 1 ? 'y' : 'ies'}`);
-  if (removed.length < pruneSet.length) {
-    log.warn(`${pruneSet.length - removed.length} entr${pruneSet.length - removed.length === 1 ? 'y' : 'ies'} could not be removed (permissions or concurrent access)`);
-  }
-}
-
-module.exports = { list, prune };
+'use strict';
+
+// F12: cache inspection + targeted pruning for both cache types.
+//
+// Two machine-wide caches exist:
+//   src  — source-build cache at %LOCALAPPDATA%\wyvrnpm\bc\
+//           (entries built from source via wyvrnpm install --build=missing)
+//   pkg  — binary package cache at %LOCALAPPDATA%\wyvrnpm\pkg\
+//           (downloaded prebuilt zips; TTL 14 days)
+//
+// `wyvrnpm cache list [pattern] [--type src|pkg|all]`
+//   Prints a human-readable table (or JSON with --format json) of entries
+//   from the selected cache type(s).
+//
+// `wyvrnpm cache prune [--type src|pkg|all] [--keep-last N] [--older-than 30d] ...`
+//   Removes entries per a policy; --type restricts which cache(s) are pruned.
+//
+// `wyvrnpm clean --build-cache` / `wyvrnpm clean --pkg-cache` still nuke
+// each cache root entirely; these commands are the targeted alternative.
+
+const {
+  listCacheEntries,
+  computePruneSet,
+  removeCacheEntries,
+  parseDurationToCutoff,
+  getBuildCacheRoot,
+} = require('../build/cache');
+const {
+  listPkgCacheEntries,
+  computePkgPruneSet,
+  removePkgCacheEntries,
+  getPkgCacheRoot,
+} = require('../pkg-cache');
+const log = require('../logger');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function formatBytes(n) {
+  if (n < 1024) return `${n} B`;
+  const units = ['KB', 'MB', 'GB', 'TB'];
+  let size = n / 1024, i = 0;
+  while (size >= 1024 && i < units.length - 1) { size /= 1024; i++; }
+  return `${size.toFixed(size >= 100 ? 0 : 1)} ${units[i]}`;
+}
+
+function formatMtime(ms) {
+  if (!ms) return '<unknown>';
+  return new Date(ms).toISOString().replace('T', ' ').slice(0, 16);
+}
+
+function globToRegExp(glob) {
+  const escaped = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`^${escaped.replace(/\*/g, '.*').replace(/\?/g, '.')}$`);
+}
+
+function patternFor(argPattern, positional) {
+  const src = argPattern ?? positional ?? null;
+  return src ? globToRegExp(src) : null;
+}
+
+/**
+ * Resolve --type to the set of cache types to act on.
+ * @param {string|undefined} typeArg
+ * @returns {{ includeSrc: boolean, includePkg: boolean }}
+ */
+function resolveType(typeArg) {
+  const t = (typeArg ?? 'all').toLowerCase();
+  if (t === 'src')  return { includeSrc: true,  includePkg: false };
+  if (t === 'pkg')  return { includeSrc: false, includePkg: true  };
+  if (t === 'all')  return { includeSrc: true,  includePkg: true  };
+  throw new Error(`--type must be src, pkg, or all (got ${JSON.stringify(typeArg)})`);
+}
+
+// ---------------------------------------------------------------------------
+// list
+// ---------------------------------------------------------------------------
+
+/**
+ * wyvrnpm cache list [pattern] [--type src|pkg|all] [--format json|text]
+ *
+ * @param {object} argv
+ */
+function list(argv) {
+  let typeOpts;
+  try { typeOpts = resolveType(argv.type); }
+  catch (err) { log.error(err.message); process.exit(1); }
+
+  const { includeSrc, includePkg } = typeOpts;
+  const regex = patternFor(argv.pattern, argv._?.[1]);
+
+  // Collect entries from each selected cache, tagged with type.
+  const allEntries = [];
+  if (includeSrc) {
+    for (const e of listCacheEntries()) {
+      allEntries.push({ ...e, cacheType: 'src' });
+    }
+  }
+  if (includePkg) {
+    for (const e of listPkgCacheEntries()) {
+      allEntries.push({ ...e, cacheType: 'pkg' });
+    }
+  }
+
+  const filtered = regex ? allEntries.filter((e) => regex.test(e.name)) : allEntries;
+  filtered.sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  if (argv.format === 'json') {
+    process.stdout.write(JSON.stringify({
+      command:      'cache-list',
+      cacheRoots:   {
+        ...(includeSrc ? { src: getBuildCacheRoot() } : {}),
+        ...(includePkg ? { pkg: getPkgCacheRoot()   } : {}),
+      },
+      totalEntries: filtered.length,
+      totalBytes:   filtered.reduce((s, e) => s + e.sizeBytes, 0),
+      entries:      filtered.map((e) => ({
+        type:        e.cacheType,
+        name:        e.name,
+        version:     e.version,
+        profileHash: e.profileHash,
+        sizeBytes:   e.sizeBytes,
+        mtime:       new Date(e.mtimeMs).toISOString(),
+        ...(e.cacheType === 'src'
+          ? { hasArtefact: e.hasArtefact, uploadCount: e.uploads?.length ?? 0 }
+          : { downloadedAt: e.downloadedAt }),
+      })),
+    }, null, 2) + '\n');
+    return;
+  }
+
+  // Text output — show each selected cache root.
+  if (includeSrc) log.info(`Source-build cache : ${getBuildCacheRoot()}`);
+  if (includePkg) log.info(`Binary pkg cache   : ${getPkgCacheRoot()}`);
+
+  if (filtered.length === 0) {
+    log.info('  (empty)');
+    return;
+  }
+
+  const showType = includeSrc && includePkg;
+  const rows = filtered.map((e) => [
+    ...(showType ? [e.cacheType] : []),
+    e.name,
+    e.version,
+    e.profileHash,
+    formatBytes(e.sizeBytes),
+    formatMtime(e.mtimeMs),
+    e.cacheType === 'src'
+      ? (e.uploads?.length > 0 ? `${e.uploads.length}` : '-')
+      : (e.downloadedAt ? e.downloadedAt.slice(0, 10) : '-'),
+  ]);
+  const header = [
+    ...(showType ? ['TYPE'] : []),
+    'NAME', 'VERSION', 'PROFILE HASH', 'SIZE', 'MTIME',
+    showType ? 'UPLOADS/DL' : (includeSrc ? 'UPLOADS' : 'DOWNLOADED'),
+  ];
+  const widths = header.map((h, i) =>
+    Math.max(h.length, ...rows.map((r) => String(r[i]).length)),
+  );
+  const format = (cells) => cells.map((c, i) => String(c).padEnd(widths[i])).join('  ');
+  console.log('');
+  console.log('  ' + format(header));
+  console.log('  ' + widths.map((w) => '-'.repeat(w)).join('  '));
+  for (const r of rows) console.log('  ' + format(r));
+  console.log('');
+
+  const totalBytes = filtered.reduce((s, e) => s + e.sizeBytes, 0);
+  log.info(`${filtered.length} entries, ${formatBytes(totalBytes)} total`);
+}
+
+// ---------------------------------------------------------------------------
+// prune
+// ---------------------------------------------------------------------------
+
+/**
+ * wyvrnpm cache prune [--type src|pkg|all] [--keep-last N] [--older-than 30d] [--pattern X] [--dry-run]
+ *
+ * @param {object} argv
+ */
+function prune(argv) {
+  let typeOpts;
+  try { typeOpts = resolveType(argv.type); }
+  catch (err) { log.error(err.message); process.exit(1); }
+
+  const { includeSrc, includePkg } = typeOpts;
+  const hasKeep  = argv.keepLast !== undefined && argv.keepLast !== null;
+  const hasOlder = typeof argv.olderThan === 'string' && argv.olderThan.length > 0;
+
+  if (!hasKeep && !hasOlder) {
+    const clearCmd = includeSrc && includePkg
+      ? '`wyvrnpm clean --build-cache` / `wyvrnpm clean --pkg-cache`'
+      : includeSrc ? '`wyvrnpm clean --build-cache`' : '`wyvrnpm clean --pkg-cache`';
+    log.error(
+      `cache prune: specify --keep-last <N> and/or --older-than <duration>.\n` +
+      `  To wipe the entire cache, use ${clearCmd}.`,
+    );
+    process.exit(1);
+  }
+
+  const policy = {};
+  if (hasKeep) {
+    const n = Number(argv.keepLast);
+    if (!Number.isInteger(n) || n < 0) {
+      log.error(`--keep-last must be a non-negative integer, got ${argv.keepLast}`);
+      process.exit(1);
+    }
+    policy.keepLast = n;
+  }
+  if (hasOlder) {
+    try { policy.olderThanMs = parseDurationToCutoff(argv.olderThan); }
+    catch (err) { log.error(err.message); process.exit(1); }
+  }
+  if (argv.pattern) {
+    policy.patternRegex = globToRegExp(argv.pattern);
+  }
+
+  // Collect prune sets from selected caches, tagged with type.
+  const pruneSet = [];
+  if (includeSrc) {
+    for (const e of computePruneSet(listCacheEntries(), policy)) {
+      pruneSet.push({ ...e, cacheType: 'src' });
+    }
+  }
+  if (includePkg) {
+    for (const e of computePkgPruneSet(listPkgCacheEntries(), policy)) {
+      pruneSet.push({ ...e, cacheType: 'pkg' });
+    }
+  }
+  pruneSet.sort((a, b) => b.mtimeMs - a.mtimeMs);
+
+  if (pruneSet.length === 0) {
+    log.info('Nothing to prune under that policy.');
+    return;
+  }
+
+  const totalBytes = pruneSet.reduce((s, e) => s + e.sizeBytes, 0);
+  const verb = argv.dryRun ? 'Would remove' : 'Removing';
+  const showType = includeSrc && includePkg;
+  log.info(`${verb} ${pruneSet.length} cache entr${pruneSet.length === 1 ? 'y' : 'ies'}, ${formatBytes(totalBytes)}:`);
+  for (const e of pruneSet) {
+    const typeTag = showType ? `[${e.cacheType}] ` : '';
+    console.log(`  - ${typeTag}${e.name}@${e.version} [${e.profileHash}]  ${formatBytes(e.sizeBytes)}  ${formatMtime(e.mtimeMs)}`);
+  }
+
+  if (argv.dryRun) {
+    log.info('(dry-run — nothing deleted)');
+    return;
+  }
+
+  // Partition and remove per cache type.
+  const srcEntries = pruneSet.filter((e) => e.cacheType === 'src');
+  const pkgEntries = pruneSet.filter((e) => e.cacheType === 'pkg');
+  const removedSrc = srcEntries.length > 0 ? removeCacheEntries(srcEntries) : [];
+  const removedPkg = pkgEntries.length > 0 ? removePkgCacheEntries(pkgEntries) : [];
+  const totalRemoved = removedSrc.length + removedPkg.length;
+
+  log.info(`Removed ${totalRemoved} of ${pruneSet.length} cache entr${pruneSet.length === 1 ? 'y' : 'ies'}`);
+  if (totalRemoved < pruneSet.length) {
+    log.warn(`${pruneSet.length - totalRemoved} entr${pruneSet.length - totalRemoved === 1 ? 'y' : 'ies'} could not be removed (permissions or concurrent access)`);
+  }
+}
+
+module.exports = { list, prune };

package/src/commands/clean.js

@@ -8,6 +8,7 @@ const {
   getBuildCacheRoot,
   clearUploadSidecars,
 } = require('../build/cache');
+const { clearPkgCache, getPkgCacheRoot } = require('../pkg-cache');
 const { readConfig }                = require('../config');
 const { readLocalOverlay }          = require('../conf');
 const { resolveBinaryDirRoot }      = require('../binary-dir');
@@ -149,6 +150,7 @@ function stripPresetsFromWorkspace(rootDir, { dryRun }) {
  * @param {boolean} [argv.buildDir]       When true, also wipes <binaryDirRoot>/wyvrn-<profile>/.
  * @param {boolean} [argv.all]            When true, scorched-earth workspace cleanup.
  * @param {boolean} [argv.buildCache]     When true, also nukes the source-build cache.
+ * @param {boolean} [argv.pkgCache]       When true, also nukes the binary pkg cache.
  * @param {boolean} [argv.uploadedBuilt]  When true, wipes upload sidecars only.
  * @param {boolean} [argv.dryRun]         When true, log intentions but write nothing.
  * @returns {Promise<void>}
@@ -240,6 +242,21 @@ async function clean(argv) {
     }
   }
 
+  if (argv.pkgCache) {
+    if (dryRun) {
+      log.info(`Would remove binary package cache ${getPkgCacheRoot()}`);
+      removedAnything = true;
+    } else {
+      const removed = clearPkgCache();
+      if (removed) {
+        log.info(`Removed binary package cache ${removed}`);
+        removedAnything = true;
+      } else {
+        log.info(`No binary package cache at ${getPkgCacheRoot()}`);
+      }
+    }
+  }
+
   if (!removedAnything) {
     log.info('Nothing to clean.');
   } else if (dryRun) {

package/src/commands/install.js

@@ -18,6 +18,7 @@ const { resolveBinaryDirRoot }                              = require('../binary
 const { hashProfile, formatProfile, mergeProfile }          = require('../profile');
 const { generateToolchain, generateCMakePresets }           = require('../toolchain');
 const { normalizeRecipe, hasBuildRecipe }                   = require('../build/recipe');
+const { resolveEffectiveGenerator }                         = require('../build/default-generator');
 const { buildContext }                                      = require('../context');
 const {
   normalizeOptionsDeclaration,
@@ -661,6 +662,21 @@ async function install(argv) {
     }
   }
 
+  // When no generator was pinned by a recipe (the common recipe-less consumer
+  // case), CMake falls back to its platform default. On Windows that's the
+  // newest Visual Studio, which silently targets host x64 unless
+  // `-A`/architecture is pinned — so an x86 (or any non-host-arch) profile
+  // would produce mismatched binaries that find_package() later rejects with a
+  // pointer-size error. Resolve the default to a concrete VS generator so the
+  // preset carries both `generator` and `architecture` (buildConfigurePreset
+  // pins arch only when it knows the generator is VS). Non-Windows / non-MSVC
+  // → null, leaving the preset generator-less exactly as before. See
+  // claude/PLAN-VS-ARCH-PIN.md.
+  presetGenerator = await resolveEffectiveGenerator({
+    explicit: presetGenerator,
+    profile:  baseProfile,
+  });
+
   // PLAN-CONF.md §4.3 / §5 presets sink: fold effectiveConf's
   // cmake.cache namespace into the preset's cacheVariables. Runs
   // regardless of whether the project has its own build recipe —

package/src/download.js

@@ -8,6 +8,12 @@ const StreamZip = require('node-stream-zip');
 
 const { isLink, getLinkTarget } = require('./link-utils');
 const { sha256Of }              = require('./profile');
+const {
+  getPkgCacheDir,
+  readPkgCacheMeta,
+  writePkgCacheMeta,
+  isCacheEntryFresh,
+} = require('./pkg-cache');
 const { getProvider }           = require('./providers');
 const { evaluateCompat, pickBestCandidate, summarizeReasons } = require('./compat');
 const { buildFromSource }       = require('./build');
@@ -18,6 +24,82 @@ const { verifyAttestation, parseSigEnvelope } = require('./signing');
 const { assertBoundHashes }     = require('./signing/attestation');
 const log                       = require('./logger');
 
+// ---------------------------------------------------------------------------
+// Machine-wide binary package cache helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Check the machine-wide pkg cache for a fresh entry. Returns a hit descriptor
+ * or null on miss. Does NOT SHA-verify the cached zip — we trust local disk
+ * integrity the same way Conan does; corrupt zips surface as extract errors
+ * and fall through to re-download.
+ *
+ * @param {{ name, version, profileHash, requestConfigs: string[]|null }} args
+ * @returns {{ kind: 'fat-zip'|'slice', zipPath?: string, contentSha256?: string|null,
+ *             slices?: Array<{config,zipPath,sha256}>, configs?: string[], meta: object }|null}
+ */
+function checkPkgCacheHit({ name, version, profileHash, requestConfigs }) {
+  const cacheDir = getPkgCacheDir({ name, version, profileHash });
+  const meta     = readPkgCacheMeta(cacheDir);
+  if (!meta || !isCacheEntryFresh(meta)) return null;
+
+  if (!meta.configs) {
+    // Fat-zip entry
+    const zipPath = path.join(cacheDir, 'wyvrn.zip');
+    if (!fs.existsSync(zipPath)) return null;
+    return { kind: 'fat-zip', zipPath, contentSha256: meta.contentSha256 ?? null, meta };
+  }
+
+  // Slice entry — serve requested configs that are cached; full miss if any are absent
+  const available = Object.keys(meta.configs);
+  const requested = (Array.isArray(requestConfigs) && requestConfigs.length > 0)
+    ? requestConfigs
+    : available;
+  const toServe = requested.filter((c) => available.includes(c));
+  if (toServe.length === 0) return null;
+
+  const slices = [];
+  for (const config of toServe) {
+    const zipPath = path.join(cacheDir, `wyvrn-${config}.zip`);
+    if (!fs.existsSync(zipPath)) return null; // partial cache — re-download everything
+    slices.push({ config, zipPath, sha256: meta.configs[config] ?? null });
+  }
+  return { kind: 'slice', slices, configs: toServe.slice().sort(), meta };
+}
+
+/**
+ * Save a successfully-downloaded v2 artefact to the pkg cache. Non-fatal:
+ * caller wraps in try/catch and logs a warning on failure.
+ *
+ * @param {{ name, version, profileHash, downloadResult: object, destZipPath: string }} args
+ */
+function saveToPkgCache({ name, version, profileHash, downloadResult, destZipPath }) {
+  const cacheDir = getPkgCacheDir({ name, version, profileHash });
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  if (downloadResult.kind === 'slice') {
+    for (const slice of downloadResult.slices ?? []) {
+      fs.copyFileSync(slice.zipPath, path.join(cacheDir, `wyvrn-${slice.config}.zip`));
+    }
+    writePkgCacheMeta(cacheDir, {
+      name, version, profileHash,
+      downloadedAt: new Date().toISOString(),
+      configs:  Object.fromEntries((downloadResult.slices ?? []).map((s) => [s.config, s.sha256])),
+      gitSha:   downloadResult.gitSha  ?? null,
+      gitRepo:  downloadResult.gitRepo ?? null,
+    });
+  } else {
+    fs.copyFileSync(destZipPath, path.join(cacheDir, 'wyvrn.zip'));
+    writePkgCacheMeta(cacheDir, {
+      name, version, profileHash,
+      downloadedAt:  new Date().toISOString(),
+      contentSha256: downloadResult.contentSha256 ?? null,
+      gitSha:        downloadResult.gitSha        ?? null,
+      gitRepo:       downloadResult.gitRepo       ?? null,
+    });
+  }
+}
+
 // ---------------------------------------------------------------------------
 // v1 (legacy) download helpers
 // ---------------------------------------------------------------------------
@@ -722,6 +804,68 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
       }
     }
 
+    // ── Check machine-wide binary package cache ────────────────────────────
+    // Skip under --build=always (F9 forces a fresh source-build, so serving
+    // from cache defeats the purpose) and for legacy deps without a profile.
+    if (profileHash && profile && buildMode !== 'always') {
+      const pkgHit = checkPkgCacheHit({
+        name, version, profileHash,
+        requestConfigs: depEffectiveRequestConfigs,
+      });
+      if (pkgHit) {
+        try {
+          fs.mkdirSync(extractDir, { recursive: true });
+          if (pkgHit.kind === 'slice') {
+            for (const slice of pkgHit.slices) {
+              await extractZip(slice.zipPath, extractDir);
+            }
+          } else {
+            await extractZip(pkgHit.zipPath, extractDir);
+          }
+          fs.writeFileSync(versionFile, version, 'utf8');
+          const restoredMeta = {
+            version,
+            resolvedFrom: 'cached',
+            profileHash,
+            ...(pkgHit.kind === 'slice'
+              ? {
+                  configs:         pkgHit.configs,
+                  perConfigSha256: Object.fromEntries(pkgHit.slices.map((s) => [s.config, s.sha256])),
+                }
+              : { contentSha256: pkgHit.contentSha256 }),
+            gitSha:      pkgHit.meta.gitSha  ?? null,
+            gitRepo:     pkgHit.meta.gitRepo ?? null,
+            installedAt: new Date().toISOString(),
+            signer:      pkgHit.meta.signer  ?? null,
+          };
+          fs.writeFileSync(metaFile, JSON.stringify(restoredMeta, null, 2) + '\n', 'utf8');
+          log.info(
+            `Restored from pkg cache: ${name}@${version} [${profileHash}]` +
+            (pkgHit.kind === 'slice' ? ` configs=[${pkgHit.configs.join(', ')}]` : ''),
+          );
+          lockEntries.set(name, {
+            version,
+            resolvedFrom: 'cached',
+            profileHash,
+            ...(pkgHit.kind === 'slice'
+              ? {
+                  configs:         pkgHit.configs,
+                  perConfigSha256: Object.fromEntries(pkgHit.slices.map((s) => [s.config, s.sha256])),
+                }
+              : { contentSha256: pkgHit.contentSha256 }),
+            gitSha: pkgHit.meta.gitSha ?? null,
+            ...(options      ? { options }                   : {}),
+            ...(pinnedSource ? { source: pinnedSource.name } : {}),
+          });
+          continue;
+        } catch (err) {
+          log.warn(`pkg-cache restore failed for ${name}@${version} — ${err.message}; re-downloading`);
+          // Clean up partial extract and fall through to normal download.
+          try { fs.rmSync(extractDir, { recursive: true, force: true }); } catch { /* ignore */ }
+        }
+      }
+    }
+
     log.info(`Downloading: ${name}@${version}`);
     const destZipPath = path.join(razerDir, `${name}.zip`);
 
@@ -934,6 +1078,23 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
       }
     }
 
+    // ── Save to machine-wide binary package cache ──────────────────────────
+    // Only for exact v2 hits (resolvedFrom v2 or v2-slice) where the
+    // downloaded profileHash matches the consumer's requested hash.
+    // Compat and source-build have different trust/reuse stories so we
+    // leave them out of the pkg cache in phase 1.
+    if (
+      profileHash &&
+      (resolvedFrom === 'v2' || resolvedFrom === 'v2-slice') &&
+      downloadResult?.profileHash === profileHash
+    ) {
+      try {
+        saveToPkgCache({ name, version, profileHash, downloadResult, destZipPath });
+      } catch (err) {
+        log.warn(`pkg-cache: failed to save ${name}@${version} — ${err.message}`);
+      }
+    }
+
     // ── Extract ─────────────────────────────────────────────────────────────
     try {
       fs.mkdirSync(extractDir, { recursive: true });

package/src/pkg-cache.js

@@ -0,0 +1,296 @@
+'use strict';
+
+// Machine-wide binary package cache.
+//
+// Downloaded prebuilt zips are stored here so that a `wyvrnpm clean` or a
+// fresh CI agent can restore from local disk instead of hitting S3 again.
+//
+// Cache root:
+//   Windows: %LOCALAPPDATA%\wyvrnpm\pkg\
+//   Unix   : ~/.cache/wyvrnpm/pkg/
+//
+// Entry layout per (name, version, profileHash):
+//   <root>/<name>-<version>-<profileHash>/
+//     wyvrn.zip               (fat-zip publish)
+//     wyvrn-<Config>.zip      (per-config slice publish, one per config)
+//     .pkg-meta.json          sidecar — see schema below
+//
+// .pkg-meta.json schema:
+//   { name, version, profileHash,
+//     downloadedAt: ISO8601,          <- TTL anchor
+//     contentSha256?: string,         <- fat-zip SHA (absent for slices)
+//     configs?: { Config: sha256 },   <- slice SHAs (absent for fat-zip)
+//     gitSha?:   string,
+//     gitRepo?:  string }
+//
+// TTL: 14 days from downloadedAt (strict — stale entries are re-downloaded).
+// Cache writes are non-fatal: a failure logs a warning and install continues.
+//
+// Prune / clear surface:
+//   wyvrnpm clean --pkg-cache           wipe the entire pkg\ root
+//   wyvrnpm cache list --type pkg       list pkg entries
+//   wyvrnpm cache prune --type pkg      policy-based prune
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const { parseDurationToCutoff, CACHE_DIR_RE } = require('./build/cache');
+
+const DEFAULT_PKG_CACHE_TTL_MS = 14 * 24 * 60 * 60 * 1000; // 14 days
+
+const PKG_META_FILE = '.pkg-meta.json';
+
+// ---------------------------------------------------------------------------
+// Path helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Root directory for the binary package cache.
+ *   Windows: %LOCALAPPDATA%\wyvrnpm\pkg\
+ *   Unix   : ~/.cache/wyvrnpm/pkg/
+ *
+ * @returns {string}
+ */
+function getPkgCacheRoot() {
+  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, 'pkg');
+}
+
+/**
+ * Per-artefact cache directory, keyed by `(name, version, profileHash)`.
+ *
+ * @param {{ name: string, version: string, profileHash: string }} args
+ * @returns {string}
+ */
+function getPkgCacheDir({ name, version, profileHash }) {
+  const safeName    = name.replace(/[^\w.-]/g, '_');
+  const safeVersion = version.replace(/[^\w.-]/g, '_');
+  const safeHash    = profileHash.replace(/[^\w.-]/g, '_');
+  return path.join(getPkgCacheRoot(), `${safeName}-${safeVersion}-${safeHash}`);
+}
+
+/**
+ * Standard paths within a pkg cache entry.
+ *
+ * @param {{ name: string, version: string, profileHash: string }} args
+ * @returns {{ dir: string, metaFile: string, zipFile: string, sliceZip: (config: string) => string }}
+ */
+function getPkgCachePaths({ name, version, profileHash }) {
+  const dir = getPkgCacheDir({ name, version, profileHash });
+  return {
+    dir,
+    metaFile: path.join(dir, PKG_META_FILE),
+    zipFile:  path.join(dir, 'wyvrn.zip'),
+    sliceZip: (config) => path.join(dir, `wyvrn-${config}.zip`),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Meta sidecar
+// ---------------------------------------------------------------------------
+
+/**
+ * Read `.pkg-meta.json` from a cache entry dir. Returns null when absent or corrupt.
+ *
+ * @param {string} dir
+ * @returns {object|null}
+ */
+function readPkgCacheMeta(dir) {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(dir, PKG_META_FILE), 'utf8'));
+    if (!raw || typeof raw !== 'object') return null;
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write `.pkg-meta.json` to a cache entry dir (creates the dir if needed).
+ *
+ * @param {string} dir
+ * @param {object} meta
+ */
+function writePkgCacheMeta(dir, meta) {
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(
+    path.join(dir, PKG_META_FILE),
+    JSON.stringify(meta, null, 2) + '\n',
+    'utf8',
+  );
+}
+
+// ---------------------------------------------------------------------------
+// TTL
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a pkg cache meta entry is still within its TTL.
+ * Uses `downloadedAt` (ISO8601 string) as the anchor; defaults to 14 days.
+ *
+ * @param {object|null} meta
+ * @param {number} [ttlMs]
+ * @returns {boolean}
+ */
+function isCacheEntryFresh(meta, ttlMs = DEFAULT_PKG_CACHE_TTL_MS) {
+  if (!meta || typeof meta.downloadedAt !== 'string') return false;
+  const parsed = Date.parse(meta.downloadedAt);
+  if (Number.isNaN(parsed)) return false;
+  const age = Date.now() - parsed;
+  return age >= 0 && age < ttlMs;
+}
+
+// ---------------------------------------------------------------------------
+// Clear
+// ---------------------------------------------------------------------------
+
+/**
+ * Wipe the entire pkg cache root. Used by `wyvrnpm clean --pkg-cache`.
+ * @returns {string|null}  the path removed, or null if nothing was there.
+ */
+function clearPkgCache() {
+  const root = getPkgCacheRoot();
+  if (!fs.existsSync(root)) return null;
+  fs.rmSync(root, { recursive: true, force: true });
+  return root;
+}
+
+// ---------------------------------------------------------------------------
+// Cache inspection
+// ---------------------------------------------------------------------------
+
+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 */ }
+  }
+  return total;
+}
+
+/**
+ * List every entry in the pkg cache, enriched with metadata.
+ * Entries whose directory name can't be parsed are silently skipped.
+ *
+ * @returns {Array<{
+ *   name:          string,
+ *   version:       string,
+ *   profileHash:   string,
+ *   cacheDir:      string,
+ *   sizeBytes:     number,
+ *   mtimeMs:       number,   <- derived from downloadedAt for reliable sorting
+ *   downloadedAt:  string|null,
+ *   contentSha256: string|null,
+ *   configs:       object|null,  <- { Config: sha256 } for slices
+ * }>}
+ */
+function listPkgCacheEntries() {
+  const root = getPkgCacheRoot();
+  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;
+    const [, name, version, profileHash] = m;
+
+    const cacheDir = path.join(root, entry.name);
+    const meta     = readPkgCacheMeta(cacheDir);
+
+    const downloadedAt = meta?.downloadedAt ?? null;
+    const mtimeMs = downloadedAt
+      ? (Date.parse(downloadedAt) || 0)
+      : (() => { try { return fs.statSync(cacheDir).mtimeMs; } catch { return 0; } })();
+
+    out.push({
+      name, version, profileHash, cacheDir,
+      sizeBytes:    dirSizeBytes(cacheDir),
+      mtimeMs,
+      downloadedAt,
+      contentSha256: meta?.contentSha256 ?? null,
+      configs:       meta?.configs       ?? null,
+    });
+  }
+  return out;
+}
+
+/**
+ * Compute which pkg cache entries would be pruned under the given policy.
+ * Pure — does no I/O. Same semantics as `computePruneSet` in build/cache.js.
+ *
+ * @param {ReturnType<typeof listPkgCacheEntries>} entries
+ * @param {{ keepLast?: number, olderThanMs?: number, patternRegex?: RegExp }} policy
+ * @returns {ReturnType<typeof listPkgCacheEntries>}
+ */
+function computePkgPruneSet(entries, { keepLast, olderThanMs, patternRegex } = {}) {
+  let candidates = entries;
+  if (patternRegex) candidates = candidates.filter((e) => patternRegex.test(e.name));
+
+  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);
+      }
+    }
+  }
+
+  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 pkg cache entries. Returns the subset actually removed.
+ *
+ * @param {ReturnType<typeof listPkgCacheEntries>} entries
+ * @returns {ReturnType<typeof listPkgCacheEntries>}
+ */
+function removePkgCacheEntries(entries) {
+  const removed = [];
+  for (const e of entries) {
+    try {
+      fs.rmSync(e.cacheDir, { recursive: true, force: true });
+      removed.push(e);
+    } catch { /* skip — caller reports the delta */ }
+  }
+  return removed;
+}
+
+module.exports = {
+  DEFAULT_PKG_CACHE_TTL_MS,
+  getPkgCacheRoot,
+  getPkgCacheDir,
+  getPkgCachePaths,
+  readPkgCacheMeta,
+  writePkgCacheMeta,
+  isCacheEntryFresh,
+  clearPkgCache,
+  listPkgCacheEntries,
+  computePkgPruneSet,
+  removePkgCacheEntries,
+  // Re-export for convenience in tests
+  parseDurationToCutoff,
+};