@smoothbricks/cli 0.11.16 → 0.11.18

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smoothbricks/cli",
-  "version": "0.11.16",
+  "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.10",
+    "@smoothbricks/nx-plugin": "0.4.12",
     "@smoothbricks/validation": "0.1.8",
     "commander": "^14.0.3",
     "make-synchronized": "^0.8.0",

package/src/cli.ts

@@ -6,7 +6,9 @@ import { cliPackageVersion } from './lib/cli-package.js';
 import { decode, findRepoRoot, printCommandOutput } from './lib/run.js';
 import { ensureChromium } from './playwright/index.js';
 import { resolvePrConflicts } from './pr/index.js';
+import { secretsSet, secretsStatus, secretsSync } from './secrets/commands.js';
 import { cleanupPullRequest, deployStage } from './wrangler/deploy-stage.js';
+import { deployedVersion } from './wrangler/deployed-version.js';
 import { scaffold } from './wrangler/scaffold.js';
 
 export async function runCli(argv = process.argv.slice(2)): Promise<void> {
@@ -525,6 +527,54 @@ function buildProgram(): Command {
       await ensureChromium();
     });
 
+  const secrets = program
+    .command('secrets')
+    .description('Reconcile declared secrets: what Workers need, what workflows pass, what the repository holds');
+  secrets
+    .command('status')
+    .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 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(
+      '-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);
+    });
+
   const wrangler = program.command('wrangler').description('Cloudflare wrangler project helpers');
   wrangler
     .command('scaffold <project>')
