wyvrnpm 2.10.0 → 2.11.0

package/README.md

@@ -235,6 +235,51 @@ wyvrnpm add zlib fmt@10.2.0.0 spdlog
 
 ---
 
+### `wyvrnpm version`
+
+Read, set, or partially update the top-level `version` field in `wyvrn.json`. Designed for CI/CD — bumps the build component from a pipeline variable, prints the result for capture, and never touches git (CI pipelines own tagging and commits).
+
+- **Bare** — prints the current version on stdout, naked (no `[wyvrn]` prefix), so `VER=$(wyvrnpm version)` works straight away.
+- **Full set** — `wyvrnpm version 1.2.3.4` writes the value verbatim. Strict 4-part `x.y.z.b` validation; leading zeros and 3-part semver are rejected.
+- **Component flags** — `--major / --minor / --patch / --build N` replace one component while leaving the others alone. Combine flags freely (`--minor 3 --build 0`).
+- Positional and component flags are mutually exclusive — pick a mode.
+
+```bash
+# Read the current version (CI capture)
+VER=$(wyvrnpm version)
+
+# Inject the build number from a pipeline variable
+wyvrnpm version --build "$BUILD_ID"
+
+# Cut a minor release — reset the build component to 0
+wyvrnpm version --minor 3 --build 0
+
+# Set a full version verbatim
+wyvrnpm version 2.0.0.0
+
+# CI-friendly capture
+wyvrnpm version --build "$BUILD_ID" --format json
+# {"command":"version","previous":"1.2.3.4","version":"1.2.3.99","written":true,...}
+
+# Preview without writing
+wyvrnpm version --build 99 --dry-run
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `<newVersion>` positional | — | Full 4-part version (e.g. `1.2.3.4`). Mutex with `--major/--minor/--patch/--build`. |
+| `--major` | — | Replace the 1st component. |
+| `--minor` | — | Replace the 2nd component. |
+| `--patch` | — | Replace the 3rd component. |
+| `--build` | — | Replace the 4th component (typical CI use). |
+| `--dry-run` | `false` | Compute and print the proposed version without writing. |
+| `--format` | `text` | Output format: `text` (human) or `json` (CI — single object on stdout). |
+| `--manifest` | `./wyvrn.json` | Path to the manifest file. |
+
+---
+
 ### `wyvrnpm install`
 
 Resolves the full dependency graph and downloads all packages.
@@ -431,6 +476,10 @@ wyvrnpm publish --path ./dist
 
 # Overwrite an existing build (same version + profile hash)
 wyvrnpm publish --force
+
+# Dry-run — show the upload plan without touching the registry
+wyvrnpm publish --dry-run
+wyvrnpm publish --dry-run --format json | jq '.wouldOverwrite, .plan'
 ```
 
 **Options**
@@ -445,6 +494,7 @@ wyvrnpm publish --force
 | `--path` | `.` | Directory to zip and publish. |
 | `--manifest` | `./wyvrn.json` | Path to the manifest file. |
 | `--force` / `-f` | `false` | Overwrite an existing published version (same version + profile hash). |
+| `--dry-run` | `false` | Run every step (profile, options, zip, SHA256, `v2Exists` check) and print the upload plan, but skip the provider write. An existing published version is reported as a warning (not an error) so the full plan still prints. Pair with `--format json` to gate CI on `wouldOverwrite`. |
 
 During publish the tool also:
 - reads `wyvrn.lock` to pin locked dependency versions into the uploaded manifest

package/bin/wyvrn.js

@@ -5,6 +5,7 @@
 const yargs     = require('yargs');
 const init         = require('../src/commands/init');
 const add          = require('../src/commands/add');
+const versionCmd   = require('../src/commands/version');
 const install      = require('../src/commands/install');
 const clean        = require('../src/commands/clean');
 const publish      = require('../src/commands/publish');
@@ -143,6 +144,40 @@ yargs
     (argv) => add(argv),
   )
 
