wyvrnpm 2.8.1 → 2.10.0

package/src/commands/show.js

@@ -1,9 +1,8 @@
 'use strict';
 
-const { readConfig }       = require('../config');
-const { getProvider }      = require('../providers');
-const { resolveSourceAuth } = require('../auth');
-const log                  = require('../logger');
+const { getProvider }  = require('../providers');
+const { buildContext } = require('../context');
+const log              = require('../logger');
 
 /**
  * `wyvrnpm show <pkg>` — surface registry metadata for a package.
@@ -37,10 +36,19 @@ async function show(argv) {
     process.exit(1);
   }
 
-  const jsonOut = argv.format === 'json';
-  if (jsonOut) log.setJsonMode(true);
+  // Shared per-invocation state (config, auth, JSON-mode toggle). `show`
+  // never reads the manifest, which is why ctx.manifest is lazy. See
+  // src/context.js + claude/PLAN-COMMAND-CONTEXT.md.
+  let ctx;
+  try {
+    ctx = buildContext(argv);
+  } catch (err) {
+    log.error(err.message);
+    process.exit(1);
+  }
+  const jsonOut = ctx.flags.format === 'json';
 
-  const { sources, awsProfile, token } = resolveSources(argv);
+  const { sources, awsProfile, token } = resolveSources(argv, ctx);
   if (sources.length === 0) {
     log.error(
       'no sources configured. ' +
@@ -199,8 +207,8 @@ function parseSpec(spec) {
   };
 }
 
-function resolveSources(argv) {
-  const config = readConfig();
+function resolveSources(argv, ctx) {
+  const { config } = ctx;
   const sources = (argv.source && argv.source.length > 0)
     ? argv.source
     : config.installSources.map((s) => s.url);
@@ -209,10 +217,7 @@ function resolveSources(argv) {
   return {
     sources,
     awsProfile: argv.awsProfile ?? firstConfig?.profile,
-    token:      resolveSourceAuth(
-      { token: argv.token, tokenEnv: argv.tokenEnv },
-      firstConfig,
-    ).token,
+    token:      ctx.auth.for(firstConfig).token,
   };
 }
 

package/src/context.js

@@ -0,0 +1,230 @@
+'use strict';
+
+/**
+ * CommandContext — the shared per-invocation state every command consumes.
+ *
+ * Commands used to each re-read the manifest, re-resolve the profile name,
+ * re-read config, re-resolve auth, and each toggle JSON mode on the logger.
+ * The divergence was cheap at 11 commands; it starts costing real bugs
+ * once F3 (`tool_requires`) and F4 (build/host profile split) double the
+ * flag surface. See [claude/PLAN-COMMAND-CONTEXT.md](../claude/PLAN-COMMAND-CONTEXT.md).
+ *
+ * `buildContext(argv)` runs once at the top of each command. It:
+ *   - resolves filesystem anchors (rootDir, manifestPath)
+ *   - reads config once
+ *   - resolves the profile-name fallback chain + loads the profile
+ *   - parses CLI options + conf (format-level only; namespace allow-
+ *     listing happens later in the sinks that need it)
+ *   - sets JSON mode on the logger if --format=json
+ *   - exposes an auth helper pre-curried with CLI --token / --token-env
+ *   - exposes a lazy manifest getter (show never reads the manifest)
+ *
+ * `buildContext` does NOT do source filtering — each command has subtly
+ * different CLI shape there (publish takes name-or-URL, install/show
+ * take URL arrays, pin-resolution only matters for install). That
+ * stays per-command until a second feature shows the same duplication.
+ *
+ * Errors: `buildContext` THROWS on all input-validation failures. Each
+ * command wraps the call in one try/catch that does `log.error + exit`.
+ * This keeps buildContext unit-testable; behaviour from the user's
+ * point of view is unchanged.
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+const { readConfig }        = require('./config');
+const { loadProfile }       = require('./profile');
+const { readManifest }      = require('./manifest');
+const { resolveSourceAuth } = require('./auth');
+const { parseCliOptions }   = require('./options');
+const { parseCliConf }      = require('./conf');
+const log                   = require('./logger');
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the active profile name per the long-standing precedence:
+ *   --profile > config.defaultProfile > 'default'
+ */
+function resolveProfileName(argv, config) {
+  if (typeof argv.profile === 'string' && argv.profile.length > 0) {
+    return argv.profile;
+  }
+  if (typeof config.defaultProfile === 'string' && config.defaultProfile.length > 0) {
+    return config.defaultProfile;
+  }
+  return 'default';
+}
+
+/**
+ * Normalise CLI flags into the stable `ctx.flags` shape. Centralising
+ * defaults here means individual commands don't each re-apply
+ * `?? 'never'` / `?? 'Release'` / etc.
+ *
+ * Flags that are command-specific (argv.preset, argv.pkg, argv.clean,
+ * argv.verbose, argv.generator, argv.install, argv.installPrefix,
+ * argv.uploadSource, argv.autoInstall, argv.noGpgSign, ...) stay on
+ * argv and commands read them there. `ctx.argv` is the escape hatch.
+ */
+function normaliseFlags(argv) {
+  return {
+    format:      argv.format === 'json' ? 'json' : 'text',
+    dryRun:      argv.dryRun === true,
+    build:       argv.build ?? 'never',
+    uploadBuilt: argv.uploadBuilt === true,
+    force:       argv.force === true,
+    platform:    argv.platform ?? defaultPlatform(),
+    timeout:     typeof argv.timeout === 'number' ? argv.timeout : 300,
+  };
+}
+
+/**
+ * Default platform string when --platform is absent. Mirrors what
+ * bin/wyvrn.js passes when yargs applies its own default — keeping
+ * it here makes context.js testable without exercising the CLI layer.
+ */
+function defaultPlatform() {
+  if (process.platform === 'win32') {
+    return process.arch === 'ia32' ? 'win_x86' : 'win_x64';
+  }
+  if (process.platform === 'darwin') return 'macos';
+  return 'linux';
+}
+
+/**
+ * Produce a frozen `{ host, build }` profile pair. Today both point at
+ * the same resolved object — when F4 (build/host profile split) lands,
+ * only this function changes; every command reading `ctx.profiles.host`
+ * or `ctx.profiles.build` continues to work.
+ *
+ * The two sub-objects share a reference today. A regression test in
+ * tests/context.test.js asserts `ctx.profiles.host === ctx.profiles.build`
+ * — that test is expected to be removed (not fixed) when F4 makes them
+ * legitimately distinct.
+ */
+function resolveProfiles(argv, config) {
+  const name = resolveProfileName(argv, config);
+  const { profile, fromFile } = loadProfile(name);
+  const entry = Object.freeze({ name, profile, fromFile });
+  return Object.freeze({ host: entry, build: entry });
+}
+
+// ---------------------------------------------------------------------------
+// buildContext
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the per-invocation CommandContext.
+ *
+ * @param {object} argv - yargs-parsed argument map. Fields read:
+ *   root, manifest, profile, format, dryRun, build, uploadBuilt,
+ *   force, platform, timeout, token, tokenEnv, option, conf.
+ *   Command-specific fields pass through on ctx.argv unchanged.
+ *
+ * @returns {CommandContext}
+ *
+ * @throws on:
+ *   - parseCliOptions: malformed `-o pkg:name=value`
+ *   - parseCliConf:    malformed `--conf KEY=VALUE`
+ *   - loadProfile:     malformed profile JSON, cycle in `extends`, etc.
+ *
+ * Does NOT throw on:
+ *   - missing manifest (lazy — throws at first ctx.manifest access)
+ *   - missing config   (readConfig returns empty defaults)
+ *   - missing profile  (loadProfile falls back to detectProfile())
+ *   - missing --token-env value (resolveSourceAuth throws at ctx.auth.for time)
+ */
+function buildContext(argv = {}) {
+  // 1. Filesystem anchors — pure path math, no I/O.
+  const rootDir = path.resolve(argv.root ?? '.');
+  const manifestPath = path.resolve(
+    argv.manifest ?? path.join(rootDir, 'wyvrn.json'),
+  );
+
+  // 2. Config — sync, small file, every command needs at least .defaultProfile.
+  const config = readConfig();
+
+  // 3. Profile (F4-ready shape).
+  const profiles = resolveProfiles(argv, config);
+
+  // 4. CLI auth, kept as the raw pair. Actual token lookup happens
+  //    through ctx.auth.for(sourceEntry), which runs resolveSourceAuth
+  //    each time so --token-env misses surface at use (same as today).
+  const authCli = Object.freeze({
+    token:    typeof argv.token    === 'string' ? argv.token    : undefined,
+    tokenEnv: typeof argv.tokenEnv === 'string' ? argv.tokenEnv : undefined,
+  });
+
+  // 5. CLI options + conf — format-level parsing only. Namespace
+  //    allow-listing for conf happens later in resolveEffectiveConf;
+  //    options validation against the recipe's declared `allowed` set
+  //    happens at resolveEffectiveOptions time.
+  //    Both can throw — that's the contract: buildContext surfaces
+  //    input-level errors up front.
+  const cliOptions = parseCliOptions(argv.option);
+  const cliConf    = parseCliConf(argv.conf);
+
+  // 6. Flags.
+  const flags = normaliseFlags(argv);
+
+  // 7. JSON mode — side effect that must happen before the command
+  //    starts logging. Flipping the logger here means every command
+  //    that constructs a ctx gets JSON mode right automatically.
+  if (flags.format === 'json') log.setJsonMode(true);
+
+  // 8. Assemble.
+  const ctx = {
+    rootDir,
+    manifestPath,
+    cwd: process.cwd(),
+    profiles,
+    config,
+    auth: Object.freeze({
+      cli: authCli,
+      for: (sourceEntry) => resolveSourceAuth(authCli, sourceEntry ?? null),
+    }),
+    cliOptions,
+    cliConf,
+    flags,
+    argv,
+  };
+
+  // 9. Lazy manifest getter. Most commands need it; `show` does not.
+  //    Defining as a getter means:
+  //      - show pays nothing.
+  //      - other commands pay once, cached.
+  //      - an invalid manifest surfaces at first use, not at ctx
+  //        construction — so `show` never trips over it.
+  let manifestCache = null;
+  let manifestLoaded = false;
+  Object.defineProperty(ctx, 'manifest', {
+    configurable: false,
+    enumerable:   true,
+    get() {
+      if (!manifestLoaded) {
+        if (!fs.existsSync(manifestPath)) {
+          throw new Error(`Manifest not found: ${manifestPath}`);
+        }
+        manifestCache = readManifest(manifestPath);
+        manifestLoaded = true;
+      }
+      return manifestCache;
+    },
+  });
+
+  return ctx;
+}
+
+module.exports = {
+  buildContext,
+  // Exported for unit tests — kept out of the default import surface.
+  _helpers: {
+    resolveProfileName,
+    normaliseFlags,
+    defaultPlatform,
+    resolveProfiles,
+  },
+};

