wyvrnpm 2.0.2 → 2.1.0

package/src/logger.js

@@ -0,0 +1,78 @@
+'use strict';
+
+// ANSI-coloured, level-tagged logger for wyvrnpm CLI output.
+//
+// All user-facing lines go through this module so the `[wyvrn]` prefix and
+// level markers are applied consistently. Callers pass the message content
+// only — the prefix is never written at call sites.
+//
+// Colour is emitted when the target stream is a TTY, unless overridden by
+// the NO_COLOR or FORCE_COLOR environment variables (see https://no-color.org).
+
+const PREFIX = '[wyvrn]';
+
+const ANSI = {
+  reset:  '\x1b[0m',
+  bold:   '\x1b[1m',
+  dim:    '\x1b[2m',
+  red:    '\x1b[31m',
+  green:  '\x1b[32m',
+  yellow: '\x1b[33m',
+  cyan:   '\x1b[36m',
+};
+
+function colorEnabled(stream) {
+  if (process.env.NO_COLOR)    return false;
+  if (process.env.FORCE_COLOR) return true;
+  return !!(stream && stream.isTTY);
+}
+
+function paint(text, code, stream) {
+  return colorEnabled(stream) ? `${code}${text}${ANSI.reset}` : text;
+}
+
+function emit(stream, consoleFn, coloredPrefix, message) {
+  // Every line in a multi-line message gets the prefix — so multi-line errors
+  // line up visually without the caller having to repeat `[wyvrn]` per line.
+  const out = String(message)
+    .split('\n')
+    .map((line) => `${coloredPrefix} ${line}`)
+    .join('\n');
+  consoleFn(out);
+}
+
+function info(message) {
+  emit(
+    process.stdout,
+    console.log,
+    paint(PREFIX, ANSI.dim, process.stdout),
+    message,
+  );
+}
+
+function warn(message) {
+  const p   = paint(PREFIX, ANSI.yellow, process.stderr);
+  const tag = paint('warn', ANSI.yellow + ANSI.bold, process.stderr);
+  emit(process.stderr, console.warn, `${p} ${tag}`, message);
+}
+
+function error(message) {
+  const p   = paint(PREFIX, ANSI.red, process.stderr);
+  const tag = paint('error', ANSI.red + ANSI.bold, process.stderr);
+  emit(process.stderr, console.error, `${p} ${tag}`, message);
+}
+
+function success(message) {
+  const p   = paint(PREFIX, ANSI.green, process.stdout);
+  const tag = paint('ok', ANSI.green + ANSI.bold, process.stdout);
+  emit(process.stdout, console.log, `${p} ${tag}`, message);
+}
+
+function debug(message) {
+  if (!process.env.WYVRNPM_DEBUG) return;
+  const p   = paint(PREFIX, ANSI.dim, process.stderr);
+  const tag = paint('debug', ANSI.cyan, process.stderr);
+  emit(process.stderr, console.error, `${p} ${tag}`, message);
+}
+
+module.exports = { info, warn, error, success, debug };

package/src/profile.js

@@ -214,6 +214,33 @@ function getGitRepo(cwd) {
   return tryExec(`git -C "${cwd || '.'}" remote get-url origin`) || null;
 }
 
