wyvrnpm 2.0.2 → 2.1.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.0.1** — Last updated to reflect the v2 build-profile system.
+> **README version: 2.1.0** — Adds CMake toolchain generation, the `wyvrnpm build` command, declarative compatibility, and `--build=missing` source-build.
 
 ---
 
@@ -40,10 +40,13 @@ wyvrnpm configure profile detect
 # 4. Install dependencies (resolved against your build profile)
 wyvrnpm install
 
-# 5. Publish your package (uses the active profile automatically)
+# 5. Configure and build via the generated CMake preset
+wyvrnpm build
+
+# 6. Publish your package (uses the active profile automatically)
 wyvrnpm publish
 
-# 6. (Optional) Link local packages for development
+# 7. (Optional) Link local packages for development
 cd ../my-local-lib && wyvrnpm link
 cd ../my-app && wyvrnpm link my-local-lib
 ```
@@ -112,7 +115,14 @@ Resolves the full dependency graph and downloads all packages.
 
 **Source priority:** CLI `--source` values are used if provided. If omitted, sources are loaded from the [configuration file](#configuration-file).
 
-**Profile resolution:** `--profile` selects the named build profile. If omitted, `config.defaultProfile` is used, falling back to `"default"`. v2 binaries are matched first by exact profile hash; if no exact match is found, the tool looks for a compatible build (same OS + arch, any compiler), then falls back to the v1 legacy path.
+**Profile resolution:** `--profile` selects the named build profile. If omitted, `config.defaultProfile` is used, falling back to `"default"`. v2 binaries are resolved in this order:
+
+1. **Exact profile-hash match** — the preferred path.
+2. **Declarative compatibility** — each published build may advertise a `compatibility` block (e.g. "compatible with any `msvc.version ≥ 193` on `Windows/x86_64`"). The best compatible candidate is picked deterministically.
+3. **Source build** (with `--build=missing`) — clones the package's source at the published `gitSha`, resolves its own dependencies, invokes CMake through the shared toolchain generator, and caches the result under `%LOCALAPPDATA%\wyvrnpm\bc\`. On Windows/MSVC with a Ninja or Make generator, `vcvarsall.bat` is auto-activated.
+4. **v1 legacy path** — only when no v2 entry exists for the package at all.
+
+The pre-2.1 "same OS + arch, any compiler" loose fallback is removed from the default path. It remains reachable for one release cycle via `WYVRNPM_ALLOW_LOOSE_COMPAT=1` and prints a deprecation warning.
 
 ```bash
 # Use configured sources and the default build profile
@@ -128,6 +138,9 @@ wyvrnpm install --source https://pkg.example.com/cpp
 wyvrnpm install \
   --source https://primary.example.com/cpp \
   --source https://mirror.example.com/cpp
