@smoothbricks/cli 0.11.17 → 0.11.18

package/dist/wrangler/stage-secrets.d.ts

@@ -0,0 +1,57 @@
+import { type DeploymentStage } from './stage.js';
+/**
+ * How a declaration names a stage. The fixed stages go by their own name; every `prN` stage is
+ * `preview`, because a scope is written once and pull-request numbers are not knowable in advance.
+ */
+export type SecretStageScope = 'staging' | 'production' | 'preview';
+/**
+ * `smoo.wrangler.secretStages`: a declared secret name mapped to the stages it belongs to. The map
+ * answers two questions with one declaration, and both directions matter:
+ *
+ * - requirement — a stage the secret belongs to refuses to deploy without a value for it;
+ * - permission — a stage the secret does *not* belong to never receives it, however loudly the
+ *   deploying shell exports it. A test-only capability exported by CI for preview stages must not
+ *   ride along into production just because the variable happens to be set.
+ *
+ * A declared name absent from the map belongs to every stage. A name mapped to `[]` belongs to no
+ * stage, which is how a value that exists only for local development is declared.
+ */
+export type SecretStageMap = Record<string, SecretStageScope[]>;
+/** Secret NAMES the project declares. Values live on the Worker; the repo only ever holds the keys. */
+export declare function readDeclaredSecretNames(cwd: string): string[];
+/** `smoo.wrangler.secretStages` from the project's package.json; no file and no block scope nothing. */
+export declare function readSecretStageMap(cwd: string): SecretStageMap;
+/** Which of a project's declared secrets one stage may see, and which belong to other stages. */
+export interface StageSecretPlan {
+    stage: DeploymentStage;
+    /** Declared names this stage requires — and the only ones a deploy of it may carry. */
+    required: string[];
+    /** Declared names scoped to other stages: withheld from this deploy even when a value is exported. */
+    withheld: string[];
+    /** The declaration itself, so a refusal can say why each name is where it is. */
+    scopes: SecretStageMap;
+}
+/**
+ * Splits the declared secrets by whether `stage` is in scope for each.
+ *
+ * A scope on an undeclared name is refused rather than ignored: it is almost always a typo of a
+ * real secret's name, and its effect is the dangerous direction — the misspelt entry scopes
+ * nothing while the real secret, still absent from the map, reaches every stage.
+ */
+export declare function planStageSecrets(declared: string[], stage: DeploymentStage, scopes: SecretStageMap): StageSecretPlan;
+/**
+ * Why this deploy must not proceed, or nothing when it may.
+ *
+ * Two refusals, reported together so one run names every problem:
+ *
+ * - a required secret with no value anywhere. `--secrets-file` applies additively, so a deploy
+ *   that never mentions a secret leaves whatever the Worker already holds — silence that reads as
+ *   success while a secret introduced after the first deploy never arrives, and the code that
+ *   needs it fails at runtime instead of here.
+ * - a withheld secret the Worker already holds. Filtering it out of this deploy's payload cannot
+ *   remove it, so the scope would be nominal rather than enforced until someone deletes it.
+ *
+ * A value is never read, never formatted, and never named beyond its key.
+ */
+export declare function stageSecretRefusal(plan: StageSecretPlan, exported: ReadonlySet<string>, held: ReadonlySet<string>, workerName: string): string | undefined;
+//# sourceMappingURL=stage-secrets.d.ts.map

package/dist/wrangler/stage-secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-secrets.d.ts","sourceRoot":"","sources":["../../src/wrangler/stage-secrets.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,KAAK,eAAe,EAAsB,MAAM,YAAY,CAAC;AAEtE;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,YAAY,GAAG,SAAS,CAAC;AAEpE;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,EAAE,CAAC,CAAC;AAahE,uGAAuG;AACvG,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAG7D;AAED,wGAAwG;AACxG,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAQ9D;AAED,iGAAiG;AACjG,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,eAAe,CAAC;IACvB,uFAAuF;IACvF,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,sGAAsG;IACtG,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,iFAAiF;IACjF,MAAM,EAAE,cAAc,CAAC;CACxB;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,cAAc,GAAG,eAAe,CAsBpH;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,eAAe,EACrB,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,EAC7B,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,EACzB,UAAU,EAAE,MAAM,GACjB,MAAM,GAAG,SAAS,CAsBpB"}

package/dist/wrangler/stage-secrets.js

