wyvrnpm 2.3.2 → 2.8.1

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) {

package/src/commands/init.js

@@ -3,8 +3,35 @@
 const fs = require('fs');
 const path = require('path');
 const { defaultManifest, writeManifest } = require('../manifest');
+const { LOCAL_OVERLAY_FILENAME } = require('../conf');
 const log = require('../logger');
 
+// The wyvrn.local.json overlay must never be committed — it is by design
+// per-developer state. init writes a gitignore entry; existing projects
+// get a one-line nudge from install (see install.js) when the file is
+// present but not ignored.
+const GITIGNORE_MARKER_LINE = '# wyvrnpm — per-developer conf overlay (never commit)';
+
+function ensureGitignoreEntry(rootDir) {
+  const gitignorePath = path.join(rootDir, '.gitignore');
+  const desiredLines  = [GITIGNORE_MARKER_LINE, LOCAL_OVERLAY_FILENAME];
+
+  let existing = '';
+  if (fs.existsSync(gitignorePath)) {
+    existing = fs.readFileSync(gitignorePath, 'utf8');
+    const hasEntry = existing.split(/\r?\n/).some((l) => l.trim() === LOCAL_OVERLAY_FILENAME);
+    if (hasEntry) return { action: 'already-present', path: gitignorePath };
+  }
+
+  const needsLeadingNewline = existing.length > 0 && !existing.endsWith('\n');
+  const block = (needsLeadingNewline ? '\n' : '') + desiredLines.join('\n') + '\n';
+  fs.writeFileSync(gitignorePath, existing + block, 'utf8');
+  return {
+    action: existing.length > 0 ? 'appended' : 'created',
+    path:   gitignorePath,
+  };
+}
+
 /**
  * Initialises a new wyvrn.json manifest in the project root.
  * If a manifest already exists the command exits early without overwriting it.
@@ -28,7 +55,16 @@ async function init(argv) {
 
   writeManifest(manifestPath, manifest);
 
+  const gitignore = ensureGitignoreEntry(rootDir);
+  if (gitignore.action === 'created') {
+    log.info(`Created .gitignore at ${gitignore.path} with ${LOCAL_OVERLAY_FILENAME} exclusion`);
+  } else if (gitignore.action === 'appended') {
+    log.info(`Added ${LOCAL_OVERLAY_FILENAME} to ${gitignore.path}`);
+  }
+
   log.success(`Created manifest at ${manifestPath}`);
 }
 
 module.exports = init;
+module.exports.ensureGitignoreEntry  = ensureGitignoreEntry;
+module.exports.GITIGNORE_MARKER_LINE = GITIGNORE_MARKER_LINE;

package/src/commands/install-skill.js

@@ -5,6 +5,7 @@ const os   = require('os');
 const path = require('path');
 const AdmZip = require('adm-zip');
 
+const { assertAllSafeZipEntryNames } = require('../zip-safe');
 const log = require('../logger');
 
 // ---------------------------------------------------------------------------
@@ -72,6 +73,13 @@ function installForClaude({ force, dryRun }) {
   rmrf(destZip);
 
   const zip = new AdmZip(zipPath);
+  // Zip Slip defense-in-depth (EVALUATION.md S2). The shipped .skill zip
+  // is trusted-by-provenance, but validating consistently keeps the
+  // attack surface flat across all extraction call sites.
+  assertAllSafeZipEntryNames(
+    zip.getEntries().map((e) => e.entryName),
+    `${SKILL_NAME}.skill`,
+  );
   zip.extractAllTo(skillsDir, /* overwrite */ true);
   fs.copyFileSync(zipPath, destZip);
 

package/src/commands/install.js

