@smoothbricks/cli 0.10.9 → 0.10.10

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

@@ -232,7 +232,7 @@ describe('publish workflow definition', () => {
     );
     expect(rendered).not.toContain('GITHUB_SHA:');
     expect(finalJob).toContain("needs.linux-release-candidate.outputs.mode != 'none'");
-    expect(finalJob).toContain("inputs.deploy_environment == 'production'");
+    expect(finalJob).toContain("inputs.deploy_stage == 'production'");
     expect(finalJob).toContain("inputs.dry_run != 'true'");
     expect(finalJob).toContain('smoo release publish --bump "${{ inputs.bump }}" --dry-run "${{ inputs.dry_run }}"');
     expect(finalJob).toContain('CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}');
@@ -250,7 +250,7 @@ describe('publish workflow definition', () => {
   it('omits production deploy controls when no production deploy target exists', () => {
     const rendered = renderPublishWorkflowYaml({ repoName: '@smoothbricks/codebase' });
 
-    expect(rendered).not.toContain('deploy_environment');
+    expect(rendered).not.toContain('deploy_stage');
     expect(rendered).not.toContain('Deploy production');
     expect(rendered).not.toContain('nx-deploy');
   });
@@ -258,12 +258,12 @@ describe('publish workflow definition', () => {
   it('renders production deploy controls for repos with production deploy targets', () => {
     const rendered = renderPublishWorkflowYaml({ deploy: true, repoName: '@smoothbricks/codebase' });
 
-    expect(rendered).toContain('deploy_environment:');
+    expect(rendered).toContain('deploy_stage:');
     expect(rendered).toContain('- name: 🚀 Deploy production');
     expect(rendered).not.toContain('CLOUDFLARE_API_TOKEN');
     expect(rendered).not.toContain('CLOUDFLARE_ACCOUNT_ID');
     expect(rendered).toContain(
-      'smoo github-ci nx-deploy --environment production --mode run-many --verify --name "Deploy Production"',
+      'smoo github-ci nx-deploy --stage production --mode run-many --verify --name "Deploy Production"',
     );
   });
 
@@ -284,7 +284,7 @@ describe('publish workflow definition', () => {
       repairs: [],
       current: [],
       bump: 'auto',
-      deployEnvironment: 'production',
+      deployStage: 'production',
       dryRun: false,
       version: { mode: 'new', projects: ['app'] },
     }).run();
@@ -293,7 +293,7 @@ describe('publish workflow definition', () => {
       repairs: [],
       current: [],
       bump: 'auto',
-      deployEnvironment: 'production',
+      deployStage: 'production',
       dryRun: true,
       version: { mode: 'new', projects: ['app'] },
     }).run();
@@ -422,7 +422,7 @@ interface WorkflowScenarioConfig {
   repairs: ReleaseGap[];
   current: ReleaseGap[];
   bump: PublishWorkflowBump;
-  deployEnvironment?: 'none' | 'production';
+  deployStage?: 'none' | 'production';
   dryRun: boolean;
   version: PublishWorkflowVersionOutputs;
 }
@@ -448,7 +448,7 @@ function publishWorkflowScenario(config: WorkflowScenarioConfig): { run(): Promi
     async run() {
       const state = new WorkflowScenarioState(config);
       await runPublishWorkflow(definePublishWorkflow({ deploy: config.deploy, repoName: config.repoName }), {
-        inputs: { bump: config.bump, deployEnvironment: config.deployEnvironment ?? 'none', dryRun: config.dryRun },
+        inputs: { bump: config.bump, deployStage: config.deployStage ?? 'none', dryRun: config.dryRun },
         callbacks: state.callbacks(),
       });
       return state.outcome();

package/src/monorepo/ci-workflow.ts

@@ -8,6 +8,7 @@ export enum CiWorkflowStepKind {
   SetNxShas = 'set-nx-shas',
   RestoreNxCache = 'restore-nx-cache',
   Build = 'build',
+  BrowserTests = 'browser-tests',
   Lint = 'lint',
   UnitTests = 'unit-tests',
   ManagedFilesCheck = 'managed-files-check',
@@ -26,6 +27,8 @@ export interface CiWorkflowStep {
 
 export interface CiWorkflowDefinitionOptions {
   deploy: boolean;
+  browserTests: boolean;
+  e2eDeployment: boolean;
   deployProvider?: 'cloudflare';
   pushBranches: string[];
   /** Default ubuntu-latest when omitted. */
@@ -41,15 +44,20 @@ export function defineCiWorkflow(options: CiWorkflowDefinitionOptions): CiWorkfl
     { kind: CiWorkflowStepKind.SetNxShas, name: '🧭 Set Nx SHAs' },
     { kind: CiWorkflowStepKind.RestoreNxCache, name: '🧠 Restore Nx cache' },
     { kind: CiWorkflowStepKind.Build, name: '🔨 Build' },
-    { kind: CiWorkflowStepKind.Lint, name: '🔍 Lint' },
-    { kind: CiWorkflowStepKind.UnitTests, name: '🧪 Unit Tests' },
-    { kind: CiWorkflowStepKind.ManagedFilesCheck, name: '🩺 Check managed-file drift' },
-    { kind: CiWorkflowStepKind.ManagedFilesDispatch, name: '🔁 Dispatch managed-file drift healing' },
   ];
   if (options.deploy) {
-    steps.push({ kind: CiWorkflowStepKind.Deploy, name: '🚀 Deploy Environment' });
+    steps.push({ kind: CiWorkflowStepKind.Deploy, name: '🚀 Deploy Stage' });
   }
   steps.push(
+    { kind: CiWorkflowStepKind.Lint, name: '🔍 Lint' },
+    { kind: CiWorkflowStepKind.UnitTests, name: '🧪 Unit Tests' },
+  );
+  if (options.browserTests) {
+    steps.push({ kind: CiWorkflowStepKind.BrowserTests, name: '🌐 Browser Tests' });
+  }
+  steps.push(
+    { kind: CiWorkflowStepKind.ManagedFilesCheck, name: '🩺 Check managed-file drift' },
+    { kind: CiWorkflowStepKind.ManagedFilesDispatch, name: '🔁 Dispatch managed-file drift healing' },
     { kind: CiWorkflowStepKind.SaveNxCache, name: '💾 Save Nx cache' },
     { kind: CiWorkflowStepKind.UploadTraceDbs, name: '📎 Upload trace DBs' },
     { kind: CiWorkflowStepKind.SaveNixDevenv, name: '🧹 Cleanup and cache Nix/devenv' },
@@ -59,7 +67,7 @@ export function defineCiWorkflow(options: CiWorkflowDefinitionOptions): CiWorkfl
 
 export function renderCiWorkflowYaml(options: CiWorkflowDefinitionOptions): string {
   const steps = defineCiWorkflow(options);
-  return `${renderCiWorkflowHeader(options)}${renderCiWorkflowSteps(steps, options)}`;
+  return `${renderCiWorkflowHeader(options)}${renderCiWorkflowSteps(steps, options)}${renderE2eDeploymentJob(options)}`;
 }
 
 function renderCiWorkflowHeader(options: CiWorkflowDefinitionOptions): string {
@@ -77,6 +85,10 @@ permissions:
   contents: read
 ${options.deploy ? '  deployments: write\n' : ''}  statuses: write
 
+concurrency:
+  group: \${{ github.workflow }}-\${{ github.ref }}
+  cancel-in-progress: true
+
 defaults:
   run:
     working-directory: tooling/direnv
@@ -86,7 +98,13 @@ jobs:
     name: Validate
 ${renderRunsOnLine(options.runsOn)}
     timeout-minutes: 45
-    env:
+${
+  options.e2eDeployment
+    ? `    outputs:
+      deployment-stage: ${githubExpression('steps.deploy.outputs.stage')}
+`
+    : ''
+}    env:
       NIX_STORE_NAR: ${githubExpression('github.workspace')}/nix-store.nar
       GH_TOKEN: ${githubExpression('github.token')}
     steps:
@@ -169,6 +187,8 @@ function yamlLinesForStep(step: CiWorkflowStep, options: CiWorkflowDefinitionOpt
       return [`      - name: ${step.name}`, '        id: nx-cache', '        uses: ./.github/actions/cache-nx'];
     case CiWorkflowStepKind.Build:
       return nxSmartStep(step, 'build', 'Build');
+    case CiWorkflowStepKind.BrowserTests:
+      return nxSmartStep(step, 'test-browser', 'Browser Tests');
     case CiWorkflowStepKind.Lint:
       return nxSmartStep(step, 'lint', 'Lint');
     case CiWorkflowStepKind.UnitTests:
@@ -197,6 +217,7 @@ function yamlLinesForStep(step: CiWorkflowStep, options: CiWorkflowDefinitionOpt
     case CiWorkflowStepKind.Deploy:
       return [
         `      - name: ${step.name}`,
+        '        id: deploy',
         '        if: >-',
         '          ${{',
         "            (github.event_name == 'pull_request' &&",
@@ -205,7 +226,7 @@ function yamlLinesForStep(step: CiWorkflowStep, options: CiWorkflowDefinitionOpt
         "            (github.event_name == 'push' && github.ref == 'refs/heads/private')",
         '          }}',
         ...deployEnvLines(options),
-        `        run: smoo github-ci nx-deploy --mode run-many --name "Deploy Environment" --step ${step.number}`,
+        `        run: smoo github-ci nx-deploy --mode run-many --name "Deploy Stage" --step ${step.number}`,
       ];
     case CiWorkflowStepKind.SaveNxCache:
       return [
@@ -255,12 +276,6 @@ function deployEnvLines(options: CiWorkflowDefinitionOptions): string[] {
     '        env:',
     '          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}',
     '          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}',
-    '          GITHUB_CLIENT_SECRET: ${{ secrets.GITHUB_CLIENT_SECRET }}',
-    '          GITHUB_APP_PRIVATE_KEY: ${{ secrets.GITHUB_APP_PRIVATE_KEY }}',
-    '          GITHUB_APP_PRIVATE_KEY_PEM: ${{ secrets.GITHUB_APP_PRIVATE_KEY_PEM }}',
-    '          OAUTH_STATE_SIGNING_KEY: ${{ secrets.OAUTH_STATE_SIGNING_KEY }}',
-    '          MAIL_CAPTURE_CONTROL_TOKEN: ${{ secrets.MAIL_CAPTURE_CONTROL_TOKEN }}',
-    '          TOKEN_ENCRYPTION_KEY: ${{ secrets.TOKEN_ENCRYPTION_KEY }}',
   ];
 }
 
@@ -275,3 +290,41 @@ function renderYamlList(values: string[], spaces: number): string {
   const indent = ' '.repeat(spaces);
   return values.map((value) => `${indent}- ${value}`).join('\n');
 }
+
+function renderE2eDeploymentJob(options: CiWorkflowDefinitionOptions): string {
+  if (!options.e2eDeployment) return '';
+  return `
+
+  e2e-deployment:
+    name: Deployment E2E
+    needs: main
+${renderRunsOnLine(options.runsOn)}
+    timeout-minutes: 15
+    if: \${{ needs.main.result == 'success' && needs.main.outputs.deployment-stage != '' }}
+    steps:
+      # Step 1: GitHub adds "Set up job" automatically
+      # Step 2
+      - name: 📥 Checkout
+        uses: actions/checkout@v6.0.2
+        with:
+          filter: blob:none
+          fetch-depth: 0
+
+      # Step 3. Composite action internals do not affect top-level job step anchors.
+      - name: 🧱 Setup Nix/devenv
+        id: setup
+        uses: ./.github/actions/setup-devenv
+
+      # Step 4
+      - name: Deployment E2E
+        run: smoo github-ci nx-smart --target e2e-deployment --mode run-many --stage "\${{ needs.main.outputs.deployment-stage }}" --name "Deployment E2E" --step 4
+
+      # Step 5
+      - name: 🧹 Cleanup and cache Nix/devenv
+        if: always()
+        uses: ./.github/actions/save-nix-devenv
+        with:
+          nix-cache-hit: \${{ steps.setup.outputs.nix-cache-hit }}
+          devenv-cache-hit: \${{ steps.setup.outputs.devenv-cache-hit }}
+`;
+}

package/src/monorepo/managed-files.test.ts

@@ -9,6 +9,7 @@ import { type NxProjects, targetNamesFromProjects } from '../nx/index.js';
 import {
   deployTargetInfoFromProjects,
   extractInlineLocalBlocksForTest,
+  hasExactTargetForTest,
   INLINE_LOCAL_BEGIN,
   INLINE_LOCAL_END,
   LOCAL_SECTION_MARKER,
@@ -128,7 +129,14 @@ describe('managed-file inline local blocks', () => {
   it("reinserting refuses when the anchor no longer appears — never silently drops the repo's customization", () => {
     const fresh = ['a:', '  - one', 'b:'].join('\n'); // '  - two' is gone
     expect(() => reinsertInlineLocalBlocksForTest(fresh, [{ anchor: '  - two', lines: '  - repo-owned' }])).toThrow(
-      /no longer matches/,
+      /matches no line/,
+    );
+  });
+
+  it('reinserting refuses an ambiguous multiply occurring anchor', () => {
+    const fresh = ['anchor', 'middle', 'anchor'].join('\n');
+    expect(() => reinsertInlineLocalBlocksForTest(fresh, [{ anchor: 'anchor', lines: 'repo-owned' }])).toThrow(
+      /matches 2 lines/,
     );
   });
 
@@ -136,8 +144,7 @@ describe('managed-file inline local blocks', () => {
     // Lines that can serve as anchors: non-empty, not a marker, and each drawn
     // from a small alphabet so uniqueness is checkable — the round-trip only
     // holds when an anchor line occurs exactly once in the managed section
-    // (reinsert finds the FIRST occurrence by design, same as the real file
-    // shape: comments/patterns are unique in practice).
+    // because ambiguous anchors are rejected rather than selecting one.
     const linePool = fc.constantFrom('alpha', 'beta', 'gamma', 'delta', 'epsilon', 'zeta');
     fc.assert(
       fc.property(
@@ -205,6 +212,20 @@ describe('nx graph project helpers', () => {
     );
   });
 
+  it('detects browser and deployment E2E targets by exact name only', () => {
+    const exact = targetNamesFromProjects({
+      app: { targets: { 'test-browser': {}, 'e2e-deployment': {} } },
+    });
+    const nearMisses = targetNamesFromProjects({
+      app: { targets: { 'test-browser-extra': {}, 'e2e-deployments': {}, 'pre-e2e-deployment': {} } },
+    });
+
+    expect(hasExactTargetForTest(exact, 'test-browser')).toBe(true);
+    expect(hasExactTargetForTest(exact, 'e2e-deployment')).toBe(true);
+    expect(hasExactTargetForTest(nearMisses, 'test-browser')).toBe(false);
+    expect(hasExactTargetForTest(nearMisses, 'e2e-deployment')).toBe(false);
+  });
+
   it('detects deploy configurations and cloudflare provider from graph nodes', () => {
     expect(deployTargetInfoFromProjects(sampleProjects, 'staging')).toEqual({
       exists: true,
@@ -217,12 +238,12 @@ describe('nx graph project helpers', () => {
     expect(deployTargetInfoFromProjects(sampleProjects, 'preview')).toEqual({ exists: false });
   });
 
-  it('recognizes convention-driven deploy-environment targets without per-environment configurations', () => {
+  it('recognizes convention-driven deploy-stage targets without per-stage configurations', () => {
     const projects: NxProjects = {
       app: {
         targets: {
           deploy: {
-            options: { command: 'smoo wrangler deploy-environment --environment {args.environment}' },
+            options: { command: 'smoo wrangler deploy-stage --stage {args.stage}' },
           },
         },
       },

package/src/monorepo/managed-files.ts

@@ -105,13 +105,15 @@ function reinsertInlineLocalBlocks(content: string, blocks: InlineLocalBlock[]):
   if (blocks.length === 0) return content;
   const lines = content.split('\n');
   for (const block of blocks) {
-    const index = lines.indexOf(block.anchor);
-    if (index === -1) {
+    const matches = lines.flatMap((line, index) => (line === block.anchor ? [index] : []));
+    if (matches.length !== 1) {
+      const reason = matches.length === 0 ? 'no line' : `${matches.length} lines`;
       throw new Error(
-        `${INLINE_LOCAL_BEGIN} block anchored on "${block.anchor}" no longer matches any line in the updated ` +
+        `${INLINE_LOCAL_BEGIN} block anchored on "${block.anchor}" matches ${reason} in the updated ` +
           'template — reconcile the repo-owned block manually',
       );
     }
+    const index = matches[0] as number;
     const markerIndent = block.markerIndent ?? '';
     lines.splice(
       index + 1,
@@ -136,6 +138,8 @@ interface ManagedFileContext {
   hasReleasePackages: boolean;
   hasStagingDeployTargets: boolean;
   hasProductionDeployTargets: boolean;
+  hasBrowserTestTargets: boolean;
+  hasE2eDeploymentTargets: boolean;
   stagingDeployProvider?: 'cloudflare';
   productionDeployProvider?: 'cloudflare';
   ciPushBranches: string[];
@@ -320,6 +324,8 @@ function getManagedContent(file: ManagedFile, context: ManagedFileContext): stri
       return renderCiWorkflowYaml({
         deploy: context.hasStagingDeployTargets,
         deployProvider: context.stagingDeployProvider,
+        browserTests: context.hasBrowserTestTargets,
+        e2eDeployment: context.hasStagingDeployTargets && context.hasE2eDeploymentTargets,
         pushBranches: context.ciPushBranches,
         runsOn: context.ciRunsOn,
       });
@@ -356,7 +362,8 @@ async function getManagedFileContext(root: string): Promise<ManagedFileContext>
   const nxProjects = await loadNxProjects(root);
   const stagingDeploy = deployTargetInfoFromProjects(nxProjects, 'staging');
   const productionDeploy = deployTargetInfoFromProjects(nxProjects, 'production');
-  const platformTargetGlobs = platformTargetGlobsForTest(targetNamesFromProjects(nxProjects));
+  const targetNames = targetNamesFromProjects(nxProjects);
+  const platformTargetGlobs = platformTargetGlobsForTest(targetNames);
   const nodeModulesCacheKey = existsSync(join(root, 'bun.lock'))
     ? `$${"{{ hashFiles('bun.lock', 'package.json', 'packages/*/package.json') }}"}`
     : `$${"{{ hashFiles('bun.lockb', 'package.json', 'packages/*/package.json') }}"}`;
@@ -364,6 +371,8 @@ async function getManagedFileContext(root: string): Promise<ManagedFileContext>
     hasReleasePackages: listReleasePackages(root, packageJson).length > 0,
     hasStagingDeployTargets: stagingDeploy.exists,
     hasProductionDeployTargets: productionDeploy.exists,
+    hasBrowserTestTargets: hasExactTargetForTest(targetNames, 'test-browser'),
+    hasE2eDeploymentTargets: hasExactTargetForTest(targetNames, 'e2e-deployment'),
     stagingDeployProvider: stagingDeploy.provider,
     productionDeployProvider: productionDeploy.provider,
     ciPushBranches,
@@ -374,6 +383,10 @@ async function getManagedFileContext(root: string): Promise<ManagedFileContext>
   };
 }
 
+export function hasExactTargetForTest(targetNames: Iterable<string>, target: string): boolean {
+  return [...targetNames].includes(target);
+}
+
 export function platformTargetGlobsForTest(targetNames: Iterable<string>): string[] {
   const names = [...targetNames];
   return PLATFORM_TARGET_GLOBS.filter((glob) => {
@@ -404,7 +417,7 @@ function deployTargetInfoFromTargets(targets: Record<string, NxTargetConfig>, co
   }
   const baseCommandValue = deploy.options?.command ?? deploy.command;
   const baseCommand = typeof baseCommandValue === 'string' ? baseCommandValue : '';
-  if (baseCommand.includes('smoo wrangler deploy-environment')) {
+  if (baseCommand.includes('smoo wrangler deploy-stage')) {
     return { exists: true, provider: 'cloudflare' };
   }
   const config = deploy.configurations?.[configuration];

package/src/monorepo/publish-workflow.ts

@@ -18,7 +18,7 @@ const PUBLISH_WORKFLOW_FORMAT_OPTIONS = Object.freeze({
 export type PublishWorkflowBump = 'auto' | 'patch' | 'minor' | 'major' | 'prerelease';
 export type PublishWorkflowCondition = 'version-mode-not-none' | 'deploy-production' | 'failure' | 'always';
 export type PublishWorkflowNxTarget = 'build' | 'lint' | 'test';
-export type PublishWorkflowDeployEnvironment = 'none' | 'production';
+export type PublishWorkflowDeployStage = 'none' | 'production';
 
 export enum PublishWorkflowStepKind {
   Checkout = 'checkout',
@@ -62,7 +62,7 @@ export interface PublishWorkflowDefinitionOptions {
 
 export interface PublishWorkflowInputs {
   bump: PublishWorkflowBump;
-  deployEnvironment: PublishWorkflowDeployEnvironment;
+  deployStage: PublishWorkflowDeployStage;
   dryRun: boolean;
 }
 
@@ -263,7 +263,7 @@ function shouldRunStep(
     return version.mode !== 'none';
   }
   if (step.condition === 'deploy-production') {
-    return version.mode !== 'none' && inputs.deployEnvironment === 'production' && !inputs.dryRun;
+    return version.mode !== 'none' && inputs.deployStage === 'production' && !inputs.dryRun;
   }
   if (step.condition === 'failure') {
     return failed;
@@ -291,7 +291,7 @@ function renderPublishWorkflowHeader(options: PublishWorkflowDefinitionOptions):
   const deployInput =
     options.deploy === true
       ? `
-      deploy_environment:
+      deploy_stage:
         type: choice
         description: Deploy live systems after a successful publish.
         options: [none, production]
@@ -483,10 +483,10 @@ function deployProductionStep(step: PublishWorkflowStep, options: PublishWorkflo
   return [
     `      - name: ${step.name}`,
     '        if:',
-    "          ${{ steps.version.outputs.mode != 'none' && inputs.deploy_environment == 'production' && inputs.dry_run !=",
+    "          ${{ steps.version.outputs.mode != 'none' && inputs.deploy_stage == 'production' && inputs.dry_run !=",
     "          'true' }}",
     ...deployEnvLines(options),
-    '        run: smoo github-ci nx-deploy --environment production --mode run-many --verify --name "Deploy Production"',
+    '        run: smoo github-ci nx-deploy --stage production --mode run-many --verify --name "Deploy Production"',
   ];
 }
 
@@ -534,7 +534,7 @@ function renderPlatformPublishWorkflowYaml(options: PublishWorkflowDefinitionOpt
   const deployInput =
     options.deploy === true
       ? `
-      deploy_environment:
+      deploy_stage:
         type: choice
         description: Deploy live systems after a successful publish.
         options: [none, production]
@@ -940,10 +940,10 @@ function renderFinalLinuxPublishSteps(options: PublishWorkflowDefinitionOptions)
       `      # Step ${stepNumber++}`,
       '      - name: 🚀 Deploy production',
       '        if:',
-      "          ${{ needs.linux-release-candidate.outputs.mode != 'none' && inputs.deploy_environment == 'production' &&",
+      "          ${{ needs.linux-release-candidate.outputs.mode != 'none' && inputs.deploy_stage == 'production' &&",
       "          inputs.dry_run != 'true' }}",
       ...deployEnvLines(options),
-      '        run: smoo github-ci nx-deploy --environment production --mode run-many --verify --name "Deploy Production"',
+      '        run: smoo github-ci nx-deploy --stage production --mode run-many --verify --name "Deploy Production"',
     );
   }
   lines.push(

package/src/wrangler/cloudflare.ts

@@ -1,5 +1,5 @@
 import typia from 'typia';
-import type { LiveKvNamespace } from './environment.js';
+import type { LiveKvNamespace } from './stage.js';
 
 export interface R2Bucket {
   name: string;

package/src/wrangler/{deploy-environment.test.ts → deploy-stage.test.ts}

@@ -12,8 +12,8 @@ import type {
   WorkerRoute,
   WorkerScript,
 } from './cloudflare.js';
-import { cleanupPullRequest, deployEnvironment, type ProcessResult, type ProcessRunner } from './deploy-environment.js';
-import type { LiveKvNamespace } from './environment.js';
+import { cleanupPullRequest, deployStage, type ProcessResult, type ProcessRunner } from './deploy-stage.js';
+import type { LiveKvNamespace } from './stage.js';
 
 const HASH = '16577780061662788004';
 const FIXTURE = `[env.staging]
@@ -154,14 +154,14 @@ class FakeCloudflare implements CloudflareClient {
   }
 }
 
-describe('deploy-environment remote version fallback', () => {
+describe('deploy-stage remote version fallback', () => {
   it('returns a remote cache hit for the active tagged 100% version', async () => {
     const root = await fixtureRoot();
     const runner = new FakeRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
       versions: [{ version_id: 'version-1', percentage: 100 }],
     });
 
-    const result = await deployEnvironment(root, 'pr123', dependencies(runner, new FakeCloudflare()));
+    const result = await deployStage(root, 'pr123', dependencies(runner, new FakeCloudflare()));
 
     expect(result.action).toBe('remote-cache-hit');
     expect(runner.calls.map((args) => args.slice(0, 2))).toEqual([
@@ -176,7 +176,7 @@ describe('deploy-environment remote version fallback', () => {
       versions: [{ version_id: 'version-2', percentage: 100 }],
     });
 
-    const result = await deployEnvironment(root, 'pr123', dependencies(runner, new FakeCloudflare()));
+    const result = await deployStage(root, 'pr123', dependencies(runner, new FakeCloudflare()));
 
     expect(result.action).toBe('activated');
     expect(runner.calls.at(-1)?.slice(0, 3)).toEqual(['versions', 'deploy', '--version-tag']);
@@ -189,7 +189,7 @@ describe('deploy-environment remote version fallback', () => {
     await writeFile(join(root, '.dev.vars.example'), 'OAUTH_STATE_SIGNING_KEY=""\nTOKEN_ENCRYPTION_KEY=""\n');
     const runner = new FakeRunner([], { versions: [{ version_id: 'version-2', percentage: 100 }] });
 
-    const result = await deployEnvironment(root, 'pr123', {
+    const result = await deployStage(root, 'pr123', {
       ...dependencies(runner, new FakeCloudflare()),
       processEnv: {
         CLOUDFLARE_ACCOUNT_ID: 'account-1',
@@ -214,13 +214,13 @@ describe('deploy-environment remote version fallback', () => {
     expect(existsSync(requiredTestValue(runner.secretsPathSeen, 'secrets path'))).toBe(false);
   });
 
-  it('passes only present manifest values for fixed environments and preserves absent remote secrets', async () => {
+  it('passes only present manifest values for fixed stages and preserves absent remote secrets', async () => {
     const root = await fixtureRoot();
     await writeFile(join(root, '.dev.vars.example'), 'OAUTH_STATE_SIGNING_KEY=""\nTOKEN_ENCRYPTION_KEY=""\n');
     const runner = new FakeRunner([], {});
     const cloudflare = new FakeCloudflare();
 
-    const result = await deployEnvironment(root, 'staging', {
+    const result = await deployStage(root, 'staging', {
       runner,
       cloudflare,
       processEnv: {
@@ -244,7 +244,7 @@ describe('deploy-environment remote version fallback', () => {
     cloudflare.scripts = [];
 
     await expect(
-      deployEnvironment(root, 'pr123', {
+      deployStage(root, 'pr123', {
         ...dependencies(new FakeRunner([], {}), cloudflare),
         processEnv: {
           CLOUDFLARE_ACCOUNT_ID: 'account-1',
@@ -268,7 +268,7 @@ describe('deploy-environment remote version fallback', () => {
       throw new Error('record already exists');
     };
 
-    const result = await deployEnvironment(root, 'pr123', dependencies(new FakeRunner([], {}), cloudflare));
+    const result = await deployStage(root, 'pr123', dependencies(new FakeRunner([], {}), cloudflare));
 
     expect(result.action).toBe('deployed');
     expect(createAttempts).toBe(1);
@@ -276,7 +276,7 @@ describe('deploy-environment remote version fallback', () => {
   });
 });
 
-describe('cleanup-pr exact environment matching', () => {
+describe('cleanup-pr exact stage matching', () => {
   it('rejects an invalid PR before touching the client', async () => {
     const cloudflare = new FakeCloudflare();
     let calls = 0;