wyvrnpm 2.10.2 → 2.12.2

package/src/commands/publish.js

@@ -1,555 +1,584 @@
-'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');
-
-/**
- * Human-friendly byte formatter for the dry-run summary.
- *
- * @param {number} n
- * @returns {string}
- */
-function formatBytes(n) {
-  if (!Number.isFinite(n) || n < 0) return `${n}`;
-  if (n < 1024)             return `${n} B`;
-  if (n < 1024 * 1024)      return `${(n / 1024).toFixed(1)} KB`;
-  if (n < 1024 * 1024 * 1024) return `${(n / 1024 / 1024).toFixed(2)} MB`;
-  return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
-}
-
-/**
- * Compute the registry URLs/paths that `v2Publish` would write to. Pure —
- * no network, no filesystem. Mirrors the keys produced by S3/HTTP/File
- * providers (§4.5 of CLAUDE.md), so dry-run can surface the exact shape
- * of the upload without actually performing it.
- *
- * @param {{
- *   source:       string,
- *   name:         string,
- *   version:      string,
- *   profileHash:  string,
- *   gitSha?:      string | null,
- *   gitRepo?:     string | null,
- *   updateLatest?: boolean,
- * }} opts
- * @returns {Array<{ path: string, kind: 'wyvrn.zip'|'wyvrn.json'|'source.json'|'versions.json'|'latest.json' }>}
- */
-function planPublishUrls({
-  source, name, version, profileHash,
-  gitSha = null, gitRepo = null, updateLatest = true,
-}) {
-  const base = source.replace(/\/$/, '');
-  const v2root    = `${base}/v2/${name}`;
-  const buildRoot = `${v2root}/${version}/${profileHash}`;
-
-  const plan = [
-    { path: `${buildRoot}/wyvrn.zip`,   kind: 'wyvrn.zip' },
-    { path: `${buildRoot}/wyvrn.json`,  kind: 'wyvrn.json' },
-  ];
-  if (gitSha || gitRepo) {
-    plan.push({ path: `${v2root}/${version}/source.json`, kind: 'source.json' });
-  }
-  plan.push({ path: `${v2root}/versions.json`, kind: 'versions.json' });
-  if (updateLatest) {
-    plan.push({ path: `${v2root}/latest.json`, kind: 'latest.json' });
-  }
-  return plan;
-}
-
-/**
- * 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 dryRun  = Boolean(argv.dryRun);
-  const jsonOut = ctx.flags.format === 'json';
-  if (dryRun) {
-    log.info('DRY RUN — no upload will occur. Previewing publish plan only.');
-  }
-
-  // ── 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 ────────────────────────────────────────────────────
-  // Dry-run softens the overwrite-without-force error to a warning so the
-  // full plan still prints — CI callers should parse `--format json` and
-  // gate on `wouldOverwrite` rather than on the exit code.
-  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 if (dryRun) {
-      log.warn(
-        `${name}@${version} [${profileHash}] already exists on the registry. ` +
-        `A real publish would refuse without --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);
-    const zipBytes      = fs.statSync(tmpZipPath).size;
-    const manifestBytes = fs.statSync(tmpManifestPath).size;
-    log.info(`Content SHA256 : ${contentSha256}`);
-    log.info(`Zip size       : ${formatBytes(zipBytes)} (${zipBytes} bytes)`);
-
-    // ── Dry run: print the plan, skip the actual upload ──────────────────
-    // Mirrors `npm publish --dry-run` — every step above (profile, options,
-    // zip, hash, v2Exists) runs; only the provider write is skipped.
-    if (dryRun) {
-      const plan = planPublishUrls({
-        source, name, version, profileHash, gitSha, gitRepo, updateLatest: true,
-      });
-
-      if (!jsonOut) {
-        console.log();
-        console.log(`Would publish ${name}@${version} [${profileHash}] to ${source}`);
-        console.log(`  contentSha256 : ${contentSha256}`);
-        console.log(`  zip size      : ${formatBytes(zipBytes)}`);
-        console.log(`  manifest size : ${formatBytes(manifestBytes)}`);
-        if (v2AlreadyExists) {
-          console.log(`  overwrite     : YES — ${force ? '--force set, would proceed' : 'NOT SET, real publish would refuse'}`);
-        }
-        console.log();
-        console.log('Registry writes:');
-        for (const { path: p, kind } of plan) {
-          console.log(`  → ${p}    (${kind})`);
-        }
-        console.log();
-        log.success('Dry run OK — nothing uploaded.');
-      } else {
-        const payload = {
-          command:        'publish',
-          dryRun:         true,
-          wyvrnpmVersion: require('../../package.json').version,
-          name,
-          version,
-          profileHash,
-          source,
-          contentSha256,
-          zipBytes,
-          manifestBytes,
-          options:         effectiveOptions ?? null,
-          gitSha:          gitSha  ?? null,
-          gitRepo:         gitRepo ?? null,
-          wouldOverwrite:  Boolean(v2AlreadyExists),
-          forceSet:        Boolean(force),
-          publishedLock,
-          publishedConf:   Object.keys(publishedConf).length > 0 ? unflattenConf(publishedConf) : null,
-          plan,
-        };
-        process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
-      }
-      return;
-    }
-
-    // ── 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;
-module.exports.planPublishUrls         = planPublishUrls;
-module.exports.formatBytes             = formatBytes;
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+
+const { StreamingZipWriter }                               = require('../zip-stream');
+const { getProvider }                                      = require('../providers');
+const {
+  readRecipeConf,
+  mergeConfLayers,
+  unflattenConf,
+  readLocalOverlay,
+}                                                          = require('../conf');
+const { resolveBinaryDirRoot }                             = require('../binary-dir');
+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');
+
+/**
+ * Human-friendly byte formatter for the dry-run summary.
+ *
+ * @param {number} n
+ * @returns {string}
+ */
+function formatBytes(n) {
+  if (!Number.isFinite(n) || n < 0) return `${n}`;
+  if (n < 1024)             return `${n} B`;
+  if (n < 1024 * 1024)      return `${(n / 1024).toFixed(1)} KB`;
+  if (n < 1024 * 1024 * 1024) return `${(n / 1024 / 1024).toFixed(2)} MB`;
+  return `${(n / 1024 / 1024 / 1024).toFixed(2)} GB`;
+}
+
+/**
+ * Compute the registry URLs/paths that `v2Publish` would write to. Pure —
+ * no network, no filesystem. Mirrors the keys produced by S3/HTTP/File
+ * providers (§4.5 of CLAUDE.md), so dry-run can surface the exact shape
+ * of the upload without actually performing it.
+ *
+ * @param {{
+ *   source:       string,
+ *   name:         string,
+ *   version:      string,
+ *   profileHash:  string,
+ *   gitSha?:      string | null,
+ *   gitRepo?:     string | null,
+ *   updateLatest?: boolean,
+ * }} opts
+ * @returns {Array<{ path: string, kind: 'wyvrn.zip'|'wyvrn.json'|'source.json'|'versions.json'|'latest.json' }>}
+ */
+function planPublishUrls({
+  source, name, version, profileHash,
+  gitSha = null, gitRepo = null, updateLatest = true,
+}) {
+  const base = source.replace(/\/$/, '');
+  const v2root    = `${base}/v2/${name}`;
+  const buildRoot = `${v2root}/${version}/${profileHash}`;
+
+  const plan = [
+    { path: `${buildRoot}/wyvrn.zip`,   kind: 'wyvrn.zip' },
+    { path: `${buildRoot}/wyvrn.json`,  kind: 'wyvrn.json' },
+  ];
+  if (gitSha || gitRepo) {
+    plan.push({ path: `${v2root}/${version}/source.json`, kind: 'source.json' });
+  }
+  plan.push({ path: `${v2root}/versions.json`, kind: 'versions.json' });
+  if (updateLatest) {
+    plan.push({ path: `${v2root}/latest.json`, kind: 'latest.json' });
+  }
+  return plan;
+}
+
+/**
+ * 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 dryRun  = Boolean(argv.dryRun);
+  const jsonOut = ctx.flags.format === 'json';
+  if (dryRun) {
+    log.info('DRY RUN — no upload will occur. Previewing publish plan only.');
+  }
+
+  // ── 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 ────────────────────────────────────────────────────
+  // Dry-run softens the overwrite-without-force error to a warning so the
+  // full plan still prints — CI callers should parse `--format json` and
+  // gate on `wouldOverwrite` rather than on the exit code.
+  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 if (dryRun) {
+      log.warn(
+        `${name}@${version} [${profileHash}] already exists on the registry. ` +
+        `A real publish would refuse without --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)}`);
+  }
+
+  // ── Resolve binaryDirRoot for install-tree lookup ────────────────────────
+  // Publish reads the overlay only to LOCATE the install tree on disk —
+  // not to fold any of its `conf` data into the published artefact (that
+  // remains explicitly excluded per CLAUDE.md §4.7 "Publish reads recipe
+  // + CLI only"). The build-dir path is a local filesystem detail, not
+  // ABI/config that ships with the zip, so reading `binaryDirRoot` here
+  // doesn't leak dev-machine state into the registry.
+  let publishBinaryDirRoot;
+  try {
+    const overlay = readLocalOverlay(srcDir);
+    publishBinaryDirRoot = resolveBinaryDirRoot({
+      cliBuildDir:               argv.buildDir,
+      localOverlayBinaryDirRoot: overlay.binaryDirRoot,
+    });
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+
+  // ── 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, publishBinaryDirRoot, `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} ...`);
+    // StreamingZipWriter — replaces adm-zip on the write path. archiver
+    // streams each file in via fs.createReadStream rather than the
+    // sync-readFileSync adm-zip used, so multi-GB artefacts (gRPC's
+    // static libs hit ~2.7 GB at RelWithDebInfo, the bug that prompted
+    // the swap) no longer trip Node's ~2-GiB Buffer cap. archiver
+    // auto-promotes to ZIP64 when total size or entry count crosses
+    // the 4 GB / 65535 thresholds; node-stream-zip on the consumer
+    // side reads ZIP64 transparently.
+    const zip = new StreamingZipWriter(tmpZipPath);
+    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`);
+    }
+    await zip.finalize();
+
+    const contentSha256 = sha256Of(tmpZipPath);
+    const zipBytes      = fs.statSync(tmpZipPath).size;
+    const manifestBytes = fs.statSync(tmpManifestPath).size;
+    log.info(`Content SHA256 : ${contentSha256}`);
+    log.info(`Zip size       : ${formatBytes(zipBytes)} (${zipBytes} bytes)`);
+
+    // ── Dry run: print the plan, skip the actual upload ──────────────────
+    // Mirrors `npm publish --dry-run` — every step above (profile, options,
+    // zip, hash, v2Exists) runs; only the provider write is skipped.
+    if (dryRun) {
+      const plan = planPublishUrls({
+        source, name, version, profileHash, gitSha, gitRepo, updateLatest: true,
+      });
+
+      if (!jsonOut) {
+        console.log();
+        console.log(`Would publish ${name}@${version} [${profileHash}] to ${source}`);
+        console.log(`  contentSha256 : ${contentSha256}`);
+        console.log(`  zip size      : ${formatBytes(zipBytes)}`);
+        console.log(`  manifest size : ${formatBytes(manifestBytes)}`);
+        if (v2AlreadyExists) {
+          console.log(`  overwrite     : YES — ${force ? '--force set, would proceed' : 'NOT SET, real publish would refuse'}`);
+        }
+        console.log();
+        console.log('Registry writes:');
+        for (const { path: p, kind } of plan) {
+          console.log(`  → ${p}    (${kind})`);
+        }
+        console.log();
+        log.success('Dry run OK — nothing uploaded.');
+      } else {
+        const payload = {
+          command:        'publish',
+          dryRun:         true,
+          wyvrnpmVersion: require('../../package.json').version,
+          name,
+          version,
+          profileHash,
+          source,
+          contentSha256,
+          zipBytes,
+          manifestBytes,
+          options:         effectiveOptions ?? null,
+          gitSha:          gitSha  ?? null,
+          gitRepo:         gitRepo ?? null,
+          wouldOverwrite:  Boolean(v2AlreadyExists),
+          forceSet:        Boolean(force),
+          publishedLock,
+          publishedConf:   Object.keys(publishedConf).length > 0 ? unflattenConf(publishedConf) : null,
+          plan,
+        };
+        process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+      }
+      return;
+    }
+
+    // ── 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;
+module.exports.planPublishUrls         = planPublishUrls;
+module.exports.formatBytes             = formatBytes;