wyvrnpm 2.8.1 → 2.10.0

package/src/bootstrap/index.js

@@ -0,0 +1,220 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const { tagToVersion, nameFromUrl } = require('./version');
+const { detectFromRepo }            = require('./detect');
+const { lookupCookbook }            = require('./cookbook');
+const log                           = require('../logger');
+
+/**
+ * Clone `gitUrl` into `destDir` so bootstrap can read the tree.
+ * Defaults to a full clone — bootstrap's target audience is "I forked
+ * these repos to maintain them", so they want the history. `--shallow`
+ * opts into `--depth 1` (faster, but `git describe --tags` will miss
+ * tags that aren't reachable from the single fetched commit, so the
+ * version detection degrades to HEAD SHA placeholder + TODO).
+ *
+ * Uses the user's ambient git auth (SSH keys, credential helper). We do
+ * NOT manage credentials here.
+ *
+ * @param {{ gitUrl: string, destDir: string, ref?: string | null, shallow?: boolean }} opts
+ */
+function cloneRepo({ gitUrl, destDir, ref = null, shallow = false }) {
+  const args = ['clone'];
+  if (shallow) args.push('--depth', '1');
+  if (ref)     args.push('--branch', ref);
+  args.push('--', gitUrl, destDir);
+  log.info(`  git ${args.join(' ')}`);
+  execFileSync('git', args, { stdio: 'inherit' });
+}
+
+/**
+ * Read HEAD SHA + nearest tag out of an existing clone. Pure
+ * read-side — never writes. Returns nulls on failure so the caller
+ * can surface a TODO rather than abort.
+ *
+ * @param {string} repoDir
+ * @returns {{ sha: string | null, tag: string | null }}
+ */
+function readGitState(repoDir) {
+  const safe = (args) => {
+    try {
+      return execFileSync('git', args, { cwd: repoDir, stdio: ['ignore', 'pipe', 'ignore'] })
+        .toString('utf8').trim() || null;
+    } catch { return null; }
+  };
+  return {
+    sha: safe(['rev-parse', 'HEAD']),
+    // `--abbrev=0` gives the nearest tag without the "-<N>-g<sha>" suffix.
+    tag: safe(['describe', '--tags', '--abbrev=0']),
+  };
+}
+
+/**
+ * Compose a first-draft `wyvrn.json` from detection + cookbook data.
+ * Pure: no filesystem writes, no network. `compose` is the unit-testable
+ * seam between orchestration (`bootstrap`) and persistence.
+ *
+ * Precedence for each field (highest wins):
+ *   CLI override → cookbook hint → filesystem detection → safe default.
+ *
+ * @param {{
+ *   url:        string,
+ *   repoDir:    string,
+ *   overrides?: { name?: string, version?: string, kind?: string, description?: string },
+ *   detect?:    ReturnType<typeof detectFromRepo>,
+ *   gitState?:  { sha: string | null, tag: string | null },
+ * }} args
+ * @returns {{ manifest: object, todos: string[] }}
+ */
+function compose({ url, repoDir, overrides = {}, detect = null, gitState = null }) {
+  const todos = [];
+  const detection = detect ?? detectFromRepo(repoDir);
+  const { sha, tag } = gitState ?? { sha: null, tag: null };
+
+  const repoTail = nameFromUrl(url);
+  const cookbook = lookupCookbook(repoTail) ?? {};
+
+  const name = overrides.name || repoTail;
+  if (!name) todos.push('name could not be derived from the URL — set "name" manually.');
+
+  let version = overrides.version || null;
+  if (!version && tag) {
+    version = tagToVersion(tag);
+    if (!version) {
+      todos.push(`nearest tag "${tag}" doesn't match a clean numeric version — set "version" manually (used HEAD SHA as a placeholder).`);
+    }
+  }
+  if (!version) {
+    version = '0.0.0.0';
+    todos.push('no usable git tag found — "version" defaulted to 0.0.0.0. Pin to a real release before publish.');
+  }
+
+  const kind = overrides.kind || cookbook.kind || detection.kind;
+  if (kind === 'unknown') {
+    todos.push('kind could not be detected — set "kind" to ConsoleApp | StaticLib | DynamicLib | HeaderOnlyLib | WebApp | Utility | Service | TestProject.');
+  }
+  for (const note of detection.notes) todos.push(`detect: ${note}`);
+  for (const note of (cookbook.notes ?? [])) todos.push(`cookbook: ${note}`);
+
+  // Safe default recipe for any CMake project. Header-only still goes
+  // through cmake --install so the INTERFACE target + install() rules
+  // land in the published zip.
+  const build = {
+    system:    'cmake',
+    configs:   ['Debug', 'Release', 'RelWithDebInfo', 'MinSizeRel'],
+    configure: cookbook.configure ? [...cookbook.configure] : [],
+    installDir: 'install',
+  };
+
+  const manifest = {
+    name,
+    version,
+    schemaVersion: 2,
+    kind:          kind === 'unknown' ? 'StaticLib' : kind,
+    description:   overrides.description || `TODO: one-line description of ${name}`,
+    dependencies:  cookbook.dependencies ? { ...cookbook.dependencies } : {},
+    build,
+  };
+
+  if (cookbook.dependencies) {
+    todos.push(
+      `dependencies seeded from cookbook: ${Object.keys(cookbook.dependencies).join(', ')}. ` +
+      `Verify versions and pin ranges before publish.`,
+    );
+  }
+
+  // `gitRepo` / `gitSha` are normally captured by `wyvrnpm publish` at
+  // publish time — we leave them out of the manifest (not an author
+  // field) but surface them in the TODO report so the user can
+  // double-check the clone landed at the ref they expected.
+  if (sha) todos.push(`git HEAD at bootstrap: ${sha}`);
+  if (tag) todos.push(`nearest git tag: ${tag}`);
+
+  return { manifest, todos };
+}
+
+/**
+ * Full bootstrap flow: optionally clone, read git state, compose manifest,
+ * write it to disk. Returns the result so callers (CLI, tests) can decide
+ * what to print.
+ *
+ * @param {{
+ *   url:      string,
+ *   dest:     string,
+ *   ref?:     string | null,
+ *   name?:    string,
+ *   version?: string,
+ *   kind?:    string,
+ *   description?: string,
+ *   noClone?: boolean,
+ *   dryRun?:  boolean,
+ *   force?:   boolean,
+ * }} opts
+ * @returns {{ manifest: object, todos: string[], manifestPath: string, wrote: boolean }}
+ */
+function bootstrap(opts) {
+  const {
+    url, dest, ref = null,
+    name, version, kind, description,
+    noClone = false, dryRun = false, force = false, shallow = false,
+  } = opts;
+
+  if (!url && !noClone) throw new Error('bootstrap: --url (or a positional git URL) is required unless --no-clone');
+  if (!dest) throw new Error('bootstrap: --dest (or positional) is required');
+
+  const repoDir = path.resolve(dest);
+
+  if (!noClone) {
+    if (fs.existsSync(repoDir) && !force) {
+      throw new Error(
+        `bootstrap: destination already exists: ${repoDir}\n` +
+        '  Pass --force to reuse it, or --no-clone to operate on it in place.',
+      );
+    }
+    if (fs.existsSync(repoDir) && force) {
+      fs.rmSync(repoDir, { recursive: true, force: true });
+    }
+    cloneRepo({ gitUrl: url, destDir: repoDir, ref, shallow });
+  } else if (!fs.existsSync(repoDir)) {
+    throw new Error(`bootstrap: --no-clone but directory does not exist: ${repoDir}`);
+  }
+
+  const detect   = detectFromRepo(repoDir);
+  const gitState = readGitState(repoDir);
+
+  const { manifest, todos } = compose({
+    url:       url || gitRemoteUrl(repoDir) || '',
+    repoDir,
+    overrides: { name, version, kind, description },
+    detect,
+    gitState,
+  });
+
+  const manifestPath = path.join(repoDir, 'wyvrn.json');
+  let wrote = false;
+  if (!dryRun) {
+    if (fs.existsSync(manifestPath) && !force) {
+      throw new Error(
+        `bootstrap: ${manifestPath} already exists. Pass --force to overwrite, or --dry-run to preview only.`,
+      );
+    }
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
+    wrote = true;
+  }
+
+  return { manifest, todos, manifestPath, wrote };
+}
+
+function gitRemoteUrl(repoDir) {
+  try {
+    return execFileSync('git', ['remote', 'get-url', 'origin'], {
+      cwd: repoDir, stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString('utf8').trim() || null;
+  } catch { return null; }
+}
+
+module.exports = { bootstrap, compose, readGitState, cloneRepo };

package/src/bootstrap/version.js

@@ -0,0 +1,72 @@
+'use strict';
+
+/**
+ * Parse an upstream git tag into wyvrnpm's 4-part version scheme.
+ *
+ * Most C++ OSS projects publish 3-part semver tags (`v1.2.3`, `11.0.2`,
+ * `1.3.12`). wyvrnpm uses a 4-part `major.minor.patch.build` scheme
+ * throughout (see CLAUDE.md §4.2). We pad the upstream tag with `.0` for
+ * the build component so published manifests look like `1.3.12.0`.
+ *
+ * Accepted tag shapes:
+ *   v1.2.3      → "1.2.3.0"
+ *   1.2.3       → "1.2.3.0"
+ *   v1.2.3.4    → "1.2.3.4"
+ *   v11.0       → "11.0.0.0"  (2-part — padded)
+ *   v11         → "11.0.0.0"  (1-part — padded)
+ *   release-1.2 → "1.2.0.0"   (strips a leading "release-" / "ver-")
+ *
+ * Rejected (returns null):
+ *   empty / non-string
+ *   tags with suffixes ("1.2.3-rc1", "1.2.3+git", "1.2.3a") — callers
+ *     fall back to the HEAD SHA and flag a TODO
+ *   tags with 5+ numeric components
+ *
+ * @param {string | null} tag
+ * @returns {string | null} 4-part version, or null when the tag can't be
+ *                          cleanly promoted.
+ */
+function tagToVersion(tag) {
+  if (typeof tag !== 'string') return null;
+  let t = tag.trim();
+  if (!t) return null;
+
+  // Strip the most common prefixes authors use on git tags. Longest
+  // alternatives first so `version-2.0` matches the whole word, not
+  // just the leading `v`. We keep the allowlist tight — we'd rather
+  // fall through than silently misparse `release-candidate-1.2.3`.
+  t = t.replace(/^(version|release|ver|v)[-_.]?/i, '');
+
+  // Must be bare numeric segments separated by dots, nothing else.
+  if (!/^\d+(\.\d+){0,3}$/.test(t)) return null;
+
+  const parts = t.split('.').map((n) => parseInt(n, 10));
+  if (parts.some((n) => !Number.isFinite(n) || n < 0)) return null;
+
+  while (parts.length < 4) parts.push(0);
+  return parts.join('.');
+}
+
+/**
+ * Derive a wyvrnpm package name from a git URL.
+ *
+ *   https://github.com/fmtlib/fmt.git          → "fmt"
+ *   git@github.com:fmtlib/fmt.git              → "fmt"
+ *   https://gitlab.com/bzip2/bzip2.git         → "bzip2"
+ *   https://github.com/Tencent/rapidjson.git   → "rapidjson"
+ *   https://github.com/nlohmann/json.git       → "json"  (caller may want "nlohmann-json")
+ *
+ * Pure: does not hit the network.
+ *
+ * @param {string} url
+ * @returns {string}
+ */
+function nameFromUrl(url) {
+  if (typeof url !== 'string' || !url.trim()) return '';
+  const trimmed = url.trim().replace(/\/$/, '');
+  // Split on the last slash or colon (SSH form).
+  const tail = trimmed.split(/[/:]/).pop() || '';
+  return tail.replace(/\.git$/i, '');
+}
+
+module.exports = { tagToVersion, nameFromUrl };

package/src/build/index.js

@@ -15,6 +15,7 @@ const { hashProfile, mergeProfile, sha256Of } = require('../profile');
 const { generateToolchain }     = require('../toolchain');
 const { normalizeOptionsDeclaration, resolveEffectiveOptions } = require('../options');
 const { readRecipeConf, cmakeCacheVariables } = require('../conf');
+const { wyvrnFetch }            = require('../http-fetch');
 const log                       = require('../logger');
 
 /**
@@ -195,7 +196,7 @@ async function buildFromSource(args) {
   log.info(`  resolving ${Object.keys(depsForResolution).length} transitive dep(s)`);
   const transitiveManifests = new Map();
   const resolvedDeps = await resolveDependencies(
-    depsForResolution, packageSources, platform, fetch, new Map(),
+    depsForResolution, packageSources, platform, wyvrnFetch, new Map(),
     transitiveManifests,
   );
 
@@ -231,7 +232,7 @@ async function buildFromSource(args) {
   if (enrichedDeps.size > 0) {
     await downloadDependencies(
       enrichedDeps, packageSources, platform, paths.internal,
-      fetch, Math.max(30, Math.round(timeoutMs / 1000)),
+      wyvrnFetch, Math.max(30, Math.round(timeoutMs / 1000)),
       { ...authOptions, buildMode },
     );
   } else {

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/bootstrap.js

@@ -0,0 +1,96 @@
+'use strict';
+
+const path = require('path');
+
+const { bootstrap } = require('../bootstrap');
+const { nameFromUrl } = require('../bootstrap/version');
+const log           = require('../logger');
+
+/**
+ * `wyvrnpm bootstrap <git-url>` — scaffold a first-draft `wyvrn.json`
+ * inside a cloned OSS repo so it can be built + published as a wyvrnpm
+ * package. See CLAUDE.md §5.9 and
+ * claude/skills/wyvrnpm/references/oss-conversion-patterns.md.
+ *
+ * Typical use — batch-convert a list of OSS libraries into wyvrnpm:
+ *
+ *   while read url; do
+ *     wyvrnpm bootstrap "$url" --dest "./pkgs/$(basename "$url" .git)"
+ *   done < urls.txt
+ *
+ * The output is always a *first draft* — bootstrap prints a TODO report
+ * flagging gotchas that need human review (install gates, test-skip
+ * flags upstream-specific, missing CMakeLists.txt on header-drop repos
+ * like stb/imgui). Always review before `wyvrnpm publish`.
+ *
+ * @param {object} argv
+ */
+async function bootstrapCmd(argv) {
+  const url = argv.url ?? argv._?.[1] ?? null;
+  if (!url && !argv.noClone) {
+    log.error('bootstrap: missing git URL.\n  Usage: wyvrnpm bootstrap <git-url> [--dest <dir>]');
+    process.exit(1);
+  }
+
+  const dest = argv.dest || path.resolve(nameFromUrl(url ?? '') || 'package');
+
+  let result;
+  try {
+    result = bootstrap({
+      url,
+      dest,
+      ref:         argv.ref,
+      name:        argv.name,
+      version:     argv.version,
+      kind:        argv.kind,
+      description: argv.description,
+      noClone:     Boolean(argv.noClone),
+      dryRun:      Boolean(argv.dryRun),
+      force:       Boolean(argv.force),
+    });
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+
+  const { manifest, todos, manifestPath, wrote } = result;
+
+  if (argv.format === 'json') {
+    process.stdout.write(JSON.stringify({
+      command: 'bootstrap',
+      wyvrnpmVersion: require('../../package.json').version,
+      dest,
+      manifestPath,
+      wrote,
+      manifest,
+      todos,
+    }, null, 2) + '\n');
+    return;
+  }
+
+  console.log();
+  console.log(`─── ${manifest.name}@${manifest.version} (${manifest.kind}) ───`);
+  console.log(JSON.stringify(manifest, null, 2));
+  console.log();
+
+  if (wrote) log.success(`Wrote ${manifestPath}`);
+  else       log.info(`Dry run — no manifest written.`);
+
+  if (todos.length > 0) {
+    console.log();
+    console.log('TODOs — review before `wyvrnpm publish`:');
+    for (const t of todos) console.log(`  • ${t}`);
+  }
+
+  if (wrote) {
+    console.log();
+    console.log('Next steps:');
+    console.log(`  cd ${path.relative(process.cwd(), path.resolve(dest)) || '.'}`);
+    console.log('  wyvrnpm install');
+    console.log('  wyvrnpm build --install --all-configs');
+    console.log('  # review the install tree, then:');
+    console.log('  wyvrnpm publish --source <your-s3-publish-source>');
+  }
+}
+
+module.exports = bootstrapCmd;

package/src/commands/build.js

@@ -4,14 +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 { parseCliConf } = require('../conf');
 const { LOCAL_OVERLAY_FILENAME } = require('../conf');
+const { buildContext } = require('../context');
 const install          = require('./install');
 const log              = require('../logger');
 
@@ -141,6 +138,51 @@ function buildConfigureArgs({
   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.
  *
@@ -225,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
@@ -278,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 {
@@ -321,16 +383,10 @@ 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.
-  let cliConfSets, cliConfUnsets;
-  try {
-    const cli = parseCliConf(argv.conf);
-    cliConfSets   = cli.sets;
-    cliConfUnsets = cli.unsets;
-  } catch (err) {
-    log.error(`--conf parse error: ${err.message}`);
-    process.exit(1);
-  }
+  // 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,
@@ -342,35 +398,43 @@ async function build(argv) {
   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;
@@ -381,6 +445,7 @@ module.exports._helpers = {
   isToolchainStale,
   resolvePresetName,
   resolveBinaryDir,
+  resolveConfigList,
   buildConfigureArgs,
   buildBuildArgs,
   buildInstallArgs,