wyvrnpm 2.0.4 → 2.3.2

package/src/download.js

@@ -9,6 +9,10 @@ const StreamZip = require('node-stream-zip');
 const { isLink, getLinkTarget } = require('./link-utils');
 const { sha256Of }              = require('./profile');
 const { getProvider }           = require('./providers');
+const { evaluateCompat, pickBestCandidate, summarizeReasons } = require('./compat');
+const { buildFromSource }       = require('./build');
+const { uploadSourceBuiltArtefact } = require('./upload-built');
+const log                       = require('./logger');
 
 // ---------------------------------------------------------------------------
 // v1 (legacy) download helpers
@@ -42,7 +46,7 @@ async function tryDownloadFromSources(name, version, packageSources, platform, h
         await downloadFile(url, destZipPath, httpClient, timeoutMs);
         return true;
       } catch (err) {
-        console.warn(`[wyvrn] Could not download ${name}@${version} from ${url}: ${err.message}`);
+        log.warn(`Could not download ${name}@${version} from ${url}: ${err.message}`);
       }
     }
   }
@@ -52,101 +56,257 @@ async function tryDownloadFromSources(name, version, packageSources, platform, h
 // ---------------------------------------------------------------------------
 // v2 download helpers
 // ---------------------------------------------------------------------------
+//
+// PLAN-BUILD-MISSING phase 1: strict-by-default resolution.
+//
+// The v2 path is split in two:
+//
+//   tryV2Exact  — ONLY attempts the exact profile-hash match. Also returns
+//                 the versions index if the package exists in v2 (so the
+//                 caller can distinguish "v2 knows this package but not your
+//                 profile" from "v2 doesn't know this package at all").
+//
+//   tryV2Compat — the old OS+arch compatibility fallback. Now dead code on
+//                 the default path; only reachable via the escape-hatch env
+//                 var WYVRNPM_ALLOW_LOOSE_COMPAT=1 (deprecated — prints a
+//                 warning when used). Will be deleted in a future release.
+//
 
 /**
- * Try to download a v2 prebuilt binary for a package.
+ * Attempt an exact v2 profile-hash download across all configured sources.
  *
- * Resolution order:
- *   1. Exact profile hash match
- *   2. Compatible build from versions.json (same OS + arch, any compiler)
- *   3. Return null (caller should fall back to v1)
+ * Semantics:
+ *   - If ANY source has a byte-exact match, we download from the first one
+ *     and return `found: true`.
+ *   - Otherwise we return `found: false`, along with whether any source had
+ *     a versions.json entry for (name, version). The caller uses that flag
+ *     to decide whether to fall through to the v1 legacy path (only when
+ *     the package is unknown in v2 entirely) or to fail strictly (when v2
+ *     knows the package but not the requested profile).
  *
- * @param {{
- *   name:         string,
- *   version:      string,
- *   profileHash:  string,
- *   profile:      import('./profile').WyvrnProfile,
- * }} dep
- * @param {string[]}  packageSources
- * @param {string}    destZipPath
- * @param {number}    timeoutMs
- * @param {object}    authOptions  - { awsProfile?, token? }
+ * @param {{ name: string, version: string, profileHash: string }} dep
+ * @param {string[]} packageSources
+ * @param {string}   destZipPath
+ * @param {number}   timeoutMs
+ * @param {object}   authOptions   { awsProfile?, token? }
  * @returns {Promise<{
- *   found:         boolean,
- *   contentSha256: string|null,
- *   gitSha:        string|null,
- *   gitRepo:       string|null,
- *   profileHash:   string,
- *   source:        string,       // which source URL was used
- * }|null>}  null = not found in v2
+ *   found:              boolean,
+ *   result?:            { contentSha256: string|null, gitSha: string|null, gitRepo: string|null, profileHash: string, source: string },
+ *   indexFoundInSource: string|null,    // which source returned a versions index (null = none did)
+ *   availableProfiles:  string[],       // profile hashes the registry HAS, for the error message
+ *   versionsIndex?:     object,         // pre-fetched index, reusable by tryV2Compat
+ * }>}
  */
-async function tryDownloadV2(dep, packageSources, destZipPath, timeoutMs, authOptions = {}) {
-  const { name, version, profileHash, profile } = dep;
+async function tryV2Exact(dep, packageSources, destZipPath, timeoutMs, authOptions = {}) {
+  const { name, version, profileHash } = dep;
   const { awsProfile, token } = authOptions;
 
+  let indexFoundInSource = null;
+  let versionsIndex      = null;
+  let availableProfiles  = [];
+
   for (const source of packageSources) {
     let provider;
     try { provider = getProvider(source); } catch { continue; }
 
-    // 1) Exact profile hash
     const base = source.replace(/\/$/, '');
     const metaUrl = `${base}/v2/${name}/${version}/${profileHash}/wyvrn.json`;
-    console.log(`[wyvrn] Trying v2: ${metaUrl}`);
+    log.info(`Trying v2: ${metaUrl}`);
     const exactMeta = await provider.v2GetMeta({ source, name, version, profileHash, awsProfile, token });
     if (exactMeta) {
       const ok = await provider.v2DownloadZip({ source, name, version, profileHash, awsProfile, token }, destZipPath, timeoutMs);
       if (ok) {
         return {
-          found:         true,
-          contentSha256: exactMeta.contentSha256 ?? null,
-          gitSha:        exactMeta.gitSha        ?? null,
-          gitRepo:       exactMeta.gitRepo       ?? null,
-          profileHash,
-          source,
+          found:              true,
+          result: {
+            contentSha256: exactMeta.contentSha256 ?? null,
+            gitSha:        exactMeta.gitSha        ?? null,
+            gitRepo:       exactMeta.gitRepo       ?? null,
+            profileHash,
+            source,
+          },
+          indexFoundInSource: source,
+          availableProfiles:  [],
         };
       }
     } else {
-      console.log(`[wyvrn] v2 miss (no exact profile match): ${metaUrl}`);
+      log.info(`v2 miss (no exact profile match): ${metaUrl}`);
     }
 
-    // 2) Fallback: scan versions.json for a compatible build (same OS + arch)
-    const versionsUrl = `${base}/v2/${name}/versions.json`;
-    console.log(`[wyvrn] Trying v2 versions index: ${versionsUrl}`);
-    const idx = await provider.v2GetVersionsIndex({ source, name, awsProfile, token });
-    if (!idx?.versions?.[version]?.profiles) {
-      console.log(`[wyvrn] v2 miss (no versions index or no entry for ${version}): ${versionsUrl}`);
-      continue;
+    // No exact match from this source. Check whether v2 knows the package
+    // at all — keep the first non-null index we find (for error messages
+    // and potential compat fallback).
+    if (!versionsIndex) {
+      const idx = await provider.v2GetVersionsIndex({ source, name, awsProfile, token });
+      if (idx?.versions?.[version]?.profiles) {
+        versionsIndex      = idx;
+        indexFoundInSource = source;
+        availableProfiles  = Object.keys(idx.versions[version].profiles);
+      }
     }
+  }
 
-    const versionEntry = idx.versions[version];
-    for (const [ph, buildEntry] of Object.entries(versionEntry.profiles)) {
-      // buildSettings is the copy of the profile stored for debugging at publish time
-      const bp = buildEntry.buildSettings ?? buildEntry.profile;
-      if (!bp) continue;
-      if (bp.os !== profile.os) continue;
-      if (bp.arch !== profile.arch) continue;
-      // Same OS + arch — accept as a compatible fallback
-      console.warn(
-        `[wyvrn] No exact profile match for ${name}@${version}; using compatible build [${ph}]` +
-        ` (${bp.compiler} ${bp['compiler.version']})`,
-      );
-      const ok = await provider.v2DownloadZip({ source, name, version, profileHash: ph, awsProfile, token }, destZipPath, timeoutMs);
-      if (ok) {
-        return {
-          found:         true,
-          contentSha256: buildEntry.contentSha256 ?? null,
-          gitSha:        versionEntry.source?.gitSha  ?? null,
-          gitRepo:       versionEntry.source?.gitRepo ?? null,
-          profileHash:   ph,
-          source,
-        };
-      }
+  return { found: false, indexFoundInSource, availableProfiles, versionsIndex };
+}
+
+/**
+ * Declarative per-package compatibility resolver (PLAN-BUILD-MISSING phase 2).
+ *
+ * When no exact profileHash match exists but the v2 registry knows the
+ * package, we evaluate each registry-side build's `compatibility` block
+ * (from the build's `wyvrn.json`) against the consumer's profile. If any
+ * candidates are compatible, the tiebreaker picks one.
+ *
+ * Cost: O(n) HTTP round-trips (one `v2GetMeta` per build) — acceptable at
+ * phase 2; phase 2.1 could fold the compat block into `versions.json` to
+ * make this O(1).
+ *
+ * @param {object}   args
+ * @param {string}   args.name
+ * @param {string}   args.version
+ * @param {import('./profile').WyvrnProfile} args.consumerProfile
+ * @param {object}   args.versionsIndex          pre-fetched from tryV2Exact
+ * @param {string}   args.source                 source URL that returned the index
+ * @param {object}   args.authOptions
+ * @returns {Promise<{
+ *   profileHash:   string,
+ *   contentSha256: string|null,
+ *   gitSha:        string|null,
+ *   gitRepo:       string|null,
+ *   source:        string,
+ *   reasons:       Array<object>,
+ *   meta:          object,
+ * }|null>}
+ */
+async function findCompatibleBuild({ name, version, consumerProfile, consumerOptions, versionsIndex, source, authOptions = {} }) {
+  const { awsProfile, token } = authOptions;
+  let provider;
+  try { provider = getProvider(source); } catch { return null; }
+
+  const versionEntry = versionsIndex?.versions?.[version];
+  if (!versionEntry?.profiles) return null;
+
+  // Consumer side includes options so the compat evaluator can see them.
+  const consumerFull = consumerOptions
+    ? { ...consumerProfile, options: consumerOptions }
+    : consumerProfile;
+
+  const candidates = [];
+  for (const [profileHash, buildEntry] of Object.entries(versionEntry.profiles)) {
+    const packageProfile = buildEntry.buildSettings ?? buildEntry.profile;
+    if (!packageProfile) continue;
+
+    // Compatibility block lives on the per-build wyvrn.json. Fetch it.
+    const meta = await provider.v2GetMeta({ source, name, version, profileHash, awsProfile, token });
+    if (!meta) continue;
+
+    // Package-side options may live on the nested buildSettings.options (new
+    // publish path) or as a sibling key when publish-time metadata diverges.
+    const packageFull = packageProfile.options
+      ? packageProfile
+      : (meta.buildSettings?.options
+         ? { ...packageProfile, options: meta.buildSettings.options }
+         : packageProfile);
+
+    const rawCompat = meta.compatibility ?? null;
+    const { compatible, reasons } = evaluateCompat(consumerFull, packageFull, rawCompat);
+    if (compatible) {
+      candidates.push({ profileHash, packageProfile, reasons, buildEntry, meta });
     }
   }
 
+  const best = pickBestCandidate(candidates, consumerProfile);
+  if (!best) return null;
+
+  return {
+    profileHash:   best.profileHash,
+    contentSha256: best.buildEntry.contentSha256         ?? best.meta.contentSha256 ?? null,
+    gitSha:        versionEntry.source?.gitSha            ?? best.meta.gitSha       ?? null,
+    gitRepo:       versionEntry.source?.gitRepo           ?? best.meta.gitRepo      ?? null,
+    source,
+    reasons:       best.reasons,
+    meta:          best.meta,
+  };
+}
+
+/**
+ * LEGACY compat fallback — scan versions.json for a build with the same OS +
+ * arch as the consumer's profile and use it. Reachable only via
+ * WYVRNPM_ALLOW_LOOSE_COMPAT=1. Prints a deprecation warning whenever it
+ * succeeds. Will be removed after one release cycle.
+ *
+ * @param {{ name: string, version: string, profile: import('./profile').WyvrnProfile }} dep
+ * @param {object} versionsIndex     pre-fetched from tryV2Exact
+ * @param {string} source            source URL that returned the index
+ * @param {string} destZipPath
+ * @param {number} timeoutMs
+ * @param {object} authOptions
+ * @returns {Promise<object|null>}   same shape as tryV2Exact.result, or null
+ */
+async function tryV2Compat(dep, versionsIndex, source, destZipPath, timeoutMs, authOptions = {}) {
+  const { name, version, profile } = dep;
+  const { awsProfile, token } = authOptions;
+
+  let provider;
+  try { provider = getProvider(source); } catch { return null; }
+
+  const versionEntry = versionsIndex?.versions?.[version];
+  if (!versionEntry?.profiles) return null;
+
+  for (const [ph, buildEntry] of Object.entries(versionEntry.profiles)) {
+    const bp = buildEntry.buildSettings ?? buildEntry.profile;
+    if (!bp) continue;
+    if (bp.os   !== profile.os)   continue;
+    if (bp.arch !== profile.arch) continue;
+
+    log.warn(
+      `⚠  DEPRECATED loose-compat fallback (WYVRNPM_ALLOW_LOOSE_COMPAT=1):\n` +
+      `  ${name}@${version} — using build [${ph}] (${bp.compiler} ${bp['compiler.version']})\n` +
+      `  cppstd/runtime may differ from your profile. This fallback will be removed in the next release.`,
+    );
+    const ok = await provider.v2DownloadZip({ source, name, version, profileHash: ph, awsProfile, token }, destZipPath, timeoutMs);
+    if (ok) {
+      return {
+        contentSha256: buildEntry.contentSha256   ?? null,
+        gitSha:        versionEntry.source?.gitSha  ?? null,
+        gitRepo:       versionEntry.source?.gitRepo ?? null,
+        profileHash:   ph,
+        source,
+      };
+    }
+  }
   return null;
 }
 
+/**
+ * Build the structured error message shown when a package exists in the v2
+ * registry but no build matches the consumer's profileHash.
+ */
+function buildStrictMissMessage({ name, version, profileHash, availableProfiles, buildMode, loose }) {
+  const lines = [
+    `no v2 build of ${name}@${version} matches profile [${profileHash}]`,
+    availableProfiles.length > 0
+      ? `  Available builds on the registry: ${availableProfiles.map((p) => `[${p}]`).join(' ')}`
+      : `  The registry lists no builds for this version.`,
+  ];
+  if (buildMode === 'missing') {
+    lines.push(
+      `  --build=missing source-build was attempted but did not produce a usable binary. ` +
+      `See the error above for details (missing git metadata, missing "build" section in source manifest, or compile failure).`,
+    );
+  } else {
+    lines.push(
+      `  Fix: publish a build for your profile, switch to a compatible one, or rerun with --build=missing to source-build.`,
+    );
+  }
+  if (!loose) {
+    lines.push(
+      `  Escape hatch: WYVRNPM_ALLOW_LOOSE_COMPAT=1 (deprecated — accepts same OS+arch with possibly-different cppstd/runtime).`,
+    );
+  }
+  return lines.join('\n');
+}
+
 // ---------------------------------------------------------------------------
 // Extraction helper
 // ---------------------------------------------------------------------------
@@ -163,7 +323,21 @@ async function extractZip(destZipPath, extractDir) {
 
 /**
  * Downloads and extracts all resolved dependencies.
- * Tries v2 first (profile-aware + SHA256 verification), falls back to v1.
+ *
+ * Resolution order (v2 path, i.e. enriched deps with a profileHash):
+ *   1. Exact profile-hash match from any configured v2 source → use it.
+ *   2. Otherwise, if the package exists in v2 (versions.json returned an
+ *      entry for this version) but nothing matches our profile:
+ *        - Default: STRICT FAIL with a structured error. Does not fall back
+ *          to v1 (that would silently accept a build with different settings).
+ *        - `buildMode === 'missing'`: same strict fail for now; error hints
+ *          at PLAN-BUILD-MISSING phase 3.
+ *        - WYVRNPM_ALLOW_LOOSE_COMPAT=1 (deprecated escape hatch): try the
+ *          old OS+arch compat fallback with a deprecation warning.
+ *   3. Otherwise (v2 doesn't know the package at all) → v1 legacy fallback.
+ *
+ * Legacy deps (plain `Map<name, version>`, no profile info) skip v2 entirely
+ * and use the v1 path, same as before.
  *
  * @param {Map<string, string | {version:string, profileHash:string|null, profile:import('./profile').WyvrnProfile|null}>} deps
  *   Either a plain `Map<name, version>` (legacy callers / tests) or the enriched map
@@ -173,12 +347,29 @@ async function extractZip(destZipPath, extractDir) {
  * @param {string}    razerDir
  * @param {Function}  httpClient      - fetch-compatible
  * @param {number}    timeout         - seconds
- * @param {object}    [authOptions]   - { awsProfile?, token? }
+ * @param {object}    [options]       - { awsProfile?, token?, buildMode? }
+ *                                       buildMode: 'never' (default) | 'missing' | 'always'
  * @returns {Promise<Map<string, {version:string, profileHash?:string, contentSha256?:string, gitSha?:string, resolvedFrom:string}>>}
  */
-async function downloadDependencies(deps, packageSources, platform, razerDir, httpClient, timeout, authOptions = {}) {
+async function downloadDependencies(deps, packageSources, platform, razerDir, httpClient, timeout, options = {}) {
   const timeoutMs = timeout * 1000;
-  const { awsProfile, token } = authOptions;
+  const {
+    awsProfile, token, buildMode = 'never', profileName = 'default',
+    uploadBuilt = false, uploadSource, uploadAuth,
+    // Optional accumulator. When provided, upload outcomes are pushed here
+    // so the caller can print a single aggregated summary at the end of an
+    // install (see src/commands/install.js). Mutated in place.
+    uploadStats,
+  } = options;
+
+  if (buildMode === 'always') {
+    throw new Error(
+      '--build=always is not implemented (requires PLAN-BUILD-MISSING phase 3). ' +
+      'Use --build=never (default) or --build=missing.',
+    );
+  }
+
+  const looseCompatAllowed = process.env.WYVRNPM_ALLOW_LOOSE_COMPAT === '1';
 
   if (!fs.existsSync(razerDir)) {
     fs.mkdirSync(razerDir, { recursive: true });
@@ -193,6 +384,7 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
     const version     = isLegacyEntry ? depInfoOrVersion : depInfoOrVersion.version;
     const profileHash = isLegacyEntry ? null : (depInfoOrVersion.profileHash ?? null);
     const profile     = isLegacyEntry ? null : (depInfoOrVersion.profile     ?? null);
+    const options     = isLegacyEntry ? null : (depInfoOrVersion.options     ?? null);
 
     const extractDir  = path.join(razerDir, name);
     const versionFile = path.join(extractDir, '.wyvrn-version');
@@ -201,7 +393,7 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
     // Skip linked packages
     if (isLink(extractDir)) {
       const linkTarget = getLinkTarget(extractDir);
-      console.log(`[wyvrn] Linked: ${name} → ${linkTarget} (skipping download)`);
+      log.info(`Linked: ${name} → ${linkTarget} (skipping download)`);
       lockEntries.set(name, { version, resolvedFrom: 'link' });
       continue;
     }
@@ -219,47 +411,166 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
       const sameProfile = !profileHash || installedMeta?.profileHash === profileHash;
 
       if (sameVersion && sameProfile) {
-        console.log(`[wyvrn] Already present: ${name}@${version}${profileHash ? ` [${installedMeta?.profileHash}]` : ''} — skipping`);
+        log.info(`Already present: ${name}@${version}${profileHash ? ` [${installedMeta?.profileHash}]` : ''} — skipping`);
         lockEntries.set(name, {
           version,
           profileHash:   installedMeta?.profileHash   ?? null,
           contentSha256: installedMeta?.contentSha256 ?? null,
           gitSha:        installedMeta?.gitSha        ?? null,
           resolvedFrom:  installedMeta?.resolvedFrom  ?? 'cached',
+          ...(options ? { options } : {}),
         });
         continue;
       }
       if (!sameVersion) {
-        console.log(`[wyvrn] Version changed: ${name} ${installedVersion} → ${version}, re-downloading`);
+        log.info(`Version changed: ${name} ${installedVersion} → ${version}, re-downloading`);
       } else {
-        console.log(`[wyvrn] Profile changed for ${name}@${version}, re-downloading`);
+        log.info(`Profile changed for ${name}@${version}, re-downloading`);
       }
       fs.rmSync(extractDir, { recursive: true, force: true });
     }
 
-    console.log(`[wyvrn] Downloading: ${name}@${version}`);
+    log.info(`Downloading: ${name}@${version}`);
     const destZipPath = path.join(razerDir, `${name}.zip`);
 
     let downloadResult = null;
     let resolvedFrom   = 'v1';
+    let skipV1Fallback = false;
 
-    // ── Try v2 first ────────────────────────────────────────────────────────
+    // ── Try v2 exact ────────────────────────────────────────────────────────
     if (profileHash && profile) {
-      downloadResult = await tryDownloadV2(
-        { name, version, profileHash, profile },
+      const v2 = await tryV2Exact(
+        { name, version, profileHash },
         packageSources,
         destZipPath,
         timeoutMs,
         { awsProfile, token },
       );
-      if (downloadResult) resolvedFrom = 'v2';
+
+      if (v2.found) {
+        downloadResult = v2.result;
+        resolvedFrom   = 'v2';
+      } else if (v2.indexFoundInSource) {
+        // v2 knows this package but no exact profile match. Do NOT fall back
+        // to v1 — that would silently accept a binary with different build
+        // settings. Try declarative compatibility first (phase 2), then the
+        // deprecated env-var escape hatch, then fail strictly.
+        skipV1Fallback = true;
+
+        // ── Phase 2: declarative per-package compatibility ─────────────────
+        const compatResult = await findCompatibleBuild({
+          name, version,
+          consumerProfile:  profile,
+          consumerOptions:  options,
+          versionsIndex:    v2.versionsIndex,
+          source:           v2.indexFoundInSource,
+          authOptions:      { awsProfile, token },
+        });
+        if (compatResult) {
+          // Download the chosen compatible build's zip.
+          const compatProvider = getProvider(compatResult.source);
+          const ok = await compatProvider.v2DownloadZip(
+            { source: compatResult.source, name, version, profileHash: compatResult.profileHash, awsProfile, token },
+            destZipPath,
+            timeoutMs,
+          );
+          if (ok) {
+            log.info(
+              `Compatibility match for ${name}@${version}: [${compatResult.profileHash}] — ` +
+              `${summarizeReasons(compatResult.reasons)}`,
+            );
+            downloadResult = {
+              contentSha256: compatResult.contentSha256,
+              gitSha:        compatResult.gitSha,
+              gitRepo:       compatResult.gitRepo,
+              profileHash:   compatResult.profileHash,
+              source:        compatResult.source,
+            };
+            resolvedFrom = 'v2-compat';
+          }
+        }
+
+        // ── Phase 3: source-build when `--build=missing` is active ─────────
+        if (!downloadResult && buildMode === 'missing') {
+          const sourceInfo = v2.versionsIndex?.versions?.[version]?.source;
+          if (sourceInfo?.gitRepo && sourceInfo?.gitSha) {
+            try {
+              const built = await buildFromSource({
+                name, version,
+                profile, profileName, profileHash,
+                options,
+                gitRepo:        sourceInfo.gitRepo,
+                gitSha:         sourceInfo.gitSha,
+                destZipPath,
+                packageSources,
+                platform,
+                timeoutMs,
+                buildMode,
+                authOptions:    { awsProfile, token },
+              });
+              downloadResult = {
+                contentSha256: built.contentSha256,
+                gitSha:        built.gitSha,
+                gitRepo:       built.gitRepo,
+                profileHash:   built.profileHash,
+                source:        built.source,
+                // Carried through so the post-extraction upload step can
+                // read the manifest and push the zip without re-doing work.
+                artefactPath:       built.artefactPath,
+                clonedManifestPath: built.clonedManifestPath,
+              };
+              resolvedFrom = 'v2-source-build';
+            } catch (err) {
+              log.error(`Source-build failed for ${name}@${version}: ${err.message}`);
+            }
+          } else {
+            log.error(
+              `Cannot source-build ${name}@${version}: no git metadata on registry ` +
+              `(gitRepo/gitSha). Publisher must re-publish with git info.`,
+            );
+          }
+        }
+
+        // ── Deprecated escape hatch: WYVRNPM_ALLOW_LOOSE_COMPAT=1 ──────────
+        if (!downloadResult && looseCompatAllowed) {
+          const compat = await tryV2Compat(
+            { name, version, profile },
+            v2.versionsIndex,
+            v2.indexFoundInSource,
+            destZipPath,
+            timeoutMs,
+            { awsProfile, token },
+          );
+          if (compat) {
+            downloadResult = compat;
+            resolvedFrom   = 'v2-compat-deprecated';
+          }
+        }
+
+        if (!downloadResult) {
+          log.error(buildStrictMissMessage({
+            name, version, profileHash,
+            availableProfiles: v2.availableProfiles,
+            buildMode,
+            loose: looseCompatAllowed,
+          }));
+          lockEntries.set(name, {
+            version,
+            profileHash,
+            resolvedFrom: buildMode === 'missing' ? 'source-build-failed' : 'no-exact-match',
+            availableProfiles: v2.availableProfiles,
+          });
+          continue;
+        }
+      }
+      // else: no v2 index anywhere → fall through to v1
     }
 
     // ── Fall back to v1 ─────────────────────────────────────────────────────
-    if (!downloadResult) {
+    if (!downloadResult && !skipV1Fallback) {
       const ok = await tryDownloadFromSources(name, version, packageSources, platform, httpClient, timeoutMs, destZipPath);
       if (!ok) {
-        console.warn(`[wyvrn] Warning: package ${name}@${version} was not found in any configured source`);
+        log.warn(`package ${name}@${version} was not found in any configured source`);
         lockEntries.set(name, { version, resolvedFrom: 'not-found' });
         continue;
       }
@@ -269,8 +580,8 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
     if (downloadResult?.contentSha256) {
       const actual = sha256Of(destZipPath);
       if (actual !== downloadResult.contentSha256) {
-        console.error(
-          `[wyvrn] Error: SHA256 mismatch for ${name}@${version}\n` +
+        log.error(
+          `SHA256 mismatch for ${name}@${version}\n` +
           `  expected: ${downloadResult.contentSha256}\n` +
           `  actual:   ${actual}`,
         );
@@ -278,7 +589,7 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
         lockEntries.set(name, { version, resolvedFrom: 'sha256-mismatch' });
         continue;
       }
-      console.log(`[wyvrn] SHA256 verified: ${actual.slice(0, 16)}...`);
+      log.info(`SHA256 verified: ${actual.slice(0, 16)}...`);
     }
 
     // ── Extract ─────────────────────────────────────────────────────────────
@@ -301,16 +612,16 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
       };
       fs.writeFileSync(metaFile, JSON.stringify(meta, null, 2) + '\n', 'utf8');
 
-      console.log(
-        `[wyvrn] Extracted: ${name}@${version}` +
+      log.info(
+        `Extracted: ${name}@${version}` +
         (downloadResult?.profileHash ? ` [${downloadResult.profileHash}]` : '') +
         ` (${resolvedFrom}) → ${extractDir}`,
       );
 
       if (downloadResult?.gitSha) {
-        console.log(`[wyvrn]   Source commit : ${downloadResult.gitSha}`);
+        log.info(`  Source commit : ${downloadResult.gitSha}`);
         if (downloadResult?.gitRepo) {
-          console.log(`[wyvrn]   Source repo   : ${downloadResult.gitRepo}`);
+          log.info(`  Source repo   : ${downloadResult.gitRepo}`);
         }
       }
 
@@ -320,9 +631,42 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
         profileHash:   downloadResult?.profileHash   ?? null,
         contentSha256: downloadResult?.contentSha256 ?? null,
         gitSha:        downloadResult?.gitSha        ?? null,
+        ...(options ? { options } : {}),
       });
+
+      // ── Upload freshly source-built artefact back to the registry ────────
+      // Opt-in via --upload-built. Runs after extraction succeeds so a
+      // bad artefact is never uploaded. Upload failures log but never
+      // break the install — the consumer already has a working install.
+      if (uploadBuilt && resolvedFrom === 'v2-source-build' && downloadResult?.artefactPath) {
+        try {
+          const outcome = await uploadSourceBuiltArtefact({
+            name, version,
+            profile, profileHash,
+            artefactPath:       downloadResult.artefactPath,
+            clonedManifestPath: downloadResult.clonedManifestPath,
+            contentSha256:      downloadResult.contentSha256,
+            gitRepo:            downloadResult.gitRepo,
+            gitSha:             downloadResult.gitSha,
+            options,
+            uploadSource,
+            uploadAuth:         uploadAuth ?? { awsProfile, token },
+          });
+          if (uploadStats) {
+            const bucket = outcome.uploaded
+              ? 'uploaded'
+              : /already exists/.test(outcome.reason) ? 'skipped' : 'failed';
+            uploadStats[bucket].push({ name, version, profileHash, reason: outcome.reason });
+          }
+        } catch (err) {
+          log.warn(`upload-built: ${name}@${version} upload skipped — ${err.message}`);
+          if (uploadStats) {
+            uploadStats.failed.push({ name, version, profileHash, reason: err.message });
+          }
+        }
+      }
     } catch (err) {
-      console.warn(`[wyvrn] Failed to extract ${name}@${version}: ${err.message}`);
+      log.warn(`Failed to extract ${name}@${version}: ${err.message}`);
       lockEntries.set(name, { version, resolvedFrom: 'extract-failed' });
     } finally {
       try { fs.unlinkSync(destZipPath); } catch { /* ignore */ }