@@ -0,0 +1,178 @@
+import * as _accessExpressionAsString_1 from "typia/lib/internal/_accessExpressionAsString";
+const __typia_transform__accessExpressionAsString = _accessExpressionAsString_1._accessExpressionAsString;
+import * as _validateReport_1 from "typia/lib/internal/_validateReport";
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import typia from 'typia';
+import { formatValidationErrors, parseJsonFileText } from '../lib/json.js';
+import { parseDevVarsExample } from './prepare-env.js';
+import { isPullRequestStage } from './stage.js';
+const validateWranglerManifest = (() => {
+    const _io0 = input => undefined === input.smoo || "object" === typeof input.smoo && null !== input.smoo && false === Array.isArray(input.smoo) && _io1(input.smoo);
+    const _io1 = input => undefined === input.wrangler || "object" === typeof input.wrangler && null !== input.wrangler && false === Array.isArray(input.wrangler) && _io2(input.wrangler);
+    const _io2 = input => undefined === input.secretStages || "object" === typeof input.secretStages && null !== input.secretStages && false === Array.isArray(input.secretStages) && _io3(input.secretStages);
+    const _io3 = input => Object.keys(input).every(key => {
+        const value = input[key];
+        if (undefined === value)
+            return true;
+        return Array.isArray(value) && value.every(elem => "preview" === elem || "production" === elem || "staging" === elem);
+    });
+    const _vo0 = (input, _path, _exceptionable = true) => [undefined === input.smoo || ("object" === typeof input.smoo && null !== input.smoo && false === Array.isArray(input.smoo) || _report(_exceptionable, {
+            path: _path + ".smoo",
+            expected: "(undefined | { wrangler?: { secretStages?: SecretStageMap | undefined; } | undefined; })",
+            value: input.smoo
+        })) && _vo1(input.smoo, _path + ".smoo", true && _exceptionable) || _report(_exceptionable, {
+            path: _path + ".smoo",
+            expected: "(undefined | { wrangler?: { secretStages?: SecretStageMap | undefined; } | undefined; })",
+            value: input.smoo
+        })].every(flag => flag);
+    const _vo1 = (input, _path, _exceptionable = true) => [undefined === input.wrangler || ("object" === typeof input.wrangler && null !== input.wrangler && false === Array.isArray(input.wrangler) || _report(_exceptionable, {
+            path: _path + ".wrangler",
+            expected: "(undefined | { secretStages?: SecretStageMap | undefined; })",
+            value: input.wrangler
+        })) && _vo2(input.wrangler, _path + ".wrangler", true && _exceptionable) || _report(_exceptionable, {
+            path: _path + ".wrangler",
+            expected: "(undefined | { secretStages?: SecretStageMap | undefined; })",
+            value: input.wrangler
+        })].every(flag => flag);
+    const _vo2 = (input, _path, _exceptionable = true) => [undefined === input.secretStages || ("object" === typeof input.secretStages && null !== input.secretStages && false === Array.isArray(input.secretStages) || _report(_exceptionable, {
+            path: _path + ".secretStages",
+            expected: "(SecretStageMap | undefined)",
+            value: input.secretStages
+        })) && _vo3(input.secretStages, _path + ".secretStages", true && _exceptionable) || _report(_exceptionable, {
+            path: _path + ".secretStages",
+            expected: "(SecretStageMap | undefined)",
+            value: input.secretStages
+        })].every(flag => flag);
+    const _vo3 = (input, _path, _exceptionable = true) => [false === _exceptionable || Object.keys(input).map(key => {
+            const value = input[key];
+            if (undefined === value)
+                return true;
+            return (Array.isArray(value) || _report(_exceptionable, {
+                path: _path + __typia_transform__accessExpressionAsString(key),
+                expected: "Array<SecretStageScope>",
+                value: value
+            })) && value.map((elem, _index2) => "preview" === elem || "production" === elem || "staging" === elem || _report(_exceptionable, {
+                path: _path + __typia_transform__accessExpressionAsString(key) + "[" + _index2 + "]",
+                expected: "(\"preview\" | \"production\" | \"staging\")",
+                value: elem
+            })).every(flag => flag) || _report(_exceptionable, {
+                path: _path + __typia_transform__accessExpressionAsString(key),
+                expected: "Array<SecretStageScope>",
+                value: value
+            });
+        }).every(flag => flag)].every(flag => flag);
+    const __is = input => "object" === typeof input && null !== input && false === Array.isArray(input) && _io0(input);
+    let errors;
+    let _report;
+    const __validate = input => {
+        if (false === __is(input)) {
+            errors = [];
+            _report = _validateReport_1._validateReport(errors);
+            ((input, _path, _exceptionable = true) => ("object" === typeof input && null !== input && false === Array.isArray(input) || _report(true, {
+                path: _path + "",
+                expected: "WranglerPackageManifest",
+                value: input
+            })) && _vo0(input, _path + "", true) || _report(true, {
+                path: _path + "",
+                expected: "WranglerPackageManifest",
+                value: input
+            }))(input, "$input", true);
+            const success = 0 === errors.length;
+            return success ? {
+                success,
+                data: input
+            } : {
+                success,
+                errors,
+                data: input
+            };
+        }
+        return {
+            success: true,
+            data: input
+        };
+    };
+    return input => __validate(JSON.parse(input));
+})();
+/** Secret NAMES the project declares. Values live on the Worker; the repo only ever holds the keys. */
+export function readDeclaredSecretNames(cwd) {
+    const path = join(cwd, '.dev.vars.example');
+    return existsSync(path) ? parseDevVarsExample(readFileSync(path, 'utf8')) : [];
+}
+/** `smoo.wrangler.secretStages` from the project's package.json; no file and no block scope nothing. */
+export function readSecretStageMap(cwd) {
+    const path = join(cwd, 'package.json');
+    if (!existsSync(path))
+        return {};
+    const result = parseJsonFileText(path, readFileSync(path, 'utf8'), validateWranglerManifest);
+    if (!result.success) {
+        throw new Error(`${path} declares an invalid smoo.wrangler block: ${formatValidationErrors(result.errors)}`);
+    }
+    return result.data.smoo?.wrangler?.secretStages ?? {};
+}
+/**
+ * Splits the declared secrets by whether `stage` is in scope for each.
+ *
+ * A scope on an undeclared name is refused rather than ignored: it is almost always a typo of a
+ * real secret's name, and its effect is the dangerous direction — the misspelt entry scopes
+ * nothing while the real secret, still absent from the map, reaches every stage.
+ */
+export function planStageSecrets(declared, stage, scopes) {
+    const declaredNames = new Set(declared);
+    const undeclared = Object.keys(scopes).filter((name) => !declaredNames.has(name));
+    if (undeclared.length > 0) {
+        throw new Error(`smoo.wrangler.secretStages scopes ${undeclared.join(', ')}, which .dev.vars.example does not declare. ` +
+            'A scope on a name no secret has leaves the secret it was meant for unscoped, so that secret reaches every stage.');
+    }
+    // Every `prN` stage answers to one written token: a scope cannot name pull requests in advance.
+    const scope = isPullRequestStage(stage) ? 'preview' : stage;
+    const required = [];
+    const withheld = [];
+    for (const name of declared) {
+        const declaredScope = scopes[name];
+        if (declaredScope === undefined || declaredScope.includes(scope)) {
+            required.push(name);
+        }
+        else {
+            withheld.push(name);
+        }
+    }
+    return { stage, required, withheld, scopes };
+}
+/**
+ * Why this deploy must not proceed, or nothing when it may.
+ *
+ * Two refusals, reported together so one run names every problem:
+ *
+ * - a required secret with no value anywhere. `--secrets-file` applies additively, so a deploy
+ *   that never mentions a secret leaves whatever the Worker already holds — silence that reads as
+ *   success while a secret introduced after the first deploy never arrives, and the code that
+ *   needs it fails at runtime instead of here.
+ * - a withheld secret the Worker already holds. Filtering it out of this deploy's payload cannot
+ *   remove it, so the scope would be nominal rather than enforced until someone deletes it.
+ *
+ * A value is never read, never formatted, and never named beyond its key.
+ */
+export function stageSecretRefusal(plan, exported, held, workerName) {
+    const unavailable = plan.required.filter((name) => !exported.has(name) && !held.has(name));
+    const installed = plan.withheld.filter((name) => held.has(name));
+    if (unavailable.length === 0 && installed.length === 0)
+        return undefined;
+    const lines = [`Refusing to deploy ${workerName} to ${plan.stage}.`];
+    if (unavailable.length > 0) {
+        lines.push(`Stage ${plan.stage} requires these secrets and no value exists for them, neither in this environment nor on the Worker:`, ...unavailable.map((name) => `  ${name} — ${scopeDescription(name, plan.scopes)}`), 'Export each one in the deploying shell before the deploy. Once the Worker exists,', `\`wrangler secret put <NAME> --name ${workerName}\` supplies it too.`);
+    }
+    if (installed.length > 0) {
+        lines.push(`The Worker holds these secrets, which smoo.wrangler.secretStages keeps out of ${plan.stage}:`, ...installed.map((name) => `  ${name} — ${scopeDescription(name, plan.scopes)}`), `Delete each one with \`wrangler secret delete <NAME> --name ${workerName}\`. A deploy of this stage`, 'never sends them, so leaving them installed would keep the scope nominal.');
+    }
+    return lines.join('\n');
+}
+function scopeDescription(name, scopes) {
+    const scope = scopes[name];
+    if (scope === undefined)
+        return 'unscoped, so every stage requires it';
+    if (scope.length === 0)
+        return 'scoped to no stage (local development only)';
+    return `scoped to ${scope.join(', ')}`;
+}