@@ -7,6 +7,8 @@ const { readManifest, normalizeDependencies }               = require('../manife
 const { resolveDependencies }                               = require('../resolve');
 const { downloadDependencies }                              = require('../download');
 const { readConfig }                                        = require('../config');
+const { resolveSourceAuth }                                 = require('../auth');
+const { resolveEffectiveConf, cmakeCacheVariables, unflattenConf } = require('../conf');
 const { loadProfile, hashProfile, formatProfile, mergeProfile } = require('../profile');
 const { generateToolchain, generateCMakePresets }           = require('../toolchain');
 const { normalizeRecipe, hasBuildRecipe }                   = require('../build/recipe');
@@ -15,6 +17,10 @@ const {
   resolveEffectiveOptions,
   parseCliOptions,
 }                                                            = require('../options');
+const {
+  normalizeSettingsOverrides,
+  resolveOverrideSettings,
+}                                                            = require('../settings-overrides');
 const {
   resolveUploadDestination,
   createUploadStats,
@@ -119,6 +125,45 @@ async function install(argv) {
     Object.entries(normalizedDeps).map(([name, d]) => [name, d.version]),
   );
 
+  // Per-package source pinning (EVALUATION.md S4). Deps declaring
+  // `"source": "primary-s3"` restrict to that named source's URL from
+  // config — typosquat / mirror-shadow defense. Unknown name → fail
+  // fast (silent fallback to fan-out would defeat the point).
+  //
+  // `argv.source` overrides config entirely; if the user passes
+  // `--source <url>` but a dep pins a name, we can't resolve the name
+  // → warn and fall back to fan-out across the CLI-supplied URLs.
+  //
+  // Transitive deps continue to fan out — a pinned top-level dep's
+  // recipe can reference whatever it wants.
+  const sourcesByName = new Map();
+  if (!argv.source || argv.source.length === 0) {
+    for (const s of config.installSources ?? []) {
+      if (s.name && s.url) sourcesByName.set(s.name, s.url);
+    }
+  }
+  const pinnedSources = new Map();
+  for (const [name, d] of Object.entries(normalizedDeps)) {
+    if (!d.source) continue;
+    if (argv.source && argv.source.length > 0) {
+      log.warn(
+        `"${name}" pins source "${d.source}" but --source was passed on CLI — ` +
+        `pin ignored for this run`,
+      );
+      continue;
+    }
+    const url = sourcesByName.get(d.source);
+    if (!url) {
+      log.error(
+        `"${name}" pins source "${d.source}" but no install source by that name is configured. ` +
+        `Run "wyvrnpm configure list" to see configured sources.`,
+      );
+      process.exit(1);
+    }
+    pinnedSources.set(name, url);
+    log.info(`${name}: pinned to source "${d.source}"`);
+  }
+
   log.info(
     `Installing dependencies for "${manifest.name}" (platform: ${argv.platform})`,
   );
@@ -134,11 +179,31 @@ async function install(argv) {
     fetch,
     lockedVersions,
     depManifests,
+    // F13: prefer the consumer's own profileHash when picking which build
+    // entry to read wyvrn.json from. Today every published build for a
+    // given (name, version) ships the same manifest, so this is harmless;
+    // it future-proofs against per-profile manifest variance.
+    hashProfile(baseProfile),
+    pinnedSources,
   );
 
   // CLI `-o <pkg>:<name>=<value>` overrides, parsed into { pkg → {name: value} }.
   const cliOptionsByPkg = parseCliOptions(argv.option);
 
+  // F11: pattern-based settings overrides. `manifest.settingsOverrides`
+  // is { "<glob>": { <setting>: <value> }, ... }. Validated + sorted by
+  // specificity once here; `resolveOverrideSettings(depName, ...)` then
+  // returns the merged-from-patterns settings for each dep. Literal
+  // per-dep `settings` still override these (authors pinning a specific
+  // dep win over a team-wide pattern).
+  let settingsOverrides;
+  try {
+    settingsOverrides = normalizeSettingsOverrides(manifest.settingsOverrides);
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+
   // ── Build per-dependency enriched map ─────────────────────────────────────
   // Each dep gets:
   //   - an effective profile (base + per-dep settings overrides)
@@ -146,7 +211,12 @@ async function install(argv) {
   //   - profileHash computed from both (options only hashed in when declared)
   const enrichedDeps = new Map();
   for (const [name, version] of resolvedDeps) {
-    const depOverrides     = normalizedDeps[name]?.settings ?? {};
+    // F11: layer pattern overrides first (less-specific applied first
+    // inside resolveOverrideSettings), then the literal per-dep
+    // settings on top. Literal wins over any pattern.
+    const patternOverrides = resolveOverrideSettings(name, settingsOverrides);
+    const literalOverrides = normalizedDeps[name]?.settings ?? {};
+    const depOverrides     = { ...patternOverrides, ...literalOverrides };
     const effectiveProfile = mergeProfile(baseProfile, depOverrides);
 
     const depManifest    = depManifests.get(name);
@@ -177,16 +247,85 @@ async function install(argv) {
       profileHash,
       profile: effectiveProfile,
       options: effectiveOptions,
+      // S4: pinned install source (name + URL). Only set for direct
+      // deps that declared `"source": "..."`; transitive deps stay
+      // undefined so they fan out across configured sources.
+      pinnedSource: pinnedSources.has(name)
+        ? { name: normalizedDeps[name].source, url: pinnedSources.get(name) }
+        : undefined,
     });
   }
 
+  // ── Resolve effective conf (PLAN-CONF.md §4) ──────────────────────────────
+  // Four layers (phase 2): CLI > wyvrn.local.json > profile > recipe.
+  // Non-ABI; does not fold into profileHash. Feeds into CMakePresets.json
+  // cacheVariables below. `baseProfile` may carry its own `conf` block —
+  // an auto-detected profile (no on-disk file) does not.
+  let effectiveConfResult;
+  try {
+    effectiveConfResult = resolveEffectiveConf({
+      manifest,
+      rootDir,
+      cliConf: argv.conf,             // yargs array: string[]
+      profile: baseProfile,           // named profile may carry a `conf` block (phase 2)
+    });
+  } catch (err) {
+    log.error(`conf resolution failed: ${err.message}`);
+    process.exit(1);
+  }
+  const effectiveConf = effectiveConfResult.flat;
+  if (effectiveConfResult.localOverlayPath) {
+    log.info(`Local overlay: ${effectiveConfResult.localOverlayPath}`);
+    // One-line nudge when wyvrn.local.json exists but isn't gitignored —
+    // catching the existing-project case init.js's scaffold can't cover.
+    // Non-fatal; we never rewrite the user's .gitignore at install time.
+    const gitignorePath = path.join(rootDir, '.gitignore');
+    if (fs.existsSync(gitignorePath)) {
+      const gi = fs.readFileSync(gitignorePath, 'utf8');
+      const ignored = gi.split(/\r?\n/).some((l) => l.trim() === 'wyvrn.local.json');
+      if (!ignored) {
+        log.warn(
+          `wyvrn.local.json is present but not in ${gitignorePath} — ` +
+          `add a line "wyvrn.local.json" to keep dev-local overrides out of version control.`,
+        );
+      }
+    }
+  }
+  if (Object.keys(effectiveConf).length > 0) {
+    log.info(`Effective conf: ${JSON.stringify(effectiveConf)}`);
+  }
+
+  // ── --dry-run: print the resolved plan and exit (EVALUATION.md F6) ────────
+  // Runs the resolver + profile/options math end-to-end, then reports what
+  // WOULD be installed — no download, no wyvrn.lock, no wyvrn_internal/, no
+  // toolchain. Preserves --format=json for CI ingestion.
+  if (argv.dryRun) {
+    emitDryRunPlan({
+      enrichedDeps,
+      resolvedDeps,
+      baseProfile,
+      profileName,
+      buildMode,
+      packageSources,
+      effectiveConf,
+      jsonOut,
+    });
+    return;
+  }
+
   const razerDir = path.join(rootDir, 'wyvrn_internal');
 
-  // Extract auth from the first install source (if any)
+  // Extract auth from the first install source (if any). Prefer
+  // `tokenEnv` over a literal `token` stored in config — closes
+  // EVALUATION.md S8 (no plaintext secret persisted, value is looked up
+  // fresh each run).
   const firstInstallSrc = config.installSources?.[0];
   const downloadOptions = {
     awsProfile: firstInstallSrc?.profile ?? undefined,
-    token:      firstInstallSrc?.token   ?? undefined,
+    token:      resolveSourceAuth(
+      { token: argv.token, tokenEnv: argv.tokenEnv },
+      firstInstallSrc,
+    ).token,
     buildMode,
     profileName,
   };
@@ -199,7 +338,10 @@ async function install(argv) {
       {
         uploadSource: argv.uploadSource,
         awsProfile:   argv.awsProfile ?? firstInstallSrc?.profile,
-        token:        argv.token      ?? firstInstallSrc?.token,
+        token:        resolveSourceAuth(
+          { token: argv.token, tokenEnv: argv.tokenEnv },
+          firstInstallSrc,
+        ).token,
       },
       config,
     );
@@ -249,6 +391,12 @@ async function install(argv) {
     profile:      baseProfile,
     profileHash:  hashProfile(baseProfile),
     packages:     sortedPackages,
+    // PLAN-CONF.md §4.8.1: informational only, not consulted during
+    // resolution. Omitted entirely when empty so pre-conf locks
+    // remain byte-identical to today's output.
+    ...(Object.keys(effectiveConf).length > 0
+      ? { effectiveConf: unflattenConf(effectiveConf) }
+      : {}),
   };
 
   fs.writeFileSync(lockPath, JSON.stringify(lockData, null, 2) + '\n', 'utf8');
@@ -278,6 +426,7 @@ async function install(argv) {
   let presetGenerator = null;
   let presetCacheVariables = null;
   let presetInstallDir = null;
+  let presetConfigs = null;
   if (hasBuildRecipe(manifest)) {
     try {
       // Resolve the project's own options to expand ${options.*} in its
@@ -291,7 +440,7 @@ async function install(argv) {
       const projectEffectiveOptions = resolveEffectiveOptions(
         projectDeclaration, {}, projectCliOverrides, manifest.name,
       );
-      const recipe = normalizeRecipe(manifest.build, projectEffectiveOptions);
+      const recipe = normalizeRecipe(manifest.build, projectEffectiveOptions, manifest);
 
       if (recipe.generators.length > 0) {
         // First entry in the generator fallback chain. Users whose system
@@ -316,6 +465,14 @@ async function install(argv) {
       // (C:/Program Files on Windows, /usr/local on Unix). Same semantics as
       // the source-build path which passes -DCMAKE_INSTALL_PREFIX explicitly.
       presetInstallDir = recipe.installDir;
+
+      // Propagate `build.configs` so multi-config generators (Ninja
+      // Multi-Config, Visual Studio) generate build files for every
+      // config the recipe declares. Pre-2.8.1 the preset only carried
+      // Debug/Release, so a recipe listing MinSizeRel would fail with
+      // `ninja: error: loading 'build-MinSizeRel.ninja'`. CLAUDE.md §8
+      // documented that sharp edge; this closes it.
+      presetConfigs = recipe.configs;
     } catch (err) {
       log.warn(
         `could not derive CMake preset config from the project's build recipe: ${err.message}\n` +
@@ -325,6 +482,31 @@ async function install(argv) {
     }
   }
 
+  // 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 —
+  // a consumer with no recipe but a wyvrn.local.json conf still gets
+  // their overrides into the generated preset.
+  //
+  // Conf wins on collisions with build.configure-derived vars. The
+  // recipe-normaliser blocks author-side collisions (§4.7); a
+  // collision here can only come from a consumer's CLI --conf or
+  // wyvrn.local.json overriding a value the author also sets via
+  // build.configure. Warn so the override is visible.
+  const confCacheVars = cmakeCacheVariables(effectiveConf);
+  if (Object.keys(confCacheVars).length > 0) {
+    presetCacheVariables = presetCacheVariables ?? {};
+    for (const [k, v] of Object.entries(confCacheVars)) {
+      if (k in presetCacheVariables && presetCacheVariables[k] !== v) {
+        log.warn(
+          `conf override: cmake.cache.${k} = ${JSON.stringify(v)} ` +
+          `supersedes build.configure's ${JSON.stringify(presetCacheVariables[k])}`,
+        );
+      }
+      presetCacheVariables[k] = v;
+    }
+  }
+
   const presetResult = generateCMakePresets({
     projectRoot:  rootDir,
     profileName,
@@ -333,6 +515,8 @@ async function install(argv) {
     generator:           presetGenerator,
     extraCacheVariables: presetCacheVariables,
     installDir:          presetInstallDir,
+    profileArch:         baseProfile.arch ?? null,
+    configs:             presetConfigs,
   });
   if (presetResult.action === 'skipped') {
     log.warn(
@@ -396,4 +580,86 @@ async function install(argv) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// --dry-run plan emitter (EVALUATION.md F6)
+// ---------------------------------------------------------------------------
+
+/**
+ * Render the resolved install plan WITHOUT touching disk. Called from
+ * `install()` when `--dry-run` is passed; exits the install flow before
+ * download, lockfile write, or toolchain generation.
+ *
+ * Text mode: human-readable per-dep summary.
+ * JSON mode (`--format=json`): structured payload on stdout with
+ * `command: "install-dry-run"` so log consumers can disambiguate it
+ * from a real install.
+ */
+function emitDryRunPlan({
+  enrichedDeps, resolvedDeps, baseProfile, profileName, buildMode,
+  packageSources, effectiveConf = {}, jsonOut,
+}) {
+  const baseHash = hashProfile(baseProfile);
+  const packages = [...resolvedDeps.keys()].sort().map((name) => {
+    const entry = enrichedDeps.get(name) ?? {};
+    return {
+      name,
+      version:     resolvedDeps.get(name),
+      profileHash: entry.profileHash ?? null,
+      options:     entry.options ?? null,
+      // Whether the dep's effective profile differs from the consumer's
+      // base (i.e. per-dep settings override produced a distinct hash).
+      overridesBaseProfile: entry.profileHash && entry.profileHash !== baseHash,
+    };
+  });
+
+  if (jsonOut) {
+    const payload = {
+      command:        'install-dry-run',
+      wyvrnpmVersion: require('../../package.json').version,
+      profile:        baseProfile,
+      profileName,
+      profileHash:    baseHash,
+      buildMode,
+      sources:        packageSources,
+      effectiveConf:  Object.keys(effectiveConf).length > 0
+                        ? unflattenConf(effectiveConf)
+                        : {},
+      packages,
+    };
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+    return;
+  }
+
+  log.info('── install plan (--dry-run) ─────────────────────────────────────');
+  log.info(`Profile : "${profileName}" [${baseHash}]`);
+  log.info(`Build   : ${buildMode}`);
+  log.info(`Sources : ${packageSources.length > 0 ? packageSources.join(', ') : '(none)'}`);
+  const confKeys = Object.keys(effectiveConf).sort();
+  if (confKeys.length > 0) {
+    log.info(`Conf    : ${confKeys.map((k) => `${k}=${effectiveConf[k]}`).join(', ')}`);
+  }
+  if (packages.length === 0) {
+    log.info('(no dependencies)');
+    return;
+  }
+
+  const nameW    = Math.max(4, ...packages.map((p) => p.name.length));
+  const versionW = Math.max(7, ...packages.map((p) => p.version.length));
+  const header = `  ${'name'.padEnd(nameW)}  ${'version'.padEnd(versionW)}  profileHash       options`;
+  log.info(header);
+  log.info(`  ${'-'.repeat(nameW)}  ${'-'.repeat(versionW)}  ----------------  --------------------`);
+  for (const p of packages) {
+    const override = p.overridesBaseProfile ? ' *' : '  ';
+    const optStr   = p.options ? JSON.stringify(p.options) : '-';
+    log.info(
+      `  ${p.name.padEnd(nameW)}  ${p.version.padEnd(versionW)}  ${p.profileHash ?? '(none)         '}${override} ${optStr}`,
+    );
+  }
+  log.info('');
+  log.info('(nothing was downloaded; wyvrn.lock / wyvrn_internal / toolchain untouched)');
+  if (packages.some((p) => p.overridesBaseProfile)) {
+    log.info('  * = per-dep settings override produces a profileHash distinct from the base.');
+  }
+}
+
 module.exports = install;