wyvrnpm 2.4.1 → 2.9.0

package/src/commands/publish.js

@@ -1,383 +1,435 @@
-'use strict';
-
-const fs   = require('fs');
-const path = require('path');
-const os   = require('os');
-const AdmZip = require('adm-zip');
-
-const { readManifest }                                     = require('../manifest');
-const { getProvider }                                      = require('../providers');
-const { readConfig }                                       = require('../config');
-const { loadProfile, hashProfile, sha256Of, getGitSha, getGitRepo, isShaOnRemote } = require('../profile');
-const { defaultCompatBlock }                               = require('../compat');
-const {
-  normalizeOptionsDeclaration,
-  resolveEffectiveOptions,
-  parseCliOptions,
-}                                                          = require('../options');
-const { loadIgnorePatterns, isIgnored }                    = require('../ignore');
-const { hasBuildRecipe, normalizeRecipe }                  = require('../build/recipe');
-const log                                                  = require('../logger');
-
-/**
- * Walk `dir` recursively and add every file to `zip`, skipping anything that
- * matches `.wyvrnignore` patterns OR whose zip-relative path is already in
- * `reservedRelPaths`. The reserved set lets the install-tree overlay win
- * on path collisions (e.g. `include/foo.h` shipped by both source and
- * install trees).
- */
-function addFolderFiltered(zip, dir, base, patterns, reservedRelPaths = new Set()) {
-  for (const entry of fs.readdirSync(dir)) {
-    const fullPath = path.join(dir, entry);
-    const relPath  = path.relative(base, fullPath).replace(/\\/g, '/');
-    const stat     = fs.statSync(fullPath);
-    const isDir    = stat.isDirectory();
-    if (isIgnored(relPath, isDir, patterns)) {
-      log.info(`  Ignoring: ${relPath}${isDir ? '/' : ''}`);
-      continue;
-    }
-    if (isDir) {
-      addFolderFiltered(zip, fullPath, base, patterns, reservedRelPaths);
-    } else if (reservedRelPaths.has(relPath)) {
-      // Install tree has a canonical version of this file; let that win.
-      log.info(`  Install-tree wins: ${relPath}`);
-    } else {
-      const zipDir = path.dirname(relPath).replace(/\\/g, '/');
-      zip.addLocalFile(fullPath, zipDir === '.' ? '' : zipDir);
-    }
-  }
-}
-
-/**
- * Collect every file under `dir` as a `{ fullPath, relPath }` pair. `relPath`
- * is forward-slash-separated and relative to `dir` — so the install tree's
- * `install/cmake/FooConfig.cmake` lands as `cmake/FooConfig.cmake` at the
- * zip root, which is where `find_package(Foo CONFIG)` expects it on the
- * consumer side after extraction into `wyvrn_internal/<name>/`.
- */
-function collectInstallTreeFiles(dir) {
-  const files = [];
-  function walk(current) {
-    for (const entry of fs.readdirSync(current)) {
-      const full = path.join(current, entry);
-      const stat = fs.statSync(full);
-      if (stat.isDirectory()) {
-        walk(full);
-      } else {
-        const rel = path.relative(dir, full).replace(/\\/g, '/');
-        files.push({ fullPath: full, relPath: rel });
-      }
-    }
-  }
-  walk(dir);
-  return files;
-}
-
-function addInstallTree(zip, installDir) {
-  const files = collectInstallTreeFiles(installDir);
-  const added = new Set();
-  for (const { fullPath, relPath } of files) {
-    const zipDir = path.dirname(relPath).replace(/\\/g, '/');
-    zip.addLocalFile(fullPath, zipDir === '.' ? '' : zipDir);
-    added.add(relPath);
-  }
-  return added;
-}
-
-// ---------------------------------------------------------------------------
-// Source resolution
-// ---------------------------------------------------------------------------
-
-function resolveSource(argv) {
-  let { source, awsProfile, token } = argv;
-  const config = readConfig();
-
-  if (source) {
-    const named = config.publishSources.find((s) => s.name === source);
-    if (named) {
-      log.info(`Using publish source "${named.name}" from config`);
-      source     = named.url;
-      awsProfile = awsProfile ?? named.profile;
-      token      = token      ?? named.token;
-    }
-  } else {
-    if (config.publishSources.length === 0) {
-      log.error(
-        '--source is required (or configure one with: ' +
-          'wyvrnpm configure add-source --kind publish ...)',
-      );
-      process.exit(1);
-    }
-    const first = config.publishSources[0];
-    log.info(`Using publish source "${first.name}" from config`);
-    source     = first.url;
-    awsProfile = awsProfile ?? first.profile;
-    token      = token      ?? first.token;
-  }
-
-  return { source, awsProfile, token };
-}
-
-// ---------------------------------------------------------------------------
-// Main publish command
-// ---------------------------------------------------------------------------
-
-async function publish(argv) {
-  const { source, awsProfile, token } = resolveSource(argv);
-  const {
-    profile: profileName,
-    path: publishPath,
-    force,
-    manifest: manifestArg,
-  } = argv;
-  const jsonOut = argv.format === 'json';
-  if (jsonOut) log.setJsonMode(true);
-
-  // ── Load manifest ─────────────────────────────────────────────────────────
-  const manifestPath = path.resolve(manifestArg || './wyvrn.json');
-  const manifest = await readManifest(manifestPath);
-  if (!manifest) {
-    log.error(`Could not read manifest at ${manifestPath}`);
-    process.exit(1);
-  }
-
-  const { name, version } = manifest;
-  if (!name || !version) {
-    log.error('Manifest must have "name" and "version" fields');
-    process.exit(1);
-  }
-
-  const srcDir = path.resolve(publishPath || '.');
-  if (!fs.existsSync(srcDir)) {
-    log.error(`Publish path does not exist: ${srcDir}`);
-    process.exit(1);
-  }
-
-  // ── Resolve provider ──────────────────────────────────────────────────────
-  let provider;
-  try {
-    provider = getProvider(source);
-  } catch (err) {
-    log.error(err.message);
-    process.exit(1);
-  }
-
-  // ── Load build profile ────────────────────────────────────────────────────
-  const config = readConfig();
-  const activeProfileName = profileName ?? config.defaultProfile ?? 'default';
-  const { profile: buildProfile, fromFile } = loadProfile(activeProfileName);
-
-  // ── Resolve this package's own declared options ─────────────────────────
-  // Publishing needs to commit to a specific value for every option the
-  // recipe declares. Sources for overrides: CLI `-o <pkg>:...` flags
-  // (scoped to the package being published), else the recipe's defaults.
-  const ownDeclaration = manifest.options
-    ? normalizeOptionsDeclaration(manifest.options, `${name}@${version}`)
-    : null;
-  const cliOptionsByPkg = parseCliOptions(argv.option);
-  const effectiveOptions = resolveEffectiveOptions(
-    ownDeclaration,
-    {},                               // consumer-side overrides don't apply to self-publish
-    cliOptionsByPkg[name] ?? {},
-    `${name}@${version}`,
-  );
-
-  const profileHash = hashProfile(buildProfile, effectiveOptions);
-
-  log.info(
-    `Publishing ${name}@${version}\n` +
-    `Profile     : "${activeProfileName}"${fromFile ? '' : ' (auto-detected — save with `wyvrnpm configure profile detect`)'}\n` +
-    `  ${buildProfile.os}/${buildProfile.arch}  ` +
-    `${buildProfile.compiler} ${buildProfile['compiler.version']}  ` +
-    `C++${buildProfile['compiler.cppstd']}` +
-    (buildProfile['compiler.runtime'] ? `  [${buildProfile['compiler.runtime']}]` : '') + '\n' +
-    (effectiveOptions ? `Options     : ${JSON.stringify(effectiveOptions)}\n` : '') +
-    `Profile hash: ${profileHash}\n` +
-    `Provider    : ${provider.constructor.providerName}`,
-  );
-
-  // ── Check v2 existence ────────────────────────────────────────────────────
-  const v2AlreadyExists = await provider.v2Exists({ source, name, version, profileHash, awsProfile, token });
-  if (v2AlreadyExists) {
-    if (force) {
-      log.warn(`${name}@${version} [${profileHash}] already exists — overwriting (--force)`);
-    } else {
-      log.error(
-        `${name}@${version} [${profileHash}] already exists.\n` +
-          '  Bump the version, use a different profile, or pass --force to overwrite.',
-      );
-      process.exit(1);
-    }
-  }
-
-  // ── Read locked dependency versions from wyvrn.lock ──────────────────────
-  const lockPath = path.join(path.dirname(manifestPath), 'wyvrn.lock');
-  const lockedDependencies = {};
-  if (fs.existsSync(lockPath)) {
-    try {
-      const lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
-      for (const [pkgName, entry] of Object.entries(lock.packages ?? {})) {
-        const ver = typeof entry === 'string' ? entry : entry.version;
-        if (ver) lockedDependencies[pkgName] = ver;
-      }
-      log.info(`Lock file  : ${Object.keys(lockedDependencies).length} pinned package(s)`);
-    } catch {
-      log.warn('could not read wyvrn.lock — dependency versions will be published as-is from wyvrn.json');
-    }
-  } else {
-    log.warn('no wyvrn.lock found — run `wyvrnpm install` before publishing to pin dependency versions');
-  }
-
-  // ── Git metadata ──────────────────────────────────────────────────────────
-  const gitSha  = getGitSha(srcDir);
-  const gitRepo = getGitRepo(srcDir);
-  if (gitSha)  log.info(`Git commit : ${gitSha}`);
-  if (gitRepo) log.info(`Git remote : ${gitRepo}`);
-
-  // Warn (but don't block) if HEAD isn't reachable from origin. Downstream
-  // `--build=missing` consumers will fail to fetch this commit — the fix
-  // is almost always `git push` before publishing.
-  if (gitSha && gitRepo && !isShaOnRemote(gitSha, srcDir)) {
-    log.warn(
-      `commit ${gitSha.slice(0, 12)} is not reachable from any remote ` +
-      `branch or tag on origin.\n` +
-      `  Consumers building this package from source will fail to retrieve it.\n` +
-      `  Fix: push your branch (or tag the commit) before publishing.`,
-    );
-  }
-
-  // ── .wyvrnignore ──────────────────────────────────────────────────────────
-  const ignoreFile = path.join(srcDir, '.wyvrnignore');
-  const ignorePatterns = loadIgnorePatterns(ignoreFile);
-  if (ignorePatterns.length > 0) {
-    log.info(`Loaded ${ignorePatterns.length} pattern(s) from .wyvrnignore`);
-  }
-
-  // ── Build zip ─────────────────────────────────────────────────────────────
-  const tmpZipPath = path.join(os.tmpdir(), `wyvrnpm-${name}-${version}-${Date.now()}.zip`);
-
-  // ── Inject default `compatibility` block if the source manifest lacks one ──
-  // Written to a temp file so the source wyvrn.json is never modified.
-  // A published manifest must always carry a compat block so install-time
-  // resolution has something to evaluate (default = all fields `exact`,
-  // identical semantics to pre-phase-2 strict behaviour).
-  const tmpManifestPath = path.join(
-    os.tmpdir(),
-    `wyvrnpm-manifest-${name}-${version}-${Date.now()}.json`,
-  );
-  const manifestForPublish = {
-    ...manifest,
-    compatibility: manifest.compatibility ?? defaultCompatBlock(),
-  };
-  fs.writeFileSync(tmpManifestPath, JSON.stringify(manifestForPublish, null, 2), 'utf8');
-  if (!manifest.compatibility) {
-    log.info('Injecting default `compatibility` block (all fields `exact`) — override by adding one to wyvrn.json');
-  } else {
-    log.info(`Using package-declared compatibility: ${JSON.stringify(manifest.compatibility)}`);
-  }
-
-  // ── Install-tree overlay ──────────────────────────────────────────────────
-  // Publish zips the source tree (filtered by .wyvrnignore), but consumers
-  // actually need the install tree — `lib/cmake/<Name>/<Name>Config.cmake`,
-  // the installed headers, compiled libs — so find_package() works after
-  // extraction. When a build recipe is declared, locate the per-profile
-  // install dir (populated by `wyvrnpm build --config <cfg> --install`) and
-  // overlay its contents on top of the source zip. Install-tree files win
-  // on path collisions (e.g. `include/`).
-  let installOverlayDir = null;
-  let installOverlayPaths = new Set();
-  if (hasBuildRecipe(manifest)) {
-    try {
-      const recipe = normalizeRecipe(manifest.build, effectiveOptions);
-      const candidate = path.join(
-        srcDir, 'build', `wyvrn-${activeProfileName}`, recipe.installDir,
-      );
-      if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
-        installOverlayDir = candidate;
-      } else {
-        log.warn(
-          `build recipe is declared but no install tree found at ${candidate}.\n` +
-          '  Consumers\' find_package() will likely fail. Fix: run\n' +
-          '    wyvrnpm build --config Debug --install\n' +
-          '    wyvrnpm build --config Release --install\n' +
-          '    wyvrnpm build --config RelWithDebInfo --install\n' +
-          '    wyvrnpm build --config MinSizeRel --install\n' +
-          '  then re-run publish.',
-        );
-      }
-    } catch (err) {
-      log.warn(`could not locate install tree: ${err.message} — publishing source tree only`);
-    }
-  }
-
-  try {
-    log.info(`Zipping ${srcDir} ...`);
-    const zip = new AdmZip();
-    if (installOverlayDir) {
-      // Collect install-tree paths first so the source-tree walker can skip
-      // anything the install tree will add canonically.
-      const peek = collectInstallTreeFiles(installOverlayDir);
-      installOverlayPaths = new Set(peek.map((f) => f.relPath));
-    }
-    addFolderFiltered(zip, srcDir, srcDir, ignorePatterns, installOverlayPaths);
-    if (installOverlayDir) {
-      log.info(`Overlaying install tree: ${installOverlayDir}`);
-      const added = addInstallTree(zip, installOverlayDir);
-      log.info(`  Added ${added.size} file(s) from install tree`);
-    }
-    zip.writeZip(tmpZipPath);
-
-    const contentSha256 = sha256Of(tmpZipPath);
-    log.info(`Content SHA256 : ${contentSha256}`);
-
-    // ── v2 publish ────────────────────────────────────────────────────────
-    log.info('Publishing (v2) ...');
-    await provider.v2Publish(
-      { manifest: tmpManifestPath, zip: tmpZipPath },
-      {
-        source,
-        name,
-        version,
-        profileHash,
-        // buildSettings stored in metadata for debugging — NOT wyvrn.json
-        buildSettings: effectiveOptions
-          ? { ...buildProfile, options: effectiveOptions }
-          : buildProfile,
-        contentSha256,
-        gitSha,
-        gitRepo,
-        lockedDependencies,
-        awsProfile,
-        token,
-      },
-    );
-
-    log.success(`Successfully published ${name}@${version} [${profileHash}] to ${source}`);
-
-    if (jsonOut) {
-      const payload = {
-        command:        'publish',
-        wyvrnpmVersion: require('../../package.json').version,
-        name,
-        version,
-        profileHash,
-        source,
-        contentSha256,
-        options:        effectiveOptions ?? null,
-        gitSha:         gitSha  ?? null,
-        gitRepo:        gitRepo ?? null,
-        publishedAt:    new Date().toISOString(),
-      };
-      process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
-    }
-  } finally {
-    if (fs.existsSync(tmpZipPath))      fs.unlinkSync(tmpZipPath);
-    if (fs.existsSync(tmpManifestPath)) fs.unlinkSync(tmpManifestPath);
-  }
-}
-
-module.exports = publish;
-// Exported for tests only
-module.exports.addFolderFiltered       = addFolderFiltered;
-module.exports.addInstallTree          = addInstallTree;
-module.exports.collectInstallTreeFiles = collectInstallTreeFiles;
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+const AdmZip = require('adm-zip');
+
+const { getProvider }                                      = require('../providers');
+const {
+  readRecipeConf,
+  mergeConfLayers,
+  unflattenConf,
+}                                                          = require('../conf');
+const { hashProfile, sha256Of, getGitSha, getGitRepo, isShaOnRemote } = require('../profile');
+const { defaultCompatBlock }                               = require('../compat');
+const { buildContext }                                     = require('../context');
+const {
+  normalizeOptionsDeclaration,
+  resolveEffectiveOptions,
+}                                                          = require('../options');
+const { loadIgnorePatterns, isIgnored }                    = require('../ignore');
+const { hasBuildRecipe, normalizeRecipe }                  = require('../build/recipe');
+const log                                                  = require('../logger');
+
+/**
+ * Walk `dir` recursively and add every file to `zip`, skipping anything that
+ * matches `.wyvrnignore` patterns OR whose zip-relative path is already in
+ * `reservedRelPaths`. The reserved set lets the install-tree overlay win
+ * on path collisions (e.g. `include/foo.h` shipped by both source and
+ * install trees).
+ */
+function addFolderFiltered(zip, dir, base, patterns, reservedRelPaths = new Set()) {
+  for (const entry of fs.readdirSync(dir)) {
+    const fullPath = path.join(dir, entry);
+    const relPath  = path.relative(base, fullPath).replace(/\\/g, '/');
+    const stat     = fs.statSync(fullPath);
+    const isDir    = stat.isDirectory();
+    if (isIgnored(relPath, isDir, patterns)) {
+      log.info(`  Ignoring: ${relPath}${isDir ? '/' : ''}`);
+      continue;
+    }
+    if (isDir) {
+      addFolderFiltered(zip, fullPath, base, patterns, reservedRelPaths);
+    } else if (reservedRelPaths.has(relPath)) {
+      // Install tree has a canonical version of this file; let that win.
+      log.info(`  Install-tree wins: ${relPath}`);
+    } else {
+      const zipDir = path.dirname(relPath).replace(/\\/g, '/');
+      zip.addLocalFile(fullPath, zipDir === '.' ? '' : zipDir);
+    }
+  }
+}
+
+/**
+ * Collect every file under `dir` as a `{ fullPath, relPath }` pair. `relPath`
+ * is forward-slash-separated and relative to `dir` — so the install tree's
+ * `install/cmake/FooConfig.cmake` lands as `cmake/FooConfig.cmake` at the
+ * zip root, which is where `find_package(Foo CONFIG)` expects it on the
+ * consumer side after extraction into `wyvrn_internal/<name>/`.
+ */
+function collectInstallTreeFiles(dir) {
+  const files = [];
+  function walk(current) {
+    for (const entry of fs.readdirSync(current)) {
+      const full = path.join(current, entry);
+      const stat = fs.statSync(full);
+      if (stat.isDirectory()) {
+        walk(full);
+      } else {
+        const rel = path.relative(dir, full).replace(/\\/g, '/');
+        files.push({ fullPath: full, relPath: rel });
+      }
+    }
+  }
+  walk(dir);
+  return files;
+}
+
+function addInstallTree(zip, installDir) {
+  const files = collectInstallTreeFiles(installDir);
+  const added = new Set();
+  for (const { fullPath, relPath } of files) {
+    const zipDir = path.dirname(relPath).replace(/\\/g, '/');
+    zip.addLocalFile(fullPath, zipDir === '.' ? '' : zipDir);
+    added.add(relPath);
+  }
+  return added;
+}
+
+// ---------------------------------------------------------------------------
+// Source resolution
+// ---------------------------------------------------------------------------
+
+function resolveSource(argv, ctx) {
+  let { source, awsProfile } = argv;
+  const { config } = ctx;
+  let sourceEntry = null;
+
+  if (source) {
+    const named = config.publishSources.find((s) => s.name === source);
+    if (named) {
+      log.info(`Using publish source "${named.name}" from config`);
+      source     = named.url;
+      awsProfile = awsProfile ?? named.profile;
+      sourceEntry = named;
+    }
+  } else {
+    if (config.publishSources.length === 0) {
+      log.error(
+        '--source is required (or configure one with: ' +
+          'wyvrnpm configure add-source --kind publish ...)',
+      );
+      process.exit(1);
+    }
+    const first = config.publishSources[0];
+    log.info(`Using publish source "${first.name}" from config`);
+    source     = first.url;
+    awsProfile = awsProfile ?? first.profile;
+    sourceEntry = first;
+  }
+
+  // Auth flows through ctx.auth.for — same literal > --token-env >
+  // config.token > config.tokenEnv precedence, centralised once in
+  // buildContext.
+  const { token } = ctx.auth.for(sourceEntry);
+
+  return { source, awsProfile, token };
+}
+
+// ---------------------------------------------------------------------------
+// Main publish command
+// ---------------------------------------------------------------------------
+
+async function publish(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. Also throws on malformed --option /
+  // --conf so bad inputs surface before we hit the registry.
+  let ctx;
+  try {
+    ctx = buildContext(argv);
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+
+  const { source, awsProfile, token } = resolveSource(argv, ctx);
+  const { path: publishPath, force } = argv;
+  const jsonOut = ctx.flags.format === 'json';
+
+  // ── Load manifest ─────────────────────────────────────────────────────────
+  // ctx.manifest is a lazy getter — throws on first access if the file is
+  // missing or malformed, which is exactly what we want here.
+  const { manifestPath } = ctx;
+  let manifest;
+  try {
+    manifest = ctx.manifest;
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+
+  const { name, version } = manifest;
+  if (!name || !version) {
+    log.error('Manifest must have "name" and "version" fields');
+    process.exit(1);
+  }
+
+  const srcDir = path.resolve(publishPath || '.');
+  if (!fs.existsSync(srcDir)) {
+    log.error(`Publish path does not exist: ${srcDir}`);
+    process.exit(1);
+  }
+
+  // ── Resolve provider ──────────────────────────────────────────────────────
+  let provider;
+  try {
+    provider = getProvider(source);
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+
+  // ── Load build profile ────────────────────────────────────────────────────
+  // Resolved once in buildContext(). argv.profile → config.defaultProfile
+  // → "default" fallback is applied there. `--profile` to publish still
+  // works identically — it just flows through ctx.
+  const {
+    name: activeProfileName,
+    profile: buildProfile,
+    fromFile,
+  } = ctx.profiles.host;
+
+  // ── Resolve this package's own declared options ─────────────────────────
+  // Publishing needs to commit to a specific value for every option the
+  // recipe declares. Sources for overrides: CLI `-o <pkg>:...` flags
+  // (scoped to the package being published), else the recipe's defaults.
+  const ownDeclaration = manifest.options
+    ? normalizeOptionsDeclaration(manifest.options, `${name}@${version}`)
+    : null;
+  const cliOptionsByPkg = ctx.cliOptions;
+  const effectiveOptions = resolveEffectiveOptions(
+    ownDeclaration,
+    {},                               // consumer-side overrides don't apply to self-publish
+    cliOptionsByPkg[name] ?? {},
+    `${name}@${version}`,
+  );
+
+  const profileHash = hashProfile(buildProfile, effectiveOptions);
+
+  log.info(
+    `Publishing ${name}@${version}\n` +
+    `Profile     : "${activeProfileName}"${fromFile ? '' : ' (auto-detected — save with `wyvrnpm configure profile detect`)'}\n` +
+    `  ${buildProfile.os}/${buildProfile.arch}  ` +
+    `${buildProfile.compiler} ${buildProfile['compiler.version']}  ` +
+    `C++${buildProfile['compiler.cppstd']}` +
+    (buildProfile['compiler.runtime'] ? `  [${buildProfile['compiler.runtime']}]` : '') + '\n' +
+    (effectiveOptions ? `Options     : ${JSON.stringify(effectiveOptions)}\n` : '') +
+    `Profile hash: ${profileHash}\n` +
+    `Provider    : ${provider.constructor.providerName}`,
+  );
+
+  // ── Check v2 existence ────────────────────────────────────────────────────
+  const v2AlreadyExists = await provider.v2Exists({ source, name, version, profileHash, awsProfile, token });
+  if (v2AlreadyExists) {
+    if (force) {
+      log.warn(`${name}@${version} [${profileHash}] already exists — overwriting (--force)`);
+    } else {
+      log.error(
+        `${name}@${version} [${profileHash}] already exists.\n` +
+          '  Bump the version, use a different profile, or pass --force to overwrite.',
+      );
+      process.exit(1);
+    }
+  }
+
+  // ── Read the author's lockfile snapshot for `publishedLock` audit ────────
+  // Dependencies in wyvrn.json are published verbatim (ranges stay as ranges).
+  // The exact versions from wyvrn.lock are attached as `publishedLock` metadata
+  // on the uploaded manifest so future forensics can tell what the author
+  // actually tested against — without constraining consumer resolution.
+  const lockPath = path.join(path.dirname(manifestPath), 'wyvrn.lock');
+  const publishedLock = {};
+  if (fs.existsSync(lockPath)) {
+    try {
+      const lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+      for (const [pkgName, entry] of Object.entries(lock.packages ?? {})) {
+        const ver = typeof entry === 'string' ? entry : entry.version;
+        if (ver) publishedLock[pkgName] = ver;
+      }
+      log.info(`Lock snapshot: ${Object.keys(publishedLock).length} package(s) recorded in publishedLock`);
+    } catch {
+      log.warn('could not read wyvrn.lock — publishedLock audit block will be empty');
+    }
+  } else {
+    log.warn('no wyvrn.lock found — run `wyvrnpm install` before publishing so publishedLock records tested versions');
+  }
+
+  // ── Git metadata ──────────────────────────────────────────────────────────
+  const gitSha  = getGitSha(srcDir);
+  const gitRepo = getGitRepo(srcDir);
+  if (gitSha)  log.info(`Git commit : ${gitSha}`);
+  if (gitRepo) log.info(`Git remote : ${gitRepo}`);
+
+  // Warn (but don't block) if HEAD isn't reachable from origin. Downstream
+  // `--build=missing` consumers will fail to fetch this commit — the fix
+  // is almost always `git push` before publishing.
+  if (gitSha && gitRepo && !isShaOnRemote(gitSha, srcDir)) {
+    log.warn(
+      `commit ${gitSha.slice(0, 12)} is not reachable from any remote ` +
+      `branch or tag on origin.\n` +
+      `  Consumers building this package from source will fail to retrieve it.\n` +
+      `  Fix: push your branch (or tag the commit) before publishing.`,
+    );
+  }
+
+  // ── .wyvrnignore ──────────────────────────────────────────────────────────
+  const ignoreFile = path.join(srcDir, '.wyvrnignore');
+  const ignorePatterns = loadIgnorePatterns(ignoreFile);
+  if (ignorePatterns.length > 0) {
+    log.info(`Loaded ${ignorePatterns.length} pattern(s) from .wyvrnignore`);
+  }
+
+  // ── Build zip ─────────────────────────────────────────────────────────────
+  const tmpZipPath = path.join(os.tmpdir(), `wyvrnpm-${name}-${version}-${Date.now()}.zip`);
+
+  // ── Inject default `compatibility` block if the source manifest lacks one ──
+  // Written to a temp file so the source wyvrn.json is never modified.
+  // A published manifest must always carry a compat block so install-time
+  // resolution has something to evaluate (default = all fields `exact`,
+  // identical semantics to pre-phase-2 strict behaviour).
+  const tmpManifestPath = path.join(
+    os.tmpdir(),
+    `wyvrnpm-manifest-${name}-${version}-${Date.now()}.json`,
+  );
+  // ── publishedConf (PLAN-CONF.md §4.6) ────────────────────────────────────
+  // Publish reads ONLY the recipe conf + CLI --conf — wyvrn.local.json is
+  // intentionally ignored (plan §4.5 / §8.4) so dev-local overlays never
+  // leak into shared artefacts. Recorded on the published manifest as
+  // informational metadata: it tells maintainers what the publisher's
+  // CMake cache vars were at build time but does NOT drive resolution on
+  // the consumer side.
+  let publishedConf = {};
+  try {
+    const recipeConfFlat = readRecipeConf(manifest);
+    // ctx.cliConf is pre-parsed by buildContext. Malformed --conf would
+    // have thrown up there before we reached this block.
+    publishedConf = mergeConfLayers(recipeConfFlat, {}, ctx.cliConf);
+  } catch (err) {
+    log.error(`conf resolution failed: ${err.message}`);
+    process.exit(1);
+  }
+  if (Object.keys(publishedConf).length > 0) {
+    log.info(`Published conf: ${JSON.stringify(publishedConf)}`);
+  }
+
+  const manifestForPublish = {
+    ...manifest,
+    compatibility: manifest.compatibility ?? defaultCompatBlock(),
+    ...(Object.keys(publishedConf).length > 0
+      ? { publishedConf: unflattenConf(publishedConf) }
+      : {}),
+  };
+  fs.writeFileSync(tmpManifestPath, JSON.stringify(manifestForPublish, null, 2), 'utf8');
+  if (!manifest.compatibility) {
+    log.info('Injecting default `compatibility` block (all fields `exact`) — override by adding one to wyvrn.json');
+  } else {
+    log.info(`Using package-declared compatibility: ${JSON.stringify(manifest.compatibility)}`);
+  }
+
+  // ── Install-tree overlay ──────────────────────────────────────────────────
+  // Publish zips the source tree (filtered by .wyvrnignore), but consumers
+  // actually need the install tree — `lib/cmake/<Name>/<Name>Config.cmake`,
+  // the installed headers, compiled libs — so find_package() works after
+  // extraction. When a build recipe is declared, locate the per-profile
+  // install dir (populated by `wyvrnpm build --config <cfg> --install`) and
+  // overlay its contents on top of the source zip. Install-tree files win
+  // on path collisions (e.g. `include/`).
+  let installOverlayDir = null;
+  let installOverlayPaths = new Set();
+  if (hasBuildRecipe(manifest)) {
+    try {
+      const recipe = normalizeRecipe(manifest.build, effectiveOptions, manifest);
+      const candidate = path.join(
+        srcDir, 'build', `wyvrn-${activeProfileName}`, recipe.installDir,
+      );
+      if (fs.existsSync(candidate) && fs.statSync(candidate).isDirectory()) {
+        installOverlayDir = candidate;
+      } else {
+        log.warn(
+          `build recipe is declared but no install tree found at ${candidate}.\n` +
+          '  Consumers\' find_package() will likely fail. Fix: run\n' +
+          '    wyvrnpm build --config Debug --install\n' +
+          '    wyvrnpm build --config Release --install\n' +
+          '    wyvrnpm build --config RelWithDebInfo --install\n' +
+          '    wyvrnpm build --config MinSizeRel --install\n' +
+          '  then re-run publish.',
+        );
+      }
+    } catch (err) {
+      log.warn(`could not locate install tree: ${err.message} — publishing source tree only`);
+    }
+  }
+
+  try {
+    log.info(`Zipping ${srcDir} ...`);
+    const zip = new AdmZip();
+    if (installOverlayDir) {
+      // Collect install-tree paths first so the source-tree walker can skip
+      // anything the install tree will add canonically.
+      const peek = collectInstallTreeFiles(installOverlayDir);
+      installOverlayPaths = new Set(peek.map((f) => f.relPath));
+    }
+    addFolderFiltered(zip, srcDir, srcDir, ignorePatterns, installOverlayPaths);
+    if (installOverlayDir) {
+      log.info(`Overlaying install tree: ${installOverlayDir}`);
+      const added = addInstallTree(zip, installOverlayDir);
+      log.info(`  Added ${added.size} file(s) from install tree`);
+    }
+    zip.writeZip(tmpZipPath);
+
+    const contentSha256 = sha256Of(tmpZipPath);
+    log.info(`Content SHA256 : ${contentSha256}`);
+
+    // ── v2 publish ────────────────────────────────────────────────────────
+    log.info('Publishing (v2) ...');
+    await provider.v2Publish(
+      { manifest: tmpManifestPath, zip: tmpZipPath },
+      {
+        source,
+        name,
+        version,
+        profileHash,
+        // buildSettings stored in metadata for debugging — NOT wyvrn.json
+        buildSettings: effectiveOptions
+          ? { ...buildProfile, options: effectiveOptions }
+          : buildProfile,
+        contentSha256,
+        gitSha,
+        gitRepo,
+        publishedLock,
+        awsProfile,
+        token,
+      },
+    );
+
+    log.success(`Successfully published ${name}@${version} [${profileHash}] to ${source}`);
+
+    if (jsonOut) {
+      const payload = {
+        command:        'publish',
+        wyvrnpmVersion: require('../../package.json').version,
+        name,
+        version,
+        profileHash,
+        source,
+        contentSha256,
+        options:        effectiveOptions ?? null,
+        gitSha:         gitSha  ?? null,
+        gitRepo:        gitRepo ?? null,
+        publishedAt:    new Date().toISOString(),
+      };
+      process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+    }
+  } finally {
+    if (fs.existsSync(tmpZipPath))      fs.unlinkSync(tmpZipPath);
+    if (fs.existsSync(tmpManifestPath)) fs.unlinkSync(tmpManifestPath);
+  }
+}
+
+module.exports = publish;
+// Exported for tests only
+module.exports.addFolderFiltered       = addFolderFiltered;
+module.exports.addInstallTree          = addInstallTree;
+module.exports.collectInstallTreeFiles = collectInstallTreeFiles;