wyvrnpm 2.0.4 → 2.3.2

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

@@ -0,0 +1,94 @@
+'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',
+};
+
+// 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);
+}
+
+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) {
+  // 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) {
+  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) {
+  // 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) {
+  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, 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,
+};

package/src/profile.js

@@ -163,25 +163,49 @@ function detectProfile() {
 }
 
 /**
- * Compute a stable 16-char SHA256 prefix that identifies a unique build profile.
- * Only non-null, non-wildcard fields contribute to the hash.
+ * Compute a stable 16-char SHA256 prefix identifying a unique build.
+ * Inputs:
+ *   - `profile`: the toolchain/ABI fields (os, arch, compiler, etc.).
+ *   - `options`: (optional) recipe-declared feature toggles resolved to
+ *     their effective values for this build.
+ *
+ * Backward-compat contract: when `options` is null / undefined / empty,
+ * the hash is byte-identical to what pre-F1 wyvrnpm produced. Packages
+ * without an `options` block keep their existing registry addresses.
+ * The caller therefore passes `null` (not `{}`) to mean "this recipe
+ * has no options declared" — consistent with what
+ * `resolveEffectiveOptions` returns in that case.
+ *
+ * See claude/PLAN-OPTIONS.md §3.2 for the full design.
  *
  * @param {WyvrnProfile} profile
+ * @param {Record<string, any>|null} [options]  effective options (after defaults + overrides)
  * @returns {string} 16-character lowercase hex string
  */
-function hashProfile(profile) {
+function hashProfile(profile, options = null) {
   const significant = Object.fromEntries(
     Object.entries(profile)
       .filter(([, v]) => v !== null && v !== undefined && v !== '*' && v !== '')
       .sort(([a], [b]) => a.localeCompare(b)),
   );
+
+  const payload = (options && Object.keys(options).length > 0)
+    ? { ...significant, options: sortOptionsForHashing(options) }
+    : significant;
+
   return crypto
     .createHash('sha256')
-    .update(JSON.stringify(significant))
+    .update(JSON.stringify(payload))
     .digest('hex')
     .slice(0, 16);
 }
 
+function sortOptionsForHashing(options) {
+  return Object.fromEntries(
+    Object.entries(options).sort(([a], [b]) => a.localeCompare(b)),
+  );
+}
+
 /**
  * Compute the SHA256 hash of a file or Buffer.
  *
@@ -214,6 +238,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 +405,7 @@ module.exports = {
   sha256Of,
   getGitSha,
   getGitRepo,
+  isShaOnRemote,
   formatProfile,
   mergeProfile,
   // Profile file management

package/src/providers/base.js

@@ -69,7 +69,20 @@ class BaseProvider {
 
   /**
    * Publish to the v2 path.
-   * Writes wyvrn.json + wyvrn.zip under profileHash, updates versions.json and latest.json.
+   * Writes wyvrn.json + wyvrn.zip under profileHash, updates versions.json and
+   * (when `updateLatest !== false`) latest.json.
+   *
+   * `updateLatest: false` is used by the `upload-built` flow (a consumer
+   * returning a source-built artefact — see PLAN-UPLOAD-BUILT.md). A consumer
+   * upload is NOT introducing a new package version, so `latest.json` must
+   * not be clobbered. For the same reason the `latest` pointer inside
+   * `versions.json` is also left alone. Defaults to `true` to preserve
+   * existing `publish` semantics.
+   *
+   * The optional `uploadedBy` field in `options` is written verbatim into
+   * the per-build `wyvrn.json` as provenance metadata. Absent by default
+   * (author publish); populated by the upload-built flow. Readers ignore
+   * the field — it is informational only.
    *
    * @param {{ manifest: string, zip: string }} files  - local file paths
    * @param {{
@@ -81,6 +94,8 @@ class BaseProvider {
    *   contentSha256: string,
    *   gitSha:        string|null,
    *   gitRepo:       string|null,
+   *   updateLatest?: boolean,       // default true; false for upload-built
+   *   uploadedBy?:   object,        // optional provenance block, written into wyvrn.json
    *   awsProfile?:   string,
    *   token?:        string,
    * }} options