+  // ── version ───────────────────────────────────────────────────────────────
+  .command(
+    'version [newVersion]',
+    'Read, set, or partially update the top-level `version` field in wyvrn.json. ' +
+    'Bare `wyvrnpm version` prints the current value on stdout (for `VER=$(...)` ' +
+    'capture). Pass a full 4-part value (1.2.3.4) or component flags (--major / ' +
+    '--minor / --patch / --build) to tweak individual parts. Designed for CI/CD — ' +
+    'pair with --format json to capture { previous, version } on stdout.',
+    (y) => {
+      y
+        .positional('newVersion', {
+          type: 'string',
+          describe: 'Full 4-part version to write verbatim (e.g. 1.2.3.4). ' +
+                    'Mutually exclusive with --major/--minor/--patch/--build.',
+        })
+        .option('major', { type: 'number', description: 'Replace the 1st component (major).' })
+        .option('minor', { type: 'number', description: 'Replace the 2nd component (minor).' })
+        .option('patch', { type: 'number', description: 'Replace the 3rd component (patch).' })
+        .option('build', { type: 'number', description: 'Replace the 4th component (build) — typical CI use.' })
+        .option('dry-run', {
+          type: 'boolean',
+          default: false,
+          description: 'Compute and print the proposed version without writing wyvrn.json.',
+        })
+        .option('format', {
+          type: 'string',
+          choices: ['text', 'json'],
+          default: 'text',
+          description: 'Output format. "json" emits { command, previous, version, ... } on stdout.',
+        });
+    },
+    (argv) => versionCmd({ ...argv, dryRun: argv['dry-run'] }),
+  )
+
   // ── install ───────────────────────────────────────────────────────────────
   .command(
     'install',
@@ -529,6 +564,17 @@ yargs
           description: 'Overwrite an existing published version',
           default: false,
         })
+        .option('dry-run', {
+          type: 'boolean',
+          default: false,
+          description:
+            'Mirror of `npm publish --dry-run` — run every step (profile, ' +
+            'options, zip, SHA256, v2Exists check) and print the upload plan, ' +
+            'but skip the provider write. An existing published version is ' +
+            'reported as a warning instead of failing. Pair with --format json ' +
+            'to script bulk publish validation (plan + wouldOverwrite flag ' +
+            'land in stdout).',
+        })
         .option('option', {
           alias: 'o',
           type: 'string',
@@ -554,7 +600,12 @@ yargs
         })
         ;
     },
-    (argv) => publish({ ...argv, awsProfile: argv['aws-profile'], tokenEnv: argv['token-env'] }),
+    (argv) => publish({
+      ...argv,
+      awsProfile: argv['aws-profile'],
+      tokenEnv:   argv['token-env'],
+      dryRun:     argv['dry-run'],
+    }),
   )
 
   // ── configure ─────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wyvrnpm",