@@ -537,11 +587,29 @@ function buildProgram(): Command {
     .command('deploy-stage')
     .requiredOption('--stage <stage>', 'staging, production, or prN')
     .option('--config <path>', 'deploy a build-generated flat wrangler.json instead of ./wrangler.toml')
-    .action(async (options: { stage: string; config?: string }) => {
+    .option('--version-endpoint <url>', 'URL served by this worker whose trimmed body is the running version tag')
+    .action(async (options: { stage: string; config?: string; versionEndpoint?: string }) => {
       await deployStage(process.cwd(), {
         stage: options.stage,
         ...(options.config ? { config: resolve(options.config) } : {}),
+        ...(options.versionEndpoint ? { versionEndpoint: options.versionEndpoint } : {}),
+      });
+    });
+  wrangler
+    .command('deployed-version')
+    .description('Print the version tag serving all traffic for this project\u2019s worker on a stage')
+    .requiredOption('--stage <stage>', 'staging, production, or prN')
+    .option('--config <path>', 'resolve the worker name from a build-generated flat wrangler.json')
+    .option('--refresh', 'ask Cloudflare even when a fresh cached answer exists')
+    .action(async (options: { stage: string; config?: string; refresh?: boolean }) => {
+      const report = await deployedVersion(process.cwd(), {
+        stage: options.stage,
+        ...(options.config ? { config: resolve(options.config) } : {}),
+        ...(options.refresh ? { refresh: true } : {}),
       });
+      // The tag alone on stdout: this is read by humans and by `$(...)`, and a version deployed
+      // outside Nx genuinely has no tag, which `untagged` says without pretending to be one.
+      console.log(report.versionTag ?? 'untagged');
     });
   wrangler
     .command('cleanup-pr')

package/src/github-ci/index.test.ts

@@ -954,7 +954,7 @@ describe('event-aware stage deployment', () => {
 
   it('deploys app/backend, publishes PR metadata, and emits the resolved stage', async () => {
     const nxCalls: string[][] = [];
-    const listCalls: Array<[string, string, string, string | undefined]> = [];
+    const listCalls: Array<[string, string, string | undefined]> = [];
     const summaries: string[] = [];
     const deployments: Array<[string, string]> = [];
     const outputs: string[] = [];
@@ -975,8 +975,8 @@ describe('event-aware stage deployment', () => {
           repository: { full_name: 'owner/repo' },
           pull_request: { number: 123, head: { repo: { full_name: 'owner/repo' } } },
         },
-        listProjects: async (_root, target, mode, stage, selectTag) => {
-          listCalls.push([target, mode, stage, selectTag]);
+        listProjects: async (_root, mode, stage, selectTag) => {
+          listCalls.push([mode, stage, selectTag]);
           return ['app', 'app-backend'];
         },
         runNx: async (args) => {
@@ -995,7 +995,7 @@ describe('event-aware stage deployment', () => {
       },
     );
 
-    expect(listCalls).toEqual([['deploy', 'run-many', 'pr123', undefined]]);
+    expect(listCalls).toEqual([['run-many', 'pr123', undefined]]);
     expect(nxCalls).toHaveLength(1);
     expect(nxCalls[0]).toContain('--projects=app,app-backend');
     expect(nxCalls[0]).toContain('--exclude=tag:permanent-deploy-target,tag:staging-deploy-target');
@@ -1077,7 +1077,7 @@ describe('event-aware stage deployment', () => {
   });
 
   it('passes --select-tag through to the project selection of the production deploy', async () => {
-    const listCalls: Array<[string, string, string, string | undefined]> = [];
+    const listCalls: Array<[string, string, string | undefined]> = [];
     const nxCalls: string[][] = [];
 
     await githubCiNxDeploy(
@@ -1086,8 +1086,8 @@ describe('event-aware stage deployment', () => {
       {
         processEnv: {},
         setStatus: async () => {},
-        listProjects: async (_root, target, mode, stage, selectTag) => {
-          listCalls.push([target, mode, stage, selectTag]);
+        listProjects: async (_root, mode, stage, selectTag) => {
+          listCalls.push([mode, stage, selectTag]);
           return ['website'];
         },
         runNx: async (args) => {
@@ -1097,7 +1097,7 @@ describe('event-aware stage deployment', () => {
       },
     );
 
-    expect(listCalls).toEqual([['deploy', 'run-many', 'production', 'production-push-deploy-target']]);
+    expect(listCalls).toEqual([['run-many', 'production', 'production-push-deploy-target']]);
     expect(nxCalls).toHaveLength(1);
     expect(nxCalls[0]).toContain('--projects=website');
     expect(nxCalls[0]).toContain('--stage=production');
@@ -1193,6 +1193,90 @@ describe('event-aware stage deployment', () => {
 
     expect(statuses).toEqual(['pending', 'success']);
   });
+
+  it('deploys the whole selection in one run-many, leaving the order to the graph', async () => {
+    const nxCalls: string[][] = [];
+    await githubCiNxDeploy(
+      '/repo',
+      { stage: 'staging' },
+      {
+        processEnv: {},
+        setStatus: async () => {},
+        listProjects: async () => ['app-backend', 'website'],
+        runNx: async (args) => {
+          nxCalls.push(args);
+          return 0;
+        },
+      },
+    );
+    expect(nxCalls.map((args) => args.find((arg) => arg.startsWith('--projects=')))).toEqual([
+      '--projects=app-backend,website',
+    ]);
+    expect(nxCalls[0]).toContain('--stage=staging');
+  });
+
+  it('publishes nothing when the deploy fails', async () => {
+    const statuses: string[] = [];
+    const summaries: string[] = [];
+    const deployments: Array<[string, string]> = [];
+    const outputs: string[] = [];
+    await expect(
+      githubCiNxDeploy(
+        '/repo',
+        { mode: 'run-many' },
+        {
+          processEnv: { GITHUB_EVENT_NAME: 'pull_request', GITHUB_OUTPUT: '/output', GITHUB_STEP_SUMMARY: '/summary' },
+          github: { previewUrls: ['https://app.{stage}.example.com'] },
+          eventPayload: {
+            action: 'opened',
+            repository: { full_name: 'owner/repo' },
+            pull_request: { number: 12, head: { repo: { full_name: 'owner/repo' } } },
+          },
+          setStatus: async (status) => {
+            statuses.push(status);
+          },
+          listProjects: async () => ['app-backend', 'website'],
+          runNx: async () => 1,
+          appendSummary: async (_path, content) => {
+            summaries.push(content);
+          },
+          appendOutput: async (_path, content) => {
+            outputs.push(content);
+          },
+          publishDeployment: async (stage, url) => {
+            deployments.push([stage, url]);
+          },
+        },
+      ),
+    ).rejects.toThrow(/--projects=app-backend,website .*failed with exit code 1/);
+    expect(statuses).toEqual(['pending', 'failure']);
+    expect(outputs).toEqual([]);
+    expect(summaries).toEqual([]);
+    expect(deployments).toEqual([]);
+  });
+
+  it('verifies and deploys the whole selection with one run-many each', async () => {
+    const nxCalls: string[][] = [];
+    await githubCiNxDeploy(
+      '/repo',
+      { stage: 'production', verify: true },
+      {
+        processEnv: {},
+        setStatus: async () => {},
+        listProjects: async () => ['app-backend', 'website'],
+        runNx: async (args) => {
+          nxCalls.push(args);
+          return 0;
+        },
+      },
+    );
+    expect(nxCalls.map((args) => `${args[2]} ${args[3]}`)).toEqual([
+      'build --projects=app-backend,website',
+      'lint --projects=app-backend,website',
+      'test --projects=app-backend,website',
+      'deploy --projects=app-backend,website',
+    ]);
+  });
 });
 
 describe('resolveDeploymentStage with a configured push branch', () => {

package/src/github-ci/index.ts

@@ -338,7 +338,6 @@ export interface GithubCiNxDeployOptions {
 export interface GithubCiNxDeployDependencies {
   listProjects?: (
     root: string,
-    target: string,
     mode: 'affected' | 'run-many',
     stage: DeploymentStage,
     selectTag?: string,
@@ -371,9 +370,9 @@ export async function githubCiNxDeploy(
     ((state: 'pending' | 'success' | 'failure') =>
       state === 'pending' ? createGithubStatus(name, step) : updateGithubStatus(name, state, step));
   const mode = resolveNxSmartMode(options.mode ?? 'run-many');
-  const listProjects = dependencies.listProjects ?? listNxProjectsWithTarget;
+  const listProjects = dependencies.listProjects ?? listNxDeployProjects;
   const runNx = dependencies.runNx ?? ((args: string[], commandRoot: string) => runStatus('nx', args, commandRoot));
-  const projects = await listProjects(root, 'deploy', mode, stage, options.selectTag);
+  const projects = await listProjects(root, mode, stage, options.selectTag);
   if (projects.length === 0) {
     console.log(`No ${mode} deploy projects; skipping ${stage}.`);
     await setStatus('pending');
@@ -387,8 +386,8 @@ export async function githubCiNxDeploy(
     : undefined;
   await setStatus('pending');
 
-  const projectList = projects.join(',');
   const targets = options.verify === true ? ['build', 'lint', 'test', 'deploy'] : ['deploy'];
+  const projectList = projects.join(',');
   for (const target of targets) {
     const nxArgs = [
       'run-many',
@@ -398,6 +397,8 @@ export async function githubCiNxDeploy(
       `--exclude=${deployExclusions(stage)}`,
       `--parallel=${NX_PARALLEL}`,
     ];
+    // Deploy ordering is a `dependsOn` edge in the project graph, not a second round here: one run-many
+    // already sequences any depth of `a:deploy -> b:deploy -> c:deploy`.
     if (target === 'deploy') {
       nxArgs.push(`--stage=${stage}`);
     }
@@ -540,22 +541,18 @@ function previewUrlFromTemplate(template: string, stage: string): string {
   return template.replaceAll('{stage}', stage);
 }
 
-async function listNxProjectsWithTarget(
+async function listNxDeployProjects(
   root: string,
-  target: string,
   mode: 'affected' | 'run-many',
   stage: DeploymentStage,
   selectTag?: string,
 ): Promise<string[]> {
   const listArgs = ['show', 'projects'];
   if (mode === 'affected') listArgs.push('--affected');
-  listArgs.push('--withTarget', target);
-  if (target === 'deploy') listArgs.push(`--exclude=${deployExclusions(stage)}`);
-  listArgs.push('--json');
+  listArgs.push('--withTarget', 'deploy', `--exclude=${deployExclusions(stage)}`, '--json');
   const candidates = nxProjectList(await runText('nx', listArgs, root)).sort((left, right) =>
     left.localeCompare(right),
   );
-  if (target !== 'deploy') return candidates;
   return selectStageDeployProjects(candidates, stage, selectTag, async (project) => {
     const parsed = parseNxProjectDeployTarget(await runText('nx', ['show', 'project', project, '--json'], root));
     if (!parsed) throw new Error(`nx show project ${project} returned invalid JSON.`);

package/src/lib/secret-names.ts

@@ -0,0 +1,70 @@
+/**
+ * One rule for naming the repository secret behind an environment variable, so
+ * the workflow renderer, the reconciler and an operator all derive the same
+ * name instead of maintaining a map.
+ *
+ * GitHub refuses to create a secret whose name starts with `GITHUB_` (hence
+ * `RepositorySecretName`'s pattern), which is why a Worker's
+ * `GITHUB_CLIENT_SECRET` cannot be stored under its own name. Prefixing with
+ * the repository owner is the workaround operators already reach for by hand
+ * (`ACME_GITHUB_CLIENT_SECRET` for `acme/app`); making it the convention means
+ * nothing has to declare it.
+ */
+
+/** Names GitHub reserves: it rejects `gh secret set GITHUB_*` outright. */
+export function isReservedRepositorySecretName(envName: string): boolean {
+  return /^GITHUB_/i.test(envName);
+}
+
+/**
+ * The repository secret an env name lives in. Identity for every name GitHub
+ * accepts; owner-prefixed for the reserved ones. `owner` comes from the
+ * repository URL, so a fork or a rename derives its own names rather than
+ * inheriting a hardcoded prefix.
+ */
+export function conventionalRepositorySecretName(envName: string, owner: string): string {
+  if (!isReservedRepositorySecretName(envName)) return envName;
+  const prefix = owner
+    .replace(/[^A-Za-z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .toUpperCase();
+  if (prefix.length === 0) {
+    throw new Error(
+      `Cannot derive a repository secret name for ${envName}: GitHub reserves the GITHUB_ prefix and the repository owner is empty.`,
+    );
+  }
+  return `${prefix}_${envName}`;
+}
+
+/**
+ * Resolve the whole env -> secret mapping for a set of declared env names.
+ * Explicit entries win: an exception stays expressible, but a repository that
+ * follows the convention declares nothing.
+ */
+export function repositorySecretMapping(
+  envNames: readonly string[],
+  owner: string,
+  declared: Readonly<Record<string, string>> = {},
+): Record<string, string> {
+  const mapping: Record<string, string> = {};
+  for (const envName of [...envNames].sort((left, right) => left.localeCompare(right))) {
+    mapping[envName] = declared[envName] ?? conventionalRepositorySecretName(envName, owner);
+  }
+  for (const [envName, secretName] of Object.entries(declared)) {
+    mapping[envName] = secretName;
+  }
+  return mapping;
+}
+
+/**
+ * Repository owner from a repository URL — `acme` from
+ * `https://github.com/acme/app.git`, and the same for an ssh or forge
+ * URL. The owner is derived rather than configured so a fork or a rename
+ * carries its own prefix instead of inheriting one.
+ */
+export function repositoryOwnerFromUrl(url: string): string | null {
+  const withoutProtocol = url.replace(/^[a-z+]+:\/\//i, '').replace(/^git@/i, '');
+  const path = withoutProtocol.replace(/^[^/:]+[/:]/, '');
+  const owner = path.split('/')[0];
+  return owner && owner.length > 0 ? owner.replace(/\.git$/i, '') : null;
+}

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

@@ -6,6 +6,8 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 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,
@@ -396,9 +398,9 @@ describe('CI workflow definition', () => {
     for (const sshOrigins of [
       [],
       // scp syntax is not a URL prefix git can rewrite from a Cargo pin.
-      ['forgejo@forge.example.net:axe/minigraf.git'],
+      ['forgejo@forge.example.net:acme/widgets.git'],
       // A path would rewrite one repository, not the forge.
-      ['ssh://forge.example.net:2223/axe/minigraf.git'],
+      ['ssh://forge.example.net:2223/acme/widgets.git'],
       // A password in a declared origin is a secret in package.json.
       ['ssh://forgejo:hunter2@forge.example.net:2223/'],
       ['https://git.example.net/'],
@@ -769,6 +771,30 @@ describe('renderCiWorkflowYaml with deploy configuration', () => {
     expect(productionJob).not.toContain('needs.e2e-deployment');
   });
 
+  it('renders a production job the repository Prettier config keeps byte for byte', async () => {
+    const withoutE2e = renderCiWorkflowYaml(
+      options({ deploy: true, deployProvider: 'cloudflare', pushBranches: ['trunk'], productionOnPush: true }),
+    );
+    for (const workflow of [rendered, withoutE2e]) {
+      const productionJob = workflow.slice(workflow.indexOf('  deploy-production:'));
+      expect(productionJob).toContain('    # prettier-ignore\n    if: ${{ !cancelled() ');
+      expect(productionJob).toContain(
+        '        # prettier-ignore\n        run: smoo github-ci nx-deploy --stage production ',
+      );
+      // A consuming repo's commit hook formats staged YAML with Prettier; a rewrapped line reads as drift forever.
+      await expect(
+        format(workflow, { parser: 'yaml', printWidth: 120, proseWrap: 'always', singleQuote: true }),
+      ).resolves.toBe(workflow);
+    }
+  });
+
+  it('cancels superseded pushes when the workflow has no deploy job to protect', () => {
+    const validateOnly = renderCiWorkflowYaml(options());
+
+    expect(validateOnly).toContain('cancel-in-progress: true');
+    expect(validateOnly).not.toContain("cancel-in-progress: ${{ github.ref != 'refs/heads/main' }}");
+  });
+
   it('keeps a protected staging environment off CI runs that do not deploy', () => {
     const validateOnly = renderCiWorkflowYaml(options({ environments: { staging: 'staging' } }));
 
@@ -873,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`;
+}