wyvrnpm 2.3.2 → 2.4.1

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.1.0** — Adds CMake toolchain generation, the `wyvrnpm build` command, declarative compatibility, and `--build=missing` source-build.
+> **README version: 2.4.0** — Highlights since 2.1.0: `wyvrnpm add <name>` for dependency authoring, `HeaderOnlyLib` packages that survive cross-arch `find_package()`, `WYVRN_ARCH_SUFFIX` + the `WYVRN_APPLY_ARCH_SUFFIX(<target>)` helper so x64/x86 artefacts coexist on disk, `wyvrnpm build --generator / -G` to swap CMake generators from the CLI, package `options`, version ranges (`^`, `~`, explicit comparators), `--format=json` output, and `--upload-built` to warm the registry with source-built artefacts.
 
 ---
 
@@ -37,16 +37,19 @@ wyvrnpm configure add-source --kind publish --name default  --url s3://my-bucket
 # 3. Detect and save your build environment as the default profile
 wyvrnpm configure profile detect
 
-# 4. Install dependencies (resolved against your build profile)
+# 4. Add dependencies (resolves latest from your configured sources)
+wyvrnpm add zlib fmt@^10.0.0
+
+# 5. Install dependencies (resolved against your build profile)
 wyvrnpm install
 
-# 5. Configure and build via the generated CMake preset
+# 6. Configure and build via the generated CMake preset
 wyvrnpm build
 
-# 6. Publish your package (uses the active profile automatically)
+# 7. Publish your package (uses the active profile automatically)
 wyvrnpm publish
 
-# 7. (Optional) Link local packages for development
+# 8. (Optional) Link local packages for development
 cd ../my-local-lib && wyvrnpm link
 cd ../my-app && wyvrnpm link my-local-lib
 ```
@@ -109,6 +112,42 @@ wyvrnpm init --root ./my-project
 
 ---
 
+### `wyvrnpm add`
+
+Adds one or more dependencies to `wyvrn.json` without downloading them. Useful when you know the package name but not the latest version.
+
+- **Bare name** — resolves `latest.json` from your configured install sources and writes `"^<latest>"` (caret range, major-pinned).
+- **`name@<version>`** — writes the given string verbatim. Accepts exact pins (`1.2.3.4`), caret/tilde ranges (`^1.2.3.4`, `~1.2.3.4`), and explicit comparators (`>=1.80.0 <2.0.0`).
+
+If the dependency is already listed, it is replaced. When the prior entry was an object (`{ version, settings, options }`), the `settings` and `options` are preserved — only the version field is updated.
+
+`add` does **not** run install. Chain `wyvrnpm install` afterwards to download.
+
+```bash
+# Resolve latest, write "^<latest>"
+wyvrnpm add zlib
+
+# Pin exactly
+wyvrnpm add zlib@1.3.0.0
+
+# Use a caret / tilde / comparator range
+wyvrnpm add fmt@^10.0.0
+wyvrnpm add boost@">=1.80.0 <2.0.0"
+
+# Multiple in one call
+wyvrnpm add zlib fmt@10.2.0.0 spdlog
+```
+
+**Options**
+
+| Option | Default | Description |
+|---|---|---|
+| `--source` / `-s` | *(config)* | Base URL used for the `latest` lookup. Repeat for multiple. |
+| `--platform` | `win_x64` | v1 legacy platform sub-path (used as a fallback during `latest` lookup). |
+| `--manifest` | `./wyvrn.json` | Path to the manifest file. |
+
+---
+
 ### `wyvrnpm install`
 
 Resolves the full dependency graph and downloads all packages.
@@ -164,6 +203,25 @@ After download, `install` also generates:
 - `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.
 
+**Toolchain variables exposed to your `CMakeLists.txt` (valid BEFORE `project()`)**:
+
+| Variable | Value |
+|---|---|
+| `WYVRN_PROFILE_NAME` / `WYVRN_PROFILE_HASH` | Active profile name + 16-char hash |
+| `WYVRN_PROFILE_OS` / `WYVRN_PROFILE_ARCH` | OS + architecture from the profile |
+| `WYVRN_PROFILE_COMPILER` / `WYVRN_PROFILE_COMPILER_VERSION` | Compiler identity |
+| `WYVRN_PROFILE_CPPSTD` / `WYVRN_PROFILE_RUNTIME` | C++ standard + MSVC runtime linkage |
+| `WYVRN_ARCH_SUFFIX` | `"64"` for 64-bit arches, `"32"` for 32-bit, empty for unmapped. Derived at toolchain-generation time so it's usable before `project()` — unlike `CMAKE_SIZEOF_VOID_P`. |
+
+The optional helper `WYVRN_APPLY_ARCH_SUFFIX(<target> [BASE_NAME <name>])` from the bundled `macros.cmake` applies the suffix to a target's `OUTPUT_NAME` so x64 and x86 builds of the same library coexist on disk without overwriting each other. Target linkage (`target_link_libraries`) is unaffected — only the produced filename changes.
+
+```cmake
+project(String CXX)
+add_library(String STATIC ...)
+WYVRN_APPLY_ARCH_SUFFIX(String)                 # → String64.lib / String32.lib
+WYVRN_APPLY_ARCH_SUFFIX(String BASE_NAME my-str) # → my-str64.lib / my-str32.lib
+```
+
 ---
 
 ### `wyvrnpm build`