+
+# Build any missing binary from source
+wyvrnpm install --build=missing
 ```
 
 **Options**
@@ -136,6 +149,7 @@ wyvrnpm install \
 |---|---|---|
 | `--source` / `-s` | *(config)* | Base URL of a package source. Repeat for multiple. Overrides config when provided. |
 | `--profile` / `-p` | *(config / "default")* | Named build profile to use for v2 binary resolution. |
+| `--build` | `never` | Resolution mode when no exact or compatible profile match exists: `never` fails; `missing` clones and builds the package from its published `gitRepo@gitSha`; `always` rebuilds even when a binary exists. |
 | `--platform` | `win_x64` | v1 legacy platform sub-path (used as a fallback when no v2 binary is found). |
 | `--timeout` | `300` | HTTP request timeout in seconds. |
 | `--manifest` | `./wyvrn.json` | Path to the manifest file. |
@@ -143,6 +157,66 @@ wyvrnpm install \
 
 Packages are extracted to `wyvrn_internal/{name}/`. A `wyvrn.lock` file is written alongside the manifest recording the exact resolved versions, profile, and per-package SHA256. On subsequent installs the lock file pins all previously resolved versions — only newly added dependencies are resolved fresh.
 
+After download, `install` also generates:
+
+- `wyvrn_internal/wyvrn_toolchain.cmake` — CMake toolchain pointing at the resolved packages.
+- `wyvrn_internal/wyvrn_deps.cmake` — post-`project()` include for `find_package()` wiring and runtime DLL copy.
+- `wyvrn_internal/wyvrn_profile.json` — snapshot of the active build profile.
+- `CMakePresets.json` (or `CMakeUserPresets.json` if the project root file is user-owned) with a `wyvrn-<profile>` configure preset. Presets for other profiles are preserved so multiple profiles coexist.
+
+---
+
+### `wyvrnpm build`
+
+Configures and builds the project through the wyvrnpm-generated CMake preset. Auto-runs `install` first if `wyvrn_toolchain.cmake` is missing or `wyvrn.lock` is newer than it.
+
+```bash
+# Configure + build with the default profile's preset (wyvrn-default)
+wyvrnpm build
+
+# Build Debug, verbose compiler output
+wyvrnpm build --config Debug --verbose
+
+# Use a specific profile's preset
+wyvrnpm build --profile release
+
+# Explicit preset name (overrides profile-derived default)
+wyvrnpm build --preset wyvrn-release
+
+# Build a single target
+wyvrnpm build --target my-lib
+
+# Wipe the build directory first
+wyvrnpm build --clean
+
+# Build, then install to the CMake install prefix
+wyvrnpm build --install
+wyvrnpm build --install --install-prefix C:\out\stage
+
+# Skip the auto-install step
+wyvrnpm build --no-auto-install
+
+# Pass extra args through to cmake --build
+wyvrnpm build -- -j 8
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--preset` / `-P` | `wyvrn-<profile>` | CMake configure preset name. |
+| `--profile` / `-p` | *(config / "default")* | Build profile — determines the default preset name. |
+| `--config` / `-c` | `Release` | Build configuration (`Debug` \| `Release` \| `RelWithDebInfo` \| `MinSizeRel`). |
+| `--target` / `-t` | *(all)* | Specific CMake target to build. |
+| `--verbose` / `-v` | `false` | Pass `--verbose` to `cmake --build`. |
+| `--clean` | `false` | Remove the build directory before configuring. |
+| `--install` | `false` | Run `cmake --install` after a successful build. |
+| `--install-prefix` | *(baked in)* | Override `CMAKE_INSTALL_PREFIX` for `--install` without reconfiguring. |
+| `--auto-install` | `true` | Auto-run `wyvrnpm install` when the toolchain is stale. Disable with `--no-auto-install`. |
+| `--source` / `-s` | *(config)* | Package sources — passed through to `install` when auto-installing. |
+
+Everything after `--` is forwarded verbatim to `cmake --build` (e.g. `-j 8`).
+
 ---
 
 ### `wyvrnpm publish`
@@ -221,9 +295,19 @@ build/
 Removes the `wyvrn_internal/` package cache and `wyvrn.lock`.
 
 ```bash
+# Project-local cleanup
 wyvrnpm clean
