wyvrnpm 2.4.1 → 2.8.1

package/bin/wyvrn.js

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

package/cmake/variables.cmake

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

package/package.json

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

package/src/auth.js

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

package/src/build/cache.js

@@ -136,6 +136,196 @@ function clearUploadSidecars() {
   return removed;
 }
 
+// ---------------------------------------------------------------------------
+// Cache inspection (F12)
+// ---------------------------------------------------------------------------
+
+/**
+ * Dotted-version + 16+ hex-hash suffix. The hash tail is unambiguous
+ * (always hex, always 16 chars per src/profile.js) so parsing from the
+ * end avoids ambiguity when package names contain dashes
+ * (`boost-filesystem-1.80.0.0-abc1234567890def`).
+ */
+const CACHE_DIR_RE = /^(.+)-(\d+(?:\.\d+)+)-([a-f0-9]{16,})$/;
+
+/**
+ * Recursively compute total size of a directory in bytes. Skips symlinks
+ * to avoid accidental cycles through user-linked packages.
+ *
+ * @param {string} dir
+ * @returns {number}
+ */
+function dirSizeBytes(dir) {
+  let total = 0;
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+  catch { return 0; }
+  for (const e of entries) {
+    if (e.isSymbolicLink()) continue;
+    const p = path.join(dir, e.name);
+    try {
+      if (e.isDirectory()) {
+        total += dirSizeBytes(p);
+      } else if (e.isFile()) {
+        total += fs.statSync(p).size;
+      }
+    } catch { /* concurrent deletion — ignore */ }
+  }
+  return total;
+}
+
+/**
+ * List every entry in the source-build cache, enriched with metadata.
+ * Unparseable directory names are skipped (corrupt / manual cruft).
+ *
+ * @returns {Array<{
+ *   name:        string,
+ *   version:     string,
+ *   profileHash: string,
+ *   cacheDir:    string,
+ *   sizeBytes:   number,
+ *   mtimeMs:     number,
+ *   hasArtefact: boolean,
+ *   uploads:     Array<object>,
+ * }>}
+ */
+function listCacheEntries() {
+  const root = getBuildCacheRoot();
+  if (!fs.existsSync(root)) return [];
+
+  const out = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+
+    const m = entry.name.match(CACHE_DIR_RE);
+    if (!m) continue;   // corrupt / unknown — skip silently
+    const [, name, version, profileHash] = m;
+
+    const cacheDir    = path.join(root, entry.name);
+    const artefact    = path.join(cacheDir, LAYOUT.artefactZip);
+    const sidecarPath = path.join(cacheDir, LAYOUT.uploadSidecar);
+
+    let mtimeMs = 0;
+    try { mtimeMs = fs.statSync(cacheDir).mtimeMs; } catch { /* skip */ }
+
+    let uploads = [];
+    if (fs.existsSync(sidecarPath)) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
+        if (Array.isArray(raw?.uploads)) uploads = raw.uploads;
+      } catch { /* corrupt sidecar — surface empty */ }
+    }
+
+    out.push({
+      name, version, profileHash, cacheDir,
+      sizeBytes:   dirSizeBytes(cacheDir),
+      mtimeMs,
+      hasArtefact: fs.existsSync(artefact),
+      uploads,
+    });
+  }
+  return out;
+}
+
+/**
+ * Parse `--older-than` duration strings (`7d`, `24h`, `30m`, `3600s`).
+ * Returns the cutoff timestamp in ms-since-epoch: entries with
+ * `mtimeMs < cutoff` are older than the threshold.
+ *
+ * @param {string} spec
+ * @param {number} [now=Date.now()]
+ * @returns {number}
+ */
+function parseDurationToCutoff(spec, now = Date.now()) {
+  if (typeof spec !== 'string') {
+    throw new Error(`--older-than expects a string like "30d", got ${JSON.stringify(spec)}`);
+  }
+  const m = spec.trim().match(/^(\d+)\s*([smhd])$/i);
+  if (!m) {
+    throw new Error(
+      `--older-than ${JSON.stringify(spec)} must be <number><unit> where unit is s/m/h/d`,
+    );
+  }
+  const n = parseInt(m[1], 10);
+  const unit = m[2].toLowerCase();
+  const ms = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[unit];
+  return now - n * ms;
+}
+
+/**
+ * Compute which cache entries would be pruned under the given policy.
+ * Pure — does no I/O of its own. Caller passes in `entries` (from
+ * `listCacheEntries()`) so tests can synthesise them.
+ *
+ * Policy semantics:
+ *  - `keepLast` is **per (name, version) group** — preserves the N most
+ *    recent profileHash variants for each version so multi-profile
+ *    dev rigs don't lose every profile on a single prune.
+ *  - `olderThanMs` applies after `keepLast`; it only widens the set
+ *    of eligible-for-pruning entries; never adds entries back.
+ *  - `patternRegex` filters entries by name at the very start.
+ *
+ * Returns the prune set in descending mtime order (newest-of-the-
+ * doomed first) — handy for human-friendly "about to remove" output.
+ *
+ * @param {ReturnType<typeof listCacheEntries>} entries
+ * @param {{ keepLast?: number, olderThanMs?: number, patternRegex?: RegExp }} policy
+ * @returns {ReturnType<typeof listCacheEntries>}
+ */
+function computePruneSet(entries, { keepLast, olderThanMs, patternRegex } = {}) {
+  let candidates = entries;
+  if (patternRegex) candidates = candidates.filter((e) => patternRegex.test(e.name));
+
+  // Group by (name, version); within each group, sort by mtime desc,
+  // mark the top N as keepers when keepLast is set.
+  const keep = new Set();
+  if (typeof keepLast === 'number' && keepLast >= 0) {
+    const groups = new Map();
+    for (const e of candidates) {
+      const k = `${e.name}\x1f${e.version}`;
+      if (!groups.has(k)) groups.set(k, []);
+      groups.get(k).push(e);
+    }
+    for (const group of groups.values()) {
+      group.sort((a, b) => b.mtimeMs - a.mtimeMs);
+      for (let i = 0; i < Math.min(keepLast, group.length); i++) {
+        keep.add(group[i].cacheDir);
+      }
+    }
+  } else {
+    // No keepLast → every candidate is eligible for pruning subject to
+    // the other filters.
+  }
+
+  const toPrune = candidates.filter((e) => !keep.has(e.cacheDir));
+
+  const filtered = typeof olderThanMs === 'number'
+    ? toPrune.filter((e) => e.mtimeMs < olderThanMs)
+    : toPrune;
+
+  filtered.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return filtered;
+}
+
+/**
+ * Delete a list of cache entries. Returns the subset that was actually
+ * removed (permissions failures surface as misses). Caller should have
+ * already computed the set via `computePruneSet`.
+ *
+ * @param {ReturnType<typeof listCacheEntries>} entries
+ * @returns {ReturnType<typeof listCacheEntries>}
+ */
+function removeCacheEntries(entries) {
+  const removed = [];
+  for (const e of entries) {
+    try {
+      fs.rmSync(e.cacheDir, { recursive: true, force: true });
+      removed.push(e);
+    } catch { /* skip failures — caller reports the delta */ }
+  }
+  return removed;
+}
+
 module.exports = {
   getBuildCacheRoot,
   getPackageBuildDir,
@@ -145,4 +335,10 @@ module.exports = {
   listUploadSidecars,
   clearUploadSidecars,
   LAYOUT,
+  // Cache inspection (F12)
+  listCacheEntries,
+  computePruneSet,
+  removeCacheEntries,
+  parseDurationToCutoff,
+  CACHE_DIR_RE,
 };

package/src/build/index.js

@@ -14,6 +14,7 @@ const { resolveDependencies }   = require('../resolve');
 const { hashProfile, mergeProfile, sha256Of } = require('../profile');
 const { generateToolchain }     = require('../toolchain');
 const { normalizeOptionsDeclaration, resolveEffectiveOptions } = require('../options');
+const { readRecipeConf, cmakeCacheVariables } = require('../conf');
 const log                       = require('../logger');
 
 /**
@@ -155,8 +156,28 @@ async function buildFromSource(args) {
   }
   // Pass effective options into the recipe so `${options.<name>}` tokens in
   // `build.configure` / `build.buildArgs` expand to the concrete values that
-  // produced this build's profileHash.
-  const recipe = normalizeRecipe(clonedManifest.build, options);
+  // produced this build's profileHash. Pass the cloned manifest so PLAN-CONF.md
+  // §4.7 collision detection catches a publisher who declared the same KEY in
+  // both build.configure and conf.cmake.cache.
+  const recipe = normalizeRecipe(clonedManifest.build, options, clonedManifest);
+
+  // PLAN-CONF.md §4.8.2: source-build of a dep consumes ONLY the dep's own
+  // recipe conf — never the root project's merged conf. Translating the
+  // dep's cmake.cache namespace into -D args here keeps the dep's source-
+  // build CMake invocation aligned with its author's declared defaults
+  // while preserving cross-consumer reproducibility. The root's CLI
+  // --conf / wyvrn.local.json overlay is invisible at this seam.
+  const clonedConfFlat    = readRecipeConf(clonedManifest);
+  const clonedCacheVars   = cmakeCacheVariables(clonedConfFlat);
+  if (Object.keys(clonedCacheVars).length > 0) {
+    const confDerivedArgs = Object.entries(clonedCacheVars)
+      .map(([k, v]) => `-D${k}=${v}`);
+    recipe.configure = [...recipe.configure, ...confDerivedArgs];
+    log.info(
+      `  conf.cmake.cache → ${confDerivedArgs.length} source-build ` +
+      `configure arg(s) from the dep's own recipe`,
+    );
+  }
 
   // ── 4. Recursively resolve + download this package's OWN deps ──────────
   // Lazy-require: downloadDependencies is where we were called from, so

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