wyvrnpm 2.17.0 → 2.19.0

package/README.md

@@ -473,6 +473,62 @@ Everything after `--` is forwarded verbatim to `cmake --build` (e.g. `-j 8`).
 
 ---
 
+### `wyvrnpm test` (2.18.0+)
+
+Runs ctest against the wyvrnpm-generated test preset (`wyvrn-<profile>-<config>`). Auto-runs `wyvrnpm build` first if the toolchain or build outputs are stale — disable with `--no-build` for a pure ctest pass.
+
+```bash
+wyvrnpm test                                  # Release config, auto-builds if stale
+wyvrnpm test --all-configs                    # Loop over every recipe config
+wyvrnpm test --config Debug,Release           # Comma-separated config list
+wyvrnpm test -R BasicSpatialGrid              # Filter by test-name regex
+wyvrnpm test -L fast                          # Filter by label
+wyvrnpm test --format json                    # JSON summary on stdout for CI
+wyvrnpm test --no-build                       # Skip auto-build, just run ctest
+wyvrnpm test -- --output-on-failure -j 8      # Passthru to ctest
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--preset` / `-P` | `wyvrn-<profile>-<config>` | Override the test preset name |
+| `--profile` / `-p` | *(config)* | Build profile — selects the preset family |
+| `--config` / `-c` | `Release` | Single or comma-separated config list |
+| `--all-configs` | `false` | Loop over every config the recipe declares (or all four canonical configs) |
+| `--verbose` / `-v` | `false` | Forwards `-V` to ctest (per-test detail) |
+| `--tests-regex` / `-R` | — | Run only tests whose name matches the regex |
+| `--label-regex` / `-L` | — | Run only tests whose label matches the regex |
+| `--auto-build` | `true` | Auto-run `wyvrnpm build` when toolchain is stale. `--no-build` opts out. |
+| `--source` / `-s` | *(config)* | Forwarded to auto-build when triggered |
+| `--build-dir` | `build` | Must match the value used at install time. Persist via `wyvrn.local.json:binaryDirRoot`. |
+| `--format` | `text` | `text` (default) streams ctest verbatim; `json` emits a structured summary on stdout, logs to stderr |
+
+Everything after `--` is forwarded verbatim to `ctest` (e.g. `--repeat until-pass:3`, `--output-junit results.xml`).
+
+**`--format json` summary**:
+
+```json
+{
+  "command":        "test",
+  "wyvrnpmVersion": "2.18.0",
+  "profile":        "default",
+  "configs": [
+    { "config": "Release", "preset": "wyvrn-default-release",
+      "total": 42, "passed": 40, "failed": 2,
+      "durationMs": 1234, "exitCode": 8 }
+  ],
+  "totalConfigs":  1,
+  "passedConfigs": 0,
+  "failedConfigs": 1,
+  "ok": false
+}
+```
+
+Exit code is `0` iff every config passes; `1` otherwise. CI scripts should gate on the `ok` field or the exit code, not on the text output.
+
+**Test-only deps pattern.** For projects that need a test framework like Catch2 / GoogleTest only during the build, the canonical recipe is to declare an `options.tests` toggle and list the framework in `buildDependencies` with `whenOption: "tests"` (see §4.1 of [CLAUDE.md](CLAUDE.md)). Consumers pulling the prebuilt artefact never see the test deps; running `wyvrnpm install -o <Pkg>:tests=true && wyvrnpm test` from the project root fetches them and runs the suite.
+
+---
+
 ### `wyvrnpm publish`
 
 Zips the project directory and uploads `wyvrn.json` + `wyvrn.zip` to the destination source, tagged with the active build profile.

package/bin/wyvrnpm.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 'use strict';
 
@@ -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.17.0",
+  "version": "2.19.0",
   "description": "A simple, static-hosting-compatible C++ package manager",
   "keywords": [
     "c++",

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/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,
+};