+
+# Also wipe the machine-wide source-build cache used by --build=missing
+wyvrnpm clean --build-cache
 ```
 
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--build-cache` | `false` | Also remove the source-build cache under `%LOCALAPPDATA%\wyvrnpm\bc\` (Unix: `~/.cache/wyvrnpm/bc/`). |
+
 ---
 
 ### `wyvrnpm link`
@@ -651,6 +735,203 @@ Fields use PascalCase. `Dependencies` is an array — transitive dependencies ar
 
 **`dependencies`** can be either a plain version string (`"major.minor.patch.build"`) or an object with `version` and an optional `settings` map. The `settings` map overrides individual build profile fields for that specific dependency — useful when a dependency must be consumed with a different runtime linkage or C++ standard than your default profile.
 
+### Source-build recipe (`build`)
+
+A library package may include an optional `build` section that tells `wyvrnpm install --build=missing` how to rebuild it from source. Only `system: "cmake"` is supported today.
+
+```json
+{
+  "name": "zlib",
+  "version": "1.3.0.0",
+  "kind": "StaticLib",
+  "build": {
+    "system":       "cmake",
+    "generator":    ["Ninja", "Visual Studio 17 2022"],
+    "configs":      ["Release", "Debug"],
+    "configure":    ["-DZLIB_BUILD_EXAMPLES=OFF"],
+    "buildArgs":    ["--parallel"],
+    "installDir":   "install",
+    "sourceSubdir": "."
+  }
+}
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `system` | `cmake` | Build system. Only `cmake` is supported. |
+| `generator` | *(CMake default)* | Single generator (`"Ninja"`) or an array tried in order — first available wins. |
+| `configs` | `["Debug","Release","RelWithDebInfo","MinSizeRel"]` | CMake configurations to build and install. |
+| `configure` | `[]` | Extra args appended to `cmake` at configure time. |
+| `buildArgs` | `[]` | Extra args appended to `cmake --build`. |
+| `installDir` | `install` | Install prefix relative to the binary dir. |
+| `sourceSubdir` | `.` | Where `CMakeLists.txt` lives relative to the clone root. |
+| `requiredTools` | `[]` | Tools that must be on `PATH` before the build starts (fail-fast check). |
+
+On Windows with MSVC and a non-Visual-Studio generator (Ninja, Make), `vcvarsall.bat` is auto-activated for the spawned CMake process — no need to launch from a Developer Prompt.
+
+---
+
+## Compatibility Rules
+
+Publishers declare an optional `compatibility` block in a package's `wyvrn.json`. It tells wyvrnpm which profile fields must match the consumer's profile exactly, and which may legitimately differ without breaking ABI. When no exact `profileHash` match exists on the registry, `install` evaluates this block against every published build for the requested `(name, version)` and picks the best compatible candidate.
+
+### Block format
+
+Each field maps to a mode — either as a string shorthand or an object:
+
+```json
+{
+  "name": "zlib",
+  "version": "1.3.0.0",
+  "compatibility": {
+    "compiler.cppstd":  "lte",
+    "compiler.runtime": "exact",
+    "compiler.version": "exact-or-newer"
+  }
+}
+```
+
+Object form is accepted too (`{ "mode": "lte" }`) and leaves room for future per-field options.
+
+### Supported modes
+
+| Mode | Meaning |
+|---|---|
+| `exact` | Package and consumer values must be equal. |
+| `any` | Field is ignored for compatibility purposes. |
+| `lte` | Package value ≤ consumer value — e.g. a `cppstd=20` package is usable by a `cppstd=23` consumer. |
+| `gte` | Package value ≥ consumer value (symmetry; rarely useful). |
+| `exact-or-newer` | Same as `lte` at MVP — kept as a distinct name because it reads naturally for compiler-version fields. |
+
+**Defaults:**
+
+- Any field not listed is treated as `exact`.
+- `os` and `arch` are **always `exact`** regardless of what the block says. Cross-OS / cross-arch binaries are never ABI-compatible.
+
+### Where to author it
+
+The block lives in the **source** `wyvrn.json` (the one you commit). It is read at publish time and written into the uploaded manifest. If the source `wyvrn.json` has no `compatibility` block, `wyvrnpm publish` injects a conservative default (all fields `exact`) so existing packages behave strict-by-default.
+
+Consumers never author compatibility — it is a property of the published package.
+
+### Tiebreaker
+
+When multiple published builds satisfy the consumer's profile, the winner is picked deterministically:
+
+1. Prefer the candidate whose `compiler` matches the consumer's.
+2. Prefer the highest numeric `compiler.version`.
+3. Prefer the candidate whose `compiler.runtime` matches the consumer's.
+4. Fall back to the lexicographically earliest `profileHash`.
+
+The chosen candidate is logged along with a per-field summary (e.g. `compiler.cppstd 20→23 (lte), compiler.runtime=dynamic`).
+
+### Legacy loose fallback
+
+The pre-2.1 "same OS + arch, any compiler" fallback is removed from the default resolution path. For one release cycle it remains reachable via an env var:
+
+```bash
+WYVRNPM_ALLOW_LOOSE_COMPAT=1 wyvrnpm install
+```
+
+This prints a deprecation warning every time it fires and will be removed in the next minor release. Prefer adding a real `compatibility` block to affected packages, or rebuilding with `--build=missing`.
+
+---
+
+## Source Builds
+
+`wyvrnpm install --build=missing` clones a package's source at its published `gitSha` and builds it locally when no prebuilt binary matches (exact or compatible) the consumer's profile. This is the Conan-2.0 `--build=missing` parity feature.
+
+### When it fires
+
+1. You run `wyvrnpm install --build=missing`.
+2. For each dependency, wyvrnpm tries `v2 exact → v2 compat` first.
+3. If neither hits, it looks up `gitRepo` + `gitSha` from **any** existing build of the same `(name, version)` on the registry (they are equal across profiles for a given version).
+4. It clones, resolves the package's own transitive deps, invokes CMake through the shared toolchain generator, zips the install dir, and treats the result as a v2 download.
+
+If the package has no prior publish on the registry at all, there is no `gitSha` to clone — source-build fails fast with a clear error. Source-builds cascade transitively: if package A needs source-build and depends on package B which also needs source-build, both are built.
+
+### Authoring the `build` recipe
+
+Libraries that want to be source-buildable declare a `build` section in their own `wyvrn.json`. See [Project Manifest §Source-build recipe](#source-build-recipe-build) for the field list. Only `system: "cmake"` is supported today.
+
+### Generator fallback
+
+`build.generator` accepts either a string or an array:
+
+| Form | Behaviour |
+|---|---|
+| `"Ninja"` | Strict — fails if Ninja is not available. |
+| `["Ninja", "Visual Studio 17 2022"]` | Tried in order — first available wins. Unknown entries are trusted (CMake decides at configure time). |
+| *(omitted)* | Uses CMake's platform default. |
+
+### MSVC environment auto-activation (Windows)
+
+On Windows, when **all** of the following hold:
+
+- `profile.compiler === "msvc"`
+- The chosen generator is **not** a Visual Studio generator (e.g. Ninja, Make)
+- `cl.exe` is not on `PATH`
+
+…wyvrnpm locates Visual Studio via `vswhere.exe`, runs `vcvarsall.bat <arch>` in a sub-shell, captures the resulting environment, and uses it for the CMake spawn. You do not need to launch from a Developer Prompt.
+
+Arch mapping follows the active profile:
+
+| `profile.arch` | `vcvarsall` arg |
+|---|---|
+| `x86_64` | `x64` |
+| `x86` | `x86` |
+| `armv8` | `arm64` |
+| `armv7` | `arm` |
+
+VS generators skip this path entirely — MSBuild resolves MSVC itself.
+
+### Cache
+
+Source builds are cached machine-wide, keyed by `(name, version, profileHash)`:
+
+| Platform | Path |
+|---|---|
+| Windows | `%LOCALAPPDATA%\wyvrnpm\bc\{name}-{version}-{profileHash}\` |
+| Linux / macOS | `~/.cache/wyvrnpm/bc/{name}-{version}-{profileHash}/` |
+
+Re-running `install --build=missing` with the same inputs short-circuits to the cached artefact. The cache root is deliberately shallow (`bc/`, not `build-cache/`) to keep nested CMake paths under Windows' 260-char limit.
+
+Clone behaviour is tri-tier:
+
+1. **Shallow-SHA fetch** (`git fetch origin <sha> --depth=1`) — fastest; works when the git server allows it.
+2. **Full fetch** — falls back to a full `git clone --tags` when the server rejects shallow-SHA (older Bitbucket installs disable `uploadpack.allowReachableSHA1InWant`).
+3. **Rebuild from scratch** — if the cached clone is broken, wipes and retries.
+
+After every clone/fetch, wyvrnpm runs `git cat-file -e <sha>^{commit}` to verify the SHA is actually reachable. If it is not, the error points at the likely cause: the publisher forgot to push before running `wyvrnpm publish`.
+
+### Publish-time guard
+
+To catch the unpushed-commit case before consumers hit it, `wyvrnpm publish` checks whether the current `HEAD` is reachable from any remote branch or tag and warns if it is not:
+
+```
+[wyvrn] warn: git SHA abc1234 is not on origin — source-build consumers will fail until pushed
+```
+
+The warning does **not** block publishing.
+
+### Header-only libraries
+
+`kind: "HeaderOnlyLib"` packages still need a `build` section and a CMake `install()` rule that copies headers. There is no fast-path that zips the source tree directly — consumers get exactly what the `install()` step produces, same as any other kind.
+
+### Clearing the cache
+
+```bash
+# Remove the project-local cache (wyvrn_internal/ + wyvrn.lock)
+wyvrnpm clean
+
+# Also wipe the machine-wide source-build cache
+wyvrnpm clean --build-cache
+```
+
+### Credentials for private repos
+
+wyvrnpm uses your ambient git configuration (SSH keys, credential helpers, Windows Credential Manager). It does not manage git credentials itself. If `git clone <gitRepo>` works from your shell, source-build works.
+
 ---
 
 ## Lock File (wyvrn.lock)
@@ -687,6 +968,103 @@ Locked versions always take priority over transitive requests. A warning is prin
 
 ---
 
+## CMake Integration
+
+`wyvrnpm install` emits a ready-to-use CMake toolchain alongside the downloaded packages. Most projects only need to run:
+
+```bash
+wyvrnpm install
+wyvrnpm build
+```
+
+…which is equivalent to:
+
+```bash
+cmake --preset wyvrn-default
+cmake --build build/wyvrn-default --config Release
+```
+
+**Generated files (inside the project)**
+
+| Path | Purpose |
+|---|---|
+| `wyvrn_internal/wyvrn_toolchain.cmake` | Toolchain file — sets `CMAKE_PREFIX_PATH`, compiler/runtime, and standards from the active profile. Include via the preset or `-DCMAKE_TOOLCHAIN_FILE=…`. |
+| `wyvrn_internal/wyvrn_deps.cmake` | Include **after** `project()` (e.g. `include(${CMAKE_BINARY_DIR}/../wyvrn_internal/wyvrn_deps.cmake)`). Wires `find_package()` calls and defines `wyvrnpm_finalize_targets(<tgt>…)` for runtime DLL copy next to your executable. |
+| `wyvrn_internal/wyvrn_profile.json` | Snapshot of the profile the toolchain was generated against. |
+| `CMakePresets.json` / `CMakeUserPresets.json` | `wyvrn-<profile>` configure preset. Regenerating preserves other profiles' presets. |
+
+**Bundled CMake utilities** (shipped in the npm tarball under `cmake/`) are auto-included by `wyvrn_toolchain.cmake`:
+
+| File | Provides |
+|---|---|
+| `cpp.cmake` | C++ standard defaults (guarded — toolchain wins). |
+| `variables.cmake` | Platform detection (`WYVRN_PLATFORM_WIN`, …) and compiler flags. |
+| `options.cmake` | Feature toggles (`WYVRN_ENABLE_LOG`, …). |
+| `functions.cmake` | `SETUP_LIBRARY` / `SETUP_EXE` plus HAL source-collection helpers. |
+| `macros.cmake` | `WYVRN_INSTALL_MODULE`, `WYVRN_CONFIGURE_VERSION_HEADER`. |
+
+**Minimal `CMakeLists.txt`:**
+
+```cmake
+cmake_minimum_required(VERSION 3.21)
+project(my-app CXX)
+
+include(${CMAKE_SOURCE_DIR}/wyvrn_internal/wyvrn_deps.cmake)
+
+add_executable(my-app src/main.cpp)
+target_link_libraries(my-app PRIVATE OpenSSL::SSL zlib::zlib)
+
+wyvrnpm_finalize_targets(my-app)   # copies runtime DLLs next to the .exe
+```
+
+---
+
+## Installing Build Artifacts (`wyvrnpm build --install`)
+
+`wyvrnpm build --install` runs `cmake --install <binaryDir>` after a successful build, invoking every `install()` rule in your `CMakeLists.txt`. This is the step that produces a redistributable layout (headers + libs + runtime files in a tidy tree) rather than the raw CMake build directory.
+
+### Typical use
+
+```bash
+# Configure, build, and install to the default prefix (baked in at configure time)
+wyvrnpm build --install
+
+# Override the install prefix without reconfiguring
+wyvrnpm build --install --install-prefix C:\out\stage
+
+# Install a specific config
+wyvrnpm build --install --config Debug
+```
+
+### What it does, in order
+
+1. **Staleness check** — if `wyvrn_internal/wyvrn_toolchain.cmake` is missing or `wyvrn.lock` is newer than it, auto-runs `wyvrnpm install` first. Disable with `--no-auto-install`.
+2. **Optional clean** — `--clean` wipes the build directory before configuring.
+3. **Configure** — `cmake --preset wyvrn-<profile>` (or the value of `--preset`).
+4. **Build** — `cmake --build <binaryDir> --config <config>`.
+5. **Install** — `cmake --install <binaryDir> --config <config> [--prefix <install-prefix>]`.
+
+### `--auto-install` vs `--install`
+
+These two flags are easy to confuse — they control unrelated things:
+
+| Flag | What it does | When it runs |
+|---|---|---|
+| `--auto-install` *(default: on)* | Runs `wyvrnpm install` if the toolchain is stale. Disable with `--no-auto-install`. | **Before** configure. |
+| `--install` *(default: off)* | Runs `cmake --install` after a successful build. | **After** build. |
+
+### `--install-prefix`
+
+CMake bakes `CMAKE_INSTALL_PREFIX` into the build cache at configure time. Passing `--install-prefix` at install time uses `cmake --install --prefix <path>` to override the baked value **without** re-running configure — cheaper than a full reconfigure when you only want to stage to a different location.
+
+If you omit `--install-prefix`, the baked default is used. The baked default comes from the generated preset, typically under `build/wyvrn-<profile>/install`.
+
+### Permissions
+
+Installing to a system path (`/usr/local`, `C:\Program Files`) requires the usual elevated permissions — wyvrnpm does not auto-elevate. For staging or packaging, point `--install-prefix` at a writable user directory instead.
+
+---
+
 ## Version Conflict Resolution
 
 When the dependency graph requires the same package at multiple versions, the highest version wins. If a `wyvrn.lock` exists, locked versions always take priority over any conflicting transitive request. A warning is printed for every conflict detected.

package/bin/wyvrn.js

@@ -9,9 +9,11 @@ const clean     = require('../src/commands/clean');
 const publish   = require('../src/commands/publish');
 const configure = require('../src/commands/configure');
 const profile   = require('../src/commands/profile');
+const build     = require('../src/commands/build');
 const { link, unlink } = require('../src/commands/link');
 
 yargs
+  .parserConfiguration({ 'populate--': true })
   .option('manifest', {
     type: 'string',
     description: 'Path to manifest file',
@@ -48,6 +50,14 @@ yargs
           type: 'string',
           description: 'Build profile name to use (default: config.defaultProfile → "default")',
         })
+        .option('build', {
+          type: 'string',
+          choices: ['never', 'missing', 'always'],
+          default: 'never',
+          description:
+            'Resolution mode when no exact profile match exists. ' +
+            'never=fail; missing=build from source (pending phase 3); always=rebuild (pending phase 3)',
+        })
         .option('platform', {
           type: 'string',
           description: 'v1 legacy platform path (used as fallback if v2 not found)',
@@ -63,12 +73,95 @@ yargs
     (argv) => install(argv),
   )
 
+  // ── build ─────────────────────────────────────────────────────────────────
+  .command(
+    'build',
+    'Configure and build the project via the wyvrnpm-generated CMake preset. ' +
+    'Auto-runs `install` if the toolchain is missing or stale.',
+    (y) => {
+      y
+        .option('preset', {
+          alias: 'P',
+          type: 'string',
+          description: 'CMake configure preset name (default: wyvrn-<profile>)',
+        })
+        .option('profile', {
+          alias: 'p',
+          type: 'string',
+          description: 'Build profile name — determines the default preset',
+        })
+        .option('config', {
+          alias: 'c',
+          type: 'string',
+          choices: ['Debug', 'Release', 'RelWithDebInfo', 'MinSizeRel'],
+          default: 'Release',
+          description: 'Build configuration',
+        })
+        .option('target', {
+          alias: 't',
+          type: 'string',
+          description: 'CMake target to build (default: all)',
+        })
+        .option('verbose', {
+          alias: 'v',
+          type: 'boolean',
+          default: false,
+          description: 'Pass --verbose to cmake --build (detailed compiler output)',
+        })
+        .option('clean', {
+          type: 'boolean',
+          default: false,
+          description: 'Remove the build directory before configuring',
+        })
+        .option('install', {
+          type: 'boolean',
+          default: false,
+          description: 'Run `cmake --install` after the build (installs to the prefix baked at configure time, or --install-prefix)',
+        })
+        .option('install-prefix', {
+          type: 'string',
+          description: 'Override CMAKE_INSTALL_PREFIX for `--install` without reconfiguring',
+        })
+        .option('auto-install', {
+          type: 'boolean',
+          default: true,
+          description: 'Auto-run `wyvrnpm install` when the toolchain is stale. Disable with --no-auto-install.',
+        })
+        .option('source', {
+          alias: 's',
+          type: 'string',
+          array: true,
+          description: 'Package source(s) — passed through to `install` when auto-installing',
+        })
+        .option('platform', {
+          type: 'string',
+          choices: ['win_x64', 'win_x86', 'linux_x64', 'linux_x86', 'osx_x64', 'osx_arm64'],
+          default: 'win_x64',
+        })
+        .option('timeout', {
+          type: 'number',
+          default: 300,
+        });
+    },
+    (argv) => build({
+      ...argv,
+      autoInstall:   argv['auto-install'],
+      installPrefix: argv['install-prefix'],
+    }),
+  )
+
   // ── clean ─────────────────────────────────────────────────────────────────
   .command(
     'clean',
-    'Remove downloaded packages and lock file',
-    () => {},
-    (argv) => clean(argv),
+    'Remove downloaded packages and lock file. --build-cache also wipes the machine-wide source-build cache.',
+    (y) => {
+      y.option('build-cache', {
+        type: 'boolean',
+        default: false,
+        description: 'Also remove the source-build cache under %LOCALAPPDATA%\\wyvrnpm\\bc\\',
+      });
+    },
+    (argv) => clean({ ...argv, buildCache: argv['build-cache'] }),
   )
 
   // ── publish ───────────────────────────────────────────────────────────────

package/cmake/cpp.cmake

@@ -0,0 +1,9 @@
+# Define the cpp information ( version, compilation type, thread type, exception handling )
+# Set a C++20 default only if the consumer (or wyvrnpm's toolchain) has not
+# already chosen a standard — the toolchain sets CMAKE_CXX_STANDARD from the
+# active build profile before project(), and that explicit choice must win.
+if(NOT DEFINED CMAKE_CXX_STANDARD)
+    set(CMAKE_CXX_STANDARD 20)
+    set(CMAKE_CXX_STANDARD_REQUIRED True)
+endif()
+set(CMAKE_EXPERIMENTAL_CXX_MODULE_CMAKE_API OFF)