@@ -189,6 +247,10 @@ wyvrnpm build --target my-lib
 # Wipe the build directory first
 wyvrnpm build --clean
 
+# Override the preset's generator (pair with --clean when switching generators)
+wyvrnpm build --clean --generator "Visual Studio 17 2022"
+wyvrnpm build --clean -G "Ninja Multi-Config"
+
 # Build, then install to the CMake install prefix
 wyvrnpm build --install
 wyvrnpm build --install --install-prefix C:\out\stage
@@ -210,6 +272,7 @@ wyvrnpm build -- -j 8
 | `--target` / `-t` | *(all)* | Specific CMake target to build. |
 | `--verbose` / `-v` | `false` | Pass `--verbose` to `cmake --build`. |
 | `--clean` | `false` | Remove the build directory before configuring. |
+| `--generator` / `-G` | *(from preset)* | Override the CMake generator used at configure time (e.g. `"Visual Studio 17 2022"`, `"Ninja"`, `"Ninja Multi-Config"`). CMake bakes the generator into the cache, so pair with `--clean` when switching. When the effective generator is Visual Studio, `-A <platform>` is auto-derived from the profile's arch (`x86→Win32`, `x86_64→x64`, `armv8→ARM64`, `armv7→ARM`) so VS doesn't silently default to x64 on 32-bit profiles. |
 | `--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`. |

package/bin/wyvrn.js

@@ -4,6 +4,7 @@
 
 const yargs     = require('yargs');
 const init         = require('../src/commands/init');
+const add          = require('../src/commands/add');
 const install      = require('../src/commands/install');
 const clean        = require('../src/commands/clean');
 const publish      = require('../src/commands/publish');
@@ -35,6 +36,34 @@ yargs
     (argv) => init(argv),
   )
 
+  // ── add ───────────────────────────────────────────────────────────────────
+  .command(
+    'add <packages...>',
+    'Add dependencies to wyvrn.json. Without @version, resolves latest and writes "^<latest>"; ' +
+    'with @version, writes the given string verbatim. Does not run install.',
+    (y) => {
+      y
+        .positional('packages', {
+          type: 'string',
+          array: true,
+          describe: 'One or more <name>[@<version>] specs',
+        })
+        .option('source', {
+          alias: 's',
+          type: 'string',
+          description: 'Base URL of a package source for `latest` lookup (can be repeated)',
+          array: true,
+        })
+        .option('platform', {
+          type: 'string',
+          description: 'v1 legacy platform path (used as fallback when looking up latest)',
+          choices: ['win_x64', 'win_x86', 'linux_x64', 'linux_x86', 'osx_x64', 'osx_arm64'],
+          default: 'win_x64',
+        });
+    },
+    (argv) => add(argv),
+  )
+
   // ── install ───────────────────────────────────────────────────────────────
   .command(
     'install',
@@ -156,6 +185,13 @@ yargs
           default: false,
           description: 'Remove the build directory before configuring',
         })
