wyvrnpm 2.10.2 → 2.12.2

package/src/commands/install.js

@@ -1,674 +1,730 @@
-'use strict';
-
-const fs   = require('fs');
-const path = require('path');
-
-const { normalizeDependencies }                             = require('../manifest');
-const { resolveDependencies }                               = require('../resolve');
-const { downloadDependencies }                              = require('../download');
-const { wyvrnFetch }                                        = require('../http-fetch');
-const { resolveEffectiveConf, cmakeCacheVariables, unflattenConf } = require('../conf');
-const { hashProfile, formatProfile, mergeProfile }          = require('../profile');
-const { generateToolchain, generateCMakePresets }           = require('../toolchain');
-const { normalizeRecipe, hasBuildRecipe }                   = require('../build/recipe');
-const { buildContext }                                      = require('../context');
-const {
-  normalizeOptionsDeclaration,
-  resolveEffectiveOptions,
-}                                                            = require('../options');
-const {
-  normalizeSettingsOverrides,
-  resolveOverrideSettings,
-}                                                            = require('../settings-overrides');
-const {
-  resolveUploadDestination,
-  createUploadStats,
-  formatUploadSummary,
-}                                                            = require('../upload-built');
-const log                                                    = require('../logger');
-
-/**
- * Resolves and downloads all dependencies declared in the manifest, then writes
- * a wyvrn.lock file recording exactly what was installed.
- *
- * v2 behaviour:
- *  - Loads the named build profile (--profile flag → config.defaultProfile → "default")
- *  - Each dependency can override individual profile settings via its `settings` field
- *  - Lock file records the full profile + per-package SHA256, profileHash, and git metadata
- *
- * @param {object} argv
- */
-async function install(argv) {
-  // Shared per-invocation state (config, profile, manifest lazy, auth,
-  // CLI options/conf parsing, JSON-mode toggle). See src/context.js +
-  // claude/PLAN-COMMAND-CONTEXT.md. buildContext throws on input errors
-  // so they surface here with a single log+exit rather than deep in the
-  // command.
-  let ctx;
-  try {
-    ctx = buildContext(argv);
-  } catch (err) {
-    log.error(err.message);
-    process.exit(1);
-  }
-
-  const {
-    rootDir,
-    manifestPath,
-    config,
-    cliOptions: cliOptionsByPkg,
-    flags,
-  } = ctx;
-  const { name: profileName, profile: baseProfile, fromFile } = ctx.profiles.host;
-  const { build: buildMode, uploadBuilt } = flags;
-  const jsonOut = flags.format === 'json';
-
-  // --upload-built implies a build step happened. `--build=never` +
-  // `--upload-built` is a usage error — fail fast rather than silently
-  // accept something that cannot upload anything.
-  if (uploadBuilt && buildMode === 'never') {
-    log.error(
-      '--upload-built requires --build=missing (or --build=always).\n' +
-      '  Nothing will be built, so there is nothing to upload.',
-    );
-    process.exit(1);
-  }
-
-  if (buildMode === 'always') {
-    log.error(
-      '--build=always is not implemented (requires PLAN-BUILD-MISSING phase 3).\n' +
-      '  Use --build=never (default) or --build=missing.',
-    );
-    process.exit(1);
-  }
-
-  // ── Auth / sources ────────────────────────────────────────────────────────
-  // Source filtering stays per-command (install takes URL array + pin
-  // resolution; publish takes name-or-URL; show takes URL array). The
-  // ctx-level config read above means we do NOT call readConfig() again.
-  let packageSources;
-  if (argv.source && argv.source.length > 0) {
-    packageSources = argv.source;
-  } else {
-    packageSources = config.installSources.map((s) => s.url);
-    if (packageSources.length > 0) {
-      log.info(`Using ${packageSources.length} source(s) from config`);
-    }
-  }
-
-  if (packageSources.length === 0) {
-    log.warn(
-      'no sources configured. ' +
-        'Pass --source <url> or run: wyvrnpm configure add-source --kind install ...',
-    );
-  }
-
-  // ── Active build profile ──────────────────────────────────────────────────
-  // Resolved once during buildContext(); destructured at the top of this
-  // function. `profileName`, `baseProfile`, `fromFile` are already in scope.
-  log.info(`Profile: "${profileName}"${fromFile ? '' : ' (auto-detected)'}`);
-  console.log(formatProfile(baseProfile).split('\n').map((l) => `  ${l}`).join('\n'));
-  console.log(`  Profile hash : ${hashProfile(baseProfile)}`);
-
-  // ── Lock file ─────────────────────────────────────────────────────────────
-  const lockPath       = path.join(path.dirname(manifestPath), 'wyvrn.lock');
-  const lockedVersions = new Map();
-
-  if (fs.existsSync(lockPath)) {
-    try {
-      const lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
-      for (const [name, entry] of Object.entries(lock.packages ?? {})) {
-        const ver = typeof entry === 'string' ? entry : entry.version;
-        if (ver) lockedVersions.set(name, ver);
-      }
-      log.info(`Lock file found — ${lockedVersions.size} pinned package(s)`);
-    } catch {
-      log.warn('could not read wyvrn.lock, resolving from scratch');
-    }
-  }
-
-  // ── Read manifest ─────────────────────────────────────────────────────────
-  // ctx.manifest is a lazy getter: first access triggers readManifest()
-  // and caches the result for the rest of this invocation.
-  const manifest = ctx.manifest;
-
-  // Normalize to { name: { version, settings } }
-  const normalizedDeps = normalizeDependencies(manifest.dependencies ?? manifest.Dependencies);
-
-  // For resolution, only pass name → version (settings don't affect resolution)
-  const depsForResolution = Object.fromEntries(
-    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})`,
-  );
-
-  // Manifests collected during resolution — reused below to read each dep's
-  // recipe-declared `options` block without a second HTTP round trip.
-  const depManifests = new Map();
-
-  const resolvedDeps = await resolveDependencies(
-    depsForResolution,
-    packageSources,
-    argv.platform,
-    wyvrnFetch,
-    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 come pre-parsed from
-  // buildContext as `cliOptionsByPkg` (shape: { pkg: { name: value } }).
-
-  // 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)
-  //   - effective options (recipe defaults + consumer overrides + CLI overrides)
-  //   - profileHash computed from both (options only hashed in when declared)
-  const enrichedDeps = new Map();
-  for (const [name, version] of resolvedDeps) {
-    // 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);
-    const declaration    = depManifest?.options
-      ? normalizeOptionsDeclaration(depManifest.options, `${name}@${version}`)
-      : null;
-    const effectiveOptions = resolveEffectiveOptions(
-      declaration,
-      normalizedDeps[name]?.options ?? {},
-      cliOptionsByPkg[name]         ?? {},
-      `${name}@${version}`,
-    );
-
-    const profileHash = hashProfile(effectiveProfile, effectiveOptions);
-
-    if (Object.keys(depOverrides).length > 0) {
-      log.info(
-        `${name}: settings override → profileHash ${profileHash}` +
-        ` (${JSON.stringify(depOverrides)})`,
-      );
-    }
-    if (effectiveOptions) {
-      log.info(`${name}: options → ${JSON.stringify(effectiveOptions)}`);
-    }
-
-    enrichedDeps.set(name, {
-      version,
-      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). 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:      ctx.auth.for(firstInstallSrc).token,
-    buildMode,
-    profileName,
-  };
-
-  // ── Resolve upload destination up-front when --upload-built is set ──────
-  // Failing here (no publish source configured) avoids spending minutes on
-  // a source-build whose output we can't deliver.
-  if (uploadBuilt) {
-    const resolved = resolveUploadDestination(
-      {
-        uploadSource: argv.uploadSource,
-        awsProfile:   argv.awsProfile ?? firstInstallSrc?.profile,
-        token:        ctx.auth.for(firstInstallSrc).token,
-      },
-      config,
-    );
-    if (!resolved) {
-      log.error(
-        '--upload-built was passed but no upload destination could be resolved.\n' +
-        '  Pass --upload-source <url-or-name> or configure a publish source:\n' +
-        '    wyvrnpm configure add-source --kind publish --name ... --url ...',
-      );
-      process.exit(1);
-    }
-    downloadOptions.uploadBuilt  = true;
-    downloadOptions.uploadSource = resolved.uploadSource;
-    downloadOptions.uploadAuth   = resolved.uploadAuth;
-    downloadOptions.uploadStats  = createUploadStats();
-
-    if (resolved.uploadSource !== (packageSources[0] ?? '')) {
-      log.info(
-        `upload-built: install source(s) and upload source differ —\n` +
-        `  install: ${packageSources.join(', ') || '(none)'}\n` +
-        `  upload : ${resolved.uploadSource}`,
-      );
-    }
-  }
-
-  const lockEntries = await downloadDependencies(
-    enrichedDeps,
-    packageSources,
-    argv.platform,
-    razerDir,
-    wyvrnFetch,
-    argv.timeout,
-    downloadOptions,
-  );
-
-  // ── Write v2 lock file ────────────────────────────────────────────────────
-  const sortedPackages = {};
-  for (const key of [...resolvedDeps.keys()].sort()) {
-    sortedPackages[key] = lockEntries?.get(key) ?? { version: resolvedDeps.get(key) };
-  }
-
-  const lockData = {
-    wyvrnVersion: 2,
-    generatedAt:  new Date().toISOString(),
-    platform:     argv.platform,
-    profileName,
-    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');
-  log.info(`Lock file written to ${lockPath}`);
-
-  // ── CMake toolchain generation ────────────────────────────────────────────
-  const packageNames = [...resolvedDeps.keys()].sort();
-  const { toolchain } = generateToolchain({
-    destDir:     razerDir,
-    profile:     baseProfile,
-    profileName,
-    profileHash: hashProfile(baseProfile),
-    packageNames,
-  });
-  log.info(`CMake toolchain written to ${toolchain}`);
-
-  // ── CMakePresets.json emission ────────────────────────────────────────────
-  const toolchainRelPath = path
-    .relative(rootDir, toolchain)
-    .replace(/\\/g, '/');
-
-  // Derive generator + cacheVariables from the project's own `build` recipe
-  // so `wyvrnpm build` locally honours the same knobs the source-build /
-  // publish paths use. Without this, `build.configure` is advisory metadata
-  // and CMake falls back to its default generator (VS on Windows) — which
-  // breaks publishers whose recipe disables example/test subprojects (F15).
-  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
-      // configure args. When the project declares no options, this is null
-      // and the recipe's configure / buildArgs must not contain templates
-      // (normalizeRecipe enforces that).
-      const projectDeclaration = manifest.options
-        ? normalizeOptionsDeclaration(manifest.options, manifest.name)
-        : null;
-      const projectCliOverrides = cliOptionsByPkg[manifest.name] ?? {};
-      const projectEffectiveOptions = resolveEffectiveOptions(
-        projectDeclaration, {}, projectCliOverrides, manifest.name,
-      );
-      const recipe = normalizeRecipe(manifest.build, projectEffectiveOptions, manifest);
-
-      if (recipe.generators.length > 0) {
-        // First entry in the generator fallback chain. Users whose system
-        // lacks the first pick can override via CMakeUserPresets.json
-        // (which CMake merges in automatically).
-        [presetGenerator] = recipe.generators;
-      }
-
-      // Fold -DKEY=VALUE from recipe.configure into cacheVariables. Other
-      // configure args (anything not matching `-DKEY=VALUE`) can't be
-      // expressed in a CMake preset and are silently skipped here — the
-      // source-build path still sees them verbatim.
-      const cacheVars = {};
-      for (const arg of recipe.configure) {
-        const match = arg.match(/^-D([^=]+)=(.*)$/);
-        if (match) cacheVars[match[1]] = match[2];
-      }
-      if (Object.keys(cacheVars).length > 0) presetCacheVariables = cacheVars;
-
-      // Propagate `build.installDir` so that `wyvrnpm build --install` lands
-      // under the project's build tree instead of CMake's system default
-      // (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` +
-        `  the preset will be emitted without a generator or recipe cacheVariables. ` +
-        `Fix the recipe or override via CMakeUserPresets.json.`,
-      );
-    }
-  }
-
-  // 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,
-    profileHash:  hashProfile(baseProfile),
-    toolchainRelPath,
-    generator:           presetGenerator,
-    extraCacheVariables: presetCacheVariables,
-    installDir:          presetInstallDir,
-    profileArch:         baseProfile.arch ?? null,
-    configs:             presetConfigs,
-  });
-  if (presetResult.action === 'skipped') {
-    log.warn(
-      'could not write presets — both CMakePresets.json and ' +
-      'CMakeUserPresets.json exist and are user-owned. Add this to your presets:\n' +
-      `  { "name": "wyvrn-${profileName}", "cacheVariables": { "CMAKE_TOOLCHAIN_FILE": "\${sourceDir}/${toolchainRelPath}" } }`,
-    );
-  } else {
-    log.info(
-      `CMake presets ${presetResult.action}: ${presetResult.path}` +
-      (presetResult.isUser ? ' (user presets — CMakePresets.json is user-owned)' : ''),
-    );
-  }
-
-  const count = resolvedDeps.size;
-  log.success(`Done — ${count} package${count !== 1 ? 's' : ''} installed.`);
-
-  // ── upload-built summary ────────────────────────────────────────────────
-  const uploadSummary = formatUploadSummary(downloadOptions.uploadStats);
-  if (uploadSummary) log.info(uploadSummary);
-
-  // ── JSON payload (--format=json) ────────────────────────────────────────
-  // All log.info/success above have gone to stderr thanks to setJsonMode.
-  // stdout gets exactly one JSON object, no trailing text.
-  if (jsonOut) {
-    const packages = [...resolvedDeps.keys()].sort().map((name) => {
-      const entry       = lockEntries?.get(name) ?? {};
-      const consumerSpec = normalizedDeps[name]?.version ?? null;
-      const resolvedVer  = entry.version ?? resolvedDeps.get(name);
-      const versionRange = (consumerSpec && consumerSpec !== resolvedVer) ? consumerSpec : null;
-      return {
-        name,
-        version:       resolvedVer,
-        versionRange,
-        profileHash:   entry.profileHash   ?? null,
-        options:       entry.options       ?? null,
-        contentSha256: entry.contentSha256 ?? null,
-        gitSha:        entry.gitSha        ?? null,
-        resolvedFrom:  entry.resolvedFrom  ?? null,
-      };
-    });
-
-    const stats = downloadOptions.uploadStats;
-    const uploadSummaryJson = stats ? {
-      uploaded: stats.uploaded.length,
-      skipped:  stats.skipped.length,
-      failed:   stats.failed.length,
-    } : null;
-
-    const payload = {
-      command:        'install',
-      wyvrnpmVersion: require('../../package.json').version,
-      profile:        baseProfile,
-      profileName,
-      profileHash:    hashProfile(baseProfile),
-      packages,
-      lockFile:       lockPath,
-      uploadSummary:  uploadSummaryJson,
-    };
-    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
-  }
-}
-
-// ---------------------------------------------------------------------------
-// --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;
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const { normalizeDependencies }                             = require('../manifest');
+const { resolveDependencies }                               = require('../resolve');
+const { downloadDependencies }                              = require('../download');
+const { wyvrnFetch }                                        = require('../http-fetch');
+const { resolveEffectiveConf, cmakeCacheVariables, unflattenConf } = require('../conf');
+const { resolveBinaryDirRoot }                              = require('../binary-dir');
+const { hashProfile, formatProfile, mergeProfile }          = require('../profile');
+const { generateToolchain, generateCMakePresets }           = require('../toolchain');
+const { normalizeRecipe, hasBuildRecipe }                   = require('../build/recipe');
+const { buildContext }                                      = require('../context');
+const {
+  normalizeOptionsDeclaration,
+  resolveEffectiveOptions,
+}                                                            = require('../options');
+const {
+  normalizeSettingsOverrides,
+  resolveOverrideSettings,
+}                                                            = require('../settings-overrides');
+const {
+  resolveUploadDestination,
+  createUploadStats,
+  formatUploadSummary,
+}                                                            = require('../upload-built');
+const log                                                    = require('../logger');
+
+/**
+ * Resolves and downloads all dependencies declared in the manifest, then writes
+ * a wyvrn.lock file recording exactly what was installed.
+ *
+ * v2 behaviour:
+ *  - Loads the named build profile (--profile flag → config.defaultProfile → "default")
+ *  - Each dependency can override individual profile settings via its `settings` field
+ *  - Lock file records the full profile + per-package SHA256, profileHash, and git metadata
+ *
+ * @param {object} argv
+ */
+async function install(argv) {
+  // Shared per-invocation state (config, profile, manifest lazy, auth,
+  // CLI options/conf parsing, JSON-mode toggle). See src/context.js +
+  // claude/PLAN-COMMAND-CONTEXT.md. buildContext throws on input errors
+  // so they surface here with a single log+exit rather than deep in the
+  // command.
+  let ctx;
+  try {
+    ctx = buildContext(argv);
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+
+  const {
+    rootDir,
+    manifestPath,
+    config,
+    cliOptions: cliOptionsByPkg,
+    flags,
+  } = ctx;
+  const { name: profileName, profile: baseProfile, fromFile } = ctx.profiles.host;
+  const { build: buildMode, uploadBuilt } = flags;
+  const jsonOut = flags.format === 'json';
+
+  // --upload-built implies a build step happened. `--build=never` +
+  // `--upload-built` is a usage error — fail fast rather than silently
+  // accept something that cannot upload anything.
+  if (uploadBuilt && buildMode === 'never') {
+    log.error(
+      '--upload-built requires --build=missing (or --build=always).\n' +
+      '  Nothing will be built, so there is nothing to upload.',
+    );
+    process.exit(1);
+  }
+
+  if (buildMode === 'always') {
+    log.error(
+      '--build=always is not implemented (requires PLAN-BUILD-MISSING phase 3).\n' +
+      '  Use --build=never (default) or --build=missing.',
+    );
+    process.exit(1);
+  }
+
+  // ── Auth / sources ────────────────────────────────────────────────────────
+  // Source filtering stays per-command (install takes URL array + pin
+  // resolution; publish takes name-or-URL; show takes URL array). The
+  // ctx-level config read above means we do NOT call readConfig() again.
+  let packageSources;
+  if (argv.source && argv.source.length > 0) {
+    packageSources = argv.source;
+  } else {
+    packageSources = config.installSources.map((s) => s.url);
+    if (packageSources.length > 0) {
+      log.info(`Using ${packageSources.length} source(s) from config`);
+    }
+  }
+
+  if (packageSources.length === 0) {
+    log.warn(
+      'no sources configured. ' +
+        'Pass --source <url> or run: wyvrnpm configure add-source --kind install ...',
+    );
+  }
+
+  // ── Active build profile ──────────────────────────────────────────────────
+  // Resolved once during buildContext(); destructured at the top of this
+  // function. `profileName`, `baseProfile`, `fromFile` are already in scope.
+  log.info(`Profile: "${profileName}"${fromFile ? '' : ' (auto-detected)'}`);
+  console.log(formatProfile(baseProfile).split('\n').map((l) => `  ${l}`).join('\n'));
+  console.log(`  Profile hash : ${hashProfile(baseProfile)}`);
+
+  // ── Lock file ─────────────────────────────────────────────────────────────
+  const lockPath       = path.join(path.dirname(manifestPath), 'wyvrn.lock');
+  const lockedVersions = new Map();
+
+  if (fs.existsSync(lockPath)) {
+    try {
+      const lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+      for (const [name, entry] of Object.entries(lock.packages ?? {})) {
+        const ver = typeof entry === 'string' ? entry : entry.version;
+        if (ver) lockedVersions.set(name, ver);
+      }
+      log.info(`Lock file found — ${lockedVersions.size} pinned package(s)`);
+    } catch {
+      log.warn('could not read wyvrn.lock, resolving from scratch');
+    }
+  }
+
+  // ── Read manifest ─────────────────────────────────────────────────────────
+  // ctx.manifest is a lazy getter: first access triggers readManifest()
+  // and caches the result for the rest of this invocation.
+  const manifest = ctx.manifest;
+
+  // Normalize to { name: { version, settings } }
+  const normalizedDeps = normalizeDependencies(manifest.dependencies ?? manifest.Dependencies);
+
+  // For resolution, only pass name → version (settings don't affect resolution)
+  const depsForResolution = Object.fromEntries(
+    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})`,
+  );
+
+  // Manifests collected during resolution — reused below to read each dep's
+  // recipe-declared `options` block without a second HTTP round trip.
+  const depManifests = new Map();
+
+  const resolvedDeps = await resolveDependencies(
+    depsForResolution,
+    packageSources,
+    argv.platform,
+    wyvrnFetch,
+    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 come pre-parsed from
+  // buildContext as `cliOptionsByPkg` (shape: { pkg: { name: value } }).
+
+  // 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)
+  //   - effective options (recipe defaults + consumer overrides + CLI overrides)
+  //   - profileHash computed from both (options only hashed in when declared)
+  const enrichedDeps = new Map();
+  for (const [name, version] of resolvedDeps) {
+    // 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);
+    const declaration    = depManifest?.options
+      ? normalizeOptionsDeclaration(depManifest.options, `${name}@${version}`)
+      : null;
+    const effectiveOptions = resolveEffectiveOptions(
+      declaration,
+      normalizedDeps[name]?.options ?? {},
+      cliOptionsByPkg[name]         ?? {},
+      `${name}@${version}`,
+    );
+
+    const profileHash = hashProfile(effectiveProfile, effectiveOptions);
+
+    if (Object.keys(depOverrides).length > 0) {
+      log.info(
+        `${name}: settings override → profileHash ${profileHash}` +
+        ` (${JSON.stringify(depOverrides)})`,
+      );
+    }
+    if (effectiveOptions) {
+      log.info(`${name}: options → ${JSON.stringify(effectiveOptions)}`);
+    }
+
+    enrichedDeps.set(name, {
+      version,
+      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)}`);
+  }
+
+  // ── Resolve binaryDirRoot (CLI > wyvrn.local.json > "build") ─────────────
+  // Sibling channel to `conf` — non-ABI, dev-local. Folds into the
+  // generated preset's `binaryDir` so projects with a `BUILD` Bazel/Buck
+  // file at the root (gRPC, …) can sidestep the case-insensitive-FS
+  // collision against `build/`. See src/binary-dir.js.
+  let binaryDirRoot;
+  try {
+    binaryDirRoot = resolveBinaryDirRoot({
+      cliBuildDir:               argv.buildDir,
+      localOverlayBinaryDirRoot: effectiveConfResult.localBinaryDirRoot,
+    });
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+  if (binaryDirRoot !== 'build') {
+    log.info(`binaryDirRoot: ${binaryDirRoot} (preset binaryDir → \${sourceDir}/${binaryDirRoot}/wyvrn-${profileName})`);
+  }
+
+  // ── --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). 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:      ctx.auth.for(firstInstallSrc).token,
+    buildMode,
+    profileName,
+  };
+
+  // ── Resolve upload destination up-front when --upload-built is set ──────
+  // Failing here (no publish source configured) avoids spending minutes on
+  // a source-build whose output we can't deliver.
+  if (uploadBuilt) {
+    const resolved = resolveUploadDestination(
+      {
+        uploadSource: argv.uploadSource,
+        awsProfile:   argv.awsProfile ?? firstInstallSrc?.profile,
+        token:        ctx.auth.for(firstInstallSrc).token,
+      },
+      config,
+    );
+    if (!resolved) {
+      log.error(
+        '--upload-built was passed but no upload destination could be resolved.\n' +
+        '  Pass --upload-source <url-or-name> or configure a publish source:\n' +
+        '    wyvrnpm configure add-source --kind publish --name ... --url ...',
+      );
+      process.exit(1);
+    }
+    downloadOptions.uploadBuilt  = true;
+    downloadOptions.uploadSource = resolved.uploadSource;
+    downloadOptions.uploadAuth   = resolved.uploadAuth;
+    downloadOptions.uploadStats  = createUploadStats();
+
+    if (resolved.uploadSource !== (packageSources[0] ?? '')) {
+      log.info(
+        `upload-built: install source(s) and upload source differ —\n` +
+        `  install: ${packageSources.join(', ') || '(none)'}\n` +
+        `  upload : ${resolved.uploadSource}`,
+      );
+    }
+  }
+
+  const lockEntries = await downloadDependencies(
+    enrichedDeps,
+    packageSources,
+    argv.platform,
+    razerDir,
+    wyvrnFetch,
+    argv.timeout,
+    downloadOptions,
+  );
+
+  // ── Write v2 lock file ────────────────────────────────────────────────────
+  const sortedPackages = {};
+  for (const key of [...resolvedDeps.keys()].sort()) {
+    sortedPackages[key] = lockEntries?.get(key) ?? { version: resolvedDeps.get(key) };
+  }
+
+  const lockData = {
+    wyvrnVersion: 2,
+    generatedAt:  new Date().toISOString(),
+    platform:     argv.platform,
+    profileName,
+    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');
+  log.info(`Lock file written to ${lockPath}`);
+
+  // ── CMake toolchain generation ────────────────────────────────────────────
+  const packageNames = [...resolvedDeps.keys()].sort();
+  const { toolchain } = generateToolchain({
+    destDir:     razerDir,
+    profile:     baseProfile,
+    profileName,
+    profileHash: hashProfile(baseProfile),
+    packageNames,
+  });
+  log.info(`CMake toolchain written to ${toolchain}`);
+
+  // ── CMakePresets.json emission ────────────────────────────────────────────
+  const toolchainRelPath = path
+    .relative(rootDir, toolchain)
+    .replace(/\\/g, '/');
+
+  // Derive generator + cacheVariables from the project's own `build` recipe
+  // so `wyvrnpm build` locally honours the same knobs the source-build /
+  // publish paths use. Without this, `build.configure` is advisory metadata
+  // and CMake falls back to its default generator (VS on Windows) — which
+  // breaks publishers whose recipe disables example/test subprojects (F15).
+  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
+      // configure args. When the project declares no options, this is null
+      // and the recipe's configure / buildArgs must not contain templates
+      // (normalizeRecipe enforces that).
+      const projectDeclaration = manifest.options
+        ? normalizeOptionsDeclaration(manifest.options, manifest.name)
+        : null;
+      const projectCliOverrides = cliOptionsByPkg[manifest.name] ?? {};
+      const projectEffectiveOptions = resolveEffectiveOptions(
+        projectDeclaration, {}, projectCliOverrides, manifest.name,
+      );
+      const recipe = normalizeRecipe(manifest.build, projectEffectiveOptions, manifest);
+
+      if (recipe.generators.length > 0) {
+        // First entry in the generator fallback chain. Users whose system
+        // lacks the first pick can override via CMakeUserPresets.json
+        // (which CMake merges in automatically).
+        [presetGenerator] = recipe.generators;
+      }
+
+      // Fold -DKEY=VALUE from recipe.configure into cacheVariables. Other
+      // configure args (anything not matching `-DKEY=VALUE`) can't be
+      // expressed in a CMake preset and are silently skipped here — the
+      // source-build path still sees them verbatim.
+      const cacheVars = {};
+      for (const arg of recipe.configure) {
+        const match = arg.match(/^-D([^=]+)=(.*)$/);
+        if (match) cacheVars[match[1]] = match[2];
+      }
+      if (Object.keys(cacheVars).length > 0) presetCacheVariables = cacheVars;
+
+      // Propagate `build.installDir` so that `wyvrnpm build --install` lands
+      // under the project's build tree instead of CMake's system default
+      // (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` +
+        `  the preset will be emitted without a generator or recipe cacheVariables. ` +
+        `Fix the recipe or override via CMakeUserPresets.json.`,
+      );
+    }
+  }
+
+  // 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,
+    profileHash:  hashProfile(baseProfile),
+    toolchainRelPath,
+    generator:           presetGenerator,
+    extraCacheVariables: presetCacheVariables,
+    installDir:          presetInstallDir,
+    profileArch:         baseProfile.arch ?? null,
+    configs:             presetConfigs,
+    binaryDirRoot,
+  });
+  if (presetResult.action === 'skipped') {
+    log.warn(
+      'could not write presets — both CMakePresets.json and ' +
+      'CMakeUserPresets.json exist and are user-owned. Add this to your presets:\n' +
+      `  { "name": "wyvrn-${profileName}", "cacheVariables": { "CMAKE_TOOLCHAIN_FILE": "\${sourceDir}/${toolchainRelPath}" } }`,
+    );
+  } else {
+    log.info(
+      `CMake presets ${presetResult.action}: ${presetResult.path}` +
+      (presetResult.isUser ? ' (user presets — CMakePresets.json is user-owned)' : ''),
+    );
+  }
+
+  // ── Classify install outcomes ──────────────────────────────────────────
+  // CLAUDE.md principles 5 + 8: a sha256 mismatch / extract failure /
+  // not-found / no-exact-match / source-build-failed is a hard failure, not
+  // a silent-success-with-warning. The lockfile + toolchain were already
+  // written above so the partial state stays inspectable; we exit non-zero
+  // here so CI doesn't take "Done — N installed" at face value when one of
+  // the deps actually failed.
+  const SUCCESS_RESOLVED = new Set([
+    'v1', 'v2', 'v2-compat', 'v2-source-build', 'cached', 'link',
+  ]);
+  const failed = [];
+  for (const [name, entry] of lockEntries ?? []) {
+    if (!SUCCESS_RESOLVED.has(entry.resolvedFrom)) {
+      failed.push({ name, version: entry.version, resolvedFrom: entry.resolvedFrom });
+    }
+  }
+
+  const count          = resolvedDeps.size;
+  const installedCount = count - failed.length;
+
+  if (failed.length === 0) {
+    log.success(`Done — ${count} package${count !== 1 ? 's' : ''} installed.`);
+  } else {
+    log.error(
+      `Install incomplete — ${installedCount}/${count} package${count !== 1 ? 's' : ''} installed, ` +
+      `${failed.length} failed:`,
+    );
+    for (const f of failed) {
+      log.error(`  ${f.name}@${f.version} — ${f.resolvedFrom}`);
+    }
+  }
+
+  // ── upload-built summary ────────────────────────────────────────────────
+  const uploadSummary = formatUploadSummary(downloadOptions.uploadStats);
+  if (uploadSummary) log.info(uploadSummary);
+
+  // ── JSON payload (--format=json) ────────────────────────────────────────
+  // All log.info/success above have gone to stderr thanks to setJsonMode.
+  // stdout gets exactly one JSON object, no trailing text.
+  if (jsonOut) {
+    const packages = [...resolvedDeps.keys()].sort().map((name) => {
+      const entry       = lockEntries?.get(name) ?? {};
+      const consumerSpec = normalizedDeps[name]?.version ?? null;
+      const resolvedVer  = entry.version ?? resolvedDeps.get(name);
+      const versionRange = (consumerSpec && consumerSpec !== resolvedVer) ? consumerSpec : null;
+      return {
+        name,
+        version:       resolvedVer,
+        versionRange,
+        profileHash:   entry.profileHash   ?? null,
+        options:       entry.options       ?? null,
+        contentSha256: entry.contentSha256 ?? null,
+        gitSha:        entry.gitSha        ?? null,
+        resolvedFrom:  entry.resolvedFrom  ?? null,
+      };
+    });
+
+    const stats = downloadOptions.uploadStats;
+    const uploadSummaryJson = stats ? {
+      uploaded: stats.uploaded.length,
+      skipped:  stats.skipped.length,
+      failed:   stats.failed.length,
+    } : null;
+
+    const payload = {
+      command:        'install',
+      wyvrnpmVersion: require('../../package.json').version,
+      profile:        baseProfile,
+      profileName,
+      profileHash:    hashProfile(baseProfile),
+      packages,
+      lockFile:       lockPath,
+      uploadSummary:  uploadSummaryJson,
+      failed,
+    };
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+  }
+
+  // ── Exit non-zero on any unsuccessful resolution ────────────────────────
+  if (failed.length > 0) {
+    process.exit(1);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// --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;