package/src/http-fetch.js

@@ -0,0 +1,53 @@
+'use strict';
+
+// Shared `fetch` wrapper used by every resolver / downloader call site.
+//
+// 2.8.3 shipped with a split between the HTTP provider (which uses
+// node:https directly and sends `User-Agent: wyvrnpm/<ver>` + no
+// `Accept-Encoding`) and the resolver (which used the bare global
+// `fetch` — undici — defaulting to `Accept-Encoding: gzip, deflate,
+// br`). CloudFront caches a **separate entry per response encoding**,
+// so a `versions.json` freshly updated at origin could be stale in the
+// Brotli cache bucket for up to the full TTL while the identity bucket
+// served fresh bytes. The provider calls (show) happened to land in
+// the identity bucket (fresh); the resolver calls (install, add)
+// landed in the Brotli bucket (stale).
+//
+// Mitigation: force `Accept-Encoding: identity`. Manifest JSONs are
+// small (KB to tens of KB) so the lost compression is negligible, and
+// one encoding means one cache bucket — no split-brain. User-Agent +
+// `Accept: application/json` are included for good measure (CloudFront
+// + some WAFs 403 UA-less requests).
+//
+// Defence-in-depth: src/providers/s3.js caps every manifest-JSON PUT
+// at `CacheControl: public, max-age=300` (2.8.4), so the worst-case
+// staleness for any future publish is 5 min regardless of which
+// cache bucket a client lands in.
+//
+// See claude/PLAN-RESOLVER-HTTP-UNIFY.md for the follow-up plan to
+// route all resolver HTTP through the provider API and retire this
+// wrapper.
+
+const USER_AGENT = `wyvrnpm/${require('../package.json').version}`;
+
+/**
+ * Drop-in replacement for the global `fetch`. Injects wyvrnpm's
+ * `User-Agent`, an `Accept: application/json` hint, and forces
+ * `Accept-Encoding: identity` to avoid CloudFront's per-encoding
+ * cache-key split. Caller-supplied headers win on collision.
+ *
+ * @param {string | URL} url
+ * @param {RequestInit} [init]
+ * @returns {Promise<Response>}
+ */
+function wyvrnFetch(url, init = {}) {
+  const headers = {
+    'User-Agent': USER_AGENT,
+    Accept: 'application/json',
+    'Accept-Encoding': 'identity',
+    ...(init.headers || {}),
+  };
+  return fetch(url, { ...init, headers });
+}
+
+module.exports = { wyvrnFetch, USER_AGENT };

