wyvrnpm 2.10.2 → 2.12.2

package/src/toolchain/presets.js

@@ -1,340 +1,356 @@
-'use strict';
-
-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
-
-/**
- * Safely parse a JSON file; returns null on any error (missing, malformed, …).
- * @param {string} p
- * @returns {object|null}
- */
-function safeReadJson(p) {
-  try {
-    return JSON.parse(fs.readFileSync(p, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-/**
- * True if the parsed presets object was produced by wyvrnpm (i.e. carries our
- * vendor marker). Hand-edited or user-owned files return false.
- *
- * @param {object|null} presets
- * @returns {boolean}
- */
-function isWyvrnGenerated(presets) {
-  return !!presets && typeof presets.vendor === 'object' && !!presets.vendor[VENDOR_KEY];
-}
-
-/**
- * Build the configure preset object for the active profile.
- *
- * When the project has its own `build` recipe (i.e. it's a publishable
- * library with `build.generator` / `build.configure` declared), those are
- * propagated into the generated preset so `wyvrnpm build` locally honours
- * the same knobs the source-build + publish paths use. Without this, a
- * publisher's recipe is effectively advisory at install-time (F15 fix).
- *
- * @param {object} args
- * @param {string} args.profileName
- * @param {string} args.profileHash
- * @param {string} args.toolchainRelPath       Relative from project root, CMake-style
- *                                             forward slashes.
- * @param {string|null} [args.generator]       Single generator name to pin on the
- *                                             preset (e.g. "Ninja Multi-Config").
- *                                             Null / undefined → let CMake pick.
- * @param {Record<string,string>|null} [args.extraCacheVariables]
- *                                             Merged into cacheVariables alongside
- *                                             `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).
- * @param {string[]|null} [args.configs]       Build recipe's `configs` list
- *                                             (e.g. ['Debug','Release','MinSizeRel']).
- *                                             When provided, drives
- *                                             `CMAKE_CONFIGURATION_TYPES` so
- *                                             multi-config generators (Ninja
- *                                             Multi-Config, VS) actually
- *                                             produce every config the recipe
- *                                             declares. Null/empty → omitted
- *                                             (let CMake use its generator
- *                                             default). `extraCacheVariables`
- *                                             wins on explicit collision so
- *                                             authors that already bake the
- *                                             list into `build.configure`
- *                                             aren't overridden.
- */
-function buildConfigurePreset({
-  profileName,
-  profileHash,
-  toolchainRelPath,
-  generator = null,
-  extraCacheVariables = null,
-  installDir = null,
-  profileArch = null,
-  configs = null,
-}) {
-  const binaryDir = `\${sourceDir}/build/wyvrn-${profileName}`;
-  // CMAKE_CONFIGURATION_TYPES is a defensible default from the recipe's
-  // declared `configs` list. Applied FIRST (lowest precedence) so an
-  // explicit `-DCMAKE_CONFIGURATION_TYPES=...` in `build.configure`
-  // still wins — authors who already pin the list shouldn't silently
-  // lose their override. The wyvrn-owned entries (toolchain, install
-  // prefix) still win over both below.
-  const configsDefault = (Array.isArray(configs) && configs.length > 0)
-    ? { CMAKE_CONFIGURATION_TYPES: configs.join(';') }
-    : {};
-  const cacheVariables = {
-    ...configsDefault,
-    ...(extraCacheVariables ?? {}),
-    CMAKE_TOOLCHAIN_FILE: `\${sourceDir}/${toolchainRelPath}`,
-  };
-  if (installDir) {
-    // `installDir` in wyvrn.json is defined as relative to the binary dir
-    // (same semantics as the source-build path, which passes
-    // -DCMAKE_INSTALL_PREFIX=<buildDir>/<installDir>). Without this, a
-    // `wyvrnpm build --install` falls back to CMake's system default —
-    // on Windows that's `C:/Program Files (x86)/<Project>`, which needs
-    // admin rights and almost always fails.
-    cacheVariables.CMAKE_INSTALL_PREFIX = `${binaryDir}/${installDir}`;
-  }
-  const preset = {
-    name:         `wyvrn-${profileName}`,
-    displayName:  `wyvrnpm (${profileName})`,
-    description:  `Generated by wyvrnpm install — profile hash ${profileHash}`,
-    binaryDir,
-    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;
-}
-
-/**
- * One build preset per configuration the recipe declares (or the
- * legacy default pair `Debug` + `Release` when no list is provided).
- *
- * The preset name suffix is the configuration name lower-cased — matches
- * the previous Debug/Release naming for those two, and extends to
- * `wyvrn-<profile>-relwithdebinfo` / `-minsizerel` for the multi-config
- * cases. Authors whose recipes include `MinSizeRel` in `build.configs`
- * can now `cmake --build --preset wyvrn-<profile>-minsizerel` directly.
- *
- * @param {string} profileName
- * @param {string[]|null} [configs]  Recipe's declared configurations. When
- *   null/empty, emits the pre-2.8.1 `Debug` + `Release` pair so existing
- *   CMakePresets.json files remain byte-identical.
- * @returns {Array<object>}
- */
-function buildBuildPresets(profileName, configs = null) {
-  const base = `wyvrn-${profileName}`;
-  const list = (Array.isArray(configs) && configs.length > 0)
-    ? configs
-    : ['Debug', 'Release'];
-  return list.map((cfg) => ({
-    name:            `${base}-${cfg.toLowerCase()}`,
-    displayName:     `wyvrn ${profileName} (${cfg})`,
-    configurePreset: base,
-    configuration:   cfg,
-  }));
-}
-
-/**
- * Build a fresh presets file from scratch (no prior content to merge).
- */
-function buildFreshPresetsFile({
-  profileName,
-  profileHash,
-  toolchainRelPath,
-  generator = null,
-  extraCacheVariables = null,
-  installDir = null,
-  profileArch = null,
-  configs = null,
-}) {
-  return {
-    version: SCHEMA_VERSION,
-    vendor: {
-      [VENDOR_KEY]: {
-        profileName,
-        profileHash,
-        generatedAt: new Date().toISOString(),
-      },
-    },
-    configurePresets: [buildConfigurePreset({
-      profileName, profileHash, toolchainRelPath, generator, extraCacheVariables, installDir, profileArch, configs,
-    })],
-    buildPresets: buildBuildPresets(profileName, configs),
-  };
-}
-
-/**
- * Merge the current profile's presets into an existing wyvrnpm-generated
- * file. Presets with matching `name` are replaced; others are preserved so
- * `wyvrnpm install --profile release` followed by `wyvrnpm install --profile
- * debug` leaves both profiles available in the file.
- *
- * @param {object} existing
- * @param {object} args  forwarded to the preset builders
- * @returns {object}
- */
-function mergeIntoExisting(existing, {
-  profileName,
-  profileHash,
-  toolchainRelPath,
-  generator = null,
-  extraCacheVariables = null,
-  installDir = null,
-  profileArch = null,
-  configs = null,
-}) {
-  const newConfigure = buildConfigurePreset({
-    profileName, profileHash, toolchainRelPath, generator, extraCacheVariables, installDir, profileArch, configs,
-  });
-  const newBuilds    = buildBuildPresets(profileName, configs);
-  const newConfigureNames = new Set([newConfigure.name]);
-  // When replacing THIS profile's build presets, drop every pre-existing
-  // one that targets the same configurePreset — the fresh `newBuilds`
-  // list fully replaces them. Scoping to configurePreset avoids stepping
-  // on presets for OTHER profiles in the same file, which is the whole
-  // point of the merge path.
-  //
-  // Without this, editing `build.configs` from 4 configs down to 2 would
-  // leave orphan build presets pointing at configurations CMake won't
-  // generate.
-  const myBase = `wyvrn-${profileName}`;
-  const isMyBuildPreset = (p) => p && p.configurePreset === myBase;
-
-  const configurePresets = (existing.configurePresets ?? []).filter((p) => !newConfigureNames.has(p.name));
-  configurePresets.push(newConfigure);
-
-  // Drop every pre-existing build preset that targets THIS profile's
-  // configurePreset — the fresh `newBuilds` list (one per current
-  // `configs` entry) fully replaces them. Presets for OTHER profiles
-  // stay untouched so the multi-profile merge story is preserved.
-  const buildPresets = (existing.buildPresets ?? []).filter((p) => !isMyBuildPreset(p));
-  buildPresets.push(...newBuilds);
-
-  return {
-    ...existing,
-    version: existing.version ?? SCHEMA_VERSION,
-    vendor: {
-      ...(existing.vendor ?? {}),
-      [VENDOR_KEY]: {
-        profileName,
-        profileHash,
-        generatedAt: new Date().toISOString(),
-      },
-    },
-    configurePresets,
-    buildPresets,
-  };
-}
-
-/**
- * Write a CMakePresets.json (or CMakeUserPresets.json, as fallback) under
- * `projectRoot`. Never overwrites a user-owned file.
- *
- * Resolution order:
- *   1. CMakePresets.json
- *      - Does not exist     → create it.
- *      - Exists, wyvrn-gen  → merge into it.
- *      - Exists, user-owned → leave alone, fall through.
- *   2. CMakeUserPresets.json
- *      - Does not exist     → create it.
- *      - Exists, wyvrn-gen  → merge into it.
- *      - Exists, user-owned → skip (action: "skipped").
- *
- * @param {object} args
- * @param {string} args.projectRoot       Directory containing top-level CMakeLists.txt.
- * @param {string} args.profileName
- * @param {string} args.profileHash
- * @param {string} args.toolchainRelPath  CMake-style forward slashes, relative to projectRoot.
- * @param {string|null} [args.generator]  Propagated onto the configure preset's `generator` field.
- * @param {Record<string,string>|null} [args.extraCacheVariables]
- *                                        Merged into the configure preset's `cacheVariables`.
- * @returns {{ path: string|null, action: 'created'|'updated'|'skipped', isUser: boolean }}
- */
-function generateCMakePresets({
-  projectRoot,
-  profileName,
-  profileHash,
-  toolchainRelPath,
-  generator = null,
-  extraCacheVariables = null,
-  installDir = null,
-  profileArch = null,
-  configs = null,
-}) {
-  const args = { profileName, profileHash, toolchainRelPath, generator, extraCacheVariables, installDir, profileArch, configs };
-  const candidates = [
-    { filePath: path.join(projectRoot, 'CMakePresets.json'),     isUser: false },
-    { filePath: path.join(projectRoot, 'CMakeUserPresets.json'), isUser: true  },
-  ];
-
-  for (const { filePath, isUser } of candidates) {
-    if (!fs.existsSync(filePath)) {
-      const content = buildFreshPresetsFile(args);
-      fs.writeFileSync(filePath, JSON.stringify(content, null, 2) + '\n', 'utf8');
-      return { path: filePath, action: 'created', isUser };
-    }
-
-    const existing = safeReadJson(filePath);
-    if (isWyvrnGenerated(existing)) {
-      const merged = mergeIntoExisting(existing, args);
-      fs.writeFileSync(filePath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
-      return { path: filePath, action: 'updated', isUser };
-    }
-
-    // User-owned — do not touch, try next candidate.
-  }
-
-  return { path: null, action: 'skipped', isUser: false };
-}
-
-module.exports = {
-  generateCMakePresets,
-  // Exported for tests
-  isWyvrnGenerated,
-  buildConfigurePreset,
-  buildBuildPresets,
-  buildFreshPresetsFile,
-  mergeIntoExisting,
-  VENDOR_KEY,
-  SCHEMA_VERSION,
-};
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const { DEFAULT_BINARY_DIR_ROOT } = require('../binary-dir');
+
+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
+
+/**
+ * Safely parse a JSON file; returns null on any error (missing, malformed, …).
+ * @param {string} p
+ * @returns {object|null}
+ */
+function safeReadJson(p) {
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * True if the parsed presets object was produced by wyvrnpm (i.e. carries our
+ * vendor marker). Hand-edited or user-owned files return false.
+ *
+ * @param {object|null} presets
+ * @returns {boolean}
+ */
+function isWyvrnGenerated(presets) {
+  return !!presets && typeof presets.vendor === 'object' && !!presets.vendor[VENDOR_KEY];
+}
+
+/**
+ * Build the configure preset object for the active profile.
+ *
+ * When the project has its own `build` recipe (i.e. it's a publishable
+ * library with `build.generator` / `build.configure` declared), those are
+ * propagated into the generated preset so `wyvrnpm build` locally honours
+ * the same knobs the source-build + publish paths use. Without this, a
+ * publisher's recipe is effectively advisory at install-time (F15 fix).
+ *
+ * @param {object} args
+ * @param {string} args.profileName
+ * @param {string} args.profileHash
+ * @param {string} args.toolchainRelPath       Relative from project root, CMake-style
+ *                                             forward slashes.
+ * @param {string|null} [args.generator]       Single generator name to pin on the
+ *                                             preset (e.g. "Ninja Multi-Config").
+ *                                             Null / undefined → let CMake pick.
+ * @param {Record<string,string>|null} [args.extraCacheVariables]
+ *                                             Merged into cacheVariables alongside
+ *                                             `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).
+ * @param {string[]|null} [args.configs]       Build recipe's `configs` list
+ *                                             (e.g. ['Debug','Release','MinSizeRel']).
+ *                                             When provided, drives
+ *                                             `CMAKE_CONFIGURATION_TYPES` so
+ *                                             multi-config generators (Ninja
+ *                                             Multi-Config, VS) actually
+ *                                             produce every config the recipe
+ *                                             declares. Null/empty → omitted
+ *                                             (let CMake use its generator
+ *                                             default). `extraCacheVariables`
+ *                                             wins on explicit collision so
+ *                                             authors that already bake the
+ *                                             list into `build.configure`
+ *                                             aren't overridden.
+ * @param {string|null} [args.binaryDirRoot]   Project-relative subdir for the
+ *                                             preset's binaryDir. Defaults to
+ *                                             `"build"`. Override via
+ *                                             `--build-dir` or
+ *                                             `wyvrn.local.json:binaryDirRoot`
+ *                                             when the repo has a `BUILD`
+ *                                             Bazel/Buck file at root that
+ *                                             collides with `build/` on
+ *                                             case-insensitive filesystems.
+ */
+function buildConfigurePreset({
+  profileName,
+  profileHash,
+  toolchainRelPath,
+  generator = null,
+  extraCacheVariables = null,
+  installDir = null,
+  profileArch = null,
+  configs = null,
+  binaryDirRoot = DEFAULT_BINARY_DIR_ROOT,
+}) {
+  const root = binaryDirRoot || DEFAULT_BINARY_DIR_ROOT;
+  const binaryDir = `\${sourceDir}/${root}/wyvrn-${profileName}`;
+  // CMAKE_CONFIGURATION_TYPES is a defensible default from the recipe's
+  // declared `configs` list. Applied FIRST (lowest precedence) so an
+  // explicit `-DCMAKE_CONFIGURATION_TYPES=...` in `build.configure`
+  // still wins — authors who already pin the list shouldn't silently
+  // lose their override. The wyvrn-owned entries (toolchain, install
+  // prefix) still win over both below.
+  const configsDefault = (Array.isArray(configs) && configs.length > 0)
+    ? { CMAKE_CONFIGURATION_TYPES: configs.join(';') }
+    : {};
+  const cacheVariables = {
+    ...configsDefault,
+    ...(extraCacheVariables ?? {}),
+    CMAKE_TOOLCHAIN_FILE: `\${sourceDir}/${toolchainRelPath}`,
+  };
+  if (installDir) {
+    // `installDir` in wyvrn.json is defined as relative to the binary dir
+    // (same semantics as the source-build path, which passes
+    // -DCMAKE_INSTALL_PREFIX=<buildDir>/<installDir>). Without this, a
+    // `wyvrnpm build --install` falls back to CMake's system default —
+    // on Windows that's `C:/Program Files (x86)/<Project>`, which needs
+    // admin rights and almost always fails.
+    cacheVariables.CMAKE_INSTALL_PREFIX = `${binaryDir}/${installDir}`;
+  }
+  const preset = {
+    name:         `wyvrn-${profileName}`,
+    displayName:  `wyvrnpm (${profileName})`,
+    description:  `Generated by wyvrnpm install — profile hash ${profileHash}`,
+    binaryDir,
+    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;
+}
+
+/**
+ * One build preset per configuration the recipe declares (or the
+ * legacy default pair `Debug` + `Release` when no list is provided).
+ *
+ * The preset name suffix is the configuration name lower-cased — matches
+ * the previous Debug/Release naming for those two, and extends to
+ * `wyvrn-<profile>-relwithdebinfo` / `-minsizerel` for the multi-config
+ * cases. Authors whose recipes include `MinSizeRel` in `build.configs`
+ * can now `cmake --build --preset wyvrn-<profile>-minsizerel` directly.
+ *
+ * @param {string} profileName
+ * @param {string[]|null} [configs]  Recipe's declared configurations. When
+ *   null/empty, emits the pre-2.8.1 `Debug` + `Release` pair so existing
+ *   CMakePresets.json files remain byte-identical.
+ * @returns {Array<object>}
+ */
+function buildBuildPresets(profileName, configs = null) {
+  const base = `wyvrn-${profileName}`;
+  const list = (Array.isArray(configs) && configs.length > 0)
+    ? configs
+    : ['Debug', 'Release'];
+  return list.map((cfg) => ({
+    name:            `${base}-${cfg.toLowerCase()}`,
+    displayName:     `wyvrn ${profileName} (${cfg})`,
+    configurePreset: base,
+    configuration:   cfg,
+  }));
+}
+
+/**
+ * Build a fresh presets file from scratch (no prior content to merge).
+ */
+function buildFreshPresetsFile({
+  profileName,
+  profileHash,
+  toolchainRelPath,
+  generator = null,
+  extraCacheVariables = null,
+  installDir = null,
+  profileArch = null,
+  configs = null,
+  binaryDirRoot = DEFAULT_BINARY_DIR_ROOT,
+}) {
+  return {
+    version: SCHEMA_VERSION,
+    vendor: {
+      [VENDOR_KEY]: {
+        profileName,
+        profileHash,
+        generatedAt: new Date().toISOString(),
+      },
+    },
+    configurePresets: [buildConfigurePreset({
+      profileName, profileHash, toolchainRelPath, generator, extraCacheVariables, installDir, profileArch, configs, binaryDirRoot,
+    })],
+    buildPresets: buildBuildPresets(profileName, configs),
+  };
+}
+
+/**
+ * Merge the current profile's presets into an existing wyvrnpm-generated
+ * file. Presets with matching `name` are replaced; others are preserved so
+ * `wyvrnpm install --profile release` followed by `wyvrnpm install --profile
+ * debug` leaves both profiles available in the file.
+ *
+ * @param {object} existing
+ * @param {object} args  forwarded to the preset builders
+ * @returns {object}
+ */
+function mergeIntoExisting(existing, {
+  profileName,
+  profileHash,
+  toolchainRelPath,
+  generator = null,
+  extraCacheVariables = null,
+  installDir = null,
+  profileArch = null,
+  configs = null,
+  binaryDirRoot = DEFAULT_BINARY_DIR_ROOT,
+}) {
+  const newConfigure = buildConfigurePreset({
+    profileName, profileHash, toolchainRelPath, generator, extraCacheVariables, installDir, profileArch, configs, binaryDirRoot,
+  });
+  const newBuilds    = buildBuildPresets(profileName, configs);
+  const newConfigureNames = new Set([newConfigure.name]);
+  // When replacing THIS profile's build presets, drop every pre-existing
+  // one that targets the same configurePreset — the fresh `newBuilds`
+  // list fully replaces them. Scoping to configurePreset avoids stepping
+  // on presets for OTHER profiles in the same file, which is the whole
+  // point of the merge path.
+  //
+  // Without this, editing `build.configs` from 4 configs down to 2 would
+  // leave orphan build presets pointing at configurations CMake won't
+  // generate.
+  const myBase = `wyvrn-${profileName}`;
+  const isMyBuildPreset = (p) => p && p.configurePreset === myBase;
+
+  const configurePresets = (existing.configurePresets ?? []).filter((p) => !newConfigureNames.has(p.name));
+  configurePresets.push(newConfigure);
+
+  // Drop every pre-existing build preset that targets THIS profile's
+  // configurePreset — the fresh `newBuilds` list (one per current
+  // `configs` entry) fully replaces them. Presets for OTHER profiles
+  // stay untouched so the multi-profile merge story is preserved.
+  const buildPresets = (existing.buildPresets ?? []).filter((p) => !isMyBuildPreset(p));
+  buildPresets.push(...newBuilds);
+
+  return {
+    ...existing,
+    version: existing.version ?? SCHEMA_VERSION,
+    vendor: {
+      ...(existing.vendor ?? {}),
+      [VENDOR_KEY]: {
+        profileName,
+        profileHash,
+        generatedAt: new Date().toISOString(),
+      },
+    },
+    configurePresets,
+    buildPresets,
+  };
+}
+
+/**
+ * Write a CMakePresets.json (or CMakeUserPresets.json, as fallback) under
+ * `projectRoot`. Never overwrites a user-owned file.
+ *
+ * Resolution order:
+ *   1. CMakePresets.json
+ *      - Does not exist     → create it.
+ *      - Exists, wyvrn-gen  → merge into it.
+ *      - Exists, user-owned → leave alone, fall through.
+ *   2. CMakeUserPresets.json
+ *      - Does not exist     → create it.
+ *      - Exists, wyvrn-gen  → merge into it.
+ *      - Exists, user-owned → skip (action: "skipped").
+ *
+ * @param {object} args
+ * @param {string} args.projectRoot       Directory containing top-level CMakeLists.txt.
+ * @param {string} args.profileName
+ * @param {string} args.profileHash
+ * @param {string} args.toolchainRelPath  CMake-style forward slashes, relative to projectRoot.
+ * @param {string|null} [args.generator]  Propagated onto the configure preset's `generator` field.
+ * @param {Record<string,string>|null} [args.extraCacheVariables]
+ *                                        Merged into the configure preset's `cacheVariables`.
+ * @returns {{ path: string|null, action: 'created'|'updated'|'skipped', isUser: boolean }}
+ */
+function generateCMakePresets({
+  projectRoot,
+  profileName,
+  profileHash,
+  toolchainRelPath,
+  generator = null,
+  extraCacheVariables = null,
+  installDir = null,
+  profileArch = null,
+  configs = null,
+  binaryDirRoot = DEFAULT_BINARY_DIR_ROOT,
+}) {
+  const args = { profileName, profileHash, toolchainRelPath, generator, extraCacheVariables, installDir, profileArch, configs, binaryDirRoot };
+  const candidates = [
+    { filePath: path.join(projectRoot, 'CMakePresets.json'),     isUser: false },
+    { filePath: path.join(projectRoot, 'CMakeUserPresets.json'), isUser: true  },
+  ];
+
+  for (const { filePath, isUser } of candidates) {
+    if (!fs.existsSync(filePath)) {
+      const content = buildFreshPresetsFile(args);
+      fs.writeFileSync(filePath, JSON.stringify(content, null, 2) + '\n', 'utf8');
+      return { path: filePath, action: 'created', isUser };
+    }
+
+    const existing = safeReadJson(filePath);
+    if (isWyvrnGenerated(existing)) {
+      const merged = mergeIntoExisting(existing, args);
+      fs.writeFileSync(filePath, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+      return { path: filePath, action: 'updated', isUser };
+    }
+
+    // User-owned — do not touch, try next candidate.
+  }
+
+  return { path: null, action: 'skipped', isUser: false };
+}
+
+module.exports = {
+  generateCMakePresets,
+  // Exported for tests
+  isWyvrnGenerated,
+  buildConfigurePreset,
+  buildBuildPresets,
+  buildFreshPresetsFile,
+  mergeIntoExisting,
+  VENDOR_KEY,
+  SCHEMA_VERSION,
+};