package/managed/raw/tooling/direnv/devenv.smoo.nix

@@ -354,7 +354,15 @@
       export GOFLAGS="''${GOFLAGS:--trimpath}"
       unset GOROOT
       bun "$DEVENV_ROOT/setup-environment.ts" || exit $?
-      export NX_SOCKET_DIR="$DEVENV_RUNTIME/nx"
+      # One socket dir per Nx workspace. DEVENV_RUNTIME is keyed to the devenv
+      # ROOT, so every workspace sharing one devenv - a sibling repository, a
+      # copy-on-write clone, a scratch workspace created inside this shell -
+      # would land on one socket. The first daemon to claim it then refuses
+      # every message from the others ("received a message from a different
+      # workspace"), which reads as a hung Nx in a workspace that did nothing
+      # wrong. Nx's own diagnostic names this exact cause.
+      nx_workspace_root="$(cd "$DEVENV_ROOT/../.." >/dev/null 2>&1 && pwd || printf '%s' "$PWD")"
+      export NX_SOCKET_DIR="$DEVENV_RUNTIME/nx-$(printf '%s' "$nx_workspace_root" | cksum | cut -d' ' -f1)"
       mkdir -p "$NX_SOCKET_DIR"
       ${lib.optionalString pkgs.stdenv.isDarwin ''
         unset CC CXX

package/managed/raw/tooling/git-hooks/pre-push.sh

@@ -1,25 +1,25 @@
 #!/usr/bin/env bash
-# macOS-only Linux compile gate. Everything in tooling depends only on
-# devenv.nix packages, so this hook must also work without devenv on PATH —
-# but it may not pretend a check ran that never did. Nx task hashes can
-# differ between the bare shell and the linux-cross profile, so a bare miss
-# proves nothing on its own. Policy, in order:
-# 1. Bare `nx run-many -t cargo-lint-cross`: a hit is a prior real
-#    `cargo clippy --target x86_64-unknown-linux-gnu`; pass with no toolchain.
-# 2. If a Nix-built devenv is on PATH, `bun run check:linux` enters the
-#    linux-cross profile properly and its result decides the push.
-# 3. Otherwise refuse with the recovery command instead of a toolchain error
-
-# A Nix-built devenv binary (under /nix/store), skipping the repo wrapper
-# scripts that also answer to this name but cannot enter a profile alone.
-has_nix_devenv() {
-  while IFS= read -r candidate; do
-    case "$(realpath "$candidate" 2>/dev/null)" in
-      /nix/store/*) return 0 ;;
-    esac
-  done < <(which -a devenv 2>/dev/null)
-  return 1
-}
+# macOS-only Linux cross-compile gate. This hook is a cache PROBE and nothing
+# else: it reads the nx cache and never compiles. A hit means a real
+# `cargo clippy --target x86_64-unknown-linux-gnu` already passed for exactly
+# this tree, so the push is safe with no toolchain present. Anything else
+# refuses the push and names the one command that fixes it.
+#
+# Why probe-only. The cross-clippy needs the linux-cross C toolchain, which
+# lives in a devenv profile. A hook that entered that profile spent minutes
+# compiling on a push the user expected to take a second, and it did so in an
+# environment they never asked for. Pushing is not the place to discover that
+# the tree has not been compiled for Linux; `bun run check:linux` is.
+#
+# CC_x86_64_unknown_linux_gnu is unset for the probe deliberately. The target's
+# own guard reads it to decide whether the toolchain is present, so leaving it
+# set would let a push made from inside an already-entered linux-cross shell
+# fall through into a real multi-minute compile. It is not a declared input of
+# the target, so unsetting it cannot change the task hash — a warm entry still
+# hits.
+#
+# Everything in tooling depends only on devenv.nix packages, so this hook also
+# works with no devenv on PATH. It must never pretend a check ran that did not.
 
 cd "$(git rev-parse --show-toplevel)"
 TOOLING="$PWD/tooling"
@@ -31,17 +31,18 @@ case "$(uname -s)" in
   *) exit 0 ;;
 esac
 
-if nx run-many -t cargo-lint-cross; then
+if env -u CC_x86_64_unknown_linux_gnu nx run-many -t cargo-lint-cross --output-style=static; then
   exit 0
 fi
 
-if has_nix_devenv; then
-  exec bun run check:linux
-fi
-
 cat >&2 <<'EOF'
-pre-push: cargo-lint-cross is not cached for this tree and no Nix-built
-devenv is on PATH to enter the linux-cross profile. Run `bun run check:linux`
-from a shell with nix on PATH, wait for it to pass, then push again.
+
+pre-push: the Linux cross-compile check is NOT cached for this tree, so this
+push would ship code that has never been compiled for Linux. This hook only
+reads the cache; it does not build. The "needs the linux-cross C toolchain"
+line above is the probe refusing to compile, not a broken toolchain.
+
+  Run:  bun run check:linux
+  Wait for it to pass, then push again.
 EOF
 exit 1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smoothbricks/cli",
-  "version": "0.11.17",
+  "version": "0.11.18",
   "type": "module",
   "description": "SmoothBricks monorepo automation CLI",
   "bin": {
@@ -64,7 +64,7 @@
   ],
   "dependencies": {
     "@arethetypeswrong/core": "^0.18.2",
-    "@smoothbricks/nx-plugin": "0.4.11",
+    "@smoothbricks/nx-plugin": "0.4.12",
     "@smoothbricks/validation": "0.1.8",
     "commander": "^14.0.3",
     "make-synchronized": "^0.8.0",

package/src/cli.ts

@@ -532,23 +532,46 @@ function buildProgram(): Command {
     .description('Reconcile declared secrets: what Workers need, what workflows pass, what the repository holds');
   secrets
     .command('status')
-    .description('Show every declared secret and refuse when a workflow passes one the repository lacks')
-    .option('--repo <owner/name>', 'repository to read secrets from; defaults to the current checkout')
-    .action(async (options: { repo?: string }) => {
+    .description(
+      'Show every declared secret with the scopes holding it, and refuse when a workflow passes one none has',
+    )
+    .option(
+      '-R, --repo <owner/name|remote>',
+      "repository or remote name; defaults to the current branch's upstream remote",
+    )
+    .option(
+      '--env <environment>',
+      "also read this GitHub Environment; its value takes precedence over the repository's for a job bound to it",
+    )
+    .action(async (options: { repo?: string; env?: string }) => {
       process.exitCode = secretsStatus(await findRepoRoot(), options);
     });
   secrets
-    .command('set <name>')
-    .description('Set one repository secret from a pasted value; the value is read without echo and never logged')
-    .option('--repo <owner/name>', 'repository to set the secret on')
-    .action(async (name: string, options: { repo?: string }) => {
-      process.exitCode = await secretsSet(name, options);
+    .command('set [name]')
+    .description('Set secrets from pasted values; with no name, prompts for every secret the target scope still lacks')
+    .option(
+      '-R, --repo <owner/name|remote>',
+      "repository or remote name; defaults to the current branch's upstream remote",
+    )
+    .option(
+      '--env <environment>',
+      "write into this GitHub Environment; its value takes precedence over the repository's for a job bound to it",
+    )
+    .action(async (name: string | undefined, options: { repo?: string; env?: string }) => {
+      process.exitCode = await secretsSet(await findRepoRoot(), name, options);
     });
   secrets
     .command('sync')
     .description('Push every secret smoo.secrets can fetch locally to the repository')
-    .option('--repo <owner/name>', 'repository to set the secrets on')
-    .action(async (options: { repo?: string }) => {
+    .option(
+      '-R, --repo <owner/name|remote>',
+      "repository or remote name; defaults to the current branch's upstream remote",
+    )
+    .option(
+      '--env <environment>',
+      "write into this GitHub Environment; its value takes precedence over the repository's for a job bound to it",
+    )
+    .action(async (options: { repo?: string; env?: string }) => {
       process.exitCode = await secretsSync(await findRepoRoot(), options);
     });
 

package/src/monorepo/__tests__/ci-workflow.test.ts

@@ -7,6 +7,7 @@ import { readFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { format } from 'prettier';
+import typia from 'typia';
 import type { PackageCargoGitOrigin } from '../../lib/json.js';
 import {
   type CiWorkflowDefinitionOptions,
@@ -898,3 +899,163 @@ describe('renderCiWorkflowYaml with deploy configuration', () => {
     expect(e2eJob).not.toContain('CARGO_REGISTRIES_EXAMPLE_TOKEN');
   });
 });
+
+describe('renderCiWorkflowYaml with cross-built test archives', () => {
+  const darwin = {
+    triple: 'aarch64-apple-darwin',
+    path: 'target/nextest/archive-aarch64-apple-darwin.tar.zst',
+  };
+  const declared = options({
+    runsOn: [...nixosRunsOn],
+    macosRunsOn: ['macos-arm64', 'self-hosted'],
+    crossTestArchives: [darwin],
+  });
+
+  it('renders nothing for a repository that declares no cross archives', () => {
+    const bare = renderCiWorkflowYaml(options({ runsOn: [...nixosRunsOn] }));
+
+    // An empty declaration is the same repository as an absent one: no step, no
+    // job, and above all no renumbering of the steps that were already there.
+    expect(renderCiWorkflowYaml(options({ runsOn: [...nixosRunsOn], crossTestArchives: [] }))).toBe(bare);
+    expect(bare).not.toContain('macos-cross-tests');
+    expect(bare).not.toContain('cross-target test archives');
+    expect(bare).not.toContain('cargo-cross-test');
+  });
+
+  it('builds and uploads each archive in Validate, then executes it in a job that needs Validate', () => {
+    const rendered = renderCiWorkflowYaml(declared);
+    const workflow = typia.assert<{
+      jobs: Record<string, { needs?: string; 'runs-on'?: unknown; 'timeout-minutes'?: number; steps: unknown[] }>;
+    }>(Bun.YAML.parse(rendered));
+    const validate = workflow.jobs.main;
+    const execute = workflow.jobs['macos-cross-tests'];
+
+    expect(execute?.needs).toBe('main');
+    expect(execute?.['runs-on']).toEqual(['macos-arm64', 'self-hosted']);
+    expect(execute?.['timeout-minutes']).toBe(30);
+    // The Linux job COMPILES the darwin binaries; that is what proves the cross
+    // build works at all.
+    expect(rendered).toContain(
+      'run: smoo github-ci nx-run-many --targets "cargo-cross-test-archive-aarch64-apple-darwin"',
+    );
+    expect(JSON.stringify(validate?.steps)).toContain('cross-test-archives-${{ github.run_id }}');
+    // ...and the macOS job only RUNS them: every step is checkout, the shell,
+    // the download, the archive run, or the cache save. Nothing invokes cargo,
+    // a toolchain install, or an SDK.
+    const executeSteps = execute?.steps ?? [];
+    expect(executeSteps).toContainEqual({
+      name: '🧪 Cross-Target Unit Tests',
+      run: 'smoo github-ci nx-run-many --targets "cargo-cross-test-aarch64-apple-darwin"',
+    });
+    const executeText = JSON.stringify(executeSteps);
+    expect(executeText).toContain('cross-test-archives-${{ github.run_id }}');
+    expect(executeText).toContain('actions/download-artifact');
+    expect(executeText).not.toContain('cargo ');
+    expect(executeText).not.toContain('rustup');
+    expect(executeText).not.toContain('cargo-cross-test-archive');
+    expect(executeText).not.toContain('--target build');
+    expect(executeText).not.toContain('SDK');
+  });
+
+  it('reuses the declared cross producer for the archive step, step-scoped', () => {
+    const rendered = renderCiWorkflowYaml(
+      options({
+        ...declared,
+        platformProducer: {
+          kind: 'linux-cross',
+          preflight: 'sh scripts/prepare-macos-sdk.sh',
+          env: { ACME_CROSS: '1', SDKROOT: '${{ runner.temp }}/apple-sdk/MacOSX.sdk' },
+        },
+      }),
+    );
+    const validate = rendered.slice(0, rendered.indexOf('  macos-cross-tests:'));
+
+    expect(validate).toContain('- name: Check cross-platform toolchain prerequisites');
+    expect(validate).toContain('        working-directory: .\n');
+    expect(validate).toContain('          set -euo pipefail\n          sh scripts/prepare-macos-sdk.sh');
+    // Step-scoped, so Validate's host builds stay host builds: the pair appears
+    // once per cross step and never in the job's own env block.
+    expect(validate.match(/ACME_CROSS: "1"/g)).toHaveLength(2);
+    const jobEnv = validate.slice(validate.indexOf('    env:'), validate.indexOf('    steps:'));
+    expect(jobEnv).not.toContain('ACME_CROSS');
+    expect(jobEnv).not.toContain('SDKROOT');
+    // A declared producer with no preflight is a mechanism error at render time.
+    expect(() =>
+      renderCiWorkflowYaml(options({ ...declared, platformProducer: { kind: 'linux-cross', preflight: '  ' } })),
+    ).toThrow('nonempty toolchain preflight');
+  });
+
+  it('numbers the execute job download before the run and keeps the cleanup anchor after both', () => {
+    const execute = crossTestJob(renderCiWorkflowYaml(declared));
+
+    // Checkout 2, setup-devenv 3, download 4, run 5, cleanup 6.
+    expect(execute).toContain('# Step 4\n      - name: 📥 Download cross-target test archives');
+    expect(execute).toContain('# Step 5\n      - name: 🧪 Cross-Target Unit Tests');
+    expect(execute).toContain('# Step 6');
+    expect(execute).toContain('uses: ./.github/actions/save-nix-devenv');
+  });
+
+  it('builds a non-darwin triple without an execution job it has no runner for', () => {
+    const rendered = renderCiWorkflowYaml(
+      options({
+        crossTestArchives: [
+          { triple: 'x86_64-unknown-linux-musl', path: 'target/nextest/archive-x86_64-unknown-linux-musl.tar.zst' },
+        ],
+      }),
+    );
+
+    expect(rendered).toContain(
+      'run: smoo github-ci nx-run-many --targets "cargo-cross-test-archive-x86_64-unknown-linux-musl"',
+    );
+    expect(rendered).not.toContain('macos-cross-tests');
+  });
+
+  it('downloads a nested cargo workspace archive back to the directory its target writes', () => {
+    const execute = crossTestJob(
+      renderCiWorkflowYaml(
+        options({
+          crossTestArchives: [{ ...darwin, path: `packages/ferris/${darwin.path}` }],
+        }),
+      ),
+    );
+
+    expect(execute).toContain('path: packages/ferris/target/nextest');
+  });
+
+  it('refuses declarations the Nx graph could not have produced, at render time', () => {
+    expect(() =>
+      renderCiWorkflowYaml(options({ crossTestArchives: [{ ...darwin, path: 'target/nextest/archive.tar.zst' }] })),
+    ).toThrow('must be a repository-relative target/nextest/archive-aarch64-apple-darwin.tar.zst');
+    expect(() =>
+      renderCiWorkflowYaml(options({ crossTestArchives: [{ ...darwin, path: `../${darwin.path}` }] })),
+    ).toThrow('must stay inside the repository');
+    expect(() =>
+      renderCiWorkflowYaml(
+        options({ crossTestArchives: [{ triple: 'Bad Triple; rm -rf /', path: 'target/nextest/x.tar.zst' }] }),
+      ),
+    ).toThrow('must be a target triple');
+    // Two cargo workspaces cannot share one artifact: upload-artifact roots it
+    // at the least common ancestor, so the restored paths would be wrong for
+    // both. Refuse here rather than on the runner.
+    expect(() =>
+      renderCiWorkflowYaml(
+        options({
+          crossTestArchives: [
+            darwin,
+            { triple: 'x86_64-apple-darwin', path: `packages/ferris/${cargoArchive('x86_64-apple-darwin')}` },
+          ],
+        }),
+      ),
+    ).toThrow('must share one directory');
+  });
+});
+
+function crossTestJob(rendered: string): string {
+  const start = rendered.indexOf('  macos-cross-tests:');
+  expect(start).toBeGreaterThan(-1);
+  return rendered.slice(start);
+}
+
+function cargoArchive(triple: string): string {
+  return `target/nextest/archive-${triple}.tar.zst`;
+}