-  "version": "2.10.0",
+  "version": "2.11.0",
   "description": "A simple, static-hosting-compatible C++ package manager",
   "keywords": [
     "c++",

package/src/commands/publish.js

@@ -22,6 +22,59 @@ 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
@@ -146,7 +199,11 @@ async function publish(argv) {
 
   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
@@ -221,10 +278,18 @@ async function publish(argv) {
   );
 
   // ── 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` +
@@ -380,7 +445,60 @@ async function publish(argv) {
     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) ...');
@@ -433,3 +551,5 @@ module.exports = publish;
 module.exports.addFolderFiltered       = addFolderFiltered;
 module.exports.addInstallTree          = addInstallTree;
 module.exports.collectInstallTreeFiles = collectInstallTreeFiles;
+module.exports.planPublishUrls         = planPublishUrls;
+module.exports.formatBytes             = formatBytes;

package/src/commands/version.js

@@ -0,0 +1,187 @@
+'use strict';
+
+const path = require('path');
+
+const { readManifest, writeManifest } = require('../manifest');
+const log                             = require('../logger');
+
+/** Strict 4-part wyvrnpm version: `x.y.z.b`, all non-negative integers, no leading zeros. */
+const VERSION_RE = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+
+/**
+ * Parse a 4-part version string into `[major, minor, patch, build]`.
+ * Throws with a clear message when the string fails the wyvrnpm format.
+ *
+ * @param {string} v
+ * @returns {[number, number, number, number]}
+ */
+function parseVersion(v) {
+  if (typeof v !== 'string' || v.length === 0) {
+    throw new Error('version is empty');
+  }
+  const m = VERSION_RE.exec(v);
+  if (!m) {
+    throw new Error(
+      `"${v}" is not a valid wyvrnpm version. ` +
+      'Expected 4-part x.y.z.b with non-negative integers (e.g. 1.2.3.4).',
+    );
+  }
+  return [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+}
+
+const COMPONENT_INDEX = { major: 0, minor: 1, patch: 2, build: 3 };
+
+function isNonNegInt(n) {
+  return Number.isInteger(n) && n >= 0;
+}
+
+/**
+ * `wyvrnpm version [<new-version>]` — read, set, or partially update the
+ * top-level `version` field in wyvrn.json. Designed for CI/CD (build-number
+ * injection + tag-the-build readback).
+ *
+ *   wyvrnpm version                      → print the current version
+ *   wyvrnpm version 1.2.3.4              → set verbatim
+ *   wyvrnpm version --build 99           → only the 4th component
+ *   wyvrnpm version --minor 3 --build 0  → multiple components, others left alone
+ *
+ * Positional and component flags are mutually exclusive — pick one mode.
+ * Bare invocation is read-only (never writes, never warns about an unset
+ * version on disk — it prints `(unset)` to stderr and exits 1 in that
+ * case so scripts notice). CI scripts use --format json to capture the
+ * `{ previous, version }` payload on stdout.
+ *
+ * @param {object} argv
+ */
+function versionCmd(argv) {
+  const manifestPath = path.resolve(argv.manifest);
+  const jsonOut = argv.format === 'json';
+  if (jsonOut) log.setJsonMode(true);
+
+  const positional = argv.newVersion;
+
+  // Component flags arrive on argv as `argv.major` / `argv.minor` / etc.
+  // because yargs lowercases option names. Keep insertion order so error
+  // messages list flags in the same order as the CLI surface.
+  const partial = {};
+  for (const key of Object.keys(COMPONENT_INDEX)) {
+    if (argv[key] !== undefined) partial[key] = argv[key];
+  }
+  const partialKeys = Object.keys(partial);
+
+  if (positional && partialKeys.length > 0) {
+    log.error(
+      'cannot combine a positional version with --major/--minor/--patch/--build. ' +
+      'Use one or the other.',
+    );
+    process.exit(1);
+  }
+
+  // Read-only mode: no positional + no component flags. Prints the current
+  // version and returns without touching disk. Matches `npm version` behaviour
+  // when called bare.
+  const readOnly = !positional && partialKeys.length === 0;
+
+  let manifest;
+  try {
+    manifest = readManifest(manifestPath);
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+
+  const previous =
+    typeof manifest.version === 'string' && manifest.version.length > 0
+      ? manifest.version
+      : null;
+
+  if (readOnly) {
+    const wyvrnpmVersion = require('../../package.json').version;
+    if (jsonOut) {
+      process.stdout.write(JSON.stringify({
+        command: 'version',
+        wyvrnpmVersion,
+        path:     manifestPath,
+        version:  previous,
+        written:  false,
+      }) + '\n');
+    } else if (previous) {
+      // Bare stdout for `VER=$(wyvrnpm version)` — no `[wyvrn]` prefix here.
+      process.stdout.write(previous + '\n');
+    } else {
+      log.error(`no \`version\` field in ${manifestPath}`);
+      process.exit(1);
+    }
+    return;
+  }
+
+  let newVersion;
+  if (positional) {
+    try {
+      parseVersion(positional);
+    } catch (err) {
+      log.error(err.message);
+      process.exit(1);
+    }
+    newVersion = positional;
+  } else {
+    let parts;
+    try {
+      parts = parseVersion(previous ?? '');
+    } catch (err) {
+      log.error(
+        `cannot tweak components — current manifest version is invalid or missing: ${err.message}\n` +
+        '  Set a full version first: wyvrnpm version <x.y.z.b>',
+      );
+      process.exit(1);
+    }
+    for (const key of partialKeys) {
+      const n = partial[key];
+      if (!isNonNegInt(n)) {
+        log.error(`--${key} must be a non-negative integer (got ${JSON.stringify(n)})`);
+        process.exit(1);
+      }
+      parts[COMPONENT_INDEX[key]] = n;
+    }
+    newVersion = parts.join('.');
+  }
+
+  const wyvrnpmVersion = require('../../package.json').version;
+
+  if (argv.dryRun) {
+    if (jsonOut) {
+      process.stdout.write(JSON.stringify({
+        command: 'version',
+        wyvrnpmVersion,
+        path:     manifestPath,
+        previous,
+        version:  newVersion,
+        dryRun:   true,
+        written:  false,
+      }) + '\n');
+    } else {
+      log.info(`would set version: ${previous ?? '(unset)'} → ${newVersion} (dry-run)`);
+    }
+    return;
+  }
+
+  manifest.version = newVersion;
+  writeManifest(manifestPath, manifest);
+
+  if (jsonOut) {
+    process.stdout.write(JSON.stringify({
+      command: 'version',
+      wyvrnpmVersion,
+      path:     manifestPath,
+      previous,
+      version:  newVersion,
+      dryRun:   false,
+      written:  true,
+    }) + '\n');
+  } else {
+    log.success(`${manifestPath}: ${previous ?? '(unset)'} → ${newVersion}`);
+  }
+}
+
+module.exports = versionCmd;
+module.exports.parseVersion = parseVersion;