wyvrnpm 2.10.2 → 2.12.2

package/src/commands/build.js

@@ -1,452 +1,482 @@
-'use strict';
-
-const fs   = require('fs');
-const path = require('path');
-const { spawn } = require('child_process');
-
-const { normalizeRecipe, hasBuildRecipe, VALID_CMAKE_CONFIGS, DEFAULT_RECIPE } = require('../build/recipe');
-const { loadMsvcEnv }  = require('../build/msvc-env');
-const { archToVsPlatform, isVisualStudioGenerator } = require('../toolchain');
-const { LOCAL_OVERLAY_FILENAME } = require('../conf');
-const { buildContext } = require('../context');
-const install          = require('./install');
-const log              = require('../logger');
-
-// ---------------------------------------------------------------------------
-// Pure helpers (unit-testable — no process spawning, no filesystem writes)
-// ---------------------------------------------------------------------------
-
-/**
- * Decide whether `wyvrn install` must run before build.
- *
- *   - toolchain-missing : wyvrn_toolchain.cmake does not exist → definitely stale.
- *   - lock-newer        : wyvrn.lock was modified after the toolchain was written,
- *                         so the toolchain's package list is out of date.
- *   - fresh             : no action needed.
- *
- * @param {{ rootDir: string, manifestPath: string }} args
- * @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 localOverlayPath = path.join(rootDir, LOCAL_OVERLAY_FILENAME);
-  const presetPath       = path.join(rootDir, 'CMakePresets.json');
-
-  if (!fs.existsSync(toolchainPath)) {
-    return { stale: true, reason: 'toolchain-missing' };
-  }
-  if (!fs.existsSync(lockPath)) {
-    return { stale: false, reason: 'no-lock' };
-  }
-
-  const lockMtime      = fs.statSync(lockPath).mtimeMs;
-  const toolchainMtime = fs.statSync(toolchainPath).mtimeMs;
-  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' };
-}
-
-/**
- * Resolve the configure preset name from CLI override or profile convention.
- *
- * @param {{ presetOverride?: string, profileName: string }} args
- * @returns {string}
- */
-function resolvePresetName({ presetOverride, profileName }) {
-  if (presetOverride) return presetOverride;
-  return `wyvrn-${profileName}`;
-}
-
-/**
- * Compute the build directory for a preset, matching the pattern emitted
- * by [src/toolchain/presets.js](../toolchain/presets.js) — `${sourceDir}/build/<preset>`.
- *
- * @param {{ rootDir: string, presetName: string }} args
- * @returns {string}
- */
-function resolveBinaryDir({ rootDir, presetName }) {
-  return path.join(rootDir, 'build', presetName);
-}
-
-/**
- * Args passed to `cmake` for the configure step.
- *
- * `generator`, when set, appends `-G <name>` after `--preset`. CMake 3.21+
- * lets CLI args override a preset's declared fields, so this swaps the
- * generator at configure time without touching CMakePresets.json. Note:
- * CMake bakes the chosen generator into the cache, so switching generators
- * for an existing build directory requires `--clean` (otherwise CMake
- * errors with "CMAKE_GENERATOR has changed").
- *
- * `vsPlatform`, when set, appends `-A <platform>`. Only meaningful for
- * Visual Studio generators — they default to x64 when unspecified, which
- * silently produces a 64-bit build even for a 32-bit profile. The caller
- * is responsible for deriving this from the profile arch only when the
- * effective generator is VS (see `isVisualStudioGenerator` +
- * `archToVsPlatform`).
- *
- * @param {{ presetName: string, generator?: string|null, vsPlatform?: string|null }} args
- * @returns {string[]}
- */
-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.
- *
- * @param {{
- *   binaryDir: string,
- *   config:    string,
- *   target?:   string,
- *   verbose?:  boolean,
- *   passthru?: string[],
- * }} args
- * @returns {string[]}
- */
-function buildBuildArgs({ binaryDir, config, target, verbose, passthru = [] }) {
-  const args = ['--build', binaryDir, '--config', config];
-  if (verbose) args.push('--verbose');
-  if (target)  args.push('--target', target);
-  if (passthru.length > 0) args.push('--', ...passthru);
-  return args;
-}
-
-/**
- * Args passed to `cmake --install` for the install step.
- *
- * @param {{
- *   binaryDir: string,
- *   config:    string,
- *   prefix?:   string,   // override CMAKE_INSTALL_PREFIX at install time
- * }} args
- * @returns {string[]}
- */
-function buildInstallArgs({ binaryDir, config, prefix }) {
-  const args = ['--install', binaryDir, '--config', config];
-  if (prefix) args.push('--prefix', prefix);
-  return args;
-}
-
-// ---------------------------------------------------------------------------
-// Spawn wrapper
-// ---------------------------------------------------------------------------
-
-/**
- * Run `cmake` with the given args. Inherits stdio for real-time output.
- * Rejects if the process exits non-zero or fails to spawn.
- *
- * When `env` is provided, it replaces the ambient environment (used to
- * activate MSVC via vcvarsall for non-VS generators on Windows).
- *
- * @param {string[]} args
- * @param {NodeJS.ProcessEnv|null} [env]
- * @returns {Promise<void>}
- */
-function runCmake(args, env = null) {
-  return new Promise((resolve, reject) => {
-    const opts = { stdio: 'inherit' };
-    if (env) opts.env = env;
-    const proc = spawn('cmake', args, opts);
-    proc.on('error', (err) => {
-      reject(new Error(
-        `Failed to spawn cmake: ${err.message}\n` +
-        '  Is CMake installed and on PATH?',
-      ));
-    });
-    proc.on('close', (code) => {
-      if (code === 0) resolve();
-      else reject(new Error(`cmake ${args.join(' ')} exited with code ${code}`));
-    });
-  });
-}
-
-// ---------------------------------------------------------------------------
-// Command entry
-// ---------------------------------------------------------------------------
-
-/**
- * `wyvrnpm build` — configure + build via the generated CMake preset.
- *
- * Defaults:
- *   - preset : `wyvrn-<profileName>` (from --profile or config.defaultProfile)
- *   - config : Release
- *   - auto-install when toolchain is missing / older than wyvrn.lock
- *
- * @param {object} argv
- */
-async function build(argv) {
-  // 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 { rootDir, manifestPath } = ctx;
-  const { name: profileName, profile: activeProfile } = ctx.profiles.host;
-  const presetName  = resolvePresetName({ presetOverride: argv.preset, profileName });
-
-  // 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
-  // toolchain is missing or older than wyvrn.lock" behaviour. The separate
-  // `--install` flag below runs `cmake --install` AFTER build; the two are
-  // deliberately distinct concepts.
-  const staleness = isToolchainStale({ rootDir, manifestPath });
-  if (staleness.stale) {
-    if (argv.autoInstall === false) {
-      log.error(
-        `toolchain is stale (${staleness.reason}) and --no-auto-install was passed.\n` +
-        '  Run: wyvrnpm install',
-      );
-      process.exit(1);
-    }
-    log.info(`Toolchain ${staleness.reason} — running install first`);
-    await install({
-      manifest: argv.manifest,
-      root:     argv.root,
-      profile:  argv.profile,
-      source:   argv.source,
-      platform: argv.platform ?? 'win_x64',
-      timeout:  argv.timeout  ?? 300,
-    });
-  }
-
-  const binaryDir = resolveBinaryDir({ rootDir, presetName });
-
-  // ── Clean ─────────────────────────────────────────────────────────────────
-  if (argv.clean && fs.existsSync(binaryDir)) {
-    log.info(`Removing ${binaryDir}`);
-    fs.rmSync(binaryDir, { recursive: true, force: true });
-  }
-
-  // ── MSVC env activation (Windows + non-VS generator) ───────────────────
-  // When the preset's generator is Ninja / Ninja Multi-Config / Make / etc.
-  // and the active profile is MSVC, we need `vcvarsall.bat` to have been
-  // sourced — otherwise cmake's compiler detection fails with "CXX compiler
-  // identification is unknown". VS generators sidestep this because MSBuild
-  // finds MSVC via its own toolset resolution.
-  //
-  // Same mechanism the source-build path already uses (src/build/msvc-env.js).
-  let cmakeEnv = null;
-  let effectiveGenerator = argv.generator ?? null;
-  let effectiveProfile   = null;
-  try {
-    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 = ctx.manifest;
-    let presetGenerator = null;
-    if (hasBuildRecipe(manifest)) {
-      try {
-        const recipe = normalizeRecipe(manifest.build, null);
-        if (recipe.generators.length > 0) [presetGenerator] = recipe.generators;
-      } catch { /* templates need options → skip env activation */ }
-    }
-    // CLI --generator wins — that is the generator CMake will actually use,
-    // so it is the one that determines whether vcvarsall must be activated.
-    if (!effectiveGenerator) effectiveGenerator = presetGenerator;
-    cmakeEnv = await loadMsvcEnv({
-      profile:          activeProfile,
-      skipForGenerator: effectiveGenerator,
-    });
-  } catch (err) {
-    log.warn(`Could not resolve MSVC env activation: ${err.message}`);
-  }
-
-  // ── Configure ─────────────────────────────────────────────────────────────
-  // Auto-emit `-A <platform>` for Visual Studio generators, mapped from the
-  // active profile's arch. VS otherwise defaults to x64 regardless of the
-  // profile, which breaks x86 builds: CMake produces 64-bit artefacts but
-  // find_package() rejects the 32-bit installed dependencies with "version
-  // not compatible" (actually a CMAKE_SIZEOF_VOID_P mismatch, not a
-  // version-number check).
-  let vsPlatform = null;
-  if (isVisualStudioGenerator(effectiveGenerator) && effectiveProfile) {
-    vsPlatform = archToVsPlatform(effectiveProfile.arch);
-    if (vsPlatform) {
-      log.info(`Visual Studio generator + arch=${effectiveProfile.arch} → passing -A ${vsPlatform}`);
-    }
-  }
-
-  // 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 (+ 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,
-      target:   argv.target,
-      verbose:  argv.verbose,
-      passthru: argv['--'] ?? [],
-    });
-    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} (${configList.join(', ')})${suffix}`);
-}
-
-module.exports = build;
-module.exports.default = build;
-
-// Exported for unit tests
-module.exports._helpers = {
-  isToolchainStale,
-  resolvePresetName,
-  resolveBinaryDir,
-  resolveConfigList,
-  buildConfigureArgs,
-  buildBuildArgs,
-  buildInstallArgs,
-};
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { spawn } = require('child_process');
+
+const { normalizeRecipe, hasBuildRecipe, VALID_CMAKE_CONFIGS, DEFAULT_RECIPE } = require('../build/recipe');
+const { loadMsvcEnv }  = require('../build/msvc-env');
+const { archToVsPlatform, isVisualStudioGenerator } = require('../toolchain');
+const { LOCAL_OVERLAY_FILENAME, readLocalOverlay } = require('../conf');
+const { resolveBinaryDirRoot, DEFAULT_BINARY_DIR_ROOT } = require('../binary-dir');
+const { buildContext } = require('../context');
+const install          = require('./install');
+const log              = require('../logger');
+
+// ---------------------------------------------------------------------------
+// Pure helpers (unit-testable — no process spawning, no filesystem writes)
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide whether `wyvrn install` must run before build.
+ *
+ *   - toolchain-missing : wyvrn_toolchain.cmake does not exist → definitely stale.
+ *   - lock-newer        : wyvrn.lock was modified after the toolchain was written,
+ *                         so the toolchain's package list is out of date.
+ *   - fresh             : no action needed.
+ *
+ * @param {{ rootDir: string, manifestPath: string }} args
+ * @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 localOverlayPath = path.join(rootDir, LOCAL_OVERLAY_FILENAME);
+  const presetPath       = path.join(rootDir, 'CMakePresets.json');
+
+  if (!fs.existsSync(toolchainPath)) {
+    return { stale: true, reason: 'toolchain-missing' };
+  }
+  if (!fs.existsSync(lockPath)) {
+    return { stale: false, reason: 'no-lock' };
+  }
+
+  const lockMtime      = fs.statSync(lockPath).mtimeMs;
+  const toolchainMtime = fs.statSync(toolchainPath).mtimeMs;
+  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' };
+}
+
+/**
+ * Resolve the configure preset name from CLI override or profile convention.
+ *
+ * @param {{ presetOverride?: string, profileName: string }} args
+ * @returns {string}
+ */
+function resolvePresetName({ presetOverride, profileName }) {
+  if (presetOverride) return presetOverride;
+  return `wyvrn-${profileName}`;
+}
+
+/**
+ * Compute the build directory for a preset, matching the pattern emitted
+ * by [src/toolchain/presets.js](../toolchain/presets.js) —
+ * `${sourceDir}/<binaryDirRoot>/<preset>`. `binaryDirRoot` defaults to
+ * `"build"`; override via `--build-dir` or
+ * `wyvrn.local.json:binaryDirRoot`.
+ *
+ * @param {{ rootDir: string, presetName: string, binaryDirRoot?: string }} args
+ * @returns {string}
+ */
+function resolveBinaryDir({ rootDir, presetName, binaryDirRoot = DEFAULT_BINARY_DIR_ROOT }) {
+  const root = binaryDirRoot || DEFAULT_BINARY_DIR_ROOT;
+  return path.join(rootDir, root, presetName);
+}
+
+/**
+ * Args passed to `cmake` for the configure step.
+ *
+ * `generator`, when set, appends `-G <name>` after `--preset`. CMake 3.21+
+ * lets CLI args override a preset's declared fields, so this swaps the
+ * generator at configure time without touching CMakePresets.json. Note:
+ * CMake bakes the chosen generator into the cache, so switching generators
+ * for an existing build directory requires `--clean` (otherwise CMake
+ * errors with "CMAKE_GENERATOR has changed").
+ *
+ * `vsPlatform`, when set, appends `-A <platform>`. Only meaningful for
+ * Visual Studio generators — they default to x64 when unspecified, which
+ * silently produces a 64-bit build even for a 32-bit profile. The caller
+ * is responsible for deriving this from the profile arch only when the
+ * effective generator is VS (see `isVisualStudioGenerator` +
+ * `archToVsPlatform`).
+ *
+ * @param {{ presetName: string, generator?: string|null, vsPlatform?: string|null }} args
+ * @returns {string[]}
+ */
+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.
+ *
+ * @param {{
+ *   binaryDir: string,
+ *   config:    string,
+ *   target?:   string,
+ *   verbose?:  boolean,
+ *   passthru?: string[],
+ * }} args
+ * @returns {string[]}
+ */
+function buildBuildArgs({ binaryDir, config, target, verbose, passthru = [] }) {
+  const args = ['--build', binaryDir, '--config', config];
+  if (verbose) args.push('--verbose');
+  if (target)  args.push('--target', target);
+  if (passthru.length > 0) args.push('--', ...passthru);
+  return args;
+}
+
+/**
+ * Args passed to `cmake --install` for the install step.
+ *
+ * @param {{
+ *   binaryDir: string,
+ *   config:    string,
+ *   prefix?:   string,   // override CMAKE_INSTALL_PREFIX at install time
+ * }} args
+ * @returns {string[]}
+ */
+function buildInstallArgs({ binaryDir, config, prefix }) {
+  const args = ['--install', binaryDir, '--config', config];
+  if (prefix) args.push('--prefix', prefix);
+  return args;
+}
+
+// ---------------------------------------------------------------------------
+// Spawn wrapper
+// ---------------------------------------------------------------------------
+
+/**
+ * Run `cmake` with the given args. Inherits stdio for real-time output.
+ * Rejects if the process exits non-zero or fails to spawn.
+ *
+ * When `env` is provided, it replaces the ambient environment (used to
+ * activate MSVC via vcvarsall for non-VS generators on Windows).
+ *
+ * @param {string[]} args
+ * @param {NodeJS.ProcessEnv|null} [env]
+ * @returns {Promise<void>}
+ */
+function runCmake(args, env = null) {
+  return new Promise((resolve, reject) => {
+    const opts = { stdio: 'inherit' };
+    if (env) opts.env = env;
+    const proc = spawn('cmake', args, opts);
+    proc.on('error', (err) => {
+      reject(new Error(
+        `Failed to spawn cmake: ${err.message}\n` +
+        '  Is CMake installed and on PATH?',
+      ));
+    });
+    proc.on('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`cmake ${args.join(' ')} exited with code ${code}`));
+    });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Command entry
+// ---------------------------------------------------------------------------
+
+/**
+ * `wyvrnpm build` — configure + build via the generated CMake preset.
+ *
+ * Defaults:
+ *   - preset : `wyvrn-<profileName>` (from --profile or config.defaultProfile)
+ *   - config : Release
+ *   - auto-install when toolchain is missing / older than wyvrn.lock
+ *
+ * @param {object} argv
+ */
+async function build(argv) {
+  // 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 { rootDir, manifestPath } = ctx;
+  const { name: profileName, profile: activeProfile } = ctx.profiles.host;
+  const presetName  = resolvePresetName({ presetOverride: argv.preset, profileName });
+
+  // Resolve binaryDirRoot the same way install does (CLI > overlay >
+  // default) so `cmake --build <binaryDir>` lands at the same path the
+  // baked preset configured into. A mismatch (e.g. install ran with
+  // --build-dir foo but build did not) surfaces as a "no CMakeCache.txt"
+  // error from cmake — same failure mode as a --generator mismatch
+  // today. Persisting the value via wyvrn.local.json sidesteps the
+  // need to repeat the flag.
+  let binaryDirRoot;
+  try {
+    const overlay = readLocalOverlay(rootDir);
+    binaryDirRoot = resolveBinaryDirRoot({
+      cliBuildDir:               argv.buildDir,
+      localOverlayBinaryDirRoot: overlay.binaryDirRoot,
+    });
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+
+  // 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
+  // toolchain is missing or older than wyvrn.lock" behaviour. The separate
+  // `--install` flag below runs `cmake --install` AFTER build; the two are
+  // deliberately distinct concepts.
+  const staleness = isToolchainStale({ rootDir, manifestPath });
+  if (staleness.stale) {
+    if (argv.autoInstall === false) {
+      log.error(
+        `toolchain is stale (${staleness.reason}) and --no-auto-install was passed.\n` +
+        '  Run: wyvrnpm install',
+      );
+      process.exit(1);
+    }
+    log.info(`Toolchain ${staleness.reason} — running install first`);
+    await install({
+      manifest: argv.manifest,
+      root:     argv.root,
+      profile:  argv.profile,
+      source:   argv.source,
+      platform: argv.platform ?? 'win_x64',
+      timeout:  argv.timeout  ?? 300,
+      // Forward --build-dir so the auto-install bakes the same
+      // binaryDir into the regenerated preset. Without this, `wyvrnpm
+      // build --build-dir foo` would auto-install with the default
+      // "build" root and then promptly fail when this command tries
+      // to read CMakeCache.txt out of `foo/wyvrn-<profile>`.
+      buildDir: argv.buildDir,
+    });
+  }
+
+  const binaryDir = resolveBinaryDir({ rootDir, presetName, binaryDirRoot });
+
+  // ── Clean ─────────────────────────────────────────────────────────────────
+  if (argv.clean && fs.existsSync(binaryDir)) {
+    log.info(`Removing ${binaryDir}`);
+    fs.rmSync(binaryDir, { recursive: true, force: true });
+  }
+
+  // ── MSVC env activation (Windows + non-VS generator) ───────────────────
+  // When the preset's generator is Ninja / Ninja Multi-Config / Make / etc.
+  // and the active profile is MSVC, we need `vcvarsall.bat` to have been
+  // sourced — otherwise cmake's compiler detection fails with "CXX compiler
+  // identification is unknown". VS generators sidestep this because MSBuild
+  // finds MSVC via its own toolset resolution.
+  //
+  // Same mechanism the source-build path already uses (src/build/msvc-env.js).
+  let cmakeEnv = null;
+  let effectiveGenerator = argv.generator ?? null;
+  let effectiveProfile   = null;
+  try {
+    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 = ctx.manifest;
+    let presetGenerator = null;
+    if (hasBuildRecipe(manifest)) {
+      try {
+        const recipe = normalizeRecipe(manifest.build, null);
+        if (recipe.generators.length > 0) [presetGenerator] = recipe.generators;
+      } catch { /* templates need options → skip env activation */ }
+    }
+    // CLI --generator wins — that is the generator CMake will actually use,
+    // so it is the one that determines whether vcvarsall must be activated.
+    if (!effectiveGenerator) effectiveGenerator = presetGenerator;
+    cmakeEnv = await loadMsvcEnv({
+      profile:          activeProfile,
+      skipForGenerator: effectiveGenerator,
+    });
+  } catch (err) {
+    log.warn(`Could not resolve MSVC env activation: ${err.message}`);
+  }
+
+  // ── Configure ─────────────────────────────────────────────────────────────
+  // Auto-emit `-A <platform>` for Visual Studio generators, mapped from the
+  // active profile's arch. VS otherwise defaults to x64 regardless of the
+  // profile, which breaks x86 builds: CMake produces 64-bit artefacts but
+  // find_package() rejects the 32-bit installed dependencies with "version
+  // not compatible" (actually a CMAKE_SIZEOF_VOID_P mismatch, not a
+  // version-number check).
+  let vsPlatform = null;
+  if (isVisualStudioGenerator(effectiveGenerator) && effectiveProfile) {
+    vsPlatform = archToVsPlatform(effectiveProfile.arch);
+    if (vsPlatform) {
+      log.info(`Visual Studio generator + arch=${effectiveProfile.arch} → passing -A ${vsPlatform}`);
+    }
+  }
+
+  // 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 (+ 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,
+      target:   argv.target,
+      verbose:  argv.verbose,
+      passthru: argv['--'] ?? [],
+    });
+    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} (${configList.join(', ')})${suffix}`);
+}
+
+module.exports = build;
+module.exports.default = build;
+
+// Exported for unit tests
+module.exports._helpers = {
+  isToolchainStale,
+  resolvePresetName,
+  resolveBinaryDir,
+  resolveConfigList,
+  buildConfigureArgs,
+  buildBuildArgs,
+  buildInstallArgs,
+};