wyvrnpm 2.1.0 → 2.3.2

package/README.md

@@ -518,6 +518,101 @@ wyvrnpm configure profile delete msvc_release
 
 ---
 
+## JSON output (`--format json`)
+
+`install`, `publish`, and `show` accept `--format json` to emit a single machine-readable JSON object on stdout. Log lines (`[wyvrn]` prefix) move to **stderr** in this mode, so stdout is reserved exclusively for the JSON payload — no scraping required.
+
+```bash
+wyvrnpm install --format json > install-result.json
+wyvrnpm publish --format json 2>/dev/null           # swallow logs, keep JSON
+wyvrnpm show zlib@1.3.0.0 --format json | jq '.versions["1.3.0.0"].profiles[].origin'
+```
+
+### Shape — `install`
+
+```json
+{
+  "command": "install",
+  "wyvrnpmVersion": "2.2.1",
+  "profile": { "os": "Windows", "arch": "x86_64", "compiler": "msvc", "compiler.version": "193", "compiler.cppstd": "23", "compiler.runtime": "dynamic" },
+  "profileName": "default",
+  "profileHash": "bf341c08af0aee2d",
+  "packages": [
+    {
+      "name": "zlib",
+      "version": "1.3.0.0",
+      "versionRange": "^1.3.0.0",
+      "profileHash": "a1b2c3d4e5f60718",
+      "options": { "shared": false, "minizip": true },
+      "contentSha256": "…",
+      "gitSha": "…",
+      "resolvedFrom": "v2"
+    }
+  ],
+  "lockFile": "/abs/path/to/wyvrn.lock",
+  "uploadSummary": { "uploaded": 0, "skipped": 0, "failed": 0 }
+}
+```
+
+- `versionRange` is `null` when the user pinned an exact version.
+- `options` is `null` for packages that declare no options.
+- `uploadSummary` is `null` unless `--upload-built` was passed.
+- `packages` is sorted by name.
+
+### Shape — `publish`
+
+```json
+{
+  "command": "publish",
+  "wyvrnpmVersion": "2.2.1",
+  "name": "zlib",
+  "version": "1.3.0.0",
+  "profileHash": "a1b2c3d4e5f60718",
+  "source": "s3://team-pkgs",
+  "contentSha256": "…",
+  "options": { "shared": false, "minizip": true },
+  "gitSha": "…",
+  "gitRepo": "…",
+  "publishedAt": "2026-04-21T12:34:56.789Z"
+}
+```
+
+### Shape — `show`
+
+```json
+{
+  "command": "show",
+  "wyvrnpmVersion": "2.2.1",
+  "source": "s3://team-pkgs",
+  "package": "zlib",
+  "latest": "1.3.0.0",
+  "versions": {
+    "1.3.0.0": {
+      "source": { "gitRepo": "…", "gitSha": "…" },
+      "profiles": [
+        {
+          "profileHash": "a1b2c3d4e5f60718",
+          "contentSha256": "…",
+          "publishedAt": "…",
+          "buildSettings": { "os": "Windows", "...": "...", "options": { "minizip": true } },
+          "origin": "author-publish",
+          "uploadedBy": null,
+          "compatibility": { "compiler.cppstd": "lte" },
+          "declaredOptions": { "minizip": { "default": true, "allowed": [true, false] } }
+        }
+      ]
+    }
+  }
+}
+```
+
+- `origin` is `"author-publish"` | `"consumer-source-build"` | `null` (the last when the summary view can't tell without a deep fetch).
+- Bare-name queries (`wyvrnpm show zlib --format json`) skip the per-profile deep fetch; `origin`, `uploadedBy`, `compatibility`, `declaredOptions` are `null` for each profile.
+
+Exit codes and error behaviour are identical to text mode. Fatal errors leave stdout empty rather than emitting partial JSON.
+
+---
+
 ## Configuration File
 
 wyvrnpm stores persistent configuration in a `config.json` file:
@@ -733,7 +828,97 @@ Fields use PascalCase. `Dependencies` is an array — transitive dependencies ar
 
 **`kind` values:** `ConsoleApp`, `StaticLib`, `DynamicLib`, `HeaderOnlyLib`, `WebApp`, `Utility`, `Service`, `TestProject`
 
-**`dependencies`** can be either a plain version string (`"major.minor.patch.build"`) or an object with `version` and an optional `settings` map. The `settings` map overrides individual build profile fields for that specific dependency — useful when a dependency must be consumed with a different runtime linkage or C++ standard than your default profile.
+**`dependencies`** can be either a plain version string (`"major.minor.patch.build"`) or an object with `version`, an optional `settings` map, and an optional `options` map. The `settings` map overrides individual build profile fields for that specific dependency — useful when a dependency must be consumed with a different runtime linkage or C++ standard than your default profile. The `options` map is covered in the next section.
+
+### Version ranges
+
+The `version` field accepts ranges in addition to exact versions and the `"latest"` tag:
+
+| Spec | Meaning |
+|---|---|
+| `"1.2.3.4"` | exact — must match byte-identically |
+| `"latest"` | resolves to whatever `latest.json` points at |
+| `"^1.2.3.4"` | major-pinned — `>= 1.2.3.4` and `< 2.0.0.0` |
+| `"~1.2.3.4"` | minor-pinned — `>= 1.2.3.4` and `< 1.3.0.0` |
+| `">=1.2.3.4 <2.0.0.0"` | explicit comparators — space-separated, supports `>=`, `>`, `<=`, `<`, `=` |
+
+Ranges resolve at install time against each source's `versions.json`. wyvrnpm picks the **highest version** that satisfies the range. The resolved exact version is pinned into `wyvrn.lock` alongside the original range string, so re-installs are byte-reproducible — ranges are only re-evaluated when the lock file's entry for that dependency is removed.
+
+**Error handling:**
+
+- **No version satisfies the range** → strict failure with every published version listed so you can see what's available.
+- **Conflicting ranges across the graph** (direct consumer wants `^1.x` but a transitive wants `^2.x`) → precise error naming both contributors and their ranges.
+- **Malformed range string** → fail fast with a cheat-sheet of supported syntaxes.
+
+Example:
+
+```json
+{
+  "dependencies": {
+    "OpenSSL": "^3.0.0.0",
+    "zlib":    "~1.3.0.0",
+    "boost":   ">=1.80.0.0 <2.0.0.0"
+  }
+}
+```
+
+### Package options (`options`)
+
+A library author can declare **options** — compile-time feature toggles that change the produced binary's ABI. Examples: `shared` (shared vs static library), `minizip` (zlib's minizip support), `fips` (OpenSSL's FIPS mode). Each option produces a distinct `profileHash`, so every option combination gets its own artefact on the registry.
+
+**Author side — declare in the recipe's `wyvrn.json`:**
+
+```json
+{
+  "name": "zlib",
+  "version": "1.3.0.0",
+  "options": {
+    "shared":  { "default": false, "allowed": [true, false] },
+    "minizip": { "default": true,  "allowed": [true, false] },
+    "api":     { "default": "default", "allowed": ["default", "legacy"] }
+  },
+  "build": {
+    "configure": [
+      "-DBUILD_SHARED_LIBS=${options.shared}",
+      "-DZLIB_BUILD_MINIZIP=${options.minizip}",
+      "-DZLIB_API_MODE=${options.api}"
+    ]
+  }
+}
+```
+
+Rules for the declaration:
+
+- Option names must match `/^[a-z][a-z0-9_-]*$/`.
+- Each option needs `default` + `allowed`. `default` must be a member of `allowed`.
+- `allowed` values are `boolean` or `string`. No integers, no lists.
+- `${options.<name>}` tokens in `build.configure` / `build.buildArgs` are expanded at source-build time. Booleans expand to `ON`/`OFF`; strings expand verbatim. A typo (`${options.fips}` with no `fips` declared) is a hard error — it will not silently reach CMake.
+
+**Consumer side — override per dependency:**
+
+```json
+{
+  "dependencies": {
+    "zlib": {
+      "version": "1.3.0.0",
+      "options": { "minizip": false }
+    }
+  }
+}
+```
+
+**Consumer side — override via CLI (precedence: CLI > wyvrn.json > recipe defaults):**
+
+```bash
+wyvrnpm install -o zlib:minizip=false -o zlib:shared=true
+wyvrnpm publish -o zlib:minizip=false          # publishing a specific variant
+```
+
+Option overrides are validated against the recipe's `allowed` list at resolve time; unknown option names surface a "did you mean?" suggestion.
+
+**What happens on the registry.** Options fold into `profileHash`, so `zlib@1.3.0.0` with `minizip=true` and `zlib@1.3.0.0` with `minizip=false` are two distinct artefacts at two different URLs — same version, different hashes. `wyvrnpm show zlib@1.3.0.0` lists all published variants and prints each one's resolved options.
+
+**Backward compatibility.** Packages that do not declare an `options` block hash byte-identically to how they did before options existed. No registry migration required.
 
 ### Source-build recipe (`build`)
 
@@ -932,6 +1117,77 @@ wyvrnpm clean --build-cache
 
 wyvrnpm uses your ambient git configuration (SSH keys, credential helpers, Windows Credential Manager). It does not manage git credentials itself. If `git clone <gitRepo>` works from your shell, source-build works.
 
+### Upload back to the registry (`--upload-built`)
+
+`--build=missing` warms *your* cache. `--build=missing --upload-built` warms the *team's* cache: after a successful source-build, the freshly-zipped artefact is pushed back to the registry under the consumer's `profileHash`, so the next teammate on the same profile gets a direct v2 download.
+
+```bash
+# Build missing artefacts locally AND publish them back under your profile.
+wyvrnpm install --build=missing --upload-built
+
+# Override the upload destination (URL or configured publish-source name).
+wyvrnpm install --build=missing --upload-built --upload-source team-s3
+
+# Upload auth is resolved in order: CLI flag → named-source config → first configured publish source.
+wyvrnpm install --build=missing --upload-built --aws-profile my-sso
+wyvrnpm install --build=missing --upload-built --token mytoken
+```
+
+Semantics:
+
+- **Opt-in.** Nothing uploads unless `--upload-built` is passed. Requires `--build=missing`.
+- **Skip if exists.** If `(name, version, profileHash)` already lives on the upload source, the upload is a silent no-op. A consumer cannot overwrite an existing artefact; use `wyvrnpm publish --force` from the source repo for that.
+- **`latest.json` is untouched.** A consumer upload is a new `profileHash` of an existing version, not a new version release.
+- **Upload failures never break the install.** The consumer already has a working `wyvrn_internal/` on disk — a broken upload is logged as a warning and the install continues.
+- **Provenance.** Uploaded manifests carry a small `uploadedBy` block so maintainers can tell consumer builds apart from author publishes:
+
+  ```json
+  {
+    "uploadedBy": {
+      "kind":           "source-build",
+      "profileHash":    "a1b2c3d4e5f60718",
+      "builtFromGit":   "https://github.com/madler/zlib",
+      "builtFromSha":   "abcdef01...",
+      "uploadedAt":     "2026-04-21T12:34:56.789Z",
+      "wyvrnpmVersion": "2.1.0"
+    }
+  }
+  ```
+
+  Absence of `uploadedBy` means the artefact was published by the author via `wyvrnpm publish`.
+
+At the end of an install with `--upload-built`, a one-line summary is printed:
+
+```
+[wyvrn] upload-built summary: 2 artefacts uploaded, 1 skipped (already existed), 0 failed
+```
+
+**Trust model.** Registry write auth is the gate — only consumers with credentials for the upload destination can upload at all. The same `v2Publish` path is used as `wyvrnpm publish`, so the resulting artefact is byte-identical in layout. SHA256 verification on the download side protects against in-transit tampering. Uploading deliberately opts into "your machine's build of this package is trusted by everyone else on this profile" — use CI with clean toolchains rather than developer workstations if you care about reproducibility.
+
+#### Auditing consumer uploads (`wyvrnpm show`)
+
+Maintainers can list every build of a package and tell author-published artefacts apart from consumer uploads:
+
+```bash
+wyvrnpm show zlib                      # all versions + their profile hashes
+wyvrnpm show zlib@1.3.0.0              # every profile for that version, with origin + builtFromSha
+wyvrnpm show zlib@1.3.0.0@a1b2c3d4...  # one specific build, full metadata
+```
+
+With a version specified, `show` fetches each build's `wyvrn.json` and reports `author publish` or `consumer upload (source-build)` alongside the relevant `uploadedBy` fields. Sources default to the configured install sources; override with `--source <url>`.
+
+#### Forgetting uploads (`clean --uploaded-built`)
+
+Each successful upload writes a `.uploaded-to.json` sidecar alongside the cached artefact under `%LOCALAPPDATA%\wyvrnpm\bc\{name}-{version}-{profileHash}\`. It records destination, timestamp, and SHA — purely informational, nothing reads it during install.
+
+To wipe just those local records (no effect on the registry, the artefact zips, or `wyvrn_internal/`):
+
+```bash
+wyvrnpm clean --uploaded-built
+```
+
+This is a privacy / local-audit cleanup knob — `clean --build-cache` already removes sidecars as a side effect of nuking the cache.
+
 ---
 
 ## Lock File (wyvrn.lock)

package/bin/wyvrn.js

@@ -3,13 +3,15 @@
 'use strict';
 
 const yargs     = require('yargs');
-const init      = require('../src/commands/init');
-const install   = require('../src/commands/install');
-const clean     = require('../src/commands/clean');
-const publish   = require('../src/commands/publish');
-const configure = require('../src/commands/configure');
-const profile   = require('../src/commands/profile');
-const build     = require('../src/commands/build');
+const init         = require('../src/commands/init');
+const install      = require('../src/commands/install');
+const clean        = require('../src/commands/clean');
+const publish      = require('../src/commands/publish');
+const configure    = require('../src/commands/configure');
+const profile      = require('../src/commands/profile');
+const build        = require('../src/commands/build');
+const show         = require('../src/commands/show');
+const installSkill = require('../src/commands/install-skill');
 const { link, unlink } = require('../src/commands/link');
 
 yargs
@@ -58,6 +60,36 @@ yargs
             'Resolution mode when no exact profile match exists. ' +
             'never=fail; missing=build from source (pending phase 3); always=rebuild (pending phase 3)',
         })
+        .option('option', {
+          alias: 'o',
+          type: 'string',
+          array: true,
+          description:
+            'Override a package option. Repeatable. Format: <pkg>:<name>=<value>. ' +
+            'Example: -o zlib:minizip=false -o OpenSSL:fips=true',
+        })
+        .option('upload-built', {
+          type: 'boolean',
+          default: false,
+          description:
+            'After successful --build=missing, upload each source-built artefact ' +
+            'back to the registry under the active profileHash so the next consumer ' +
+            'gets a direct download. Requires write credentials for the upload source.',
+        })
+        .option('upload-source', {
+          type: 'string',
+          description:
+            'Destination for --upload-built (URL or configured publish-source name). ' +
+            'Defaults to the first configured publish source.',
+        })
+        .option('aws-profile', {
+          type: 'string',
+          description: 'AWS SSO profile for --upload-built when uploading to S3',
+        })
+        .option('token', {
+          type: 'string',
+          description: 'Bearer token for --upload-built when uploading to HTTP',
+        })
         .option('platform', {
           type: 'string',
           description: 'v1 legacy platform path (used as fallback if v2 not found)',
@@ -68,9 +100,20 @@ yargs
           type: 'number',
           description: 'HTTP timeout in seconds',
           default: 300,
+        })
+        .option('format', {
+          type: 'string',
+          choices: ['text', 'json'],
+          default: 'text',
+          description: 'Output format. "json" emits a single JSON object on stdout; log lines go to stderr.',
         });
     },
-    (argv) => install(argv),
+    (argv) => install({
+      ...argv,
+      uploadBuilt:  argv['upload-built'],
+      uploadSource: argv['upload-source'],
+      awsProfile:   argv['aws-profile'],
+    }),
   )
 
   // ── build ─────────────────────────────────────────────────────────────────
@@ -155,13 +198,60 @@ yargs
     'clean',
     'Remove downloaded packages and lock file. --build-cache also wipes the machine-wide source-build cache.',
     (y) => {
-      y.option('build-cache', {
-        type: 'boolean',
-        default: false,
-        description: 'Also remove the source-build cache under %LOCALAPPDATA%\\wyvrnpm\\bc\\',
-      });
+      y
+        .option('build-cache', {
+          type: 'boolean',
+          default: false,
+          description: 'Also remove the source-build cache under %LOCALAPPDATA%\\wyvrnpm\\bc\\',
+        })
+        .option('uploaded-built', {
+          type: 'boolean',
+          default: false,
+          description:
+            'Wipe only the local record of artefacts uploaded via --upload-built ' +
+            '(the .uploaded-to.json sidecars in the build cache). Does not touch ' +
+            'the registry, the artefact zips, or wyvrn_internal/.',
+        });
+    },
+    (argv) => clean({
+      ...argv,
+      buildCache:     argv['build-cache'],
+      uploadedBuilt:  argv['uploaded-built'],
+    }),
+  )
+
+  // ── show ──────────────────────────────────────────────────────────────────
+  .command(
+    'show <pkg>',
+    'Display registry metadata for a package. Surfaces `uploadedBy` so consumer uploads can be told apart from author publishes.',
+    (y) => {
+      y
+        .positional('pkg', {
+          type: 'string',
+          description: 'Spec: <name>[@<version>[@<profileHash>]]',
+        })
+        .option('source', {
+          alias: 's',
+          type: 'string',
+          array: true,
+          description: 'Source URL(s) to query; defaults to configured install sources',
+        })
+        .option('aws-profile', {
+          type: 'string',
+          description: 'AWS SSO profile for S3 sources',
+        })
+        .option('token', {
+          type: 'string',
+          description: 'Bearer token for HTTP sources',
+        })
+        .option('format', {
+          type: 'string',
+          choices: ['text', 'json'],
+          default: 'text',
+          description: 'Output format. "json" emits a single JSON object on stdout; log lines go to stderr.',
+        });
     },
-    (argv) => clean({ ...argv, buildCache: argv['build-cache'] }),
+    (argv) => show({ ...argv, awsProfile: argv['aws-profile'] }),
   )
 
   // ── publish ───────────────────────────────────────────────────────────────
@@ -200,6 +290,20 @@ yargs
           description: 'Overwrite an existing published version',
           default: false,
         })
+        .option('option', {
+          alias: 'o',
+          type: 'string',
+          array: true,
+          description:
+            'Override an option value at publish time. Repeatable. ' +
+            'Format: <pkg>:<name>=<value> (pkg must match the package being published).',
+        })
+        .option('format', {
+          type: 'string',
+          choices: ['text', 'json'],
+          default: 'text',
+          description: 'Output format. "json" emits a single JSON object on stdout; log lines go to stderr.',
+        })
         ;
     },
     (argv) => publish({ ...argv, awsProfile: argv['aws-profile'] }),
@@ -365,6 +469,19 @@ yargs
     (argv) => unlink(argv),
   )
 
+  // ── install-skill ─────────────────────────────────────────────────────────
+  .command(
+    'install-skill',
+    'Install the bundled wyvrnpm Agent Skill into Claude Code (~/.claude/skills/wyvrnpm/)',
+    (y) => {
+      y
+        .option('claude',  { type: 'boolean', description: 'Install for Claude Code',            default: false })
+        .option('force',   { type: 'boolean', description: 'Overwrite an existing installation', default: false })
+        .option('dry-run', { type: 'boolean', description: 'Report actions without writing',     default: false });
+    },
+    (argv) => installSkill(argv),
+  )
+
   .demandCommand(1)
   .strict()
   .help()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wyvrnpm",
-  "version": "2.1.0",
+  "version": "2.3.2",
   "description": "A simple, static-hosting-compatible C++ package manager",
   "keywords": [
     "c++",
@@ -20,6 +20,7 @@
     "bin/",
     "src/",
     "cmake/",
+    "claude/skills/wyvrnpm.skill",
     "README.md"
   ],
   "scripts": {

package/src/build/cache.js

@@ -51,6 +51,7 @@ const LAYOUT = Object.freeze({
   buildDir:      'build',
   installSubdir: 'install', // relative to buildDir — can be overridden by recipe.installDir
   artefactZip:   'wyvrn.zip',
+  uploadSidecar: '.uploaded-to.json',
 });
 
 /**
@@ -91,11 +92,57 @@ function hasValidArtefact(args) {
   return fs.existsSync(artefact);
 }
 
+/**
+ * Find every `.uploaded-to.json` sidecar under the build cache. Each file
+ * records the destinations that a cached artefact has been pushed to via
+ * `wyvrnpm install --build=missing --upload-built`.
+ *
+ * Used by `wyvrnpm clean --uploaded-built` and for audit tooling.
+ *
+ * @returns {Array<{ cacheDir: string, sidecarPath: string, uploads: Array<object> }>}
+ */
+function listUploadSidecars() {
+  const root = getBuildCacheRoot();
+  if (!fs.existsSync(root)) return [];
+  const out = [];
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const cacheDir    = path.join(root, entry.name);
+    const sidecarPath = path.join(cacheDir, LAYOUT.uploadSidecar);
+    if (!fs.existsSync(sidecarPath)) continue;
+    let uploads = [];
+    try {
+      const raw = JSON.parse(fs.readFileSync(sidecarPath, 'utf8'));
+      if (Array.isArray(raw?.uploads)) uploads = raw.uploads;
+    } catch { /* corrupt — surface as empty uploads */ }
+    out.push({ cacheDir, sidecarPath, uploads });
+  }
+  return out;
+}
+
+/**
+ * Remove every `.uploaded-to.json` sidecar under the build cache. Used by
+ * `wyvrnpm clean --uploaded-built`. Leaves all other cache content intact
+ * (the artefact zips, source clones, and build dirs stay put).
+ *
+ * @returns {number}  count of sidecar files removed
+ */
+function clearUploadSidecars() {
+  const entries = listUploadSidecars();
+  let removed = 0;
+  for (const { sidecarPath } of entries) {
+    try { fs.unlinkSync(sidecarPath); removed++; } catch { /* ignore */ }
+  }
+  return removed;
+}
+
 module.exports = {
   getBuildCacheRoot,
   getPackageBuildDir,
   getBuildPaths,
   clearBuildCache,
   hasValidArtefact,
+  listUploadSidecars,
+  clearUploadSidecars,
   LAYOUT,
 };

package/src/build/index.js

@@ -13,6 +13,7 @@ const { normalizeDependencies } = require('../manifest');
 const { resolveDependencies }   = require('../resolve');
 const { hashProfile, mergeProfile, sha256Of } = require('../profile');
 const { generateToolchain }     = require('../toolchain');
+const { normalizeOptionsDeclaration, resolveEffectiveOptions } = require('../options');
 const log                       = require('../logger');
 
 /**
@@ -62,6 +63,8 @@ function addFolder(zip, dir, base) {
  * @param {import('../profile').WyvrnProfile} args.profile
  * @param {string} args.profileName
  * @param {string} args.profileHash
+ * @param {Record<string, any>|null} [args.options]  Effective options for this build.
+ *                                                    Used to expand `${options.*}` in the recipe.
  * @param {string} args.gitRepo
  * @param {string} args.gitSha
  * @param {string} args.destZipPath    Where the caller expects the artefact zip.
@@ -73,13 +76,15 @@ function addFolder(zip, dir, base) {
  *                                      all four CMake configurations).
  * @param {object} [args.authOptions]
  * @returns {Promise<{
- *   found:          true,
- *   contentSha256:  string,
- *   profileHash:    string,
- *   gitSha:         string,
- *   gitRepo:        string,
- *   source:         string,       // build-cache path (for logging)
- *   resolvedFrom:   'v2-source-build',
+ *   found:             true,
+ *   contentSha256:     string,
+ *   profileHash:       string,
+ *   gitSha:            string,
+ *   gitRepo:           string,
+ *   source:            string,       // build-cache path (for logging)
+ *   resolvedFrom:      'v2-source-build',
+ *   artefactPath:      string,       // absolute path to the built zip in the cache
+ *   clonedManifestPath: string,      // absolute path to the cloned wyvrn.json (for upload-built)
  * }>}
  * @throws {Error} when the cloned manifest lacks a `build` section, when
  *                 CMake is missing, or when the compile itself fails.
@@ -88,6 +93,7 @@ async function buildFromSource(args) {
   const {
     name, version,
     profile, profileName, profileHash,
+    options = null,
     gitRepo, gitSha,
     destZipPath,
     packageSources,
@@ -120,6 +126,8 @@ async function buildFromSource(args) {
       gitRepo,
       source:       paths.root,
       resolvedFrom: 'v2-source-build',
+      artefactPath:       paths.artefact,
+      clonedManifestPath: path.join(paths.src, 'wyvrn.json'),
     };
   }
 
@@ -145,7 +153,10 @@ async function buildFromSource(args) {
       `Source-build is opt-in — the publisher must add a build recipe.`,
     );
   }
-  const recipe = normalizeRecipe(clonedManifest.build);
+  // Pass effective options into the recipe so `${options.<name>}` tokens in
+  // `build.configure` / `build.buildArgs` expand to the concrete values that
+  // produced this build's profileHash.
+  const recipe = normalizeRecipe(clonedManifest.build, options);
 
   // ── 4. Recursively resolve + download this package's OWN deps ──────────
   // Lazy-require: downloadDependencies is where we were called from, so
@@ -161,20 +172,38 @@ async function buildFromSource(args) {
   );
 
   log.info(`  resolving ${Object.keys(depsForResolution).length} transitive dep(s)`);
+  const transitiveManifests = new Map();
   const resolvedDeps = await resolveDependencies(
     depsForResolution, packageSources, platform, fetch, new Map(),
+    transitiveManifests,
   );
 
-  // Build an enriched deps map (profileHash per dep based on overrides).
+  // Build an enriched deps map. Same logic as install.js: per-dep settings
+  // + recipe-declared options resolved against what the *cloned* source
+  // manifest asks for. No CLI overrides — transitive options come solely
+  // from the source package's `dependencies.<n>.options`.
   const enrichedDeps = new Map();
   for (const [depName, depVersion] of resolvedDeps) {
-    const depOverrides    = rawPackageDeps[depName]?.settings ?? {};
+    const depOverrides     = rawPackageDeps[depName]?.settings ?? {};
     const effectiveProfile = mergeProfile(profile, depOverrides);
-    const depProfileHash   = hashProfile(effectiveProfile);
+
+    const transitiveManifest = transitiveManifests.get(depName);
+    const declaration = transitiveManifest?.options
+      ? normalizeOptionsDeclaration(transitiveManifest.options, `${depName}@${depVersion}`)
+      : null;
+    const effectiveOptions = resolveEffectiveOptions(
+      declaration,
+      rawPackageDeps[depName]?.options ?? {},
+      {},
+      `${depName}@${depVersion}`,
+    );
+
+    const depProfileHash = hashProfile(effectiveProfile, effectiveOptions);
     enrichedDeps.set(depName, {
       version:     depVersion,
       profileHash: depProfileHash,
       profile:     effectiveProfile,
+      options:     effectiveOptions,
     });
   }
 
@@ -238,6 +267,8 @@ async function buildFromSource(args) {
     gitRepo,
     source:       paths.root,
     resolvedFrom: 'v2-source-build',
+    artefactPath:       paths.artefact,
+    clonedManifestPath: manifestPath,
   };
 }