+        .option('generator', {
+          alias: 'G',
+          type: 'string',
+          description:
+            'Override the preset\'s CMake generator (e.g. "Visual Studio 17 2022", "Ninja", "Ninja Multi-Config"). ' +
+            'CMake locks the generator into the build-dir cache, so pair this with --clean when switching generators.',
+        })
         .option('install', {
           type: 'boolean',
           default: false,

package/cmake/macros.cmake

@@ -25,6 +25,44 @@ macro(WYVRN_CONFIGURE_VERSION_HEADER)
     )
 endmacro()
 
+# Apply WYVRN_ARCH_SUFFIX to a target's OUTPUT_NAME so the produced artefact
+# carries an unambiguous arch marker. Opt-in — call it from your CMakeLists
+# only if you want the suffixing:
+#
+#   WYVRN_APPLY_ARCH_SUFFIX(String)                       # String64.lib / String32.lib
+#   WYVRN_APPLY_ARCH_SUFFIX(String BASE_NAME my-string)   # my-string64.lib / my-string32.lib
+#
+# BASE_NAME defaults to the target name. The target linkage name (what
+# consumers pass to target_link_libraries) is untouched — only the on-disk
+# output file changes. Safe to call for any target type; does nothing if
+# WYVRN_ARCH_SUFFIX is empty (unknown / unmapped arch).
+function(WYVRN_APPLY_ARCH_SUFFIX _wyvrn_target)
+    set(options)
+    set(oneValueArgs BASE_NAME)
+    set(multiValueArgs)
+    cmake_parse_arguments(_WYVRN_ARG "${options}" "${oneValueArgs}" "${multiValueArgs}" ${ARGN})
+
+    if(NOT TARGET ${_wyvrn_target})
+        message(FATAL_ERROR "WYVRN_APPLY_ARCH_SUFFIX: '${_wyvrn_target}' is not a target")
+    endif()
+
+    if("${WYVRN_ARCH_SUFFIX}" STREQUAL "")
+        # Unknown arch — leave the output name alone rather than stamping a
+        # misleading value. The caller can still set OUTPUT_NAME manually.
+        return()
+    endif()
+
+    if(_WYVRN_ARG_BASE_NAME)
+        set(_wyvrn_base "${_WYVRN_ARG_BASE_NAME}")
+    else()
+        set(_wyvrn_base "${_wyvrn_target}")
+    endif()
+
+    set_target_properties(${_wyvrn_target} PROPERTIES
+        OUTPUT_NAME "${_wyvrn_base}${WYVRN_ARCH_SUFFIX}"
+    )
+endfunction()
+
 function(WYVRN_INSTALL_PACKAGE_EXPORT)
     set(options)
     set(oneValueArgs
@@ -84,10 +122,23 @@ function(WYVRN_INSTALL_PACKAGE_EXPORT)
         INSTALL_DESTINATION "${WYVRN_EXPORT_INSTALL_CMAKEDIR}"
     )
 
+    # INTERFACE libraries (header-only) have no compiled binary, so the arch
+    # stamped by `write_basic_package_version_file()` by default makes CMake
+    # reject the package when the consumer's CMAKE_SIZEOF_VOID_P differs —
+    # even though the headers themselves are arch-portable. Pass
+    # ARCH_INDEPENDENT so a HeaderOnlyLib published from x86_64 is consumable
+    # from x86 (and vice versa). Binary kinds keep the arch check.
+    set(_wyvrn_version_args)
+    get_target_property(_wyvrn_target_type ${WYVRN_EXPORT_TARGET} TYPE)
+    if(_wyvrn_target_type STREQUAL "INTERFACE_LIBRARY")
+        list(APPEND _wyvrn_version_args ARCH_INDEPENDENT)
+    endif()
+
     write_basic_package_version_file(
         "${WYVRN_EXPORT_VERSION_OUTPUT}"
         VERSION "${WYVRN_EXPORT_PACKAGE_VERSION}"
         COMPATIBILITY SameMajorVersion
+        ${_wyvrn_version_args}
     )
 
     install(FILES

package/package.json

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

package/src/commands/add.js

@@ -0,0 +1,140 @@
+'use strict';
+
+const path = require('path');
+
+const { readManifest, writeManifest } = require('../manifest');
+const { resolveLatestVersion }        = require('../resolve');
+const { readConfig }                  = require('../config');
+const log                             = require('../logger');
+
+/**
+ * Parse a `<name>[@<version>]` positional into its parts.
+ *
+ * `@` inside the version (e.g. tags like `latest`) is allowed — only the
+ * first `@` is treated as the separator.
+ *
+ * @param {string} spec
+ * @returns {{ name: string, version: string | null }}
+ */
+function parseSpec(spec) {
+  const at = spec.indexOf('@');
+  if (at === -1)  return { name: spec, version: null };
+  if (at === 0)   throw new Error(`invalid package spec "${spec}" — missing name before "@"`);
+  const name    = spec.slice(0, at);
+  const version = spec.slice(at + 1);
+  if (!version) throw new Error(`invalid package spec "${spec}" — missing version after "@"`);
+  return { name, version };
+}
+
+/**
+ * Add one or more dependencies to wyvrn.json.
+ *
+ *   wyvrnpm add <name>              → resolves latest, writes "^<latest>"
+ *   wyvrnpm add <name>@<version>    → writes "<version>" verbatim (exact or range)
+ *
+ * Existing entries are replaced. If the prior entry was an object
+ * (`{ version, settings, options }`), its settings/options are preserved —
+ * only `version` is updated.
+ *
+ * Does not run install. The user must `wyvrnpm install` afterwards.
+ *
+ * @param {object} argv
+ */
+async function add(argv) {
+  const manifestPath = path.resolve(argv.manifest);
+  const specs = (argv.packages ?? []).map(parseSpec);
+
+  if (specs.length === 0) {
+    log.error('no packages given. Usage: wyvrnpm add <name>[@<version>] [...]');
+    process.exit(1);
+  }
+
+  // Install sources — only needed when at least one spec omits @version and
+  // we have to hit `latest.json`.
+  let packageSources;
+  if (argv.source && argv.source.length > 0) {
+    packageSources = argv.source;
+  } else {
+    const config   = readConfig();
+    packageSources = config.installSources.map((s) => s.url);
+  }
+
+  const needsResolve = specs.some((s) => s.version === null);
+  if (needsResolve && packageSources.length === 0) {
+    log.error(
+      'no install sources configured — cannot look up latest versions.\n' +
+      '  Pass --source <url>, pin versions explicitly (`name@1.2.3.4`), or run:\n' +
+      '    wyvrnpm configure add-source --kind install --name ... --url ...',
+    );
+    process.exit(1);
+  }
+
+  const manifest = readManifest(manifestPath);
+
+  // Preserve whichever dependencies key the manifest already uses. If neither
+  // exists, create lowercase `dependencies` (the v2 convention).
+  const depsKey =
+    Object.prototype.hasOwnProperty.call(manifest, 'dependencies') ? 'dependencies' :
+    Object.prototype.hasOwnProperty.call(manifest, 'Dependencies') ? 'Dependencies' :
+    'dependencies';
+
+  let deps = manifest[depsKey];
+  // Legacy array form → object. Editing by name is the whole point of `add`,
+  // and round-tripping as an array would silently drop per-dep settings.
+  if (Array.isArray(deps)) {
+    const obj = {};
+    for (const d of deps) {
+      const n = d.Name ?? d.name;
+      const v = d.Version ?? d.version;
+      if (n && v) obj[n] = v;
+    }
+    deps = obj;
+  } else if (!deps || typeof deps !== 'object') {
+    deps = {};
+  }
+
+  for (const spec of specs) {
+    let versionToWrite;
+    if (spec.version) {
+      versionToWrite = spec.version;
+      log.info(`${spec.name}: writing "${versionToWrite}" (as given)`);
+    } else {
+      const latest = await resolveLatestVersion(spec.name, packageSources, argv.platform, fetch);
+      versionToWrite = `^${latest}`;
+      log.info(`${spec.name}: latest is ${latest} → writing "${versionToWrite}"`);
+    }
+
+    const prior = deps[spec.name];
+    if (prior !== undefined) {
+      const priorVer =
+        typeof prior === 'string' ? prior :
+        (prior && typeof prior === 'object') ? (prior.version ?? prior.Version ?? '(unknown)') :
+        '(unknown)';
+      log.info(`  replacing existing entry: "${priorVer}"`);
+    }
+
+    // If the prior entry was an object with settings/options, keep those —
+    // only bump the version field. Otherwise write the short-form string.
+    if (prior && typeof prior === 'object' && !Array.isArray(prior)) {
+      const updated = { ...prior };
+      if ('Version' in updated && !('version' in updated)) {
+        updated.Version = versionToWrite;
+      } else {
+        updated.version = versionToWrite;
+      }
+      deps[spec.name] = updated;
+    } else {
+      deps[spec.name] = versionToWrite;
+    }
+  }
+
+  manifest[depsKey] = deps;
+  writeManifest(manifestPath, manifest);
+
+  const n = specs.length;
+  log.success(`Updated ${manifestPath} — ${n} package${n !== 1 ? 's' : ''}.`);
+  log.info('Run `wyvrnpm install` to download.');
+}
+
+module.exports = add;
+module.exports.parseSpec = parseSpec;

package/src/commands/build.js

@@ -9,6 +9,7 @@ const { loadProfile }  = require('../profile');
 const { readManifest } = require('../manifest');
 const { normalizeRecipe, hasBuildRecipe } = require('../build/recipe');
 const { loadMsvcEnv }  = require('../build/msvc-env');
+const { archToVsPlatform, isVisualStudioGenerator } = require('../toolchain');
 const install          = require('./install');
 const log              = require('../logger');
 
@@ -70,11 +71,29 @@ function resolveBinaryDir({ rootDir, presetName }) {
 
 /**
  * Args passed to `cmake` for the configure step.
- * @param {{ presetName: string }} args
+ *
+ * `generator`, when set, appends `-G <name>` after `--preset`. CMake 3.21+
+ * lets CLI args override a preset's declared fields, so this swaps the
+ * generator at configure time without touching CMakePresets.json. Note:
+ * CMake bakes the chosen generator into the cache, so switching generators
+ * for an existing build directory requires `--clean` (otherwise CMake
+ * errors with "CMAKE_GENERATOR has changed").
+ *
+ * `vsPlatform`, when set, appends `-A <platform>`. Only meaningful for
+ * Visual Studio generators — they default to x64 when unspecified, which
+ * silently produces a 64-bit build even for a 32-bit profile. The caller
+ * is responsible for deriving this from the profile arch only when the
+ * effective generator is VS (see `isVisualStudioGenerator` +
+ * `archToVsPlatform`).
+ *
+ * @param {{ presetName: string, generator?: string|null, vsPlatform?: string|null }} args
  * @returns {string[]}
  */
-function buildConfigureArgs({ presetName }) {
-  return ['--preset', presetName];
+function buildConfigureArgs({ presetName, generator = null, vsPlatform = null }) {
+  const args = ['--preset', presetName];
+  if (generator)  args.push('-G', generator);
+  if (vsPlatform) args.push('-A', vsPlatform);
+  return args;
 }
 
 /**
@@ -211,8 +230,11 @@ async function build(argv) {
   //
   // Same mechanism the source-build path already uses (src/build/msvc-env.js).
   let cmakeEnv = null;
+  let effectiveGenerator = argv.generator ?? null;
+  let effectiveProfile   = null;
   try {
     const { profile: activeProfile } = loadProfile(profileName);
+    effectiveProfile = activeProfile;
     // Which generator will the preset actually use? Read it from the
     // project's own recipe if one exists. If not, default to null and let
     // cmake/CMakePresets decide — in which case MSVC env activation is
@@ -225,16 +247,37 @@ async function build(argv) {
         if (recipe.generators.length > 0) [presetGenerator] = recipe.generators;
       } catch { /* templates need options → skip env activation */ }
     }
+    // CLI --generator wins — that is the generator CMake will actually use,
+    // so it is the one that determines whether vcvarsall must be activated.
+    if (!effectiveGenerator) effectiveGenerator = presetGenerator;
     cmakeEnv = await loadMsvcEnv({
       profile:          activeProfile,
-      skipForGenerator: presetGenerator,
+      skipForGenerator: effectiveGenerator,
     });
   } catch (err) {
     log.warn(`Could not resolve MSVC env activation: ${err.message}`);
   }
 
   // ── Configure ─────────────────────────────────────────────────────────────
-  const configureArgs = buildConfigureArgs({ presetName });
+  // Auto-emit `-A <platform>` for Visual Studio generators, mapped from the
+  // active profile's arch. VS otherwise defaults to x64 regardless of the
+  // profile, which breaks x86 builds: CMake produces 64-bit artefacts but
+  // find_package() rejects the 32-bit installed dependencies with "version
+  // not compatible" (actually a CMAKE_SIZEOF_VOID_P mismatch, not a
+  // version-number check).
+  let vsPlatform = null;
+  if (isVisualStudioGenerator(effectiveGenerator) && effectiveProfile) {
+    vsPlatform = archToVsPlatform(effectiveProfile.arch);
+    if (vsPlatform) {
+      log.info(`Visual Studio generator + arch=${effectiveProfile.arch} → passing -A ${vsPlatform}`);
+    }
+  }
+
+  const configureArgs = buildConfigureArgs({
+    presetName,
+    generator:  argv.generator,
+    vsPlatform,
+  });
   log.info(`cmake ${configureArgs.join(' ')}`);
   await runCmake(configureArgs, cmakeEnv);
 

package/src/commands/install.js

@@ -333,6 +333,7 @@ async function install(argv) {
     generator:           presetGenerator,
     extraCacheVariables: presetCacheVariables,
     installDir:          presetInstallDir,
+    profileArch:         baseProfile.arch ?? null,
   });
   if (presetResult.action === 'skipped') {
     log.warn(

package/src/compat.js

@@ -34,12 +34,15 @@
  *                   | version fields and leaves room for future "same major"
  *                   | semantics without renaming.
  *
- * Missing fields default to `exact`. `os` and `arch` are ALWAYS evaluated
- * as `exact` regardless of what the block says — cross-arch/cross-OS
- * binaries are never ABI-compatible.
+ * Missing fields default to `exact`. `os` and `arch` are normally forced
+ * to `exact` regardless of what the block says — cross-arch/cross-OS
+ * binaries are never ABI-compatible. The one exception is
+ * `kind: "HeaderOnlyLib"`: header-only packages ship no binary, so the
+ * publisher's declared modes for `os`/`arch` are respected. Binary kinds
+ * (`StaticLib`, `DynamicLib`, `ConsoleApp`, …) keep the hard guarantee.
  */
 
-const OS_ARCH_ALWAYS_EXACT = new Set(['os', 'arch']);
+const OS_ARCH_FIELDS = new Set(['os', 'arch']);
 
 const DEFAULT_COMPAT_FIELDS = [
   'os',
@@ -55,19 +58,27 @@ const VALID_MODES = new Set(['exact', 'any', 'lte', 'gte', 'exact-or-newer']);
 /**
  * Normalise a raw compatibility block into `{ field → mode }`.
  * Missing fields fall back to `exact`. Unknown modes fall back to `exact`.
- * `os` and `arch` are forced to `exact`.
+ *
+ * For binary kinds (`StaticLib`, `DynamicLib`, `ConsoleApp`, …) `os` and
+ * `arch` are forced to `exact` — publisher-declared modes are silently
+ * dropped because cross-arch binaries are never ABI-safe. For
+ * `kind: "HeaderOnlyLib"` the publisher's declared modes are respected,
+ * since there is no binary to be ABI-incompatible with.
  *
  * @param {object|null|undefined} rawCompat
+ * @param {string|null|undefined} [packageKind]  Package manifest `kind` field.
  * @returns {Record<string, string>}
  */
-function normalizeCompat(rawCompat) {
+function normalizeCompat(rawCompat, packageKind) {
   const result = {};
   for (const field of DEFAULT_COMPAT_FIELDS) result[field] = 'exact';
 
   if (!rawCompat || typeof rawCompat !== 'object') return result;
 
+  const headerOnly = packageKind === 'HeaderOnlyLib';
+
   for (const [field, spec] of Object.entries(rawCompat)) {
-    if (OS_ARCH_ALWAYS_EXACT.has(field)) continue;
+    if (!headerOnly && OS_ARCH_FIELDS.has(field)) continue;
     const mode = typeof spec === 'string' ? spec : (spec && spec.mode);
     if (mode && VALID_MODES.has(mode)) result[field] = mode;
   }
@@ -147,13 +158,14 @@ function evaluateField(mode, consumerVal, packageVal) {
  * @param {Record<string, any>}         consumerProfile  may include `options: {...}`
  * @param {Record<string, any>}         packageProfile   may include `options: {...}`
  * @param {object|null|undefined}       rawCompat        compatibility block from the package manifest
+ * @param {string|null|undefined}       [packageKind]    package manifest `kind` field — unlocks `os`/`arch` modes for HeaderOnlyLib
  * @returns {{
  *   compatible: boolean,
  *   reasons: Array<{ field: string, mode: string, consumer: any, package: any, outcome: string }>,
  * }}
  */
-function evaluateCompat(consumerProfile, packageProfile, rawCompat) {
-  const compat = normalizeCompat(rawCompat);
+function evaluateCompat(consumerProfile, packageProfile, rawCompat, packageKind) {
+  const compat = normalizeCompat(rawCompat, packageKind);
   const reasons = [];
   let compatible = true;
 

package/src/download.js

@@ -209,7 +209,7 @@ async function findCompatibleBuild({ name, version, consumerProfile, consumerOpt
          : packageProfile);
 
     const rawCompat = meta.compatibility ?? null;
-    const { compatible, reasons } = evaluateCompat(consumerFull, packageFull, rawCompat);
+    const { compatible, reasons } = evaluateCompat(consumerFull, packageFull, rawCompat, meta.kind);
     if (compatible) {
       candidates.push({ profileHash, packageProfile, reasons, buildEntry, meta });
     }

package/src/toolchain/index.js

@@ -17,6 +17,73 @@ function getBundledCmakeDir() {
   return dir.replace(/\\/g, '/');
 }
 
+// Arch bit-width mapping. Kept exhaustive against `ARCH_MAP` in profile.js
+// so any arch a profile can hold has a deterministic "32"/"64" suffix.
+// Unknown arch strings fall back to an empty suffix — the consumer's
+// CMakeLists should then use another discriminator (e.g. profile hash).
+const ARCH_BIT_SUFFIX = {
+  x86_64:  '64',
+  x86:     '32',
+  armv8:   '64',
+  armv7:   '32',
+  ppc64le: '64',
+  s390x:   '64',
+  mips:    '32',
+  mipsel:  '32',
+};
+
+/**
+ * Map a profile `arch` value to the canonical "64" / "32" suffix that
+ * `WYVRN_ARCH_SUFFIX` exposes to consumer CMakeLists. Empty string for
+ * unknown arches — callers can pattern-match on that to fall back.
+ *
+ * @param {string|null|undefined} arch
+ * @returns {string}
+ */
+function archToBitSuffix(arch) {
+  if (!arch) return '';
+  return ARCH_BIT_SUFFIX[arch] ?? '';
+}
+
+// Visual Studio generator `-A <platform>` mapping. VS defaults to x64
+// when `-A` is unspecified — which silently wins against a 32-bit profile
+// and causes consumer-side `find_package()` to reject 32-bit artefacts
+// with "The version found is not compatible" (a CMake pointer-size check,
+// not a version-number check). Auto-emitting `-A` keeps VS + x86 honest.
+const ARCH_VS_PLATFORM = {
+  x86_64: 'x64',
+  x86:    'Win32',
+  armv8:  'ARM64',
+  armv7:  'ARM',
+};
+
+/**
+ * Map a profile arch to the Visual Studio generator's `-A <platform>` value.
+ * Returns null for arches that don't map to a known VS platform — callers
+ * should skip `-A` in that case and let the user pass one explicitly.
+ *
+ * @param {string|null|undefined} arch
+ * @returns {string|null}
+ */
+function archToVsPlatform(arch) {
+  if (!arch) return null;
+  return ARCH_VS_PLATFORM[arch] ?? null;
+}
+
+/**
+ * True when the generator name identifies a Visual Studio generator (e.g.
+ * "Visual Studio 17 2022"). VS generators require `-A <platform>` /
+ * `architecture` in the preset; everyone else (Ninja, Make, Xcode, …)
+ * ignores it.
+ *
+ * @param {string|null|undefined} name
+ * @returns {boolean}
+ */
+function isVisualStudioGenerator(name) {
+  if (!name) return false;
+  return /^Visual Studio \d/.test(name);
+}
+
 /**
  * Substitute `{{KEY}}` placeholders in a template string.
  *
@@ -54,6 +121,7 @@ function buildPlaceholders({ profile, profileName, profileHash, packageNames })
     PROFILE_HASH:             profileHash,
     PROFILE_OS:               profile.os ?? '',
     PROFILE_ARCH:             profile.arch ?? '',
+    PROFILE_ARCH_SUFFIX:      archToBitSuffix(profile.arch),
     PROFILE_COMPILER:         profile.compiler ?? '',
     PROFILE_COMPILER_VERSION: profile['compiler.version'] ?? '',
     PROFILE_CPPSTD:           profile['compiler.cppstd'] ?? '20',
@@ -135,7 +203,10 @@ module.exports = {
   generateToolchain,
   generateCMakePresets,
   getBundledCmakeDir,
+  archToVsPlatform,
+  isVisualStudioGenerator,
   // Exported for tests
+  archToBitSuffix,
   buildPlaceholders,
   renderTemplate,
 };

package/src/toolchain/presets.js

@@ -4,6 +4,21 @@ const fs   = require('fs');
 const path = require('path');
 
 const VENDOR_KEY = 'wyvrnpm/generated';
+
+// Local copy of the arch→VS-platform mapping. Duplicated here rather than
+// imported from ./index so preset generation can run standalone (keeps
+// the dependency graph simple — presets.js doesn't otherwise need the
+// toolchain generator). Keep in sync with `archToVsPlatform` in index.js.
+const ARCH_VS_PLATFORM = {
+  x86_64: 'x64',
+  x86:    'Win32',
+  armv8:  'ARM64',
+  armv7:  'ARM',
+};
+
+function isVsGenerator(name) {
+  return typeof name === 'string' && /^Visual Studio \d/.test(name);
+}
 const SCHEMA_VERSION = 3;  // requires CMake ≥ 3.21
 
 /**
@@ -52,6 +67,11 @@ function isWyvrnGenerated(presets) {
  *                                             `CMAKE_TOOLCHAIN_FILE`. Usually
  *                                             derived from the project's own
  *                                             `build.configure` -D args.
+ * @param {string|null} [args.profileArch]     Active profile arch — used to pin
+ *                                             `architecture` for VS generators
+ *                                             so `cmake --preset` produces
+ *                                             binaries matching the profile
+ *                                             (VS otherwise defaults to x64).
  */
 function buildConfigurePreset({
   profileName,
@@ -60,6 +80,7 @@ function buildConfigurePreset({
   generator = null,
   extraCacheVariables = null,
   installDir = null,
+  profileArch = null,
 }) {
   const binaryDir = `\${sourceDir}/build/wyvrn-${profileName}`;
   // Spread `extraCacheVariables` FIRST, then the wyvrn-owned entries. This
@@ -90,6 +111,19 @@ function buildConfigurePreset({
     cacheVariables,
   };
   if (generator) preset.generator = generator;
+
+  // Visual Studio generators default to x64 when `architecture` is
+  // unspecified — which silently overrides the profile arch and makes
+  // find_package() reject 32-bit installed packages with a pointer-size
+  // mismatch. Pin `architecture` from the profile so `cmake --preset`
+  // produces the right artefacts end-to-end.
+  if (isVsGenerator(generator) && profileArch && ARCH_VS_PLATFORM[profileArch]) {
+    preset.architecture = {
+      value:    ARCH_VS_PLATFORM[profileArch],
+      strategy: 'set',
+    };
+  }
+
   return preset;
 }
 
@@ -127,6 +161,7 @@ function buildFreshPresetsFile({
   generator = null,
   extraCacheVariables = null,
   installDir = null,
+  profileArch = null,
 }) {
   return {
     version: SCHEMA_VERSION,
@@ -138,7 +173,7 @@ function buildFreshPresetsFile({
       },
     },
     configurePresets: [buildConfigurePreset({
-      profileName, profileHash, toolchainRelPath, generator, extraCacheVariables, installDir,
+      profileName, profileHash, toolchainRelPath, generator, extraCacheVariables, installDir, profileArch,
     })],
     buildPresets: buildBuildPresets(profileName),
   };
@@ -161,9 +196,10 @@ function mergeIntoExisting(existing, {
   generator = null,
   extraCacheVariables = null,
   installDir = null,
+  profileArch = null,
 }) {
   const newConfigure = buildConfigurePreset({
-    profileName, profileHash, toolchainRelPath, generator, extraCacheVariables, installDir,
+    profileName, profileHash, toolchainRelPath, generator, extraCacheVariables, installDir, profileArch,
   });
   const newBuilds    = buildBuildPresets(profileName);
   const newConfigureNames = new Set([newConfigure.name]);
@@ -223,8 +259,9 @@ function generateCMakePresets({
   generator = null,
   extraCacheVariables = null,
   installDir = null,
+  profileArch = null,
 }) {
-  const args = { profileName, profileHash, toolchainRelPath, generator, extraCacheVariables, installDir };
+  const args = { profileName, profileHash, toolchainRelPath, generator, extraCacheVariables, installDir, profileArch };
   const candidates = [
     { filePath: path.join(projectRoot, 'CMakePresets.json'),     isUser: false },
     { filePath: path.join(projectRoot, 'CMakeUserPresets.json'), isUser: true  },

package/src/toolchain/template.cmake

@@ -17,6 +17,17 @@ set(WYVRN_PROFILE_NAME             "{{PROFILE_NAME}}")
 set(WYVRN_PROFILE_HASH             "{{PROFILE_HASH}}")
 set(WYVRN_PROFILE_OS               "{{PROFILE_OS}}")
 set(WYVRN_PROFILE_ARCH             "{{PROFILE_ARCH}}")
+
+# "64" for 64-bit arches (x86_64, armv8, …), "32" for 32-bit (x86, armv7, …),
+# empty for arches outside the known mapping. Derived at generation time from
+# the profile so it is valid BEFORE `project()` — unlike CMAKE_SIZEOF_VOID_P,
+# which is only set after the first project() call. Intended for suffixing
+# artefact names (e.g. "String${WYVRN_ARCH_SUFFIX}" → String64 / String32) so
+# x64 and x86 builds can coexist on disk without overwriting each other.
+# Call WYVRN_APPLY_ARCH_SUFFIX(<target>) from macros.cmake for the common
+# per-target shape, or reference the variable directly for other uses.
+set(WYVRN_ARCH_SUFFIX              "{{PROFILE_ARCH_SUFFIX}}")
+
 set(WYVRN_PROFILE_COMPILER         "{{PROFILE_COMPILER}}")
 set(WYVRN_PROFILE_COMPILER_VERSION "{{PROFILE_COMPILER_VERSION}}")
 set(WYVRN_PROFILE_CPPSTD           "{{PROFILE_CPPSTD}}")