package/src/providers/file.js

@@ -16,21 +16,6 @@ const log = require('../logger');
  *   //server/share/path                 (SMB UNC — forward slash)
  *   file:///path                        (file URI)
  */
-function pinDependencies(rawDeps, lockedDeps) {
-  if (!rawDeps || !lockedDeps || Object.keys(lockedDeps).length === 0) return rawDeps;
-  const result = {};
-  for (const [pkgName, value] of Object.entries(rawDeps)) {
-    const locked = lockedDeps[pkgName];
-    if (locked) {
-      result[pkgName] = typeof value === 'object' && value !== null
-        ? { ...value, version: locked }
-        : locked;
-    } else {
-      result[pkgName] = value;
-    }
-  }
-  return result;
-}
 
 class FileProvider extends BaseProvider {
   static canHandle(source) {
@@ -106,7 +91,7 @@ class FileProvider extends BaseProvider {
   async v2Publish(files, options) {
     const {
       source, name, version, profileHash, buildSettings,
-      contentSha256, gitSha, gitRepo, lockedDependencies,
+      contentSha256, gitSha, gitRepo, publishedLock,
       updateLatest = true, uploadedBy,
     } = options;
 
@@ -118,12 +103,12 @@ class FileProvider extends BaseProvider {
     this._copy(files.zip, path.join(buildDir, 'wyvrn.zip'));
 
     // 2) enriched wyvrn.json (buildSettings stored for debugging only)
-    //    Dependencies are replaced with locked versions so the server never sees "latest".
+    //    Dependencies are published verbatim from wyvrn.json — ranges stay as
+    //    ranges so consumers can intersect them with their own. The author's
+    //    lockfile snapshot is preserved in `publishedLock` for audit.
     const rawManifest = JSON.parse(fs.readFileSync(files.manifest, 'utf8'));
-    const pinnedDeps = pinDependencies(rawManifest.dependencies, lockedDependencies);
     const v2Meta = {
       ...rawManifest,
-      ...(pinnedDeps !== undefined ? { dependencies: pinnedDeps } : {}),
       schemaVersion: 2,
       profileHash,
       buildSettings,
@@ -131,6 +116,7 @@ class FileProvider extends BaseProvider {
       gitSha:      gitSha  ?? null,
       gitRepo:     gitRepo ?? null,
       publishedAt: new Date().toISOString(),
+      ...(publishedLock && Object.keys(publishedLock).length > 0 ? { publishedLock } : {}),
       ...(uploadedBy ? { uploadedBy } : {}),
     };
     this._writeJson(path.join(buildDir, 'wyvrn.json'), v2Meta);

package/src/providers/http.js

@@ -8,21 +8,11 @@ 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;
-  const result = {};
-  for (const [pkgName, value] of Object.entries(rawDeps)) {
-    const locked = lockedDeps[pkgName];
-    if (locked) {
-      result[pkgName] = typeof value === 'object' && value !== null
-        ? { ...value, version: locked }
-        : locked;
-    } else {
-      result[pkgName] = value;
-    }
-  }
-  return result;
-}
+// CloudFront / AWS WAF (and some other fronts) 403 requests that lack a
+// User-Agent header, so we MUST send one on every outbound call. Failing to
+// do so means `_getJson` swallows the 403 as `null` and the compat path
+// silently treats the registry as empty.
+const USER_AGENT = `wyvrnpm/${require('../../package.json').version}`;
 
 class HttpProvider extends BaseProvider {
   static canHandle(source) {
@@ -44,7 +34,7 @@ class HttpProvider extends BaseProvider {
     return new Promise((resolve, reject) => {
       const body = fs.readFileSync(filePath);
       const parsed = new URL(url);
-      const headers = { 'Content-Type': contentType, 'Content-Length': body.length };
+      const headers = { 'User-Agent': USER_AGENT, 'Content-Type': contentType, 'Content-Length': body.length };
       if (token) headers['Authorization'] = `Bearer ${token}`;
       log.info(`  → PUT ${url}`);
       const req = this._lib(url).request(
@@ -65,7 +55,7 @@ class HttpProvider extends BaseProvider {
   _putBuffer(url, buffer, contentType, token) {
     return new Promise((resolve, reject) => {
       const parsed = new URL(url);
-      const headers = { 'Content-Type': contentType, 'Content-Length': buffer.length };
+      const headers = { 'User-Agent': USER_AGENT, 'Content-Type': contentType, 'Content-Length': buffer.length };
       if (token) headers['Authorization'] = `Bearer ${token}`;
       log.info(`  → PUT ${url}`);
       const req = this._lib(url).request(
@@ -86,7 +76,7 @@ class HttpProvider extends BaseProvider {
   _head(url, token) {
     return new Promise((resolve, reject) => {
       const parsed = new URL(url);
-      const headers = {};
+      const headers = { 'User-Agent': USER_AGENT };
       if (token) headers['Authorization'] = `Bearer ${token}`;
       const req = this._lib(url).request(
         { hostname: parsed.hostname, port: parsed.port || undefined, path: parsed.pathname, method: 'HEAD', headers },
@@ -104,13 +94,22 @@ class HttpProvider extends BaseProvider {
   _getJson(url, token) {
     return new Promise((resolve) => {
       const parsed = new URL(url);
-      const headers = { Accept: 'application/json' };
+      const headers = { 'User-Agent': USER_AGENT, Accept: 'application/json' };
       if (token) headers['Authorization'] = `Bearer ${token}`;
       const req = this._lib(url).request(
         { hostname: parsed.hostname, port: parsed.port || undefined, path: parsed.pathname, method: 'GET', headers },
         (res) => {
           if (res.statusCode === 404) { res.resume(); resolve(null); return; }
-          if (res.statusCode < 200 || res.statusCode >= 300) { res.resume(); resolve(null); return; }
+          if (res.statusCode < 200 || res.statusCode >= 300) {
+            // A 404 is "not found" — expected. Anything else (403 from a WAF,
+            // 5xx, etc.) is surprising and should NOT be swallowed silently,
+            // or the compat path will treat the registry as empty. See the
+            // CloudFront UA-block case that motivated the default User-Agent.
+            log.warn(`HTTP GET ${url} → ${res.statusCode}; treating as missing`);
+            res.resume();
+            resolve(null);
+            return;
+          }
           const chunks = [];
           res.on('data', (c) => chunks.push(c));
           res.on('end', () => {
@@ -129,7 +128,7 @@ class HttpProvider extends BaseProvider {
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs ?? 300_000);
     try {
-      const headers = {};
+      const headers = { 'User-Agent': USER_AGENT };
       if (token) headers['Authorization'] = `Bearer ${token}`;
       const response = await fetch(url, { signal: controller.signal, headers });
       if (!response.ok) return false;
@@ -175,7 +174,7 @@ class HttpProvider extends BaseProvider {
   async v2Publish(files, options) {
     const {
       source, name, version, profileHash, buildSettings,
-      contentSha256, gitSha, gitRepo, lockedDependencies, token,
+      contentSha256, gitSha, gitRepo, publishedLock, token,
       updateLatest = true, uploadedBy,
     } = options;
     const base   = source.replace(/\/$/, '');
@@ -185,14 +184,14 @@ class HttpProvider extends BaseProvider {
     // 1) Upload the binary zip
     await this._put(`${buildRoot}/wyvrn.zip`, files.zip, 'application/zip', token);
 
-    // 2) Upload enriched wyvrn.json (original manifest + v2 metadata)
+    // 2) Upload enriched wyvrn.json (original manifest + v2 metadata).
     //    buildSettings is stored for debugging purposes only — not for configuration.
-    //    Dependencies are replaced with locked versions so the server never sees "latest".
+    //    Dependencies are published verbatim from wyvrn.json — ranges stay as
+    //    ranges so consumers can intersect them with their own. The author's
+    //    lockfile snapshot is preserved in `publishedLock` for audit.
     const rawManifest = JSON.parse(fs.readFileSync(files.manifest, 'utf8'));
-    const pinnedDeps = pinDependencies(rawManifest.dependencies, lockedDependencies);
     const v2Meta = {
       ...rawManifest,
-      ...(pinnedDeps !== undefined ? { dependencies: pinnedDeps } : {}),
       schemaVersion: 2,
       profileHash,
       buildSettings,     // copy of the profile used — for debugging
@@ -200,6 +199,7 @@ class HttpProvider extends BaseProvider {
       gitSha:      gitSha  ?? null,
       gitRepo:     gitRepo ?? null,
       publishedAt: new Date().toISOString(),
+      ...(publishedLock && Object.keys(publishedLock).length > 0 ? { publishedLock } : {}),
       ...(uploadedBy ? { uploadedBy } : {}),
     };
     await this._putBuffer(

package/src/providers/s3.js

@@ -9,21 +9,13 @@ const RE_S3_URI           = /^s3:\/\//;
 const RE_S3_VIRTUAL_HOSTED = /^https?:\/\/([^.]+)\.s3[.-][^/]*\.amazonaws\.com/;
 const RE_S3_PATH_STYLE    = /^https?:\/\/s3[.-][^/]*\.amazonaws\.com\/([^/]+)/;
 
-function pinDependencies(rawDeps, lockedDeps) {
-  if (!rawDeps || !lockedDeps || Object.keys(lockedDeps).length === 0) return rawDeps;
-  const result = {};
-  for (const [pkgName, value] of Object.entries(rawDeps)) {
-    const locked = lockedDeps[pkgName];
-    if (locked) {
-      result[pkgName] = typeof value === 'object' && value !== null
-        ? { ...value, version: locked }
-        : locked;
-    } else {
-      result[pkgName] = value;
-    }
-  }
-  return result;
-}
+// CloudFront TTL cap for mutable manifest JSON (versions.json, latest.json)
+// and the per-profile wyvrn.json / source.json. 5 min is short enough that
+// a publish is visible to `install` / `add` well within a coffee break, but
+// long enough that `install` at scale doesn't hammer the origin. Applied
+// on every JSON PUT — consumers of the ZIPs get default (long) TTLs since
+// a (name, version, profileHash) artefact is immutable by construction.
+const JSON_CACHE_CONTROL = 'public, max-age=300';
 
 class S3Provider extends BaseProvider {
   static canHandle(source) {
@@ -76,25 +68,36 @@ class S3Provider extends BaseProvider {
 
   _makeClient(awsProfile) {
     const { S3Client, fromSSO } = this._loadSdk();
-    return new S3Client(awsProfile ? { credentials: fromSSO({ profile: awsProfile }) } : {});
+    if (!awsProfile) return new S3Client({});
+
+    // fromSSO supplies credentials only. The SDK's region resolver is
+    // independent and consults AWS_REGION / AWS_DEFAULT_REGION / the profile
+    // named by AWS_PROFILE — NOT the profile handed to fromSSO. Propagate
+    // --aws-profile so its `region = …` line in ~/.aws/config is the fallback.
+    process.env.AWS_PROFILE = awsProfile;
+    return new S3Client({ credentials: fromSSO({ profile: awsProfile }) });
   }
 
   async _putFile(client, bucket, key, filePath, contentType, PutObjectCommand) {
     log.info(`  → s3://${bucket}/${key}`);
-    await client.send(new PutObjectCommand({
+    const params = {
       Bucket: bucket, Key: key,
       Body: fs.readFileSync(filePath),
       ContentType: contentType,
-    }));
+    };
+    if (contentType === 'application/json') params.CacheControl = JSON_CACHE_CONTROL;
+    await client.send(new PutObjectCommand(params));
   }
 
   async _putBuffer(client, bucket, key, content, contentType, PutObjectCommand) {
     log.info(`  → s3://${bucket}/${key}`);
-    await client.send(new PutObjectCommand({
+    const params = {
       Bucket: bucket, Key: key,
       Body: content,
       ContentType: contentType,
-    }));
+    };
+    if (contentType === 'application/json') params.CacheControl = JSON_CACHE_CONTROL;
+    await client.send(new PutObjectCommand(params));
   }
 
   async _getJson(client, bucket, key, GetObjectCommand) {
@@ -177,7 +180,7 @@ class S3Provider extends BaseProvider {
   async v2Publish(files, options) {
     const {
       source, name, version, profileHash, buildSettings,
-      contentSha256, gitSha, gitRepo, lockedDependencies, awsProfile,
+      contentSha256, gitSha, gitRepo, publishedLock, awsProfile,
       updateLatest = true, uploadedBy,
     } = options;
     const { PutObjectCommand, GetObjectCommand } = this._loadSdk();
@@ -190,14 +193,14 @@ class S3Provider extends BaseProvider {
     // 1) Upload zip
     await this._putFile(client, bucket, `${buildRoot}/wyvrn.zip`, files.zip, 'application/zip', PutObjectCommand);
 
-    // 2) Upload enriched wyvrn.json
+    // 2) Upload enriched wyvrn.json.
     //    buildSettings is stored for debugging purposes only.
-    //    Dependencies are replaced with locked versions so the server never sees "latest".
+    //    Dependencies are published verbatim from wyvrn.json — ranges stay as
+    //    ranges so consumers can intersect them with their own. The author's
+    //    lockfile snapshot is preserved in `publishedLock` for audit.
     const rawManifest = JSON.parse(fs.readFileSync(files.manifest, 'utf8'));
-    const pinnedDeps = pinDependencies(rawManifest.dependencies, lockedDependencies);
     const v2Meta = {
       ...rawManifest,
-      ...(pinnedDeps !== undefined ? { dependencies: pinnedDeps } : {}),
       schemaVersion: 2,
       profileHash,
       buildSettings,
@@ -205,6 +208,7 @@ class S3Provider extends BaseProvider {
       gitSha:      gitSha  ?? null,
       gitRepo:     gitRepo ?? null,
       publishedAt: new Date().toISOString(),
+      ...(publishedLock && Object.keys(publishedLock).length > 0 ? { publishedLock } : {}),
       ...(uploadedBy ? { uploadedBy } : {}),
     };
     await this._putBuffer(