wyvrnpm 2.4.1 → 2.9.0

package/src/build/msvc-env.js

@@ -75,17 +75,35 @@ function findVcvarsall(vsInstallPath) {
   return fs.existsSync(p) ? p : null;
 }
 
+/**
+ * The complete set of arch arguments `vcvarsall.bat` accepts AND that we
+ * are willing to splice into a shell command. Explicit allow-list — any
+ * value outside this set is rejected (EVALUATION.md S5).
+ */
+const VCVARSALL_ARCH_ALLOWLIST = new Set(['x64', 'x86', 'arm64', 'arm']);
+
+const ARCH_MAP = {
+  x86_64: 'x64',
+  x86:    'x86',
+  armv8:  'arm64',
+  armv7:  'arm',
+};
+
 /**
  * Map a wyvrnpm profile arch to the argument `vcvarsall.bat` expects.
+ * Throws on an unknown profile arch — silently defaulting to `x64` would
+ * (a) produce a build for the wrong target, and (b) hand any shell-unsafe
+ * input to cmd.exe through captureVcvarsEnv's template.
  */
 function mapArch(profileArch) {
-  switch (profileArch) {
-    case 'x86_64': return 'x64';
-    case 'x86':    return 'x86';
-    case 'armv8':  return 'arm64';
-    case 'armv7':  return 'arm';
-    default:       return 'x64';
+  const arg = ARCH_MAP[profileArch];
+  if (!arg || !VCVARSALL_ARCH_ALLOWLIST.has(arg)) {
+    throw new Error(
+      `unsupported MSVC profile arch ${JSON.stringify(profileArch)}; ` +
+      `expected one of ${Object.keys(ARCH_MAP).join(', ')}`,
+    );
   }
+  return arg;
 }
 
 /**
@@ -105,6 +123,18 @@ function mapArch(profileArch) {
  * @returns {Promise<object|null>}
  */
 async function captureVcvarsEnv(vcvarsallPath, archArg) {
+  // Defense-in-depth at the shell boundary (EVALUATION.md S5). mapArch
+  // already restricts archArg to the allow-list; re-assert here so this
+  // function is safe to call directly (e.g. from a future caller that
+  // skips mapArch). Likewise refuse a vcvarsall path containing a
+  // double-quote — it would break out of the quoted command template.
+  if (!VCVARSALL_ARCH_ALLOWLIST.has(archArg)) {
+    throw new Error(`refusing to spawn cmd.exe with unsafe arch arg ${JSON.stringify(archArg)}`);
+  }
+  if (vcvarsallPath.includes('"')) {
+    throw new Error(`refusing to spawn cmd.exe with quote in vcvarsall path ${JSON.stringify(vcvarsallPath)}`);
+  }
+
   const MARKER = '___WYVRN_ENV_MARKER___';
   // `call` is required so the batch file returns control instead of
   // `exit`-ing the cmd shell; otherwise the `echo` + `set` after it
@@ -197,7 +227,18 @@ async function loadMsvcEnv({ profile, skipForGenerator }) {
     return null;
   }
 
-  const archArg = mapArch(profile.arch);
+  let archArg;
+  try {
+    archArg = mapArch(profile.arch);
+  } catch (err) {
+    // Unknown arch for an MSVC profile is genuinely a configuration bug
+    // (MSVC only ships toolsets for x64/x86/arm64/arm). Surface clearly
+    // and fall through to the ambient env — CMake will then error with
+    // a usable compiler-detection message instead of us silently
+    // cross-targeting x64.
+    log.warn(`  ${err.message}`);
+    return null;
+  }
   log.info(`  activating MSVC build env: vcvarsall.bat ${archArg} (${vsPath})`);
   const env = await captureVcvarsEnv(vcvarsall, archArg);
   if (!env) {
@@ -214,4 +255,6 @@ module.exports = {
   findVsInstall,
   findVcvarsall,
   mapArch,
+  captureVcvarsEnv,
+  VCVARSALL_ARCH_ALLOWLIST,
 };

package/src/build/recipe.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { substituteTemplateAll } = require('../options');
+const { readRecipeConf }        = require('../conf');
 
 /**
  * The `build` section of a source-repo `wyvrn.json` tells wyvrnpm how to
@@ -60,15 +61,22 @@ const SUPPORTED_SYSTEMS = new Set(['cmake']);
  * no options), any `${options.*}` token in the recipe also fails fast —
  * recipes don't get to reference undeclared options.
  *
+ * When `manifestForConfCollisionCheck` is supplied, PLAN-CONF.md §4.7's
+ * collision detection runs: any `-DKEY=...` in `build.configure` whose
+ * KEY is ALSO declared in recipe-level `conf.cmake.cache` is a hard
+ * error. Recipes pick ONE route, avoiding silent duplication.
+ *
  * @param {object|null|undefined} rawBuild
  * @param {Record<string, any>|null} [effectiveOptions]
+ * @param {object|null} [manifestForConfCollisionCheck]
  * @returns {{ system: string, generators: string[], configure: string[],
  *            buildArgs: string[], installDir: string, sourceSubdir: string,
  *            requiredTools: string[] }}
- * @throws {Error} when `system` is set but not supported, or when a
- *                 `${options.<name>}` template references an undeclared option
+ * @throws {Error} when `system` is set but not supported, when a
+ *                 `${options.<name>}` template references an undeclared option,
+ *                 or when `build.configure` collides with `conf.cmake.cache`.
  */
-function normalizeRecipe(rawBuild, effectiveOptions = null) {
+function normalizeRecipe(rawBuild, effectiveOptions = null, manifestForConfCollisionCheck = null) {
   const b = rawBuild ?? {};
   const system = b.system ?? DEFAULT_RECIPE.system;
   if (!SUPPORTED_SYSTEMS.has(system)) {
@@ -124,6 +132,31 @@ function normalizeRecipe(rawBuild, effectiveOptions = null) {
     'build.buildArgs',
   );
 
+  // PLAN-CONF.md §4.7: recipe-side collision between `build.configure`
+  // `-DKEY=...` args and declared `conf.cmake.cache.KEY` is a hard
+  // error. Forces the author to pick one route; avoids silent
+  // duplication where one route wins opaquely.
+  if (manifestForConfCollisionCheck) {
+    const recipeConfFlat = readRecipeConf(manifestForConfCollisionCheck);
+    const confCacheKeys = new Set(
+      Object.keys(recipeConfFlat)
+        .filter((k) => k.startsWith('cmake.cache.'))
+        .map((k) => k.slice('cmake.cache.'.length)),
+    );
+    if (confCacheKeys.size > 0) {
+      for (const arg of configure) {
+        const m = arg.match(/^-D([^=]+)=/);
+        if (m && confCacheKeys.has(m[1])) {
+          throw new Error(
+            `recipe collision: "${m[1]}" is set in both ` +
+            `build.configure (as ${JSON.stringify(arg)}) and ` +
+            `conf.cmake.cache. Pick one route — see claude/PLAN-CONF.md §4.7.`,
+          );
+        }
+      }
+    }
+  }
+
   return {
     system,
     generators,

package/src/commands/add.js

@@ -5,6 +5,7 @@ const path = require('path');
 const { readManifest, writeManifest } = require('../manifest');
 const { resolveLatestVersion }        = require('../resolve');
 const { readConfig }                  = require('../config');
+const { wyvrnFetch }                  = require('../http-fetch');
 const log                             = require('../logger');
 
 /**
@@ -99,7 +100,7 @@ async function add(argv) {
       versionToWrite = spec.version;
       log.info(`${spec.name}: writing "${versionToWrite}" (as given)`);
     } else {
-      const latest = await resolveLatestVersion(spec.name, packageSources, argv.platform, fetch);
+      const latest = await resolveLatestVersion(spec.name, packageSources, argv.platform, wyvrnFetch);
       versionToWrite = `^${latest}`;
       log.info(`${spec.name}: latest is ${latest} → writing "${versionToWrite}"`);
     }

package/src/commands/build.js

@@ -4,12 +4,11 @@ const fs   = require('fs');
 const path = require('path');
 const { spawn } = require('child_process');
 
-const { readConfig }   = require('../config');
-const { loadProfile }  = require('../profile');
-const { readManifest } = require('../manifest');
-const { normalizeRecipe, hasBuildRecipe } = require('../build/recipe');
+const { normalizeRecipe, hasBuildRecipe, VALID_CMAKE_CONFIGS, DEFAULT_RECIPE } = require('../build/recipe');
 const { loadMsvcEnv }  = require('../build/msvc-env');
 const { archToVsPlatform, isVisualStudioGenerator } = require('../toolchain');
+const { LOCAL_OVERLAY_FILENAME } = require('../conf');
+const { buildContext } = require('../context');
 const install          = require('./install');
 const log              = require('../logger');
 
@@ -29,8 +28,10 @@ const log              = require('../logger');
  * @returns {{ stale: boolean, reason: string }}
  */
 function isToolchainStale({ rootDir, manifestPath }) {
-  const lockPath      = path.join(path.dirname(manifestPath), 'wyvrn.lock');
-  const toolchainPath = path.join(rootDir, 'wyvrn_internal', 'wyvrn_toolchain.cmake');
+  const lockPath         = path.join(path.dirname(manifestPath), 'wyvrn.lock');
+  const toolchainPath    = path.join(rootDir, 'wyvrn_internal', 'wyvrn_toolchain.cmake');
+  const localOverlayPath = path.join(rootDir, LOCAL_OVERLAY_FILENAME);
+  const presetPath       = path.join(rootDir, 'CMakePresets.json');
 
   if (!fs.existsSync(toolchainPath)) {
     return { stale: true, reason: 'toolchain-missing' };
@@ -44,6 +45,19 @@ function isToolchainStale({ rootDir, manifestPath }) {
   if (lockMtime > toolchainMtime) {
     return { stale: true, reason: 'lock-newer-than-toolchain' };
   }
+
+  // PLAN-CONF.md §7: if wyvrn.local.json was edited after the preset was
+  // written, the preset's cacheVariables no longer reflect the consumer's
+  // intent. Re-run install (which regenerates the preset) rather than
+  // silently running a stale configure.
+  if (fs.existsSync(localOverlayPath) && fs.existsSync(presetPath)) {
+    const overlayMtime = fs.statSync(localOverlayPath).mtimeMs;
+    const presetMtime  = fs.statSync(presetPath).mtimeMs;
+    if (overlayMtime > presetMtime) {
+      return { stale: true, reason: 'local-overlay-newer-than-preset' };
+    }
+  }
+
   return { stale: false, reason: 'fresh' };
 }
 
@@ -89,13 +103,86 @@ function resolveBinaryDir({ rootDir, presetName }) {
  * @param {{ presetName: string, generator?: string|null, vsPlatform?: string|null }} args
  * @returns {string[]}
  */
-function buildConfigureArgs({ presetName, generator = null, vsPlatform = null }) {
+function buildConfigureArgs({
+  presetName,
+  generator = null,
+  vsPlatform = null,
+  confSets = null,
+  confUnsets = null,
+}) {
   const args = ['--preset', presetName];
   if (generator)  args.push('-G', generator);
   if (vsPlatform) args.push('-A', vsPlatform);
+
+  // PLAN-CONF.md §7: CLI --conf at build time applies as -D / -U
+  // overrides on top of whatever's baked into the preset. We do NOT
+  // silently regenerate the preset — that's a separate install.
+  // Confined to the cmake.cache namespace; other namespaces have
+  // different sinks (phase 3) and don't apply to `cmake --preset`.
+  if (confSets) {
+    const prefix = 'cmake.cache.';
+    for (const key of Object.keys(confSets).sort()) {
+      if (!key.startsWith(prefix)) continue;
+      const cmakeKey = key.slice(prefix.length);
+      args.push('-D', `${cmakeKey}=${confSets[key]}`);
+    }
+  }
+  if (confUnsets) {
+    const prefix = 'cmake.cache.';
+    for (const key of [...confUnsets].sort()) {
+      if (!key.startsWith(prefix)) continue;
+      args.push('-U', key.slice(prefix.length));
+    }
+  }
+
   return args;
 }
 
+/**
+ * Resolve the list of CMake configs to build (and optionally install).
+ *
+ * Precedence:
+ *   1. `--all-configs` → recipe.configs (falls back to all four canonical
+ *      configs when no recipe declares any).
+ *   2. `--config` → comma-separated list, validated against
+ *      VALID_CMAKE_CONFIGS. Order preserved. Duplicates removed.
+ *   3. default → `['Release']`.
+ *
+ * Configure runs once per `wyvrnpm build` invocation regardless — multi-
+ * config generators (VS, Xcode, Ninja Multi-Config) produce all configs
+ * from one configure step. Single-config generators (plain Ninja, Make)
+ * bake CMAKE_BUILD_TYPE into the cache, so `cmake --build --config X`
+ * effectively ignores X for them; building two configs against a single-
+ * config generator rebuilds the same binary twice. That's wasteful but
+ * correct; fixing it properly requires per-config build dirs, which is
+ * out of scope for this helper.
+ *
+ * @param {{ argv: object, recipeConfigs?: string[] }} args
+ * @returns {string[]}
+ */
+function resolveConfigList({ argv, recipeConfigs = null }) {
+  if (argv.allConfigs) {
+    const fromRecipe = (recipeConfigs ?? []).filter((c) => VALID_CMAKE_CONFIGS.has(c));
+    return fromRecipe.length > 0 ? [...fromRecipe] : [...DEFAULT_RECIPE.configs];
+  }
+
+  const raw  = typeof argv.config === 'string' && argv.config.trim() ? argv.config : 'Release';
+  const list = raw.split(',').map((s) => s.trim()).filter(Boolean);
+
+  const invalid = list.filter((c) => !VALID_CMAKE_CONFIGS.has(c));
+  if (invalid.length > 0) {
+    const valid = [...VALID_CMAKE_CONFIGS].join(' | ');
+    throw new Error(`invalid --config "${invalid.join(', ')}" — expected ${valid}`);
+  }
+
+  const seen = new Set();
+  const deduped = [];
+  for (const c of list) {
+    if (!seen.has(c)) { seen.add(c); deduped.push(c); }
+  }
+  return deduped.length > 0 ? deduped : ['Release'];
+}
+
 /**
  * Args passed to `cmake` for the build step.
  *
@@ -180,13 +267,34 @@ function runCmake(args, env = null) {
  * @param {object} argv
  */
 async function build(argv) {
-  const rootDir      = path.resolve(argv.root);
-  const manifestPath = path.resolve(argv.manifest);
+  // Shared per-invocation state. See src/context.js +
+  // claude/PLAN-COMMAND-CONTEXT.md. Parses --conf up front so a malformed
+  // flag fails here instead of after cmake's already configured.
+  let ctx;
+  try {
+    ctx = buildContext(argv);
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
 
-  const config      = readConfig();
-  const profileName = argv.profile ?? config.defaultProfile ?? 'default';
+  const { rootDir, manifestPath } = ctx;
+  const { name: profileName, profile: activeProfile } = ctx.profiles.host;
   const presetName  = resolvePresetName({ presetOverride: argv.preset, profileName });
-  const buildConfig = argv.config ?? 'Release';
+
+  // Resolve the list of configs up front so a malformed --config fails
+  // before auto-install kicks off. `--all-configs` consults the recipe
+  // (if any); otherwise comma-separated --config, defaulting to Release.
+  let configList;
+  try {
+    const recipe = hasBuildRecipe(ctx.manifest)
+      ? (() => { try { return normalizeRecipe(ctx.manifest.build, null); } catch { return null; } })()
+      : null;
+    configList = resolveConfigList({ argv, recipeConfigs: recipe?.configs ?? null });
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
 
   // ── Stale check / auto-install ────────────────────────────────────────────
   // `--auto-install` gates the "run `wyvrnpm install` first when the
@@ -233,13 +341,12 @@ async function build(argv) {
   let effectiveGenerator = argv.generator ?? null;
   let effectiveProfile   = null;
   try {
-    const { profile: activeProfile } = loadProfile(profileName);
     effectiveProfile = activeProfile;
     // Which generator will the preset actually use? Read it from the
     // project's own recipe if one exists. If not, default to null and let
     // cmake/CMakePresets decide — in which case MSVC env activation is
     // skipped (because VS is usually the default on Windows).
-    const manifest = readManifest(manifestPath);
+    const manifest = ctx.manifest;
     let presetGenerator = null;
     if (hasBuildRecipe(manifest)) {
       try {
@@ -273,43 +380,61 @@ async function build(argv) {
     }
   }
 
+  // CLI --conf → -D / -U passthrough (PLAN-CONF.md §7). The preset's
+  // baked-in cacheVariables (from the last install) already reflect the
+  // recipe + local-overlay layers; CLI conf layers on top for this
+  // invocation only. ctx.cliConf is pre-parsed by buildContext; malformed
+  // values already threw above.
+  const cliConfSets   = ctx.cliConf.sets;
+  const cliConfUnsets = ctx.cliConf.unsets;
+
   const configureArgs = buildConfigureArgs({
     presetName,
     generator:  argv.generator,
     vsPlatform,
+    confSets:   cliConfSets,
+    confUnsets: cliConfUnsets,
   });
   log.info(`cmake ${configureArgs.join(' ')}`);
   await runCmake(configureArgs, cmakeEnv);
 
-  // ── Build ─────────────────────────────────────────────────────────────────
-  const buildArgs = buildBuildArgs({
-    binaryDir,
-    config:   buildConfig,
-    target:   argv.target,
-    verbose:  argv.verbose,
-    passthru: argv['--'] ?? [],
-  });
-  log.info(`cmake ${buildArgs.join(' ')}`);
-  await runCmake(buildArgs, cmakeEnv);
-
-  // ── Install (optional) ────────────────────────────────────────────────────
-  // `--install` runs `cmake --install <binaryDir>` after the build. Prefix
-  // defaults to whatever was baked into the cache at configure time; pass
-  // `--install-prefix` to override without reconfiguring.
-  if (argv.install) {
-    const installArgs = buildInstallArgs({
+  // ── Build (+ optional install) per config ─────────────────────────────────
+  // Configure ran once above. Multi-config generators (VS, Xcode, Ninja
+  // Multi-Config) produce every config from that one configure step; for
+  // single-config generators each iteration simply re-`cmake --build`s the
+  // same baked CMAKE_BUILD_TYPE (harmless duplication). `--install` runs
+  // per config too — the usual reason to want multi-config is so that a
+  // downstream `find_package()` can pick whichever it needs.
+  if (configList.length > 1) {
+    log.info(`Building ${configList.length} configs: ${configList.join(', ')}`);
+  }
+
+  for (const config of configList) {
+    const buildArgs = buildBuildArgs({
       binaryDir,
-      config: buildConfig,
-      prefix: argv.installPrefix,
+      config,
+      target:   argv.target,
+      verbose:  argv.verbose,
+      passthru: argv['--'] ?? [],
     });
-    log.info(`cmake ${installArgs.join(' ')}`);
-    await runCmake(installArgs, cmakeEnv);
+    log.info(`cmake ${buildArgs.join(' ')}`);
+    await runCmake(buildArgs, cmakeEnv);
+
+    if (argv.install) {
+      const installArgs = buildInstallArgs({
+        binaryDir,
+        config,
+        prefix: argv.installPrefix,
+      });
+      log.info(`cmake ${installArgs.join(' ')}`);
+      await runCmake(installArgs, cmakeEnv);
+    }
   }
 
   const suffix = argv.install
     ? ` + installed${argv.installPrefix ? ` to ${argv.installPrefix}` : ''}`
     : '';
-  log.success(`Build complete: ${binaryDir} (${buildConfig})${suffix}`);
+  log.success(`Build complete: ${binaryDir} (${configList.join(', ')})${suffix}`);
 }
 
 module.exports = build;
@@ -320,6 +445,7 @@ module.exports._helpers = {
   isToolchainStale,
   resolvePresetName,
   resolveBinaryDir,
+  resolveConfigList,
   buildConfigureArgs,
   buildBuildArgs,
   buildInstallArgs,

package/src/commands/cache.js

@@ -0,0 +1,189 @@
+'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 };

package/src/commands/configure.js

@@ -27,8 +27,9 @@ function printSection(title, sources) {
 }
 
 function authLabel(src) {
-  if (src.profile) return `[profile: ${src.profile}]`;
-  if (src.token)   return '[token: ***]';
+  if (src.profile)  return `[profile: ${src.profile}]`;
+  if (src.tokenEnv) return `[token-env: ${src.tokenEnv}]`;
+  if (src.token)    return '[token: ***]';
   return '';
 }
 
@@ -38,12 +39,22 @@ function authLabel(src) {
  */
 function addSource(argv) {
   const { kind, name, url, profile, token } = argv;
+  // yargs delivers --token-env as argv['token-env']; accept both shapes
+  // so programmatic callers with camelCase also work.
+  const tokenEnv = argv.tokenEnv ?? argv['token-env'];
+
+  if (token && tokenEnv) {
+    log.error('Pass --token OR --token-env, not both. --token-env is preferred for CI and shared setups (EVALUATION.md S8).');
+    process.exit(1);
+  }
+
   const config = readConfig();
   const key = kind === 'install' ? 'installSources' : 'publishSources';
 
   const entry = { name, url };
-  if (profile) entry.profile = profile;
-  if (token)   entry.token   = token;
+  if (profile)  entry.profile  = profile;
+  if (token)    entry.token    = token;
+  if (tokenEnv) entry.tokenEnv = tokenEnv;
 
   const idx = config[key].findIndex((s) => s.name === name);
   if (idx !== -1) {