wyvrnpm 2.1.0 → 2.3.2

package/src/download.js

@@ -11,6 +11,7 @@ const { sha256Of }              = require('./profile');
 const { getProvider }           = require('./providers');
 const { evaluateCompat, pickBestCandidate, summarizeReasons } = require('./compat');
 const { buildFromSource }       = require('./build');
+const { uploadSourceBuiltArtefact } = require('./upload-built');
 const log                       = require('./logger');
 
 // ---------------------------------------------------------------------------
@@ -177,7 +178,7 @@ async function tryV2Exact(dep, packageSources, destZipPath, timeoutMs, authOptio
  *   meta:          object,
  * }|null>}
  */
-async function findCompatibleBuild({ name, version, consumerProfile, versionsIndex, source, authOptions = {} }) {
+async function findCompatibleBuild({ name, version, consumerProfile, consumerOptions, versionsIndex, source, authOptions = {} }) {
   const { awsProfile, token } = authOptions;
   let provider;
   try { provider = getProvider(source); } catch { return null; }
@@ -185,6 +186,11 @@ async function findCompatibleBuild({ name, version, consumerProfile, versionsInd
   const versionEntry = versionsIndex?.versions?.[version];
   if (!versionEntry?.profiles) return null;
 
+  // Consumer side includes options so the compat evaluator can see them.
+  const consumerFull = consumerOptions
+    ? { ...consumerProfile, options: consumerOptions }
+    : consumerProfile;
+
   const candidates = [];
   for (const [profileHash, buildEntry] of Object.entries(versionEntry.profiles)) {
     const packageProfile = buildEntry.buildSettings ?? buildEntry.profile;
@@ -194,8 +200,16 @@ async function findCompatibleBuild({ name, version, consumerProfile, versionsInd
     const meta = await provider.v2GetMeta({ source, name, version, profileHash, awsProfile, token });
     if (!meta) continue;
 
+    // Package-side options may live on the nested buildSettings.options (new
+    // publish path) or as a sibling key when publish-time metadata diverges.
+    const packageFull = packageProfile.options
+      ? packageProfile
+      : (meta.buildSettings?.options
+         ? { ...packageProfile, options: meta.buildSettings.options }
+         : packageProfile);
+
     const rawCompat = meta.compatibility ?? null;
-    const { compatible, reasons } = evaluateCompat(consumerProfile, packageProfile, rawCompat);
+    const { compatible, reasons } = evaluateCompat(consumerFull, packageFull, rawCompat);
     if (compatible) {
       candidates.push({ profileHash, packageProfile, reasons, buildEntry, meta });
     }
@@ -339,7 +353,14 @@ async function extractZip(destZipPath, extractDir) {
  */
 async function downloadDependencies(deps, packageSources, platform, razerDir, httpClient, timeout, options = {}) {
   const timeoutMs = timeout * 1000;
-  const { awsProfile, token, buildMode = 'never', profileName = 'default' } = options;
+  const {
+    awsProfile, token, buildMode = 'never', profileName = 'default',
+    uploadBuilt = false, uploadSource, uploadAuth,
+    // Optional accumulator. When provided, upload outcomes are pushed here
+    // so the caller can print a single aggregated summary at the end of an
+    // install (see src/commands/install.js). Mutated in place.
+    uploadStats,
+  } = options;
 
   if (buildMode === 'always') {
     throw new Error(
@@ -363,6 +384,7 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
     const version     = isLegacyEntry ? depInfoOrVersion : depInfoOrVersion.version;
     const profileHash = isLegacyEntry ? null : (depInfoOrVersion.profileHash ?? null);
     const profile     = isLegacyEntry ? null : (depInfoOrVersion.profile     ?? null);
+    const options     = isLegacyEntry ? null : (depInfoOrVersion.options     ?? null);
 
     const extractDir  = path.join(razerDir, name);
     const versionFile = path.join(extractDir, '.wyvrn-version');
@@ -396,6 +418,7 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
           contentSha256: installedMeta?.contentSha256 ?? null,
           gitSha:        installedMeta?.gitSha        ?? null,
           resolvedFrom:  installedMeta?.resolvedFrom  ?? 'cached',
+          ...(options ? { options } : {}),
         });
         continue;
       }
@@ -438,6 +461,7 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
         const compatResult = await findCompatibleBuild({
           name, version,
           consumerProfile:  profile,
+          consumerOptions:  options,
           versionsIndex:    v2.versionsIndex,
           source:           v2.indexFoundInSource,
           authOptions:      { awsProfile, token },
@@ -474,6 +498,7 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
               const built = await buildFromSource({
                 name, version,
                 profile, profileName, profileHash,
+                options,
                 gitRepo:        sourceInfo.gitRepo,
                 gitSha:         sourceInfo.gitSha,
                 destZipPath,
@@ -489,6 +514,10 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
                 gitRepo:       built.gitRepo,
                 profileHash:   built.profileHash,
                 source:        built.source,
+                // Carried through so the post-extraction upload step can
+                // read the manifest and push the zip without re-doing work.
+                artefactPath:       built.artefactPath,
+                clonedManifestPath: built.clonedManifestPath,
               };
               resolvedFrom = 'v2-source-build';
             } catch (err) {
@@ -602,7 +631,40 @@ async function downloadDependencies(deps, packageSources, platform, razerDir, ht
         profileHash:   downloadResult?.profileHash   ?? null,
         contentSha256: downloadResult?.contentSha256 ?? null,
         gitSha:        downloadResult?.gitSha        ?? null,
+        ...(options ? { options } : {}),
       });
+
+      // ── Upload freshly source-built artefact back to the registry ────────
+      // Opt-in via --upload-built. Runs after extraction succeeds so a
+      // bad artefact is never uploaded. Upload failures log but never
+      // break the install — the consumer already has a working install.
+      if (uploadBuilt && resolvedFrom === 'v2-source-build' && downloadResult?.artefactPath) {
+        try {
+          const outcome = await uploadSourceBuiltArtefact({
+            name, version,
+            profile, profileHash,
+            artefactPath:       downloadResult.artefactPath,
+            clonedManifestPath: downloadResult.clonedManifestPath,
+            contentSha256:      downloadResult.contentSha256,
+            gitRepo:            downloadResult.gitRepo,
+            gitSha:             downloadResult.gitSha,
+            options,
+            uploadSource,
+            uploadAuth:         uploadAuth ?? { awsProfile, token },
+          });
+          if (uploadStats) {
+            const bucket = outcome.uploaded
+              ? 'uploaded'
+              : /already exists/.test(outcome.reason) ? 'skipped' : 'failed';
+            uploadStats[bucket].push({ name, version, profileHash, reason: outcome.reason });
+          }
+        } catch (err) {
+          log.warn(`upload-built: ${name}@${version} upload skipped — ${err.message}`);
+          if (uploadStats) {
+            uploadStats.failed.push({ name, version, profileHash, reason: err.message });
+          }
+        }
+      }
     } catch (err) {
       log.warn(`Failed to extract ${name}@${version}: ${err.message}`);
       lockEntries.set(name, { version, resolvedFrom: 'extract-failed' });

package/src/ignore.js

@@ -0,0 +1,118 @@
+'use strict';
+
+const fs = require('fs');
+
+// ---------------------------------------------------------------------------
+// .wyvrnignore matcher — follows .gitignore semantics as closely as is
+// practical for a static-archive filter. Supported:
+//
+//   - Blank lines and lines starting with `#` are ignored.
+//   - A leading `!` negates the match — re-includes a path a prior pattern
+//     excluded. Last matching pattern wins.
+//   - A trailing `/` makes the pattern directory-only: it matches directory
+//     entries only, never files. This is the single most common gitignore
+//     idiom (`build/`, `.git/`) so we honour it rather than treating the
+//     slash as a literal character.
+//   - A leading `/` anchors the pattern to the project root.
+//   - A `/` anywhere else in the pattern (excluding the trailing one) also
+//     anchors it to the root — same rule as gitignore.
+//   - Otherwise the pattern floats: it matches at any directory depth.
+//   - Globs: `*` is single-segment, `**` crosses segments, `?` is one char.
+//   - Literal leading `!` or `#` can be escaped with `\!` / `\#`.
+//
+// Not supported (unlike gitignore): pattern re-evaluation after a parent
+// directory has been excluded (gitignore can't re-include a file whose
+// parent directory was excluded — we don't recurse into excluded dirs
+// either, so the behaviour lines up in practice).
+// ---------------------------------------------------------------------------
+
+function parsePattern(raw) {
+  let p = raw;
+  if (p == null) return null;
+  p = p.replace(/\s+$/, ''); // trim trailing whitespace (gitignore rule)
+  if (p.length === 0) return null;
+  if (p.startsWith('#')) return null;
+
+  let negate = false;
+  if (p.startsWith('!')) {
+    negate = true;
+    p = p.slice(1);
+  } else if (p.startsWith('\\!') || p.startsWith('\\#')) {
+    // escaped literal leading ! or #
+    p = p.slice(1);
+  }
+
+  let dirOnly = false;
+  if (p.length > 1 && p.endsWith('/')) {
+    dirOnly = true;
+    p = p.slice(0, -1);
+  }
+
+  const leadingSlash = p.startsWith('/');
+  if (leadingSlash) p = p.slice(1);
+
+  // A `/` anywhere in the (remaining) pattern anchors it to the root.
+  // Bare names like `build` or `*.log` float — they match at any depth.
+  const anchored = leadingSlash || p.includes('/');
+
+  const re = p
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '\x00')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\?/g, '[^/]')
+    .replace(/\x00/g, '.*');
+
+  const regex = anchored
+    ? new RegExp(`^${re}(/|$)`)
+    : new RegExp(`(^|/)${re}(/|$)`);
+
+  return { raw, regex, negate, dirOnly };
+}
+
+function loadIgnorePatterns(ignoreFile) {
+  if (!fs.existsSync(ignoreFile)) return [];
+  return fs
+    .readFileSync(ignoreFile, 'utf8')
+    .split(/\r?\n/)
+    .map(parsePattern)
+    .filter(Boolean);
+}
+
+/**
+ * Determine whether a path should be excluded.
+ * @param {string}  relPath  Forward-slash-separated path relative to the root.
+ * @param {boolean} isDir    True if the path is a directory.
+ * @param {Array}   patterns Parsed patterns (from loadIgnorePatterns).
+ * @returns {boolean}
+ *
+ * Semantics follow gitignore: a dir-only pattern (`build/`) matches the
+ * directory itself AND every descendant. We honour this by testing each
+ * ancestor-prefix of the path against dir-only patterns — matters for
+ * callers who probe arbitrary paths (tests, library users) rather than
+ * walking the tree top-down (where the walker naturally stops recursing
+ * once it sees the excluded parent).
+ */
+function isIgnored(relPath, isDir, patterns) {
+  let ignored = false;
+  for (const { regex, negate, dirOnly } of patterns) {
+    let matched;
+    if (dirOnly) {
+      // Check the path itself (if it's a directory) and every ancestor dir.
+      matched = isDir && regex.test(relPath);
+      if (!matched) {
+        const parts = relPath.split('/');
+        let prefix = '';
+        for (let i = 0; i < parts.length - 1; i++) {
+          prefix = prefix ? `${prefix}/${parts[i]}` : parts[i];
+          if (regex.test(prefix)) { matched = true; break; }
+        }
+      }
+    } else {
+      matched = regex.test(relPath);
+    }
+    if (matched) ignored = !negate;
+  }
+  return ignored;
+}
+
+module.exports = { parsePattern, loadIgnorePatterns, isIgnored };

package/src/logger.js

@@ -21,7 +21,22 @@ const ANSI = {
   cyan:   '\x1b[36m',
 };
 
+// When a command is emitting a JSON payload on stdout (F7 `--format=json`),
+// stdout must be reserved exclusively for that payload. In that mode we
+// route info/success to stderr too and drop colour so stderr stays
+// log-ingestion-friendly.
+let jsonMode = false;
+
+function setJsonMode(enabled) {
+  jsonMode = Boolean(enabled);
+}
+
+function isJsonMode() {
+  return jsonMode;
+}
+
 function colorEnabled(stream) {
+  if (jsonMode)                return false;
   if (process.env.NO_COLOR)    return false;
   if (process.env.FORCE_COLOR) return true;
   return !!(stream && stream.isTTY);
@@ -42,12 +57,10 @@ function emit(stream, consoleFn, coloredPrefix, message) {
 }
 
 function info(message) {
-  emit(
-    process.stdout,
-    console.log,
-    paint(PREFIX, ANSI.dim, process.stdout),
-    message,
-  );
+  // In JSON mode stdout is reserved for the final payload — route info to stderr.
+  const stream      = jsonMode ? process.stderr : process.stdout;
+  const consoleFn   = jsonMode ? console.error  : console.log;
+  emit(stream, consoleFn, paint(PREFIX, ANSI.dim, stream), message);
 }
 
 function warn(message) {
@@ -63,9 +76,12 @@ function error(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);
+  // In JSON mode stdout is reserved for the final payload — route success to stderr.
+  const stream    = jsonMode ? process.stderr : process.stdout;
+  const consoleFn = jsonMode ? console.error  : console.log;
+  const p   = paint(PREFIX, ANSI.green, stream);
+  const tag = paint('ok', ANSI.green + ANSI.bold, stream);
+  emit(stream, consoleFn, `${p} ${tag}`, message);
 }
 
 function debug(message) {
@@ -75,4 +91,4 @@ function debug(message) {
   emit(process.stderr, console.error, `${p} ${tag}`, message);
 }
 
-module.exports = { info, warn, error, success, debug };
+module.exports = { info, warn, error, success, debug, setJsonMode, isJsonMode };

package/src/manifest.js

@@ -52,14 +52,18 @@ function defaultManifest(name) {
 
 /**
  * Normalise the raw `dependencies` field from a manifest into a consistent
- * `{ name → { version, settings } }` map, regardless of the input format:
+ * `{ name → { version, settings, options } }` map, regardless of input format:
  *
- *   • String value  : "1.0.0"               → { version: "1.0.0", settings: {} }
- *   • Object value  : { version, settings? } → kept (settings defaults to {})
- *   • Array format  : [{ Name, Version }]    → converted
+ *   • String value  : "1.0.0"                         → { version: "1.0.0", settings: {}, options: {} }
+ *   • Object value  : { version, settings?, options? } → kept (missing keys default to {})
+ *   • Array format  : [{ Name, Version }]              → converted (no settings/options)
+ *
+ * `settings` merges on top of the active profile for this dep only.
+ * `options` maps to the recipe's declared options; validated against
+ * the recipe's `allowed` list at resolve time (see src/options.js).
  *
  * @param {object|Array|undefined} rawDeps
- * @returns {Record<string, { version: string, settings: object }>}
+ * @returns {Record<string, { version: string, settings: object, options: object }>}
  */
 function normalizeDependencies(rawDeps) {
   if (!rawDeps || typeof rawDeps !== 'object') return {};
@@ -69,7 +73,7 @@ function normalizeDependencies(rawDeps) {
     for (const d of rawDeps) {
       const n = d.Name ?? d.name;
       const v = d.Version ?? d.version;
-      if (n && v) result[n] = { version: v, settings: {} };
+      if (n && v) result[n] = { version: v, settings: {}, options: {} };
     }
     return result;
   }
@@ -77,11 +81,12 @@ function normalizeDependencies(rawDeps) {
   const result = {};
   for (const [n, value] of Object.entries(rawDeps)) {
     if (typeof value === 'string') {
-      result[n] = { version: value, settings: {} };
+      result[n] = { version: value, settings: {}, options: {} };
     } else if (value && typeof value === 'object') {
       result[n] = {
         version:  value.version ?? value.Version ?? '',
         settings: value.settings ?? {},
+        options:  value.options  ?? {},
       };
     }
   }

package/src/options.js

@@ -0,0 +1,303 @@
+'use strict';
+
+/**
+ * Recipe-declared options: `wyvrn.json` gains a top-level `options` block
+ * that declares feature toggles the package exposes (shared/static,
+ * `minizip` on zlib, FIPS on OpenSSL, etc.). Consumers override per-dep
+ * via `dependencies.<name>.options` or on the CLI via `-o <name>:<key>=<value>`.
+ *
+ * Options fold into `profileHash` (via `hashProfile`), so every distinct
+ * option combination gets its own artefact on the registry.
+ *
+ * Scope:
+ *   - Recipe declares options with `default` + `allowed` per name.
+ *   - Consumer can override any declared option to any `allowed` value.
+ *   - No transitive propagation for MVP (see PLAN-OPTIONS §2).
+ *   - Values are `boolean` or string-enum; no integers/lists.
+ *
+ * See claude/PLAN-OPTIONS.md for the full design and
+ * claude/PLAN-OPTIONS-EXAMPLE.md for a worked zlib walkthrough.
+ */
+
+// Option names are conservative — lower-case, start with a letter. Prevents
+// collisions with future reserved keywords (`options.schemaVersion` etc.)
+const OPTION_NAME_RE = /^[a-z][a-z0-9_-]*$/;
+
+/**
+ * Validate and normalise a recipe's `options` block. Returns a canonical
+ * form (a fresh object with the declared options preserved, `allowed`
+ * arrays duplicated defensively), or null if the recipe has no options.
+ *
+ * Throws with a precise, user-facing message on any structural error.
+ *
+ * @param {object|null|undefined} rawOptions - the `options` field from a recipe wyvrn.json
+ * @param {string} [pkgContext] - e.g. "zlib@1.3.0.0" — included in error messages
+ * @returns {Record<string, { default: any, allowed: any[] }>|null}
+ */
+function normalizeOptionsDeclaration(rawOptions, pkgContext = '') {
+  if (rawOptions === null || rawOptions === undefined) return null;
+  const where = pkgContext ? ` in ${pkgContext}` : '';
+
+  if (typeof rawOptions !== 'object' || Array.isArray(rawOptions)) {
+    throw new Error(`\`options\`${where} must be an object mapping option names to { default, allowed } specs`);
+  }
+
+  const result = {};
+  for (const [name, spec] of Object.entries(rawOptions)) {
+    if (!OPTION_NAME_RE.test(name)) {
+      throw new Error(
+        `option name "${name}"${where} is invalid — must match /^[a-z][a-z0-9_-]*$/`,
+      );
+    }
+    if (!spec || typeof spec !== 'object' || Array.isArray(spec)) {
+      throw new Error(`options.${name}${where} must be an object of the form { default: <value>, allowed: [<value>, ...] }`);
+    }
+    if (!('default' in spec) || !('allowed' in spec)) {
+      throw new Error(
+        `options.${name}${where} is missing the \`default\` or \`allowed\` field\n` +
+        `  shape expected: { "default": <value>, "allowed": [<value>, ...] }`,
+      );
+    }
+    if (!Array.isArray(spec.allowed) || spec.allowed.length === 0) {
+      throw new Error(`options.${name}.allowed${where} must be a non-empty array`);
+    }
+    for (const v of spec.allowed) {
+      const t = typeof v;
+      if (t !== 'boolean' && t !== 'string') {
+        throw new Error(
+          `options.${name}.allowed${where} values must be boolean or string (got ${t}: ${JSON.stringify(v)})`,
+        );
+      }
+    }
+    if (!spec.allowed.includes(spec.default)) {
+      throw new Error(
+        `options.${name}.default = ${JSON.stringify(spec.default)}${where} is not in allowed: ${JSON.stringify(spec.allowed)}`,
+      );
+    }
+    result[name] = { default: spec.default, allowed: spec.allowed.slice() };
+  }
+  return result;
+}
+
+/**
+ * Compute the effective (resolved) options for a dep by starting from the
+ * recipe's declared defaults, overlaying the consumer's wyvrn.json
+ * overrides, then overlaying CLI `-o` overrides. Each override is
+ * validated against the recipe's `allowed` list.
+ *
+ * Returns null when the recipe has no declared options. Returning null
+ * (vs an empty object) is how `hashProfile` distinguishes "no options"
+ * from "options declared but all at defaults" — the former produces the
+ * pre-F1 hash for backward compatibility.
+ *
+ * @param {object|null} declaration — normalised recipe options (from `normalizeOptionsDeclaration`)
+ * @param {object} [consumerOverrides] — dependencies.<name>.options from consumer wyvrn.json
+ * @param {object} [cliOverrides] — scoped to this package, extracted from `-o` flags
+ * @param {string} [pkgContext] — "zlib@1.3.0.0" style, for error messages
+ * @returns {Record<string, any>|null}
+ */
+function resolveEffectiveOptions(declaration, consumerOverrides = {}, cliOverrides = {}, pkgContext = '') {
+  if (!declaration) {
+    // Recipe didn't declare options → consumer must not supply any
+    const extra = new Set([
+      ...Object.keys(consumerOverrides ?? {}),
+      ...Object.keys(cliOverrides ?? {}),
+    ]);
+    if (extra.size > 0) {
+      throw new Error(
+        `${pkgContext || 'package'} has no declared options, but received overrides: ${[...extra].join(', ')}`,
+      );
+    }
+    return null;
+  }
+
+  const declaredNames = Object.keys(declaration);
+
+  const validateSource = (overrides, sourceLabel) => {
+    for (const [key, value] of Object.entries(overrides ?? {})) {
+      if (!(key in declaration)) {
+        const suggestion = findClosest(key, declaredNames);
+        const hint = suggestion ? `\n  Did you mean "${suggestion}"?` : '';
+        throw new Error(
+          `unknown option "${key}" for ${pkgContext || 'package'} (from ${sourceLabel})\n` +
+          `  declared options: ${declaredNames.join(', ')}${hint}`,
+        );
+      }
+      if (!declaration[key].allowed.includes(value)) {
+        throw new Error(
+          `option ${pkgContext ? pkgContext + '.' : ''}${key} = ${JSON.stringify(value)} is not allowed (from ${sourceLabel})\n` +
+          `  allowed values: ${declaration[key].allowed.map((v) => JSON.stringify(v)).join(', ')}`,
+        );
+      }
+    }
+  };
+  validateSource(consumerOverrides, 'wyvrn.json');
+  validateSource(cliOverrides, '--option CLI flag');
+
+  const effective = {};
+  for (const [name, spec] of Object.entries(declaration)) {
+    effective[name] = spec.default;
+    if (consumerOverrides && name in consumerOverrides) effective[name] = consumerOverrides[name];
+    if (cliOverrides      && name in cliOverrides)      effective[name] = cliOverrides[name];
+  }
+  return effective;
+}
+
+/**
+ * Parse the `--option`/`-o` CLI flag values into a nested map.
+ *
+ *   ["zlib:minizip=false", "openssl:fips=true"]
+ *     ↓
+ *   { zlib: { minizip: false }, openssl: { fips: true } }
+ *
+ * Rules:
+ *   - Split once on ":" (package name cannot contain ":", enforced by
+ *     manifest validation elsewhere).
+ *   - Split the right side once on "=" so string values may contain "=".
+ *   - Coerce "true"/"false" (case-insensitive) to booleans; everything
+ *     else stays a string. Downstream validation against the recipe's
+ *     `allowed` list catches illegal values.
+ *   - Empty package name, option name, or value → usage error.
+ *
+ * @param {string|string[]|undefined} rawFlags
+ * @returns {Record<string, Record<string, any>>}
+ */
+function parseCliOptions(rawFlags) {
+  if (!rawFlags) return {};
+  const arr = Array.isArray(rawFlags) ? rawFlags : [rawFlags];
+  const result = {};
+  for (const entry of arr) {
+    if (typeof entry !== 'string' || entry.length === 0) continue;
+    const colonIdx = entry.indexOf(':');
+    if (colonIdx <= 0) {
+      throw new Error(`--option "${entry}" is malformed — expected <pkg>:<name>=<value>`);
+    }
+    const pkg = entry.slice(0, colonIdx);
+    const rest = entry.slice(colonIdx + 1);
+    const eqIdx = rest.indexOf('=');
+    if (eqIdx <= 0 || eqIdx === rest.length - 1) {
+      throw new Error(`--option "${entry}" is malformed — expected <pkg>:<name>=<value>`);
+    }
+    const name  = rest.slice(0, eqIdx);
+    const value = rest.slice(eqIdx + 1);
+    if (!result[pkg]) result[pkg] = {};
+    result[pkg][name] = coerceCliValue(value);
+  }
+  return result;
+}
+
+function coerceCliValue(raw) {
+  const lc = raw.toLowerCase();
+  if (lc === 'true')  return true;
+  if (lc === 'false') return false;
+  return raw;
+}
+
+/**
+ * Template-expand `${options.<name>}` occurrences in a single string using
+ * the supplied `effective` options map. Bool values coerce to CMake's
+ * `ON`/`OFF`; string values expand verbatim.
+ *
+ * A missing variable (`${options.fips}` with no `fips` in effective) is
+ * a hard error — a typo in the recipe must fail fast at source-build
+ * configure time, not silently reach cmake as a literal unexpanded
+ * string. If the recipe declares no options at all, every template
+ * reference fails for the same reason.
+ *
+ * @param {string} arg      a single argv element (e.g. `-DSHARED=${options.shared}`)
+ * @param {Record<string, any>|null} effective
+ * @param {string} [context] — for the error message (`build.configure`, `build.buildArgs`)
+ * @returns {string}
+ */
+function substituteTemplate(arg, effective, context = '') {
+  if (typeof arg !== 'string') return arg;
+  return arg.replace(/\$\{options\.([a-z][a-z0-9_-]*)\}/g, (_full, name) => {
+    if (!effective || !(name in effective)) {
+      const declared = effective ? Object.keys(effective) : [];
+      const declaredLine = declared.length > 0
+        ? `\n  declared options: ${declared.join(', ')}`
+        : '\n  (no options declared on this recipe)';
+      throw new Error(
+        `${context ? context + ' ' : ''}references \${options.${name}} but no such option is declared${declaredLine}`,
+      );
+    }
+    const v = effective[name];
+    if (v === true)  return 'ON';
+    if (v === false) return 'OFF';
+    return String(v);
+  });
+}
+
+/**
+ * Apply `substituteTemplate` across an array of argv elements.
+ *
+ * @param {string[]} args
+ * @param {Record<string, any>|null} effective
+ * @param {string} [context]
+ * @returns {string[]}
+ */
+function substituteTemplateAll(args, effective, context = '') {
+  if (!Array.isArray(args)) return args;
+  return args.map((a) => substituteTemplate(a, effective, context));
+}
+
+/**
+ * Return a new object with the same keys sorted alphabetically. Used as
+ * the canonical form for hashing.
+ *
+ * @param {object|null} options
+ * @returns {object|null}
+ */
+function sortAndNormaliseOptions(options) {
+  if (!options) return null;
+  return Object.fromEntries(
+    Object.entries(options).sort(([a], [b]) => a.localeCompare(b)),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// "Did you mean" suggestion helper — Levenshtein with a small-distance cap.
+// ---------------------------------------------------------------------------
+
+function findClosest(needle, haystack) {
+  if (!Array.isArray(haystack) || haystack.length === 0) return null;
+  const cap = Math.max(2, Math.floor(needle.length / 3));
+  let best = null;
+  let bestDist = Infinity;
+  for (const candidate of haystack) {
+    const d = levenshtein(needle.toLowerCase(), candidate.toLowerCase());
+    if (d < bestDist && d <= cap) {
+      best = candidate;
+      bestDist = d;
+    }
+  }
+  return best;
+}
+
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  if (m === 0) return n;
+  if (n === 0) return m;
+  let prev = new Array(n + 1);
+  for (let j = 0; j <= n; j++) prev[j] = j;
+  for (let i = 1; i <= m; i++) {
+    const curr = [i];
+    for (let j = 1; j <= n; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr.push(Math.min(prev[j] + 1, curr[j - 1] + 1, prev[j - 1] + cost));
+    }
+    prev = curr;
+  }
+  return prev[n];
+}
+
+module.exports = {
+  normalizeOptionsDeclaration,
+  resolveEffectiveOptions,
+  parseCliOptions,
+  sortAndNormaliseOptions,
+  substituteTemplate,
+  substituteTemplateAll,
+  OPTION_NAME_RE,
+};