wyvrnpm 2.0.4 → 2.3.2

package/src/commands/publish.js

@@ -8,44 +8,39 @@ const AdmZip = require('adm-zip');
 const { readManifest }                                     = require('../manifest');
 const { getProvider }                                      = require('../providers');
 const { readConfig }                                       = require('../config');
-const { loadProfile, hashProfile, sha256Of, getGitSha, getGitRepo } = require('../profile');
+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');
 
-// ---------------------------------------------------------------------------
-// .wyvrnignore helpers (unchanged from v1)
-// ---------------------------------------------------------------------------
-
-function loadIgnorePatterns(ignoreFile) {
-  if (!fs.existsSync(ignoreFile)) return [];
-  return fs
-    .readFileSync(ignoreFile, 'utf8')
-    .split(/\r?\n/)
-    .map((l) => l.trim())
-    .filter((l) => l.length > 0 && !l.startsWith('#'));
-}
-
-function patternToRegex(pattern) {
-  const anchored = pattern.startsWith('/');
-  const p = anchored ? pattern.slice(1) : pattern;
-  let re = p
-    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
-    .replace(/\*\*/g, '\x00')
-    .replace(/\*/g, '[^/]*')
-    .replace(/\?/g, '[^/]')
-    .replace(/\x00/g, '.*');
-  return anchored ? new RegExp(`^${re}(/|$)`) : new RegExp(`(^|/)${re}(/|$)`);
-}
-
-function addFolderFiltered(zip, dir, base, ignoreRe) {
+/**
+ * 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, '/');
-    if (ignoreRe.some((re) => re.test(relPath))) {
-      console.log(`[wyvrn]   Ignoring: ${relPath}`);
+    const stat     = fs.statSync(fullPath);
+    const isDir    = stat.isDirectory();
+    if (isIgnored(relPath, isDir, patterns)) {
+      log.info(`  Ignoring: ${relPath}${isDir ? '/' : ''}`);
       continue;
     }
-    const stat = fs.statSync(fullPath);
-    if (stat.isDirectory()) {
-      addFolderFiltered(zip, fullPath, base, ignoreRe);
+    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);
@@ -53,6 +48,42 @@ function addFolderFiltered(zip, dir, base, ignoreRe) {
   }
 }
 
+/**
+ * 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
 // ---------------------------------------------------------------------------
@@ -64,21 +95,21 @@ function resolveSource(argv) {
   if (source) {
     const named = config.publishSources.find((s) => s.name === source);
     if (named) {
-      console.log(`[wyvrn] Using publish source "${named.name}" from config`);
+      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) {
-      console.error(
-        '[wyvrn] Error: --source is required (or configure one with: ' +
+      log.error(
+        '--source is required (or configure one with: ' +
           'wyvrnpm configure add-source --kind publish ...)',
       );
       process.exit(1);
     }
     const first = config.publishSources[0];
-    console.log(`[wyvrn] Using publish source "${first.name}" from config`);
+    log.info(`Using publish source "${first.name}" from config`);
     source     = first.url;
     awsProfile = awsProfile ?? first.profile;
     token      = token      ?? first.token;
@@ -99,24 +130,26 @@ async function publish(argv) {
     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) {
-    console.error(`[wyvrn] Error: Could not read manifest at ${manifestPath}`);
+    log.error(`Could not read manifest at ${manifestPath}`);
     process.exit(1);
   }
 
   const { name, version } = manifest;
   if (!name || !version) {
-    console.error('[wyvrn] Error: Manifest must have "name" and "version" fields');
+    log.error('Manifest must have "name" and "version" fields');
     process.exit(1);
   }
 
   const srcDir = path.resolve(publishPath || '.');
   if (!fs.existsSync(srcDir)) {
-    console.error(`[wyvrn] Error: Publish path does not exist: ${srcDir}`);
+    log.error(`Publish path does not exist: ${srcDir}`);
     process.exit(1);
   }
 
@@ -125,7 +158,7 @@ async function publish(argv) {
   try {
     provider = getProvider(source);
   } catch (err) {
-    console.error(`[wyvrn] Error: ${err.message}`);
+    log.error(err.message);
     process.exit(1);
   }
 
@@ -133,27 +166,44 @@ async function publish(argv) {
   const config = readConfig();
   const activeProfileName = profileName ?? config.defaultProfile ?? 'default';
   const { profile: buildProfile, fromFile } = loadProfile(activeProfileName);
-  const profileHash = hashProfile(buildProfile);
 
-  console.log(
-    `[wyvrn] Publishing ${name}@${version}\n` +
-    `[wyvrn] Profile     : "${activeProfileName}"${fromFile ? '' : ' (auto-detected — save with `wyvrnpm configure profile detect`)'}\n` +
-    `[wyvrn]   ${buildProfile.os}/${buildProfile.arch}  ` +
+  // ── 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' +
-    `[wyvrn] Profile hash: ${profileHash}\n` +
-    `[wyvrn] Provider    : ${provider.constructor.providerName}`,
+    (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) {
-      console.warn(`[wyvrn] Warning: ${name}@${version} [${profileHash}] already exists — overwriting (--force)`);
+      log.warn(`${name}@${version} [${profileHash}] already exists — overwriting (--force)`);
     } else {
-      console.error(
-        `[wyvrn] Error: ${name}@${version} [${profileHash}] already exists.\n` +
+      log.error(
+        `${name}@${version} [${profileHash}] already exists.\n` +
           '  Bump the version, use a different profile, or pass --force to overwrite.',
       );
       process.exit(1);
@@ -170,50 +220,129 @@ async function publish(argv) {
         const ver = typeof entry === 'string' ? entry : entry.version;
         if (ver) lockedDependencies[pkgName] = ver;
       }
-      console.log(`[wyvrn] Lock file  : ${Object.keys(lockedDependencies).length} pinned package(s)`);
+      log.info(`Lock file  : ${Object.keys(lockedDependencies).length} pinned package(s)`);
     } catch {
-      console.warn('[wyvrn] Warning: could not read wyvrn.lock — dependency versions will be published as-is from wyvrn.json');
+      log.warn('could not read wyvrn.lock — dependency versions will be published as-is from wyvrn.json');
     }
   } else {
-    console.warn('[wyvrn] Warning: no wyvrn.lock found — run `wyvrnpm install` before publishing to pin dependency versions');
+    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)  console.log(`[wyvrn] Git commit : ${gitSha}`);
-  if (gitRepo) console.log(`[wyvrn] Git remote : ${gitRepo}`);
+  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);
-  const ignoreRe = ignorePatterns.map(patternToRegex);
   if (ignorePatterns.length > 0) {
-    console.log(`[wyvrn] Loaded ${ignorePatterns.length} pattern(s) from .wyvrnignore`);
+    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 {
-    console.log(`[wyvrn] Zipping ${srcDir} ...`);
+    log.info(`Zipping ${srcDir} ...`);
     const zip = new AdmZip();
-    addFolderFiltered(zip, srcDir, srcDir, ignoreRe);
+    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);
-    console.log(`[wyvrn] Content SHA256 : ${contentSha256}`);
+    log.info(`Content SHA256 : ${contentSha256}`);
 
     // ── v2 publish ────────────────────────────────────────────────────────
-    console.log('[wyvrn] Publishing (v2) ...');
+    log.info('Publishing (v2) ...');
     await provider.v2Publish(
-      { manifest: manifestPath, zip: tmpZipPath },
+      { manifest: tmpManifestPath, zip: tmpZipPath },
       {
         source,
         name,
         version,
         profileHash,
         // buildSettings stored in metadata for debugging — NOT wyvrn.json
-        buildSettings: buildProfile,
+        buildSettings: effectiveOptions
+          ? { ...buildProfile, options: effectiveOptions }
+          : buildProfile,
         contentSha256,
         gitSha,
         gitRepo,
@@ -223,10 +352,32 @@ async function publish(argv) {
       },
     );
 
-    console.log(`[wyvrn] Successfully published ${name}@${version} [${profileHash}] to ${source}`);
+    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(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;

package/src/commands/show.js

@@ -0,0 +1,237 @@
+'use strict';
+
+const { readConfig }  = require('../config');
+const { getProvider } = require('../providers');
+const log             = require('../logger');
+
+/**
+ * `wyvrnpm show <pkg>` — surface registry metadata for a package.
+ *
+ * Accepts:
+ *   name                         → list every published version + profile.
+ *   name@version                 → list every profile for that version,
+ *                                  fetch full metadata for each, highlight
+ *                                  consumer (`uploadedBy`) vs author builds.
+ *   name@version@profileHash     → dump full metadata for one build.
+ *
+ * Sources: CLI `--source` overrides config.installSources. First source
+ * that returns data wins (same first-match policy as `install`).
+ *
+ * Added for PLAN-UPLOAD-BUILT phase 3 so maintainers can spot-check which
+ * profileHashes were uploaded by consumers vs published by an author. The
+ * `uploadedBy` block is the signal; its absence means "author publish"
+ * by convention.
+ *
+ * @param {object} argv
+ * @param {string} argv.pkg                         e.g. "zlib", "zlib@1.3.0.0", "zlib@1.3.0.0@a1b2..."
+ * @param {string[]} [argv.source]                  source URLs
+ * @param {string} [argv.awsProfile]
+ * @param {string} [argv.token]
+ * @returns {Promise<void>}
+ */
+async function show(argv) {
+  const { name, version, profileHash } = parseSpec(argv.pkg);
+  if (!name) {
+    log.error('Usage: wyvrnpm show <name>[@<version>[@<profileHash>]]');
+    process.exit(1);
+  }
+
+  const jsonOut = argv.format === 'json';
+  if (jsonOut) log.setJsonMode(true);
+
+  const { sources, awsProfile, token } = resolveSources(argv);
+  if (sources.length === 0) {
+    log.error(
+      'no sources configured. ' +
+      'Pass --source <url> or run: wyvrnpm configure add-source --kind install ...',
+    );
+    process.exit(1);
+  }
+
+  for (const source of sources) {
+    let provider;
+    try { provider = getProvider(source); } catch { continue; }
+
+    const idx = await provider.v2GetVersionsIndex({ source, name, awsProfile, token });
+    if (!idx?.versions) continue;
+
+    const versionKeys = version
+      ? (idx.versions[version] ? [version] : [])
+      : Object.keys(idx.versions).sort();
+
+    if (version && versionKeys.length === 0) {
+      log.error(`Version ${version} not found on ${source}`);
+      process.exit(1);
+    }
+
+    // Collect a single structured result as we walk. Text rendering happens
+    // inline in the legacy path; JSON mode emits the whole object at the
+    // end of the first source that answered.
+    const result = {
+      command:        'show',
+      wyvrnpmVersion: require('../../package.json').version,
+      source,
+      package:        name,
+      latest:         idx.latest ?? null,
+      versions:       {},
+    };
+
+    if (!jsonOut) {
+      console.log(`${name}  (source: ${source})`);
+      if (idx.latest) console.log(`  latest: ${idx.latest}`);
+    }
+
+    for (const v of versionKeys) {
+      const ventry = idx.versions[v];
+      const profiles = ventry?.profiles ?? {};
+      const profileKeys = profileHash
+        ? (profiles[profileHash] ? [profileHash] : [])
+        : Object.keys(profiles).sort();
+
+      if (profileHash && profileKeys.length === 0) {
+        log.error(`ProfileHash ${profileHash} not found for ${name}@${v}`);
+        process.exit(1);
+      }
+
+      if (!jsonOut) {
+        console.log(`\n  ${name}@${v}  (${profileKeys.length} profile${profileKeys.length === 1 ? '' : 's'})`);
+        if (ventry.source?.gitSha) {
+          console.log(`    git: ${ventry.source.gitRepo ?? '?'} @ ${ventry.source.gitSha}`);
+        }
+      }
+
+      // For bare `name` queries we'd fetch O(M×N) manifests (versions ×
+      // profiles) — too noisy. Only deep-fetch when the user has narrowed
+      // to a specific version.
+      const deepFetch = Boolean(version);
+
+      const profileArr = [];
+      for (const hash of profileKeys) {
+        const entry = profiles[hash];
+        if (!jsonOut) {
+          console.log(`\n    [${hash}]`);
+          if (entry.buildSettings) {
+            console.log(`      profile : ${formatBuildSettings(entry.buildSettings)}`);
+            if (entry.buildSettings.options && Object.keys(entry.buildSettings.options).length > 0) {
+              console.log(`      options : ${formatOptions(entry.buildSettings.options)}`);
+            }
+          }
+          console.log(`      sha256  : ${entry.contentSha256 ?? '?'}`);
+          if (entry.publishedAt) console.log(`      published: ${entry.publishedAt}`);
+        }
+
+        let meta = null;
+        if (deepFetch) {
+          meta = await provider.v2GetMeta({
+            source, name, version: v, profileHash: hash, awsProfile, token,
+          });
+          if (!jsonOut) {
+            if (meta?.uploadedBy) {
+              console.log(`      origin  : consumer upload (${meta.uploadedBy.kind})`);
+              console.log(`                uploadedAt     : ${meta.uploadedBy.uploadedAt}`);
+              console.log(`                wyvrnpmVersion : ${meta.uploadedBy.wyvrnpmVersion ?? '?'}`);
+              if (meta.uploadedBy.builtFromGit) {
+                console.log(`                builtFromGit   : ${meta.uploadedBy.builtFromGit}`);
+              }
+              if (meta.uploadedBy.builtFromSha) {
+                console.log(`                builtFromSha   : ${meta.uploadedBy.builtFromSha}`);
+              }
+            } else if (meta) {
+              console.log(`      origin  : author publish`);
+            }
+            if (meta?.compatibility) {
+              console.log(`      compat  : ${JSON.stringify(meta.compatibility)}`);
+            }
+            if (meta?.options && Object.keys(meta.options).length > 0) {
+              console.log(`      declared: ${formatDeclaredOptions(meta.options)}`);
+            }
+          }
+        }
+
+        profileArr.push({
+          profileHash:     hash,
+          contentSha256:   entry.contentSha256 ?? null,
+          publishedAt:     entry.publishedAt   ?? null,
+          buildSettings:   entry.buildSettings ?? null,
+          origin:          meta?.uploadedBy ? 'consumer-source-build' : (meta ? 'author-publish' : null),
+          uploadedBy:      meta?.uploadedBy    ?? null,
+          compatibility:   meta?.compatibility ?? null,
+          declaredOptions: meta?.options       ?? null,
+        });
+      }
+
+      result.versions[v] = {
+        source:   ventry.source ?? null,
+        profiles: profileArr,
+      };
+    }
+
+    if (jsonOut) {
+      process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    }
+    return;
+  }
+
+  log.error(`Package ${name} not found in any configured source`);
+  process.exit(1);
+}
+
+/**
+ * Parse a package spec "name[@version[@profileHash]]".
+ * @param {string} spec
+ * @returns {{ name?: string, version?: string, profileHash?: string }}
+ */
+function parseSpec(spec) {
+  if (!spec || typeof spec !== 'string') return {};
+  const parts = spec.split('@');
+  const [name, version, profileHash] = parts;
+  return {
+    name:        name || undefined,
+    version:     version || undefined,
+    profileHash: profileHash || undefined,
+  };
+}
+
+function resolveSources(argv) {
+  const config = readConfig();
+  const sources = (argv.source && argv.source.length > 0)
+    ? argv.source
+    : config.installSources.map((s) => s.url);
+
+  const firstConfig = config.installSources?.[0];
+  return {
+    sources,
+    awsProfile: argv.awsProfile ?? firstConfig?.profile,
+    token:      argv.token      ?? firstConfig?.token,
+  };
+}
+
+function formatBuildSettings(bs) {
+  const parts = [
+    `${bs.os}/${bs.arch}`,
+    `${bs.compiler} ${bs['compiler.version']}`,
+    `C++${bs['compiler.cppstd']}`,
+  ];
+  if (bs['compiler.runtime']) parts.push(`[${bs['compiler.runtime']}]`);
+  return parts.join('  ');
+}
+
+function formatOptions(options) {
+  return Object.entries(options)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([k, v]) => `${k}=${typeof v === 'string' ? v : String(v)}`)
+    .join(', ');
+}
+
+function formatDeclaredOptions(declared) {
+  return Object.entries(declared)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, spec]) => {
+      const allowed = Array.isArray(spec?.allowed) ? spec.allowed : [];
+      return `${name} (default=${String(spec?.default)}, allowed=${allowed.map(String).join('|')})`;
+    })
+    .join('; ');
+}
+
+module.exports = show;
+module.exports.parseSpec = parseSpec;