+/**
+ * Check whether `sha` is reachable from any remote tracking branch or tag.
+ * Used at publish time to warn when the publisher's HEAD hasn't been pushed
+ * — a commit that isn't reachable from origin cannot be retrieved by
+ * downstream `--build=missing` consumers.
+ *
+ * @param {string} sha
+ * @param {string} [cwd]
+ * @returns {boolean} true if the commit is reachable on origin
+ */
+function isShaOnRemote(sha, cwd) {
+  if (!sha) return false;
+  // --remotes limits to remote-tracking branches; include tags too so
+  // tagged release commits on deleted branches still count as reachable.
+  const branches = tryExec(`git -C "${cwd || '.'}" branch -r --contains ${sha}`);
+  if (branches && branches.trim().length > 0) return true;
+  const tags = tryExec(`git -C "${cwd || '.'}" tag --contains ${sha}`);
+  if (tags && tags.trim().length > 0) {
+    // A local tag is only useful if it's also on origin. Check.
+    const remoteTags = tryExec(`git -C "${cwd || '.'}" ls-remote --tags origin`);
+    if (remoteTags && tags.split(/\s+/).some((t) => t && remoteTags.includes(`refs/tags/${t}`))) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Format a profile for human-readable display (Conan-style).
  *
@@ -354,6 +381,7 @@ module.exports = {
   sha256Of,
   getGitSha,
   getGitRepo,
+  isShaOnRemote,
   formatProfile,
   mergeProfile,
   // Profile file management

package/src/providers/file.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const BaseProvider = require('./base');
+const log = require('../logger');
 
 /**
  * File system provider — handles local directories and SMB/UNC shares.
@@ -56,12 +57,12 @@ class FileProvider extends BaseProvider {
   }
 
   _copy(src, dest) {
-    console.log(`[wyvrn]   → ${dest}`);
+    log.info(`  → ${dest}`);
     fs.copyFileSync(src, dest);
   }
 
   _writeJson(filePath, data) {
-    console.log(`[wyvrn]   → ${filePath}`);
+    log.info(`  → ${filePath}`);
     fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + '\n', 'utf8');
   }
 
@@ -87,7 +88,7 @@ class FileProvider extends BaseProvider {
     this._copy(files.zip,      path.join(destDir, 'wyvrn.zip'));
 
     const latestPath = path.join(packageDir, 'latest.json');
-    console.log(`[wyvrn]   → ${latestPath}`);
+    log.info(`  → ${latestPath}`);
     fs.writeFileSync(latestPath, JSON.stringify({ version }), 'utf8');
   }
 

package/src/providers/http.js

@@ -6,6 +6,7 @@ const https = require('https');
 const { pipeline } = require('stream/promises');
 const { Readable } = require('stream');
 const BaseProvider = require('./base');
+const log = require('../logger');
 
 function pinDependencies(rawDeps, lockedDeps) {
   if (!rawDeps || !lockedDeps || Object.keys(lockedDeps).length === 0) return rawDeps;
@@ -45,7 +46,7 @@ class HttpProvider extends BaseProvider {
       const parsed = new URL(url);
       const headers = { 'Content-Type': contentType, 'Content-Length': body.length };
       if (token) headers['Authorization'] = `Bearer ${token}`;
-      console.log(`[wyvrn]   → PUT ${url}`);
+      log.info(`  → PUT ${url}`);
       const req = this._lib(url).request(
         { hostname: parsed.hostname, port: parsed.port || undefined, path: parsed.pathname, method: 'PUT', headers },
         (res) => {
@@ -66,7 +67,7 @@ class HttpProvider extends BaseProvider {
       const parsed = new URL(url);
       const headers = { 'Content-Type': contentType, 'Content-Length': buffer.length };
       if (token) headers['Authorization'] = `Bearer ${token}`;
-      console.log(`[wyvrn]   → PUT ${url}`);
+      log.info(`  → PUT ${url}`);
       const req = this._lib(url).request(
         { hostname: parsed.hostname, port: parsed.port || undefined, path: parsed.pathname, method: 'PUT', headers },
         (res) => {

package/src/providers/s3.js

@@ -3,6 +3,7 @@
 const fs = require('fs');
 const path = require('path');
 const BaseProvider = require('./base');
+const log = require('../logger');
 
 const RE_S3_URI           = /^s3:\/\//;
 const RE_S3_VIRTUAL_HOSTED = /^https?:\/\/([^.]+)\.s3[.-][^/]*\.amazonaws\.com/;
@@ -79,7 +80,7 @@ class S3Provider extends BaseProvider {
   }
 
   async _putFile(client, bucket, key, filePath, contentType, PutObjectCommand) {
-    console.log(`[wyvrn]   → s3://${bucket}/${key}`);
+    log.info(`  → s3://${bucket}/${key}`);
     await client.send(new PutObjectCommand({
       Bucket: bucket, Key: key,
       Body: fs.readFileSync(filePath),
@@ -88,7 +89,7 @@ class S3Provider extends BaseProvider {
   }
 
   async _putBuffer(client, bucket, key, content, contentType, PutObjectCommand) {
-    console.log(`[wyvrn]   → s3://${bucket}/${key}`);
+    log.info(`  → s3://${bucket}/${key}`);
     await client.send(new PutObjectCommand({
       Bucket: bucket, Key: key,
       Body: content,

package/src/resolve.js

@@ -3,6 +3,8 @@
 const fs = require('fs');
 const path = require('path');
 
+const log = require('./logger');
+
 /**
  * Checks if a version string represents a linked package.
  * @param {string} version
@@ -121,6 +123,30 @@ async function fetchPackageManifest(name, version, packageSources, platform, htt
 
   for (const source of packageSources) {
     const base = source.replace(/\/$/, '');
+
+    // v2: look up any available profile hash from versions.json, then fetch that manifest
+    try {
+      const idxResp = await httpClient(`${base}/v2/${name}/versions.json`);
+      if (idxResp.ok) {
+        const idx = await idxResp.json();
+        const profiles = idx?.versions?.[version]?.profiles;
+        if (profiles) {
+          const profileHash = Object.keys(profiles)[0];
+          if (profileHash) {
+            const mResp = await httpClient(`${base}/v2/${name}/${version}/${profileHash}/wyvrn.json`);
+            if (mResp.ok) {
+              const data = await mResp.json();
+              cache.set(cacheKey, data);
+              return data;
+            }
+          }
+        }
+      }
+    } catch {
+      // fall through to v1
+    }
+
+    // v1 legacy paths
     const candidates = [
       `${base}/${platform}/${name}/${version}/wyvrn.json`,
       `${base}/${platform}/${name}/${version}/razer.json`,
@@ -140,7 +166,7 @@ async function fetchPackageManifest(name, version, packageSources, platform, htt
     }
   }
 
-  console.warn(`[wyvrn] Warning: could not fetch manifest for ${name}@${version} from any source`);
+  log.warn(`could not fetch manifest for ${name}@${version} from any source`);
   cache.set(cacheKey, null);
   return null;
 }
@@ -181,9 +207,9 @@ async function resolveDependencies(rootDeps, packageSources, platform, httpClien
     if (version === 'latest') {
       try {
         version = await resolveLatestVersion(name, packageSources, platform, httpClient);
-        console.log(`[wyvrn] Resolved "${name}@latest" → ${version}`);
+        log.info(`Resolved "${name}@latest" → ${version}`);
       } catch (err) {
-        console.warn(`[wyvrn] Warning: ${err.message}`);
+        log.warn(err.message);
         continue;
       }
     }
@@ -200,8 +226,8 @@ async function resolveDependencies(rootDeps, packageSources, platform, httpClien
       // Conflict: keep the latest version.
       const winner = compareVersions(version, existing) > 0 ? version : existing;
       if (winner !== existing) {
-        console.warn(
-          `[wyvrn] Version conflict for "${name}": ${existing} vs ${version} — using ${winner}`,
+        log.warn(
+          `Version conflict for "${name}": ${existing} vs ${version} — using ${winner}`,
         );
         resolved.set(name, winner);
         // Re-fetch the winning version's manifest to pull in its transitive deps.
@@ -218,9 +244,9 @@ async function resolveDependencies(rootDeps, packageSources, platform, httpClien
       const localPath = getLinkedPath(version);
       manifest = readLocalManifest(localPath);
       if (manifest) {
-        console.log(`[wyvrn] Linked: ${name} → ${localPath}`);
+        log.info(`Linked: ${name} → ${localPath}`);
       } else {
-        console.log(`[wyvrn] Linked: ${name} → ${localPath} (no manifest found)`);
+        log.info(`Linked: ${name} → ${localPath} (no manifest found)`);
       }
     } else {
       manifest = await fetchPackageManifest(

package/src/toolchain/deps.js

@@ -0,0 +1,164 @@
+'use strict';
+
+/**
+ * Generate the contents of `wyvrn_deps.cmake`.
+ *
+ * This file is loaded via `CMAKE_PROJECT_INCLUDE` — it runs after the
+ * consumer's first `project()` call, which is when CMake variables like
+ * `CMAKE_CXX_COMPILER_ID`, `CMAKE_SIZEOF_VOID_P`, `CMAKE_SYSTEM_NAME`, and
+ * `WIN32` / `APPLE` / `UNIX` become valid. The bundled utility scripts
+ * (`variables.cmake` etc.) rely on those, so they cannot be included from
+ * the toolchain body.
+ *
+ * @param {object}   args
+ * @param {string[]} args.packageNames       Resolved dep names in topological order.
+ * @param {string}   args.profileHash        16-char profile hash (for logging).
+ * @returns {string} CMake file content.
+ */
+function generateDepsCmake({ packageNames, profileHash }) {
+  const findPackageCalls = packageNames
+    .map((name) => `    find_package(${name} CONFIG QUIET)`)
+    .join('\n');
+
+  const resolvedList = packageNames.map((n) => `    ${n}`).join('\n');
+
+  return `# Generated by wyvrnpm — do not edit.
+# Loaded after project() via CMAKE_PROJECT_INCLUDE.
+# Profile hash: ${profileHash}
+
+if(WYVRN_DEPS_INCLUDED)
+    return()
+endif()
+set(WYVRN_DEPS_INCLUDED TRUE)
+
+# List of every package resolved by \`wyvrnpm install\`, in topological order.
+set(WYVRN_RESOLVED_PACKAGES
+${resolvedList || '    # (none)'}
+)
+
+# ── Bundled wyvrnpm CMake utilities ───────────────────────────────────────────
+# Included in the order the utility scripts expect.
+include("\${WYVRNPM_CMAKE_DIR}/variables.cmake")
+include("\${WYVRNPM_CMAKE_DIR}/options.cmake")
+include("\${WYVRNPM_CMAKE_DIR}/cpp.cmake")
+include("\${WYVRNPM_CMAKE_DIR}/functions.cmake")
+include("\${WYVRNPM_CMAKE_DIR}/macros.cmake")
+
+# ── Sanity checks (warn only — do not override the consumer's environment) ───
+if(DEFINED CMAKE_CXX_COMPILER_ID AND DEFINED WYVRN_PROFILE_COMPILER)
+    set(_wyvrn_expected_compiler_id "")
+    if(WYVRN_PROFILE_COMPILER STREQUAL "msvc")
+        set(_wyvrn_expected_compiler_id "MSVC")
+    elseif(WYVRN_PROFILE_COMPILER STREQUAL "gcc")
+        set(_wyvrn_expected_compiler_id "GNU")
+    elseif(WYVRN_PROFILE_COMPILER STREQUAL "clang")
+        set(_wyvrn_expected_compiler_id "Clang")
+    elseif(WYVRN_PROFILE_COMPILER STREQUAL "apple-clang")
+        set(_wyvrn_expected_compiler_id "AppleClang")
+    endif()
+    if(_wyvrn_expected_compiler_id AND NOT CMAKE_CXX_COMPILER_ID STREQUAL _wyvrn_expected_compiler_id)
+        message(WARNING
+            "wyvrnpm profile expects compiler '\${WYVRN_PROFILE_COMPILER}' "
+            "(CMake id '\${_wyvrn_expected_compiler_id}') but the active compiler "
+            "is '\${CMAKE_CXX_COMPILER_ID}'. Installed binaries may be ABI-incompatible."
+        )
+    endif()
+endif()
+
+if(DEFINED CMAKE_SIZEOF_VOID_P AND DEFINED WYVRN_PROFILE_ARCH)
+    if(WYVRN_PROFILE_ARCH STREQUAL "x86_64" OR WYVRN_PROFILE_ARCH STREQUAL "armv8")
+        if(NOT CMAKE_SIZEOF_VOID_P EQUAL 8)
+            message(WARNING
+                "wyvrnpm profile expects 64-bit arch '\${WYVRN_PROFILE_ARCH}' "
+                "but CMake is configuring a 32-bit build (CMAKE_SIZEOF_VOID_P=\${CMAKE_SIZEOF_VOID_P})."
+            )
+        endif()
+    elseif(WYVRN_PROFILE_ARCH STREQUAL "x86")
+        if(NOT CMAKE_SIZEOF_VOID_P EQUAL 4)
+            message(WARNING
+                "wyvrnpm profile expects 32-bit arch 'x86' "
+                "but CMake is configuring a 64-bit build (CMAKE_SIZEOF_VOID_P=\${CMAKE_SIZEOF_VOID_P})."
+            )
+        endif()
+    endif()
+endif()
+
+# ── wyvrnpm_find_dependencies() ───────────────────────────────────────────────
+# One-shot helper: resolves every package that wyvrnpm installed.
+# Packages that don't ship a CMake config are silently skipped (CONFIG QUIET).
+function(wyvrnpm_find_dependencies)
+${findPackageCalls || '    # (no dependencies)'}
+
+    # Post-find aliasing: ensure every resolved package has a wyvrn::<name>
+    # target, creating an INTERFACE alias when the package exports only
+    # <name>::<name>. Skipped when wyvrn::<name> already exists.
+    foreach(_wyvrn_pkg IN LISTS WYVRN_RESOLVED_PACKAGES)
+        if(TARGET wyvrn::\${_wyvrn_pkg})
+            # Already provided by the package's own CMake config.
+        elseif(TARGET \${_wyvrn_pkg}::\${_wyvrn_pkg})
+            add_library(wyvrn::\${_wyvrn_pkg} INTERFACE IMPORTED)
+            set_target_properties(wyvrn::\${_wyvrn_pkg} PROPERTIES
+                INTERFACE_LINK_LIBRARIES \${_wyvrn_pkg}::\${_wyvrn_pkg}
+            )
+        endif()
+    endforeach()
+endfunction()
+
+# ── wyvrnpm_enable_runtime_dll_copy(target) ───────────────────────────────────
+# Adds a POST_BUILD command that copies every runtime DLL the target depends on
+# (transitively, via \$<TARGET_RUNTIME_DLLS:...>) next to the target's own
+# binary — so consumers can run the executable straight from the build dir
+# without \`PATH\` tinkering. No-op on non-Windows platforms and on non-
+# executable targets.
+#
+# Respects the per-target opt-out property WYVRN_COPY_RUNTIME_DLLS OFF.
+# Requires CMake ≥ 3.21 (for TARGET_RUNTIME_DLLS).
+function(wyvrnpm_enable_runtime_dll_copy target)
+    if(NOT WIN32)
+        return()
+    endif()
+    if(NOT TARGET \${target})
+        message(WARNING "wyvrnpm_enable_runtime_dll_copy: target '\${target}' does not exist")
+        return()
+    endif()
+    get_target_property(_wyvrn_type \${target} TYPE)
+    if(NOT _wyvrn_type STREQUAL "EXECUTABLE")
+        return()
+    endif()
+    get_target_property(_wyvrn_optout \${target} WYVRN_COPY_RUNTIME_DLLS)
+    if(_wyvrn_optout STREQUAL "OFF" OR _wyvrn_optout STREQUAL "FALSE")
+        return()
+    endif()
+    add_custom_command(TARGET \${target} POST_BUILD
+        COMMAND \${CMAKE_COMMAND} -E copy_if_different
+                "\$<TARGET_RUNTIME_DLLS:\${target}>"
+                "\$<TARGET_FILE_DIR:\${target}>"
+        COMMAND_EXPAND_LISTS
+        VERBATIM
+    )
+endfunction()
+
+# ── wyvrnpm_finalize_targets() ────────────────────────────────────────────────
+# Discovers all executable targets in the calling directory (top-level only,
+# not recursive) and wires each one up for runtime-DLL copy. Call this at the
+# end of the consumer's top-level CMakeLists.txt, AFTER all add_executable()
+# calls, so every target is visible.
+#
+# Scope: uses the BUILDSYSTEM_TARGETS directory property of the calling
+# directory. For multi-subdirectory projects where executables are added from
+# subdirectories, consumers should either:
+#   (a) call wyvrnpm_enable_runtime_dll_copy(<tgt>) explicitly for each exe, or
+#   (b) call wyvrnpm_finalize_targets() from each subdirectory.
+function(wyvrnpm_finalize_targets)
+    get_property(_wyvrn_targets DIRECTORY PROPERTY BUILDSYSTEM_TARGETS)
+    foreach(_wyvrn_t IN LISTS _wyvrn_targets)
+        get_target_property(_wyvrn_type \${_wyvrn_t} TYPE)
+        if(_wyvrn_type STREQUAL "EXECUTABLE")
+            wyvrnpm_enable_runtime_dll_copy(\${_wyvrn_t})
+        endif()
+    endforeach()
+endfunction()
+`;
+}
+
+module.exports = { generateDepsCmake };

package/src/toolchain/index.js

@@ -0,0 +1,141 @@
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const { generateDepsCmake }     = require('./deps');
+const { generateCMakePresets } = require('./presets');
+
+/**
+ * Absolute path to the bundled `cmake/` directory shipped inside the
+ * wyvrnpm npm package. Returned in CMake-friendly form (forward slashes).
+ *
+ * @returns {string}
+ */
+function getBundledCmakeDir() {
+  const dir = path.resolve(__dirname, '..', '..', 'cmake');
+  return dir.replace(/\\/g, '/');
+}
+
+/**
+ * Substitute `{{KEY}}` placeholders in a template string.
+ *
+ * @param {string} template
+ * @param {Record<string, string>} values
+ * @returns {string}
+ */
+function renderTemplate(template, values) {
+  return template.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+    if (Object.prototype.hasOwnProperty.call(values, key)) {
+      return values[key];
+    }
+    throw new Error(`Toolchain template has no value for placeholder {{${key}}}`);
+  });
+}
+
+/**
+ * Produce the toolchain template's placeholder substitutions.
+ *
+ * @param {object} args
+ * @param {import('../profile').WyvrnProfile} args.profile
+ * @param {string} args.profileName
+ * @param {string} args.profileHash
+ * @param {string[]} args.packageNames
+ * @returns {Record<string, string>}
+ */
+function buildPlaceholders({ profile, profileName, profileHash, packageNames }) {
+  const prefixPathEntries = packageNames
+    .map((name) => `    "\${CMAKE_CURRENT_LIST_DIR}/${name}"`)
+    .join('\n');
+
+  return {
+    GENERATED_AT:             new Date().toISOString(),
+    PROFILE_NAME:             profileName,
+    PROFILE_HASH:             profileHash,
+    PROFILE_OS:               profile.os ?? '',
+    PROFILE_ARCH:             profile.arch ?? '',
+    PROFILE_COMPILER:         profile.compiler ?? '',
+    PROFILE_COMPILER_VERSION: profile['compiler.version'] ?? '',
+    PROFILE_CPPSTD:           profile['compiler.cppstd'] ?? '20',
+    PROFILE_RUNTIME:          profile['compiler.runtime'] ?? '',
+    WYVRNPM_CMAKE_DIR:        getBundledCmakeDir(),
+    PREFIX_PATH_ENTRIES:      prefixPathEntries || '    # (no dependencies)',
+  };
+}
+
+/**
+ * Generate the three toolchain artefacts under `destDir`:
+ *   - wyvrn_toolchain.cmake
+ *   - wyvrn_deps.cmake
+ *   - wyvrn_profile.json
+ *
+ * ───────────────────────────────────────────────────────────────────────────
+ * CONTRACT (PLAN-CMAKE-TOOLCHAIN Phase F ↔ PLAN-BUILD-MISSING Phase 3)
+ * ───────────────────────────────────────────────────────────────────────────
+ * This function is the **single source of truth** for translating a build
+ * profile into a CMake configuration. Two callers exist:
+ *
+ *   1. `install`              — writes the toolchain into a consumer project's
+ *                               `wyvrn_internal/`, so `cmake --preset` picks it
+ *                               up at configure time.
+ *   2. `buildFromSource`      — (not yet implemented; PLAN-BUILD-MISSING §3)
+ *                               writes the toolchain into a scratch build dir
+ *                               when we source-build a package via
+ *                               `--build=missing`. The package is compiled
+ *                               with THIS function's output, guaranteeing the
+ *                               resulting binary's profile → flag mapping is
+ *                               bit-for-bit identical to what a consumer sees.
+ *
+ * Do NOT replicate this mapping elsewhere. If PLAN-BUILD-MISSING §3 finds it
+ * needs additional behaviour (e.g. extra CMake cache variables), extend this
+ * function — do not branch.
+ *
+ * Callers choose `destDir` and `packageNames`:
+ *   - `destDir`      — any directory; in source-build, points at the scratch
+ *                      `wyvrn_internal/` co-located with the cloned source.
+ *   - `packageNames` — in `install`, the consumer's resolved deps; in
+ *                      source-build, the *package's own* resolved deps.
+ *
+ * Profile arguments (`profile`, `profileName`, `profileHash`) are always the
+ * active consumer profile — source-build still uses the consumer's profile,
+ * not the package's. That is the whole point of the source-build path.
+ * ───────────────────────────────────────────────────────────────────────────
+ *
+ * @param {object} args
+ * @param {string} args.destDir         Where to write the three files.
+ * @param {import('../profile').WyvrnProfile} args.profile
+ * @param {string} args.profileName
+ * @param {string} args.profileHash
+ * @param {string[]} args.packageNames  Resolved dep names in topological order.
+ * @returns {{ toolchain: string, deps: string, profile: string }}
+ *          Absolute paths of the three files written.
+ */
+function generateToolchain({ destDir, profile, profileName, profileHash, packageNames }) {
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const templatePath = path.join(__dirname, 'template.cmake');
+  const template     = fs.readFileSync(templatePath, 'utf8');
+  const placeholders = buildPlaceholders({ profile, profileName, profileHash, packageNames });
+  const toolchainContent = renderTemplate(template, placeholders);
+  const depsContent      = generateDepsCmake({ packageNames, profileHash });
+  const profileContent   = JSON.stringify({ name: profileName, hash: profileHash, ...profile }, null, 2) + '\n';
+
+  const toolchainPath = path.join(destDir, 'wyvrn_toolchain.cmake');
+  const depsPath      = path.join(destDir, 'wyvrn_deps.cmake');
+  const profilePath   = path.join(destDir, 'wyvrn_profile.json');
+
+  fs.writeFileSync(toolchainPath, toolchainContent, 'utf8');
+  fs.writeFileSync(depsPath,      depsContent,      'utf8');
+  fs.writeFileSync(profilePath,   profileContent,   'utf8');
+
+  return { toolchain: toolchainPath, deps: depsPath, profile: profilePath };
+}
+
+module.exports = {
+  generateToolchain,
+  generateCMakePresets,
+  getBundledCmakeDir,
+  // Exported for tests
+  buildPlaceholders,
+  renderTemplate,
+};