wyvrnpm 2.1.0 → 2.3.2

package/src/upload-built.js

@@ -0,0 +1,256 @@
+'use strict';
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+
+const { getProvider }        = require('./providers');
+const { defaultCompatBlock } = require('./compat');
+const { getBuildPaths }      = require('./build/cache');
+const log                    = require('./logger');
+
+const WYVRNPM_VERSION = require('../package.json').version;
+
+const UPLOAD_SIDECAR = '.uploaded-to.json';
+
+/**
+ * Record a successful upload in a sidecar file alongside the build-cache
+ * entry. Append-only so repeated uploads to different destinations all
+ * leave a trail. Purely informational — nothing in the install/build flow
+ * branches on these files. Wiped by `wyvrnpm clean --uploaded-built`.
+ *
+ * @param {{ name: string, version: string, profileHash: string, source: string, contentSha256: string }} args
+ */
+function recordUploadSidecar({ name, version, profileHash, source, contentSha256 }) {
+  try {
+    const paths = getBuildPaths({ name, version, profileHash });
+    if (!fs.existsSync(paths.root)) return;
+    const sidecarPath = path.join(paths.root, UPLOAD_SIDECAR);
+    let doc = { uploads: [] };
+    if (fs.existsSync(sidecarPath)) {
+      try {
+        const raw = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
+        if (Array.isArray(raw?.uploads)) doc = raw;
+      } catch { /* corrupt sidecar — overwrite with fresh doc */ }
+    }
+    doc.uploads.push({
+      uploadedAt: new Date().toISOString(),
+      source,
+      profileHash,
+      contentSha256,
+    });
+    fs.writeFileSync(sidecarPath, JSON.stringify(doc, null, 2) + '\n', 'utf8');
+  } catch {
+    // Sidecar bookkeeping is best-effort — never break an install over it.
+  }
+}
+
+/**
+ * Upload a freshly source-built artefact back to the v2 registry under the
+ * consumer's profileHash, so subsequent consumers with the same profile get
+ * a direct download instead of re-cloning and re-compiling.
+ *
+ * See PLAN-UPLOAD-BUILT.md for the full design. Key properties:
+ *
+ *   - Opt-in. Only called when the user passes `--upload-built` at install.
+ *   - Skips silently if the registry already has this (name, version,
+ *     profileHash) — the common case once the first teammate has uploaded.
+ *   - Never overwrites. A consumer with write credentials cannot clobber an
+ *     existing artefact; that still requires `publish --force` from the
+ *     source repo.
+ *   - Leaves `latest.json` and the `latest` pointer in `versions.json`
+ *     alone. A consumer upload is a new profileHash of an existing version,
+ *     not a new version release. Honoured via `updateLatest: false`.
+ *   - Records provenance in the uploaded manifest's `uploadedBy` block.
+ *     Absence of this block implies author-publish by convention.
+ *
+ * @param {object} args
+ * @param {string} args.name
+ * @param {string} args.version
+ * @param {import('./profile').WyvrnProfile} args.profile
+ * @param {string} args.profileHash
+ * @param {string} args.artefactPath       Absolute path to the built zip in %LOCALAPPDATA%\wyvrnpm\bc\.
+ * @param {string} args.clonedManifestPath Absolute path to the cloned-source wyvrn.json.
+ * @param {string} args.contentSha256      SHA256 of the built zip.
+ * @param {string} args.gitRepo            Source repo URL recorded at publish.
+ * @param {string} args.gitSha             Source commit recorded at publish.
+ * @param {string} args.uploadSource       Destination URL (resolved from --upload-source or config).
+ * @param {object} [args.uploadAuth]       { awsProfile?, token? }
+ * @param {Record<string, any>|null} [args.options]  Effective options for this build (fed through to buildSettings.options).
+ * @param {string} [args.toolchainHash]    Optional SHA of the generated wyvrn_toolchain.cmake.
+ * @returns {Promise<{ uploaded: boolean, reason: string }>}
+ */
+async function uploadSourceBuiltArtefact(args) {
+  const {
+    name, version, profile, profileHash,
+    artefactPath, clonedManifestPath,
+    contentSha256, gitRepo, gitSha,
+    uploadSource, uploadAuth = {},
+    options = null,
+    toolchainHash,
+  } = args;
+
+  if (!uploadSource) {
+    return { uploaded: false, reason: 'no upload source resolved' };
+  }
+  if (!fs.existsSync(artefactPath)) {
+    return { uploaded: false, reason: `artefact zip missing at ${artefactPath}` };
+  }
+  if (!fs.existsSync(clonedManifestPath)) {
+    // Cache-hit path on a previously-trimmed cache, or the source dir was
+    // manually deleted. We have the binary but not the manifest we would
+    // have uploaded alongside it. Surface it — nothing silent.
+    return { uploaded: false, reason: `cloned manifest missing at ${clonedManifestPath}` };
+  }
+
+  let provider;
+  try {
+    provider = getProvider(uploadSource);
+  } catch (err) {
+    return { uploaded: false, reason: `no provider for ${uploadSource}: ${err.message}` };
+  }
+
+  const { awsProfile, token } = uploadAuth;
+
+  // ── Skip-if-exists ────────────────────────────────────────────────────────
+  const exists = await provider.v2Exists({
+    source: uploadSource, name, version, profileHash, awsProfile, token,
+  });
+  if (exists) {
+    log.info(`upload-built: ${name}@${version} [${profileHash}] already on ${uploadSource} — skipping`);
+    return { uploaded: false, reason: 'already exists on registry' };
+  }
+
+  // ── Prepare manifest: cloned wyvrn.json + compat block + uploadedBy ──────
+  const rawManifest = JSON.parse(fs.readFileSync(clonedManifestPath, 'utf8'));
+  const manifestForUpload = {
+    ...rawManifest,
+    compatibility: rawManifest.compatibility ?? defaultCompatBlock(),
+    uploadedBy: {
+      kind:           'source-build',
+      profileHash,
+      builtFromGit:   gitRepo ?? null,
+      builtFromSha:   gitSha  ?? null,
+      ...(toolchainHash ? { toolchainHash } : {}),
+      uploadedAt:     new Date().toISOString(),
+      wyvrnpmVersion: WYVRNPM_VERSION,
+    },
+  };
+
+  const tmpManifestPath = path.join(
+    os.tmpdir(),
+    `wyvrnpm-upload-${name}-${version}-${profileHash}-${Date.now()}.json`,
+  );
+  fs.writeFileSync(tmpManifestPath, JSON.stringify(manifestForUpload, null, 2), 'utf8');
+
+  try {
+    log.info(`upload-built: ${name}@${version} [${profileHash}] → ${uploadSource}`);
+    await provider.v2Publish(
+      { manifest: tmpManifestPath, zip: artefactPath },
+      {
+        source:        uploadSource,
+        name, version, profileHash,
+        buildSettings: options ? { ...profile, options } : profile,
+        contentSha256,
+        gitSha:  gitSha  ?? null,
+        gitRepo: gitRepo ?? null,
+        // Consumer uploads must not reshape the "latest" pointer — see
+        // PLAN-UPLOAD-BUILT §3.3.
+        updateLatest: false,
+        uploadedBy:   manifestForUpload.uploadedBy,
+        awsProfile,
+        token,
+      },
+    );
+    log.success(`upload-built: ${name}@${version} [${profileHash}] uploaded`);
+    recordUploadSidecar({ name, version, profileHash, source: uploadSource, contentSha256 });
+    return { uploaded: true, reason: 'ok' };
+  } catch (err) {
+    // The caller wraps us in try/catch too, but returning {uploaded:false}
+    // here keeps the happy path type-stable.
+    return { uploaded: false, reason: `upload failed: ${err.message}` };
+  } finally {
+    try { fs.unlinkSync(tmpManifestPath); } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Resolve `--upload-source` (URL or configured-publish-source name) + auth
+ * into an object the orchestrator understands. Mirrors the resolution
+ * pattern in src/commands/publish.js so the two flows behave identically.
+ *
+ * Returns null if no destination can be resolved — caller decides whether
+ * that is fatal (it is, if --upload-built was passed) or just skip-worthy.
+ *
+ * @param {object} argv
+ * @param {string|undefined} argv.uploadSource
+ * @param {string|undefined} argv.awsProfile
+ * @param {string|undefined} argv.token
+ * @param {{ publishSources: Array<{name:string, url:string, profile?:string, token?:string}> }} config
+ * @returns {{ uploadSource: string, uploadAuth: { awsProfile?: string, token?: string } } | null}
+ */
+function resolveUploadDestination(argv, config) {
+  let src = argv.uploadSource;
+  let awsProfile = argv.awsProfile;
+  let token      = argv.token;
+
+  const publishSources = config.publishSources ?? [];
+
+  if (src) {
+    // Check if it matches a configured publish source by name.
+    const named = publishSources.find((s) => s.name === src);
+    if (named) {
+      src        = named.url;
+      awsProfile = awsProfile ?? named.profile;
+      token      = token      ?? named.token;
+      log.info(`upload-built: using publish source "${named.name}" from config`);
+    }
+  } else if (publishSources.length > 0) {
+    const first = publishSources[0];
+    src        = first.url;
+    awsProfile = awsProfile ?? first.profile;
+    token      = token      ?? first.token;
+    log.info(`upload-built: using first configured publish source "${first.name}"`);
+  }
+
+  if (!src) return null;
+  return { uploadSource: src, uploadAuth: { awsProfile, token } };
+}
+
+/**
+ * Create an empty accumulator for aggregated upload outcomes. Pass the
+ * returned object as `options.uploadStats` to `downloadDependencies`, then
+ * feed it to `formatUploadSummary()` at the end of the install.
+ *
+ * @returns {{ uploaded: Array<object>, skipped: Array<object>, failed: Array<object> }}
+ */
+function createUploadStats() {
+  return { uploaded: [], skipped: [], failed: [] };
+}
+
+/**
+ * Produce the one-line aggregated summary shown at the end of an install
+ * when `--upload-built` was passed. Returns null when nothing was attempted
+ * (so the caller can skip printing).
+ *
+ * @param {{ uploaded: Array, skipped: Array, failed: Array }} stats
+ * @returns {string|null}
+ */
+function formatUploadSummary(stats) {
+  if (!stats) return null;
+  const total = stats.uploaded.length + stats.skipped.length + stats.failed.length;
+  if (total === 0) return null;
+  const n = (arr, singular) => `${arr.length} ${singular}${arr.length === 1 ? '' : 's'}`;
+  return (
+    `upload-built summary: ${n(stats.uploaded, 'artefact')} uploaded, ` +
+    `${stats.skipped.length} skipped (already existed), ` +
+    `${stats.failed.length} failed`
+  );
+}
+
+module.exports = {
+  uploadSourceBuiltArtefact,
+  resolveUploadDestination,
+  createUploadStats,
+  formatUploadSummary,
+};

package/src/version-range.js

@@ -0,0 +1,301 @@
+'use strict';
+
+/**
+ * Version range parsing and matching for 4-part `major.minor.patch.build`
+ * versions.
+ *
+ * Accepts three range syntaxes in addition to the existing exact and
+ * `"latest"` strings:
+ *
+ *   "^1.2.3.4"        major-pinned  : >= 1.2.3.4  <  2.0.0.0
+ *   "~1.2.3.4"        minor-pinned  : >= 1.2.3.4  <  1.3.0.0
+ *   ">=1.2.3.4 <2.0"  explicit      : one or more space-separated comparators
+ *                                     among >=, >, <=, <, =
+ *
+ * `parseRange(s)` classifies the input; `matchesRange(v, parsed)`
+ * evaluates a candidate version; `pickHighestInRange(versions, parsed)`
+ * selects the best match; `intersectRanges(a, b)` combines two ranges
+ * (returns null when the intersection is empty).
+ *
+ * See claude/PLAN-VERSION-RANGES.md for the full design.
+ */
+
+const VERSION_RE = /^\d+\.\d+\.\d+\.\d+$/;
+
+/**
+ * Compare two 4-part versions numerically. Missing trailing components
+ * default to 0 so `compareVersions("1.2", "1.2.0.0") === 0`, though the
+ * parser elsewhere always emits fully-qualified 4-part strings.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1|0|1}
+ */
+function compareVersions(a, b) {
+  const partsOf = (s) => s.split('.').map((n) => parseInt(n, 10) || 0);
+  const pa = partsOf(a);
+  const pb = partsOf(b);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const x = pa[i] ?? 0;
+    const y = pb[i] ?? 0;
+    if (x < y) return -1;
+    if (x > y) return 1;
+  }
+  return 0;
+}
+
+function bumpMajor(v) {
+  const [maj] = v.split('.').map((n) => parseInt(n, 10) || 0);
+  return `${maj + 1}.0.0.0`;
+}
+
+function bumpMinor(v) {
+  const [maj, min] = v.split('.').map((n) => parseInt(n, 10) || 0);
+  return `${maj}.${min + 1}.0.0`;
+}
+
+/**
+ * Parse a dependency version string into a structured spec. Exact versions
+ * and `"latest"` pass through unchanged; `^` / `~` / comparator strings
+ * become `{ kind: 'range', min, max }` specs.
+ *
+ * `min` and `max` are each `{ op: '>=' | '>' | null, v: string } | null`
+ * (null means unbounded on that side — an open upper bound, etc.).
+ *
+ * Throws on malformed input with a user-friendly multi-line error that
+ * lists the supported syntaxes.
+ *
+ * @param {string} spec
+ * @returns {{ kind: 'exact', version: string }
+ *         | { kind: 'tag',   tag:    'latest' }
+ *         | { kind: 'range', raw: string,
+ *             min: { op: '>='|'>', v: string } | null,
+ *             max: { op: '<='|'<', v: string } | null,
+ *             exact?: string }}
+ */
+function parseRange(spec) {
+  if (typeof spec !== 'string' || spec.length === 0) {
+    throw new Error(malformedRangeMessage(spec, 'version spec must be a non-empty string'));
+  }
+  const s = spec.trim();
+
+  if (s === 'latest') return { kind: 'tag', tag: 'latest' };
+
+  // `linked:` is handled by resolve.js directly — not our concern.
+  if (s.startsWith('linked:')) return { kind: 'linked', raw: s };
+
+  if (VERSION_RE.test(s)) return { kind: 'exact', version: s };
+
+  // Caret / tilde — require a full 4-part version as the operand.
+  if (s[0] === '^' || s[0] === '~') {
+    const op = s[0];
+    const v  = s.slice(1).trim();
+    if (!VERSION_RE.test(v)) {
+      throw new Error(malformedRangeMessage(spec, `${op} prefix requires a 4-part version`));
+    }
+    return {
+      kind: 'range',
+      raw:  s,
+      min:  { op: '>=', v },
+      max:  { op: '<',  v: op === '^' ? bumpMajor(v) : bumpMinor(v) },
+    };
+  }
+
+  // Explicit comparator form: one or more of {>=, >, <=, <, =} each followed
+  // by a 4-part version, space-separated.
+  if (/^[<>=]/.test(s)) {
+    const tokens = s.split(/\s+/);
+    let min = null;
+    let max = null;
+    let exact = null;
+    for (const tok of tokens) {
+      const m = tok.match(/^(>=|<=|>|<|=)(\d+\.\d+\.\d+\.\d+)$/);
+      if (!m) {
+        throw new Error(malformedRangeMessage(spec, `unrecognised comparator "${tok}"`));
+      }
+      const [, op, v] = m;
+      if (op === '=') {
+        if (exact && exact !== v) {
+          throw new Error(malformedRangeMessage(spec, `conflicting = comparators (${exact} vs ${v})`));
+        }
+        exact = v;
+      } else if (op === '>=' || op === '>') {
+        if (!min || compareVersions(v, min.v) > 0 || (compareVersions(v, min.v) === 0 && op === '>')) {
+          min = { op, v };
+        }
+      } else {
+        if (!max || compareVersions(v, max.v) < 0 || (compareVersions(v, max.v) === 0 && op === '<')) {
+          max = { op, v };
+        }
+      }
+    }
+    if (exact) return { kind: 'exact', version: exact };
+    if (!min && !max) {
+      throw new Error(malformedRangeMessage(spec, 'no comparators parsed'));
+    }
+    return { kind: 'range', raw: s, min, max };
+  }
+
+  throw new Error(malformedRangeMessage(spec, 'unknown version syntax'));
+}
+
+function malformedRangeMessage(spec, why) {
+  return (
+    `cannot parse dependency version ${JSON.stringify(spec)}: ${why}\n` +
+    `  supported syntaxes:\n` +
+    `    "1.2.3.4"                    exact version\n` +
+    `    "latest"                     latest-published tag\n` +
+    `    "^1.2.3.4"                   major-pinned range (>= 1.2.3.4 < 2.0.0.0)\n` +
+    `    "~1.2.3.4"                   minor-pinned range (>= 1.2.3.4 < 1.3.0.0)\n` +
+    `    ">=1.2.3.4 <2.0.0.0"         explicit range (>=, >, <=, <, = separated by spaces)`
+  );
+}
+
+/**
+ * Returns true if `version` satisfies every bound in `parsed`. Exact-kind
+ * specs require byte-equal; tag/linked specs always return false here
+ * because they are handled upstream.
+ *
+ * @param {string} version
+ * @param {ReturnType<typeof parseRange>} parsed
+ * @returns {boolean}
+ */
+function matchesRange(version, parsed) {
+  if (!parsed) return false;
+  if (parsed.kind === 'exact') return version === parsed.version;
+  if (parsed.kind !== 'range') return false;
+  if (parsed.min) {
+    const cmp = compareVersions(version, parsed.min.v);
+    if (parsed.min.op === '>=' && cmp < 0) return false;
+    if (parsed.min.op === '>'  && cmp <= 0) return false;
+  }
+  if (parsed.max) {
+    const cmp = compareVersions(version, parsed.max.v);
+    if (parsed.max.op === '<=' && cmp > 0) return false;
+    if (parsed.max.op === '<'  && cmp >= 0) return false;
+  }
+  return true;
+}
+
+/**
+ * Pick the highest version from `publishedVersions` that satisfies
+ * `parsed`. Returns null when no version matches. Input is not mutated.
+ *
+ * @param {string[]} publishedVersions
+ * @param {ReturnType<typeof parseRange>} parsed
+ * @returns {string|null}
+ */
+function pickHighestInRange(publishedVersions, parsed) {
+  if (!Array.isArray(publishedVersions) || publishedVersions.length === 0) return null;
+  const matches = publishedVersions.filter((v) => matchesRange(v, parsed));
+  if (matches.length === 0) return null;
+  matches.sort(compareVersions);
+  return matches[matches.length - 1];
+}
+
+/**
+ * Intersect two parsed range specs. Exact specs are treated as the degenerate
+ * range `[v, v]`. Returns a new range spec or null when the intersection is
+ * empty.
+ *
+ * `tag` and `linked` kinds cannot participate in intersection — the caller
+ * must resolve them to exact first. We throw rather than silently ignore.
+ *
+ * @param {ReturnType<typeof parseRange>} a
+ * @param {ReturnType<typeof parseRange>} b
+ * @returns {{ kind: 'range'|'exact', ... }|null}
+ */
+function intersectRanges(a, b) {
+  const liftExact = (spec) => spec.kind === 'exact'
+    ? { kind: 'range', raw: spec.version, min: { op: '>=', v: spec.version }, max: { op: '<=', v: spec.version } }
+    : spec;
+
+  if (!a || !b) throw new Error('intersectRanges: null spec');
+  if (a.kind === 'tag' || a.kind === 'linked' || b.kind === 'tag' || b.kind === 'linked') {
+    throw new Error('intersectRanges: tag/linked must be resolved before intersection');
+  }
+
+  const ra = liftExact(a);
+  const rb = liftExact(b);
+
+  // Tighter min (higher value; strictly-greater beats equal under gte).
+  const tighterMin = pickTighter(ra.min, rb.min, 'min');
+  // Tighter max (lower value; strictly-less beats equal under lte).
+  const tighterMax = pickTighter(ra.max, rb.max, 'max');
+
+  if (tighterMin && tighterMax) {
+    const cmp = compareVersions(tighterMin.v, tighterMax.v);
+    if (cmp > 0) return null;
+    if (cmp === 0) {
+      // Both bounds reference the same version. Feasible only if both are
+      // inclusive; otherwise the point is excluded.
+      if (tighterMin.op !== '>=' || tighterMax.op !== '<=') return null;
+      return { kind: 'exact', version: tighterMin.v };
+    }
+  }
+
+  return {
+    kind: 'range',
+    raw:  `${ra.raw ?? 'range'} ∩ ${rb.raw ?? 'range'}`,
+    min:  tighterMin,
+    max:  tighterMax,
+  };
+}
+
+function pickTighter(a, b, kind) {
+  if (!a) return b;
+  if (!b) return a;
+  const cmp = compareVersions(a.v, b.v);
+  if (kind === 'min') {
+    if (cmp > 0) return a;
+    if (cmp < 0) return b;
+    // equal: strictly-greater is tighter than gte
+    return a.op === '>' ? a : b;
+  } else {
+    if (cmp < 0) return a;
+    if (cmp > 0) return b;
+    return a.op === '<' ? a : b;
+  }
+}
+
+/**
+ * Human-readable rendering for error messages. Exact and tag kinds pass
+ * through unchanged; ranges render as the original raw string when
+ * available, else as a comparator reconstruction.
+ *
+ * @param {ReturnType<typeof parseRange>} parsed
+ * @returns {string}
+ */
+function rangeToString(parsed) {
+  if (!parsed) return '(unparsed)';
+  if (parsed.kind === 'exact') return parsed.version;
+  if (parsed.kind === 'tag')   return parsed.tag;
+  if (parsed.kind === 'linked') return parsed.raw;
+  if (parsed.raw && !parsed.raw.includes('∩')) return parsed.raw;
+  const parts = [];
+  if (parsed.min) parts.push(`${parsed.min.op}${parsed.min.v}`);
+  if (parsed.max) parts.push(`${parsed.max.op}${parsed.max.v}`);
+  return parts.join(' ');
+}
+
+/**
+ * Convenience predicate used by the resolver: does this spec require
+ * range-based resolution (as opposed to exact / latest / linked)?
+ */
+function isRangeSpec(spec) {
+  try {
+    const parsed = parseRange(spec);
+    return parsed.kind === 'range';
+  } catch { return false; }
+}
+
+module.exports = {
+  parseRange,
+  matchesRange,
+  pickHighestInRange,
+  intersectRanges,
+  rangeToString,
+  isRangeSpec,
+  compareVersions,
+};