wyvrnpm 2.14.1 → 2.15.0

package/README.md

@@ -4,7 +4,7 @@ A simple, private C++ package manager that works with any static file hosting pr
 
 There is no central registry. You control where packages are hosted.
 
-> **README version: 2.14.0** — **New:** npm self-update notifier — when a newer `wyvrnpm` is on the npm registry, the next interactive run prints a one-line `[wyvrn] warn  wyvrnpm <old> → <new> available` banner on stderr. The fetch happens in a detached background process so the user's command never blocks on the network; the banner appears on the *following* invocation after the cache (`%LOCALAPPDATA%\wyvrnpm\update-check.json`) is populated. Auto-suppressed in CI (`$CI`), non-TTY runs, and `--format json` mode; opt out via `WYVRNPM_NO_UPDATE_CHECK=1` or `--no-update-check`. Hand-rolled (~120 lines, zero new deps) instead of pulling in `update-notifier` and its 10+ transitives. Closes the gap where users on stale CLIs silently missed bug fixes (the `2.8.4` CloudFront cache-split fix and the `2.12.2` install-failure exit code, in particular). **Resolver caches `@latest` lookups** within a single `wyvrnpm install` — when a package is referenced as `@latest` from multiple parents in the dep graph (or already resolved earlier via a range), the registry round-trip is reused instead of re-probing `latest.json` per encounter. Eliminates ~12 redundant HTTPS round-trips on a typical 16-dep graph; visible win on resolution wall-time when the registry sits behind CloudFront. Closes the parallel gap to `manifestCache` / `publishedCache` — all three S3-backed helpers in `resolve.js` now memoise per-name within one install. **Per-config artefact slicing.** Recipes opt in via `build.publishPerConfig: true`; `wyvrnpm publish` then emits one `wyvrn-<Config>.zip` per declared CMake config under one `profileHash` URL instead of a single fat zip. Consumers fetch only the configs they need: `wyvrnpm install --request-configs Release` on a CI runner pulls 1.93 GB of gRPC instead of 14.96 GB across all four configs (~87% saving). Driven by CMake's own `*Targets-<config>.cmake` exports (`IMPORTED_LOCATION_<CONFIG>`) so both the MSVC convention (`lib/<Config>/foo.lib`) and the postfix convention (`lib/foo.lib` Release vs `lib/food.lib` Debug, via `CMAKE_DEBUG_POSTFIX`) classify correctly. `wyvrn.local.json` gains `requestConfigs` (global) + `depRequestConfigs` (per-dep override — "all four configs of fmt, but MinSizeRel of grpc"). Attestation v2 binds an `artefactSha256: { config → sha }` map; one signature covers every slice. `wyvrnpm publish --dry-run` materialises the would-be-uploaded artefacts to `<build>/dry-run-publish/` for inspection (override with `--dry-run-out`), and tolerates expired AWS credentials (the existence check degrades to `wouldOverwrite: null` instead of crashing). Highlights since 2.8.3: S1 artefact signing — Ed25519 detached signatures over a canonical attestation, verified against a per-registry `.trust/keys.json`; `wyvrnpm key gen / show-pub`, `wyvrnpm trust list / refresh`, `wyvrnpm configure signing set-default / show / unset`; `--require-signatures` on install, `--no-sign` / `--signing-key-env` / `--signing-key-file` on publish; pure-Node `crypto` (no external tooling, identical on Windows / Linux / macOS). Closes S1 + S3. Profile's `compiler.cppstd` is now authoritative for the toolchain — `CMAKE_CXX_STANDARD` is set unconditionally before `project()` and `cpp.cmake` no longer touches it post-`project()`, so a `-DCMAKE_CXX_STANDARD=23` on the cmake CLI cannot defeat a `cppstd=20` profile; `wyvrnpm install` exits non-zero on partial failure (sha256-mismatch, extract-failed, no-exact-match, source-build-failed, not-found) and prints a per-dep failure summary instead of misreporting "Done — N installed"; streaming publish via `archiver` (handles >2 GiB artefacts that `adm-zip` choked on — e.g. gRPC's `RelWithDebInfo` static libs); `--build-dir <path>` + `wyvrn.local.json:binaryDirRoot` to sidestep `build/` case-insensitive-FS collisions on repos with a Bazel/Buck `BUILD` file at the root (gRPC, …); `wyvrnpm version` to read / set / partially update the top-level `version` field from CI pipelines (`wyvrnpm version --build "$BUILD_ID"`); `wyvrnpm bootstrap <git-url>` to scaffold a first-draft `wyvrn.json` for OSS C++ libraries (fmt, spdlog, zlib, …) with cookbook-driven defaults; `wyvrnpm publish --dry-run` (npm-style preview of the upload plan, plus `wouldOverwrite` flag in `--format json`); `wyvrnpm build --config Debug,Release` / `--all-configs` to build multiple configurations from a single configure; resolver hardened against the CloudFront brotli-vs-identity cache split (resolved a class of bugs where `show` listed a freshly-published version that `install` claimed didn't exist). Full list in `claude/EVALUATION.md`.
+> **README version: 2.15.0** — **New:** `buildDependencies` block + `whenOption` gating — closes EVALUATION.md **F3** (`tool_requires` + `test_requires`). Recipes can now declare author-private deps (the asio / websocketpp / boost-internals case — header-only libs that compile into a `StaticLib` and aren't exposed by its public API; the protoc / flex / bison case — executables the build invokes at configure time) in a sibling block to `dependencies`. Buildable at the author's root and at source-build of a transitive, but **never walked transitively when a downstream consumer pulls the prebuilt binary** — they just get the lean runtime closure. `whenOption: "websocket"` (or `"api=legacy"`) gates a dep on a recipe-declared option value, evaluated at the seam where the package's effective options are known (root install + source-build). The combination also subsumes Conan's `test_requires`: declare `options.tests` and list gtest in `buildDependencies` with `whenOption: "tests"` — default `tests=false` skips it, `-o MyPkg:tests=true` opts in for that build, consumers of the prebuilt binary never see it either way. Mirrors Conan 2.0's `requires` / `tool_requires` split. Backward compat is automatic — old wyvrnpm clients ignore the unknown top-level field. `wyvrnpm show` surfaces both blocks per-profile so a publisher can verify what shipped. (Cross-compilation case — tool requires resolved under a *build* profile distinct from the *host* profile — stays open as F4, deferred pending a concrete cross-compilation user.) **New:** npm self-update notifier — when a newer `wyvrnpm` is on the npm registry, the next interactive run prints a one-line `[wyvrn] warn  wyvrnpm <old> → <new> available` banner on stderr. The fetch happens in a detached background process so the user's command never blocks on the network; the banner appears on the *following* invocation after the cache (`%LOCALAPPDATA%\wyvrnpm\update-check.json`) is populated. Auto-suppressed in CI (`$CI`), non-TTY runs, and `--format json` mode; opt out via `WYVRNPM_NO_UPDATE_CHECK=1` or `--no-update-check`. Hand-rolled (~120 lines, zero new deps) instead of pulling in `update-notifier` and its 10+ transitives. Closes the gap where users on stale CLIs silently missed bug fixes (the `2.8.4` CloudFront cache-split fix and the `2.12.2` install-failure exit code, in particular). **Resolver caches `@latest` lookups** within a single `wyvrnpm install` — when a package is referenced as `@latest` from multiple parents in the dep graph (or already resolved earlier via a range), the registry round-trip is reused instead of re-probing `latest.json` per encounter. Eliminates ~12 redundant HTTPS round-trips on a typical 16-dep graph; visible win on resolution wall-time when the registry sits behind CloudFront. Closes the parallel gap to `manifestCache` / `publishedCache` — all three S3-backed helpers in `resolve.js` now memoise per-name within one install. **Per-config artefact slicing.** Recipes opt in via `build.publishPerConfig: true`; `wyvrnpm publish` then emits one `wyvrn-<Config>.zip` per declared CMake config under one `profileHash` URL instead of a single fat zip. Consumers fetch only the configs they need: `wyvrnpm install --request-configs Release` on a CI runner pulls 1.93 GB of gRPC instead of 14.96 GB across all four configs (~87% saving). Driven by CMake's own `*Targets-<config>.cmake` exports (`IMPORTED_LOCATION_<CONFIG>`) so both the MSVC convention (`lib/<Config>/foo.lib`) and the postfix convention (`lib/foo.lib` Release vs `lib/food.lib` Debug, via `CMAKE_DEBUG_POSTFIX`) classify correctly. `wyvrn.local.json` gains `requestConfigs` (global) + `depRequestConfigs` (per-dep override — "all four configs of fmt, but MinSizeRel of grpc"). Attestation v2 binds an `artefactSha256: { config → sha }` map; one signature covers every slice. `wyvrnpm publish --dry-run` materialises the would-be-uploaded artefacts to `<build>/dry-run-publish/` for inspection (override with `--dry-run-out`), and tolerates expired AWS credentials (the existence check degrades to `wouldOverwrite: null` instead of crashing). Highlights since 2.8.3: S1 artefact signing — Ed25519 detached signatures over a canonical attestation, verified against a per-registry `.trust/keys.json`; `wyvrnpm key gen / show-pub`, `wyvrnpm trust list / refresh`, `wyvrnpm configure signing set-default / show / unset`; `--require-signatures` on install, `--no-sign` / `--signing-key-env` / `--signing-key-file` on publish; pure-Node `crypto` (no external tooling, identical on Windows / Linux / macOS). Closes S1 + S3. Profile's `compiler.cppstd` is now authoritative for the toolchain — `CMAKE_CXX_STANDARD` is set unconditionally before `project()` and `cpp.cmake` no longer touches it post-`project()`, so a `-DCMAKE_CXX_STANDARD=23` on the cmake CLI cannot defeat a `cppstd=20` profile; `wyvrnpm install` exits non-zero on partial failure (sha256-mismatch, extract-failed, no-exact-match, source-build-failed, not-found) and prints a per-dep failure summary instead of misreporting "Done — N installed"; streaming publish via `archiver` (handles >2 GiB artefacts that `adm-zip` choked on — e.g. gRPC's `RelWithDebInfo` static libs); `--build-dir <path>` + `wyvrn.local.json:binaryDirRoot` to sidestep `build/` case-insensitive-FS collisions on repos with a Bazel/Buck `BUILD` file at the root (gRPC, …); `wyvrnpm version` to read / set / partially update the top-level `version` field from CI pipelines (`wyvrnpm version --build "$BUILD_ID"`); `wyvrnpm bootstrap <git-url>` to scaffold a first-draft `wyvrn.json` for OSS C++ libraries (fmt, spdlog, zlib, …) with cookbook-driven defaults; `wyvrnpm publish --dry-run` (npm-style preview of the upload plan, plus `wouldOverwrite` flag in `--format json`); `wyvrnpm build --config Debug,Release` / `--all-configs` to build multiple configurations from a single configure; resolver hardened against the CloudFront brotli-vs-identity cache split (resolved a class of bugs where `show` listed a freshly-published version that `install` claimed didn't exist). Full list in `claude/EVALUATION.md`.
 
 ---
 

package/bin/wyvrnpm.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 'use strict';
 

package/package.json

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

package/src/build/index.js

@@ -9,7 +9,12 @@ const { normalizeRecipe, hasBuildRecipe } = require('./recipe');
 const { configureBuildInstall } = require('./cmake');
 const { getBuildPaths, hasValidArtefact } = require('./cache');
 
-const { normalizeDependencies } = require('../manifest');
+const {
+  normalizeDependencies,
+  normalizeManifestDeps,
+  validateWhenOption,
+  evaluateWhenOption,
+} = require('../manifest');
 const { resolveDependencies }   = require('../resolve');
 const { hashProfile, mergeProfile, sha256Of } = require('../profile');
 const { generateToolchain }     = require('../toolchain');
@@ -188,9 +193,51 @@ async function buildFromSource(args) {
   // eslint-disable-next-line global-require
   const { downloadDependencies } = require('../download');
 
-  const rawPackageDeps = normalizeDependencies(
-    clonedManifest.dependencies ?? clonedManifest.Dependencies,
-  );
+  // Read both runtime and author-private buildDependencies from the cloned
+  // source. The source-build sandbox needs both to compile (e.g. asio +
+  // websocketpp headers when building WyvrnIPC); the fetched buildDeps
+  // stay scoped to this sandbox's `wyvrn_internal/` and never propagate
+  // up to the outer install's lockfile or wyvrn_deps.cmake.
+  let depsByKind;
+  try {
+    depsByKind = normalizeManifestDeps(clonedManifest);
+  } catch (err) {
+    throw new Error(
+      `${name}@${version}: ${err.message} (in cloned wyvrn.json at ${gitSha.slice(0, 12)})`,
+    );
+  }
+  const { runtime: runtimeDeps, build: buildDeps } = depsByKind;
+
+  // Validate + filter whenOption against the source-build's effective
+  // options (passed in from the consumer's resolution as `args.options`).
+  const declarationForFilter = clonedManifest.options
+    ? normalizeOptionsDeclaration(clonedManifest.options, `${name}@${version}`)
+    : null;
+  for (const [depName, d] of Object.entries(runtimeDeps)) {
+    if (d.whenOption) {
+      validateWhenOption(d.whenOption, declarationForFilter, `${name}.dependencies.${depName}`);
+    }
+  }
+  for (const [depName, d] of Object.entries(buildDeps)) {
+    if (d.whenOption) {
+      validateWhenOption(d.whenOption, declarationForFilter, `${name}.buildDependencies.${depName}`);
+    }
+  }
+  const filterByWhenOption = (deps) => {
+    const out = {};
+    for (const [depName, d] of Object.entries(deps)) {
+      if (!d.whenOption || evaluateWhenOption(d.whenOption, options)) {
+        out[depName] = d;
+      } else {
+        log.info(`  ${depName}: skipped (whenOption "${d.whenOption}" not satisfied)`);
+      }
+    }
+    return out;
+  };
+  const rawPackageDeps = {
+    ...filterByWhenOption(runtimeDeps),
+    ...filterByWhenOption(buildDeps),
+  };
   const depsForResolution = Object.fromEntries(
     Object.entries(rawPackageDeps).map(([n, d]) => [n, d.version]),
   );

package/src/commands/install.js

@@ -3,7 +3,12 @@
 const fs   = require('fs');
 const path = require('path');
 
-const { normalizeDependencies }                             = require('../manifest');
+const {
+  normalizeDependencies,
+  normalizeManifestDeps,
+  validateWhenOption,
+  evaluateWhenOption,
+}                                                            = require('../manifest');
 const { resolveDependencies }                               = require('../resolve');
 const { downloadDependencies }                              = require('../download');
 const { resolveSigningContext }                             = require('../signing/resolve-context');
@@ -134,8 +139,76 @@ async function install(argv) {
   // and caches the result for the rest of this invocation.
   const manifest = ctx.manifest;
 
-  // Normalize to { name: { version, settings } }
-  const normalizedDeps = normalizeDependencies(manifest.dependencies ?? manifest.Dependencies);
+  // Pull both runtime `dependencies` and author-private `buildDependencies`.
+  // The latter feeds the root install (the author needs them to compile)
+  // and source-builds of this package as a transitive, but is never walked
+  // when a downstream consumer pulls the prebuilt binary — see resolve.js.
+  let depsByKind;
+  try {
+    depsByKind = normalizeManifestDeps(manifest);
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+  const { runtime: runtimeDeps, build: buildDeps } = depsByKind;
+
+  // Resolve the project's own effective options early. Needed for
+  // `whenOption` filtering of root deps, then reused below for the
+  // CMake preset's `${options.*}` substitution.
+  let projectDeclaration  = null;
+  let projectEffectiveOptions = null;
+  try {
+    projectDeclaration = manifest.options
+      ? normalizeOptionsDeclaration(manifest.options, manifest.name)
+      : null;
+    projectEffectiveOptions = resolveEffectiveOptions(
+      projectDeclaration, {}, cliOptionsByPkg[manifest.name] ?? {}, manifest.name,
+    );
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+
+  // Validate every `whenOption` against the project's declared options
+  // before resolving anything — surface authoring errors fast.
+  try {
+    for (const [name, d] of Object.entries(runtimeDeps)) {
+      if (d.whenOption) {
+        validateWhenOption(d.whenOption, projectDeclaration, `${manifest.name}.dependencies.${name}`);
+      }
+    }
+    for (const [name, d] of Object.entries(buildDeps)) {
+      if (d.whenOption) {
+        validateWhenOption(d.whenOption, projectDeclaration, `${manifest.name}.buildDependencies.${name}`);
+      }
+    }
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+
+  // Filter both blocks by whenOption. A dep whose condition is false is
+  // omitted from the resolver's queue — the consumer never pays the
+  // download / find_package cost, and the entry stays out of wyvrn.lock.
+  const filterByWhenOption = (deps, label) => {
+    const out = {};
+    for (const [name, d] of Object.entries(deps)) {
+      if (!d.whenOption || evaluateWhenOption(d.whenOption, projectEffectiveOptions)) {
+        out[name] = d;
+      } else {
+        log.info(`${name}: ${label} skipped (whenOption "${d.whenOption}" not satisfied)`);
+      }
+    }
+    return out;
+  };
+  const activeRuntimeDeps = filterByWhenOption(runtimeDeps, 'runtime');
+  const activeBuildDeps   = filterByWhenOption(buildDeps,   'buildDep');
+
+  // Combined view for resolver + downstream lookups. `buildDepNames`
+  // is the only side-channel — used to annotate lockfile entries with
+  // `kind: "build"` and to label log lines.
+  const normalizedDeps = { ...activeRuntimeDeps, ...activeBuildDeps };
+  const buildDepNames  = new Set(Object.keys(activeBuildDeps));
 
   // For resolution, only pass name → version (settings don't affect resolution)
   const depsForResolution = Object.fromEntries(
@@ -484,7 +557,15 @@ async function install(argv) {
   // ── Write v2 lock file ────────────────────────────────────────────────────
   const sortedPackages = {};
   for (const key of [...resolvedDeps.keys()].sort()) {
-    sortedPackages[key] = lockEntries?.get(key) ?? { version: resolvedDeps.get(key) };
+    const entry = lockEntries?.get(key) ?? { version: resolvedDeps.get(key) };
+    // Annotate root-level buildDependencies so `wyvrnpm show` / audits
+    // can distinguish runtime deps from author-private build deps.
+    // Runtime deps stay un-annotated so pre-feature lockfiles round-trip
+    // byte-identically.
+    if (buildDepNames.has(key) && entry && typeof entry === 'object' && !entry.kind) {
+      entry.kind = 'build';
+    }
+    sortedPackages[key] = entry;
   }
 
   const lockData = {
@@ -533,17 +614,11 @@ async function install(argv) {
   let presetConfigs = null;
   if (hasBuildRecipe(manifest)) {
     try {
-      // Resolve the project's own options to expand ${options.*} in its
-      // configure args. When the project declares no options, this is null
-      // and the recipe's configure / buildArgs must not contain templates
-      // (normalizeRecipe enforces that).
-      const projectDeclaration = manifest.options
-        ? normalizeOptionsDeclaration(manifest.options, manifest.name)
-        : null;
-      const projectCliOverrides = cliOptionsByPkg[manifest.name] ?? {};
-      const projectEffectiveOptions = resolveEffectiveOptions(
-        projectDeclaration, {}, projectCliOverrides, manifest.name,
-      );
+      // `projectEffectiveOptions` was already resolved at the top of the
+      // function (needed for whenOption filtering). Reuse it here for
+      // `${options.*}` substitution in `build.configure` / `build.buildArgs`
+      // — normalizeRecipe enforces that template references must match a
+      // declared option.
       const recipe = normalizeRecipe(manifest.build, projectEffectiveOptions, manifest);
 
       if (recipe.generators.length > 0) {

package/src/commands/show.js

@@ -170,6 +170,17 @@ async function show(argv) {
             if (meta?.options && Object.keys(meta.options).length > 0) {
               console.log(`      declared: ${formatDeclaredOptions(meta.options)}`);
             }
+            // Author-private buildDependencies (F-buildDeps). Surface both
+            // blocks so a publisher can confirm what shipped — runtime
+            // deps propagate to consumers, buildDeps don't. `whenOption`
+            // entries are annotated inline so it's obvious which deps are
+            // gated on an option value.
+            if (meta?.dependencies && Object.keys(meta.dependencies).length > 0) {
+              console.log(`      deps    : ${formatDeps(meta.dependencies)}`);
+            }
+            if (meta?.buildDependencies && Object.keys(meta.buildDependencies).length > 0) {
+              console.log(`      buildDeps: ${formatDeps(meta.buildDependencies)}`);
+            }
             // PLAN-CONF.md §4.6 — surface publisher's publishedConf.
             // Informational only; absent for pre-2.6.0 author publishes.
             if (meta?.publishedConf && Object.keys(meta.publishedConf).length > 0) {
@@ -193,6 +204,8 @@ async function show(argv) {
           uploadedBy:      meta?.uploadedBy    ?? null,
           compatibility:   meta?.compatibility ?? null,
           declaredOptions: meta?.options       ?? null,
+          dependencies:      meta?.dependencies      ?? null,
+          buildDependencies: meta?.buildDependencies ?? null,
           publishedConf:   meta?.publishedConf ?? null,
           signing,
         });
@@ -271,5 +284,18 @@ function formatDeclaredOptions(declared) {
     .join('; ');
 }
 
+function formatDeps(deps) {
+  return Object.entries(deps)
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([name, value]) => {
+      const ver  = typeof value === 'string' ? value : (value?.version ?? '?');
+      const when = (typeof value === 'object' && value?.whenOption)
+        ? ` [when ${value.whenOption}]`
+        : '';
+      return `${name}@${ver}${when}`;
+    })
+    .join(', ');
+}
+
 module.exports = show;
 module.exports.parseSpec = parseSpec;

package/src/manifest.js

@@ -54,21 +54,24 @@ function defaultManifest(name) {
 
 /**
  * Normalise the raw `dependencies` field from a manifest into a consistent
- * `{ name → { version, settings, options, source? } }` map, regardless of
- * input format:
+ * `{ name → { version, settings, options, source?, whenOption? } }` map,
+ * regardless of input format:
  *
- *   • String value  : "1.0.0"                                 → { version: "1.0.0", settings: {}, options: {} }
- *   • Object value  : { version, settings?, options?, source? } → kept (missing keys default to {})
- *   • Array format  : [{ Name, Version }]                      → converted (no settings/options)
+ *   • String value  : "1.0.0"                                            → { version: "1.0.0", settings: {}, options: {} }
+ *   • Object value  : { version, settings?, options?, source?, whenOption? } → kept (missing keys default to {})
+ *   • Array format  : [{ Name, Version }]                                → converted (no settings/options)
  *
  * `settings` merges on top of the active profile for this dep only.
  * `options` maps to the recipe's declared options; validated against
  * the recipe's `allowed` list at resolve time (see src/options.js).
  * `source` (EVALUATION.md S4) pins the dep to a named install source
  * (e.g. `"primary-s3"`); absent = fan out across all configured sources.
+ * `whenOption` (`"name"` or `"name=value"`) gates the dep on a recipe-
+ * declared option — see `evaluateWhenOption`. Validated against the
+ * package's `options` block by `validateWhenOption` at install time.
  *
  * @param {object|Array|undefined} rawDeps
- * @returns {Record<string, { version: string, settings: object, options: object, source?: string }>}
+ * @returns {Record<string, { version: string, settings: object, options: object, source?: string, whenOption?: string }>}
  */
 function normalizeDependencies(rawDeps) {
   if (!rawDeps || typeof rawDeps !== 'object') return {};
@@ -98,12 +101,141 @@ function normalizeDependencies(rawDeps) {
       if (typeof value.source === 'string' && value.source.length > 0) {
         entry.source = value.source;
       }
+      // Option-gated dep (F-buildDeps). Preserved verbatim here; structural
+      // validation lives in `validateWhenOption` because that's where we
+      // also know the package's declared options.
+      if (typeof value.whenOption === 'string' && value.whenOption.length > 0) {
+        entry.whenOption = value.whenOption;
+      }
       result[n] = entry;
     }
   }
   return result;
 }
 
+/**
+ * Pull both runtime `dependencies` and author-private `buildDependencies`
+ * out of a manifest, normalised through `normalizeDependencies`. A package
+ * name MUST NOT appear in both blocks — that's a hard authoring error
+ * (no sensible meaning for "both runtime and build-only").
+ *
+ * `buildDependencies` are deps the package needs to compile itself but
+ * that consumers of the prebuilt binary do not need transitively. The
+ * resolver walks them at the root (and at source-build of a transitive
+ * dep) but never when reading an upstream manifest's transitive graph
+ * — see [src/resolve.js](resolve.js). Backward compat with old wyvrnpm
+ * clients is automatic: they only read `dependencies`.
+ *
+ * @param {object} manifest - parsed wyvrn.json
+ * @returns {{
+ *   runtime: Record<string, object>,
+ *   build:   Record<string, object>,
+ * }}
+ */
+function normalizeManifestDeps(manifest) {
+  const runtime = normalizeDependencies(
+    manifest?.dependencies ?? manifest?.Dependencies,
+  );
+  const build = normalizeDependencies(manifest?.buildDependencies);
+  for (const name of Object.keys(build)) {
+    if (name in runtime) {
+      throw new Error(
+        `"${name}" appears in both \`dependencies\` and \`buildDependencies\` — ` +
+        `pick one. Runtime deps propagate to consumers; buildDependencies do not.`,
+      );
+    }
+  }
+  return { runtime, build };
+}
+
+/**
+ * Parse a `whenOption` spec into `{ name, value }`. Bare `"foo"` is
+ * sugar for `"foo=true"`. Throws on malformed input. Pure structural
+ * parser — does not validate against a package's option declaration;
+ * use `validateWhenOption` for that.
+ *
+ * @param {string} spec
+ * @returns {{ name: string, value: string|boolean }}
+ */
+function parseWhenOption(spec) {
+  if (typeof spec !== 'string' || spec.length === 0) {
+    throw new Error('whenOption must be a non-empty string');
+  }
+  const eqIdx = spec.indexOf('=');
+  if (eqIdx === -1) {
+    if (!/^[a-z][a-z0-9_-]*$/.test(spec)) {
+      throw new Error(
+        `whenOption "${spec}" is malformed — option name must match /^[a-z][a-z0-9_-]*$/`,
+      );
+    }
+    return { name: spec, value: true };
+  }
+  const name = spec.slice(0, eqIdx);
+  const raw  = spec.slice(eqIdx + 1);
+  if (!/^[a-z][a-z0-9_-]*$/.test(name)) {
+    throw new Error(
+      `whenOption "${spec}" is malformed — option name must match /^[a-z][a-z0-9_-]*$/`,
+    );
+  }
+  if (raw.length === 0) {
+    throw new Error(`whenOption "${spec}" has empty value after "="`);
+  }
+  const lc = raw.toLowerCase();
+  if (lc === 'true')  return { name, value: true };
+  if (lc === 'false') return { name, value: false };
+  return { name, value: raw };
+}
+
+/**
+ * Validate a dep's `whenOption` against the owning package's normalised
+ * options declaration. Throws on:
+ *   - structural error in the spec,
+ *   - referenced option name not in the declaration,
+ *   - compared value not in the option's `allowed` list.
+ *
+ * @param {string} spec - the whenOption string
+ * @param {object|null} optionsDecl - normalised options (from src/options.js)
+ * @param {string} where - context for error messages ("WyvrnIPC.dependencies.websocketpp")
+ * @returns {{ name: string, value: any }}
+ */
+function validateWhenOption(spec, optionsDecl, where) {
+  const parsed = parseWhenOption(spec);
+  if (!optionsDecl || !(parsed.name in optionsDecl)) {
+    const declared = optionsDecl ? Object.keys(optionsDecl).join(', ') : '(none)';
+    throw new Error(
+      `whenOption on ${where} references option "${parsed.name}" which is not declared.\n` +
+      `  declared options: ${declared}`,
+    );
+  }
+  const allowed = optionsDecl[parsed.name].allowed;
+  if (!allowed.includes(parsed.value)) {
+    throw new Error(
+      `whenOption on ${where} compares ${parsed.name} = ${JSON.stringify(parsed.value)}, ` +
+      `which is not in allowed: ${JSON.stringify(allowed)}`,
+    );
+  }
+  return parsed;
+}
+
+/**
+ * Evaluate a `whenOption` spec against a resolved options map.
+ * Returns true (include the dep) when the option's resolved value
+ * matches the spec's compared value.
+ *
+ * Pre-validated: callers should run `validateWhenOption` once to
+ * surface authoring errors — `evaluateWhenOption` is the per-install
+ * runtime decision and assumes structurally valid input.
+ *
+ * @param {string} spec
+ * @param {Record<string, any>|null} effectiveOptions
+ * @returns {boolean}
+ */
+function evaluateWhenOption(spec, effectiveOptions) {
+  const parsed = parseWhenOption(spec);
+  const actual = effectiveOptions?.[parsed.name];
+  return actual === parsed.value;
+}
+
 /**
  * Reads and parses a wyvrn.json manifest from disk.
  *
@@ -160,6 +292,10 @@ module.exports = {
   VALID_KINDS,
   defaultManifest,
   normalizeDependencies,
+  normalizeManifestDeps,
+  parseWhenOption,
+  validateWhenOption,
+  evaluateWhenOption,
   readManifest,
   writeManifest,
 };