@smoothbricks/cli 0.11.15 → 0.11.17

package/src/wrangler/deploy-stage.test.ts

@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it } from 'bun:test';
-import { existsSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, mkdtempSync, readFileSync, statSync } from 'node:fs';
 import { mkdir, mkdtemp, readdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -22,6 +22,12 @@ import {
   type ProcessRunOptions,
   writeTemporaryConfigForTest,
 } from './deploy-stage.js';
+import {
+  type FetchLike,
+  findVersionIdByTag,
+  LIVE_VERSION_CACHE_TTL_MS,
+  readCachedLiveVersion,
+} from './live-version.js';
 import type { LiveKvNamespace } from './stage.js';
 
 const HASH = '16577780061662788004';
@@ -58,19 +64,49 @@ class FakeRunner implements ProcessRunner {
   secretsJson: string | undefined;
   /** Runs before the fake reports success, so a test can read a temporary file the command was handed. */
   onCall: ((args: string[], cwd: string) => Promise<void>) | undefined;
+  /**
+   * How many `deployments status` reads still answer with the OLD version after a traffic shift.
+   * This is the whole point of the fake: Cloudflare accepts the shift before it serves it.
+   */
+  propagationPolls = 0;
+
+  private pendingVersionId: string | null = null;
 
   constructor(
-    private readonly versions: unknown = [],
-    private readonly deployment: unknown = {},
+    private versions: unknown = [],
+    private deployment: unknown = {},
   ) {}
 
+  /** The versions payload as a growable list, so an upload can add the version it just created. */
+  private versionList(): unknown[] {
+    const list: unknown[] = Array.isArray(this.versions) ? this.versions : [this.versions];
+    this.versions = list;
+    return list;
+  }
+
+  private shiftTrafficTo(versionId: string): void {
+    this.pendingVersionId = versionId;
+  }
+
+  private readDeployment(): unknown {
+    if (this.pendingVersionId !== null) {
+      if (this.propagationPolls > 0) {
+        this.propagationPolls -= 1;
+      } else {
+        this.deployment = { versions: [{ version_id: this.pendingVersionId, percentage: 100 }] };
+        this.pendingVersionId = null;
+      }
+    }
+    return this.deployment;
+  }
+
   async run(command: string, args: string[], options: ProcessRunOptions): Promise<ProcessResult> {
     this.calls.push({ command, args, cwd: options.cwd, env: childEnvironment(options) });
     if (args[0] === 'versions' && args[1] === 'list') {
       return success(this.versions);
     }
     if (args[0] === 'deployments' && args[1] === 'status') {
-      return success(this.deployment);
+      return success(this.readDeployment());
     }
     const configIndex = args.indexOf('--config');
     if (configIndex >= 0) {
@@ -84,6 +120,21 @@ class FakeRunner implements ProcessRunner {
       this.secretsMode = statSync(secretsPath).mode & 0o777;
       this.secretsJson = readFileSync(secretsPath, 'utf8');
     }
+    if (args[0] === 'versions' && args[1] === 'deploy') {
+      // Resolved with the same reader the deploy uses, so the fake cannot agree with a lookup
+      // production would miss.
+      const tag = args[args.indexOf('--version-tag') + 1];
+      const existing = tag ? findVersionIdByTag(this.versions, tag) : null;
+      if (existing) this.shiftTrafficTo(existing);
+    }
+    if (args[0] === 'deploy') {
+      const tagIndex = args.indexOf('--tag');
+      if (tagIndex >= 0) {
+        const versionId = `uploaded-${args[tagIndex + 1]}`;
+        this.versionList().push({ id: versionId, annotations: { 'workers/tag': args[tagIndex + 1] } });
+        this.shiftTrafficTo(versionId);
+      }
+    }
     await this.onCall?.(args, options.cwd);
     return success({});
   }
@@ -179,8 +230,8 @@ class FakeCloudflare implements CloudflareClient {
   }
 }
 
-describe('deploy-stage remote version fallback', () => {
-  it('returns a remote cache hit for the active tagged 100% version', async () => {
+describe('deploy-stage against live state', () => {
+  it('uploads nothing and shifts no traffic when the live version already is the task hash', async () => {
     const root = await fixtureRoot();
     const runner = new FakeRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
       versions: [{ version_id: 'version-1', percentage: 100 }],
@@ -189,14 +240,17 @@ describe('deploy-stage remote version fallback', () => {
     const result = await deployStage(root, { stage: 'pr123' }, dependencies(runner, new FakeCloudflare()));
 
     expect(result.action).toBe('remote-cache-hit');
+    // Two reads and nothing else. This is what makes a redundant deploy — the one a cross-project
+    // `dependsOn` edge adds — provably free instead of assumed free.
     expect(runner.calls.map((call) => call.args.slice(0, 2))).toEqual([
       ['versions', 'list'],
       ['deployments', 'status'],
     ]);
   });
 
-  it('activates an existing tagged version that is not current', async () => {
+  it('redeploys after a rollback, when the live version is no longer the task hash', async () => {
     const root = await fixtureRoot();
+    // The build for this hash is still uploaded; someone rolled traffic back to the older version.
     const runner = new FakeRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
       versions: [{ version_id: 'version-2', percentage: 100 }],
     });
@@ -204,11 +258,108 @@ describe('deploy-stage remote version fallback', () => {
     const result = await deployStage(root, { stage: 'pr123' }, dependencies(runner, new FakeCloudflare()));
 
     expect(result.action).toBe('activated');
-    expect(runner.calls.at(-1)?.args.slice(0, 3)).toEqual(['versions', 'deploy', '--version-tag']);
-    expect(runner.configPathSeen).toBeDefined();
+    const shiftIndex = runner.calls.findIndex((call) => call.args[0] === 'versions' && call.args[1] === 'deploy');
+    expect(runner.calls[shiftIndex]?.args.slice(0, 4)).toEqual(['versions', 'deploy', '--version-tag', `nx-${HASH}`]);
+    // And the step does not return until it has read live state again after that shift.
+    expect(runner.calls.slice(shiftIndex + 1).some((call) => call.args[0] === 'deployments')).toBe(true);
     expect(existsSync(requiredTestValue(runner.configPathSeen, 'config path'))).toBe(false);
   });
 
+  it('waits out propagation before reporting the deploy done', async () => {
+    const root = await fixtureRoot();
+    const runner = new FakeRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
+      versions: [{ version_id: 'version-2', percentage: 100 }],
+    });
+    runner.propagationPolls = 3;
+
+    const result = await deployStage(root, { stage: 'pr123' }, dependencies(runner, new FakeCloudflare()));
+
+    expect(result.action).toBe('activated');
+    const statusReads = runner.calls.filter((call) => call.args[0] === 'deployments').length;
+    expect(statusReads).toBe(5);
+  });
+
+  it('fails with what it expected and what it saw when the version never becomes live', async () => {
+    const root = await fixtureRoot();
+    const runner = new FakeRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
+      versions: [{ version_id: 'version-2', percentage: 100 }],
+    });
+    runner.propagationPolls = Number.POSITIVE_INFINITY;
+
+    await expect(deployStage(root, { stage: 'pr123' }, dependencies(runner, new FakeCloudflare()))).rejects.toThrow(
+      `fixture-worker-pr123: deployed version nx-${HASH} was not serving traffic after 10s; live is an untagged version (version-2)`,
+    );
+  });
+
+  it('leaves the cache holding the tag it made live, so the next query needs no API call', async () => {
+    const root = await fixtureRoot();
+    const cacheDirectory = await mkdtemp(join(tmpdir(), 'smoo-live-version-'));
+    roots.push(cacheDirectory);
+    const runner = new FakeRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
+      versions: [{ version_id: 'version-2', percentage: 100 }],
+    });
+
+    await deployStage(
+      root,
+      { stage: 'pr123' },
+      { ...dependencies(runner, new FakeCloudflare()), liveVersionCacheDirectory: cacheDirectory },
+    );
+
+    const cached = await readCachedLiveVersion(
+      cacheDirectory,
+      { accountId: 'account-1', workerName: 'fixture-worker-pr123', stage: 'pr123' },
+      LIVE_VERSION_CACHE_TTL_MS,
+    );
+    expect(cached).toMatchObject({ versionTag: `nx-${HASH}`, versionId: 'version-1' });
+  });
+
+  it('is not done until a declared version endpoint answers with the new tag', async () => {
+    const root = await fixtureRoot();
+    const runner = new FakeRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
+      versions: [{ version_id: 'version-2', percentage: 100 }],
+    });
+    const bodies = [`nx-${'0'.repeat(20)}`, `nx-${'0'.repeat(20)}`, `nx-${HASH}`];
+    const requested: string[] = [];
+    const stubFetch: FetchLike = async (input) => {
+      requested.push(String(input));
+      return new Response(bodies.shift() ?? `nx-${HASH}`);
+    };
+
+    const result = await deployStage(
+      root,
+      { stage: 'pr123', versionEndpoint: 'https://fixture.example.test/__version' },
+      {
+        ...dependencies(runner, new FakeCloudflare()),
+        wait: { ...fakeWait(), fetch: stubFetch },
+      },
+    );
+
+    expect(result.action).toBe('activated');
+    expect(requested).toEqual([
+      'https://fixture.example.test/__version',
+      'https://fixture.example.test/__version',
+      'https://fixture.example.test/__version',
+    ]);
+  });
+
+  it('fails naming the endpoint answer when the edge never reports the new tag', async () => {
+    const root = await fixtureRoot();
+    const runner = new FakeRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
+      versions: [{ version_id: 'version-2', percentage: 100 }],
+    });
+    const stubFetch: FetchLike = async () => new Response('nx-previous');
+
+    await expect(
+      deployStage(
+        root,
+        { stage: 'pr123', versionEndpoint: 'https://fixture.example.test/__version' },
+        { ...dependencies(runner, new FakeCloudflare()), wait: { ...fakeWait(), fetch: stubFetch } },
+      ),
+    ).rejects.toThrow(
+      `fixture-worker-pr123: https://fixture.example.test/__version did not report version nx-${HASH} after 10s; it reported nx-previous`,
+    );
+  });
+
   it('uploads a missing tag with a temporary config and secure secrets file, then removes both', async () => {
     const root = await fixtureRoot();
     await writeFile(join(root, '.dev.vars.example'), 'FIXTURE_SECRET=""\nFIXTURE_TOKEN=""\n');
@@ -231,9 +382,12 @@ describe('deploy-stage remote version fallback', () => {
     );
 
     expect(result.action).toBe('deployed');
-    expect(runner.calls.at(-1)?.args[0]).toBe('deploy');
-    expect(runner.calls.at(-1)?.args).toContain('--tag');
-    expect(runner.calls.at(-1)?.args).toContain(`nx-${HASH}`);
+    const upload = requiredTestValue(
+      runner.calls.find((call) => call.args[0] === 'deploy'),
+      'upload call',
+    );
+    expect(upload.args).toContain('--tag');
+    expect(upload.args).toContain(`nx-${HASH}`);
     expect(runner.secretsMode).toBe(0o600);
     expect(JSON.parse(requiredTestValue(runner.secretsJson, 'secrets JSON'))).toEqual({
       FIXTURE_SECRET: 'shared-secret',
@@ -615,6 +769,10 @@ describe('deployStage with a flat JSON config', () => {
       ['deployments', 'status'],
       ['d1', 'migrations'],
       ['versions', 'deploy'],
+      // The traffic shift is not the end of the deploy: the step re-reads live state and only
+      // returns once the tag it activated is the one being served.
+      ['deployments', 'status'],
+      ['versions', 'list'],
     ]);
   });
 
@@ -736,10 +894,30 @@ async function fixtureRoot(toml = FIXTURE): Promise<string> {
   return root;
 }
 
+/**
+ * A wait whose clock only advances when the code under test sleeps: real bounds, no real seconds,
+ * and a deterministic poll count a test can assert on.
+ */
+function fakeWait(): { budgetMs: number; intervalMs: number; now: () => number; sleep: (ms: number) => Promise<void> } {
+  let clock = 0;
+  return {
+    budgetMs: 10_000,
+    intervalMs: 1_000,
+    now: () => clock,
+    sleep: async (ms: number) => {
+      clock += ms;
+    },
+  };
+}
+
 function dependencies(runner: ProcessRunner, cloudflare: CloudflareClient) {
+  const cacheDirectory = mkdtempSync(join(tmpdir(), 'smoo-live-version-'));
+  roots.push(cacheDirectory);
   return {
     runner,
     cloudflare,
+    wait: fakeWait(),
+    liveVersionCacheDirectory: cacheDirectory,
     processEnv: {
       CLOUDFLARE_ACCOUNT_ID: 'account-1',
       CLOUDFLARE_API_TOKEN: 'token',

package/src/wrangler/deploy-stage.ts

@@ -2,11 +2,20 @@ import { randomUUID } from 'node:crypto';
 import { existsSync, readFileSync } from 'node:fs';
 import { readFile, rm, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
-import typia from 'typia';
 import { parseJsonFileText } from '../lib/json.js';
 import { mergeEnv, printCommandOutput } from '../lib/run.js';
 import { type CloudflareClient, CloudflareRestClient, type D1DatabaseRecord } from './cloudflare.js';
 import { type FlatWranglerConfig, parseFlatWranglerConfig, planFlatStageResources } from './flat-config.js';
+import {
+  awaitLiveVersion,
+  awaitVersionEndpoint,
+  currentDeploymentVersionId,
+  findVersionIdByTag,
+  type LiveVersionProbe,
+  liveVersionCacheDirectory,
+  type VersionEndpointWaitOptions,
+  writeCachedLiveVersion,
+} from './live-version.js';
 import { parseDevVarsExample } from './prepare-env.js';
 import {
   type ConfiguredStageResourcePlan,
@@ -69,6 +78,10 @@ export interface WranglerCommandDependencies {
   runner?: ProcessRunner;
   cloudflare?: CloudflareClient;
   processEnv?: NodeJS.ProcessEnv;
+  /** Bounds and clock for the post-deploy wait; tests drive it without sleeping. */
+  wait?: VersionEndpointWaitOptions;
+  /** Where a successful deploy records the tag it made live, for `smoo wrangler deployed-version`. */
+  liveVersionCacheDirectory?: string;
 }
 
 export interface DeployStageResult {
@@ -78,13 +91,17 @@ export interface DeployStageResult {
   versionTag?: string;
 }
 
-const isUnknownRecord = typia.createIs<Record<string, unknown>>();
-
 export interface DeployStageOptions {
   /** `staging`, `production`, or `prN`. */
   stage: string;
   /** A build-generated flat wrangler.json to deploy instead of `./wrangler.toml` (see `prepareFlatConfig`). */
   config?: string;
+  /**
+   * A URL, served by this worker, whose trimmed body is the running version tag. When given, the
+   * deploy is not done until that URL answers with the tag it just made live — the control plane
+   * accepting a traffic shift is not the edge serving it.
+   */
+  versionEndpoint?: string;
 }
 
 export async function deployStage(
@@ -124,16 +141,24 @@ export async function deployStage(
     // `reconcileStageResources` nor `versions list` looks at.
     const run: ProcessRunOptions = prepared.envFlag ? { cwd } : { cwd, unsetEnv: ['CLOUDFLARE_ENV'] };
     const workerName = prepared.plan.workerName;
+    const probe: LiveVersionProbe = {
+      deployments: () => wranglerJson(runner, ['deployments', 'status', '--name', workerName, '--json'], run),
+      versions: () => wranglerJson(runner, ['versions', 'list', '--name', workerName, '--json'], run),
+    };
 
     // The tagged-version lookup runs before the migrations: a cache hit means this exact build is
     // already live, so its migrations ran with it and re-applying them would touch the remote
     // database for nothing. The activation and upload paths below still migrate first.
+    //
+    // This reads Cloudflare every time and never the local cache. A cache hit here would mean
+    // "we believe this hash is live" — exactly the belief a rollback falsifies — and believing it
+    // would skip the deploy that repairs the rollback. Reading live state is what makes a
+    // redundant deploy a proven no-op instead of an assumed one, which is in turn what makes a
+    // cross-project `dependsOn: ["<other>:deploy"]` edge cheap enough to be the ordering mechanism.
     let taggedVersionId: string | null = null;
     if (versionTag && workerExists) {
-      const versions = await wranglerJson(runner, ['versions', 'list', '--name', workerName, '--json'], run);
-      const deployments = await wranglerJson(runner, ['deployments', 'status', '--name', workerName, '--json'], run);
-      taggedVersionId = findVersionIdByTag(versions, versionTag);
-      if (taggedVersionId && isFullCurrentDeployment(deployments, taggedVersionId)) {
+      taggedVersionId = findVersionIdByTag(await probe.versions(), versionTag);
+      if (taggedVersionId && currentDeploymentVersionId(await probe.deployments()) === taggedVersionId) {
         return { stage, workerName, action: 'remote-cache-hit', versionTag };
       }
     }
@@ -163,6 +188,7 @@ export async function deployStage(
         ],
         run,
       );
+      await confirmVersionIsLive(probe, versionTag, { stage, workerName, accountId }, options, dependencies, cwd);
       return { stage, workerName, action: 'activated', versionTag };
     }
 
@@ -174,6 +200,9 @@ export async function deployStage(
       deployArgs.push('--secrets-file', temporarySecretsPath);
     }
     await wrangler(runner, deployArgs, run);
+    if (versionTag) {
+      await confirmVersionIsLive(probe, versionTag, { stage, workerName, accountId }, options, dependencies, cwd);
+    }
     return { stage, workerName, action: 'deployed', ...(versionTag ? { versionTag } : {}) };
   } finally {
     if (temporaryConfigPath) {
@@ -578,49 +607,47 @@ export function nxTaskVersionTag(environment: NodeJS.ProcessEnv): string | undef
   throw new Error('NX_TASK_HASH must be canonical decimal digits or at least 32 hexadecimal characters.');
 }
 
-export function findVersionIdByTag(value: unknown, tag: string): string | null {
-  if (Array.isArray(value)) {
-    for (const entry of value) {
-      const found = findVersionIdByTag(entry, tag);
-      if (found) return found;
-    }
-    return null;
-  }
-  if (!isUnknownRecord(value)) return null;
-  const annotations = isUnknownRecord(value.annotations) ? value.annotations : undefined;
-  const metadata = isUnknownRecord(value.metadata) ? value.metadata : undefined;
-  const annotationTag = annotations?.['workers/tag'];
-  const candidateTag =
-    typeof annotationTag === 'string' ? annotationTag : typeof value.tag === 'string' ? value.tag : metadata?.tag;
-  if (candidateTag === tag) {
-    if (typeof value.id === 'string') return value.id;
-    if (typeof value.version_id === 'string') return value.version_id;
-  }
-  for (const nested of Object.values(value)) {
-    const found = findVersionIdByTag(nested, tag);
-    if (found) return found;
-  }
-  return null;
+/** What a freshly activated version has to be true of, and where the fact gets recorded. */
+interface DeployedVersionIdentity {
+  stage: DeploymentStage;
+  workerName: string;
+  accountId: string;
 }
 
-export function isFullCurrentDeployment(value: unknown, versionId: string): boolean {
-  if (Array.isArray(value)) return value.some((entry) => isFullCurrentDeployment(entry, versionId));
-  if (!isUnknownRecord(value)) return false;
-  if (Array.isArray(value.versions)) {
-    return (
-      value.versions.length === 1 &&
-      value.versions.some(
-        (version) =>
-          isUnknownRecord(version) &&
-          (version.version_id === versionId || version.id === versionId) &&
-          Number(version.percentage) === 100,
-      )
-    );
+/**
+ * Turns "Cloudflare accepted the traffic shift" into "the new version answers".
+ *
+ * Without this the deploy step goes green while the edge still serves the previous version — the
+ * measured gap was about 20 s — so anything ordered after this deploy could call into code that
+ * has not shipped yet. The wait is what a `dependsOn: ["<other>:deploy"]` edge actually buys; an
+ * edge onto a step that returns early orders nothing.
+ */
+async function confirmVersionIsLive(
+  probe: LiveVersionProbe,
+  versionTag: string,
+  identity: DeployedVersionIdentity,
+  options: DeployStageOptions,
+  dependencies: WranglerCommandDependencies,
+  cwd: string,
+): Promise<void> {
+  const wait = dependencies.wait ?? {};
+  const live = await awaitLiveVersion(probe, versionTag, wait);
+  if (!live.ok) throw new Error(`${identity.workerName}: ${live.error.message}`);
+  if (options.versionEndpoint) {
+    const answered = await awaitVersionEndpoint(options.versionEndpoint, versionTag, wait);
+    if (!answered.ok) throw new Error(`${identity.workerName}: ${answered.error.message}`);
   }
-  return Object.values(value).some((entry) => isFullCurrentDeployment(entry, versionId));
+  const processEnv = dependencies.processEnv ?? process.env;
+  const directory = dependencies.liveVersionCacheDirectory ?? liveVersionCacheDirectory(cwd, processEnv);
+  await writeCachedLiveVersion(
+    directory,
+    { accountId: identity.accountId, workerName: identity.workerName, stage: identity.stage },
+    { versionTag, versionId: live.value.versionId, fetchedAt: Date.now() },
+  );
 }
 
-async function wranglerJson(runner: ProcessRunner, args: string[], run: ProcessRunOptions): Promise<unknown> {
+/** One wrangler invocation whose stdout must be JSON; shared by the deploy and the read-only query. */
+export async function wranglerJson(runner: ProcessRunner, args: string[], run: ProcessRunOptions): Promise<unknown> {
   const result = await wrangler(runner, args, run);
   try {
     return JSON.parse(result.stdout);

package/src/wrangler/deployed-version.test.ts

@@ -0,0 +1,150 @@
+import { afterEach, describe, expect, it } from 'bun:test';
+import { existsSync } from 'node:fs';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import type { ProcessResult, ProcessRunner, ProcessRunOptions } from './deploy-stage.js';
+import { deployedVersion } from './deployed-version.js';
+import { LIVE_VERSION_CACHE_TTL_MS, liveVersionCachePath, writeCachedLiveVersion } from './live-version.js';
+
+const HASH = '16577780061662788004';
+const FIXTURE = `[env.staging]
+name = "fixture-worker-staging"
+workers_dev = false
+
+[env.staging.vars]
+ENVIRONMENT = "staging"
+`;
+
+const roots: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })));
+});
+
+class RecordingRunner implements ProcessRunner {
+  readonly calls: string[][] = [];
+
+  constructor(
+    private readonly versions: unknown = [{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }],
+    private readonly deployment: unknown = { versions: [{ version_id: 'version-1', percentage: 100 }] },
+  ) {}
+
+  async run(_command: string, args: string[], _options: ProcessRunOptions): Promise<ProcessResult> {
+    this.calls.push(args);
+    const value = args[0] === 'versions' && args[1] === 'list' ? this.versions : this.deployment;
+    return { exitCode: 0, stdout: JSON.stringify(value), stderr: '' };
+  }
+}
+
+async function fixture(): Promise<{ root: string; cacheDirectory: string }> {
+  const root = await mkdtemp(join(tmpdir(), 'smoo-deployed-version-'));
+  roots.push(root);
+  await writeFile(join(root, 'wrangler.toml'), FIXTURE);
+  return { root, cacheDirectory: join(root, 'cache') };
+}
+
+const credentials = { CLOUDFLARE_ACCOUNT_ID: 'account-1', CLOUDFLARE_API_TOKEN: 'token' };
+
+describe('smoo wrangler deployed-version', () => {
+  it('reports the tag serving all traffic and remembers it', async () => {
+    const { root, cacheDirectory } = await fixture();
+    const runner = new RecordingRunner();
+
+    const report = await deployedVersion(
+      root,
+      { stage: 'staging' },
+      { runner, processEnv: credentials, cacheDirectory },
+    );
+
+    expect(report).toMatchObject({
+      workerName: 'fixture-worker-staging',
+      versionTag: `nx-${HASH}`,
+      source: 'cloudflare',
+    });
+    expect(runner.calls.map((args) => args.slice(0, 2))).toEqual([
+      ['deployments', 'status'],
+      ['versions', 'list'],
+    ]);
+  });
+
+  it('answers a second query from the cache without calling wrangler at all', async () => {
+    const { root, cacheDirectory } = await fixture();
+    const first = new RecordingRunner();
+    await deployedVersion(root, { stage: 'staging' }, { runner: first, processEnv: credentials, cacheDirectory });
+
+    const second = new RecordingRunner();
+    const report = await deployedVersion(
+      root,
+      { stage: 'staging' },
+      { runner: second, processEnv: credentials, cacheDirectory },
+    );
+
+    expect(report).toMatchObject({ versionTag: `nx-${HASH}`, source: 'cache' });
+    expect(second.calls).toEqual([]);
+  });
+
+  it('asks Cloudflare again once the entry is older than the TTL', async () => {
+    const { root, cacheDirectory } = await fixture();
+    await writeCachedLiveVersion(
+      cacheDirectory,
+      { accountId: 'account-1', workerName: 'fixture-worker-staging', stage: 'staging' },
+      { versionTag: 'nx-stale', versionId: 'version-0', fetchedAt: 0 },
+    );
+    const runner = new RecordingRunner();
+
+    const report = await deployedVersion(
+      root,
+      { stage: 'staging' },
+      { runner, processEnv: credentials, cacheDirectory, now: () => LIVE_VERSION_CACHE_TTL_MS + 1 },
+    );
+
+    expect(report).toMatchObject({ versionTag: `nx-${HASH}`, source: 'cloudflare' });
+    expect(runner.calls.length).toBe(2);
+  });
+
+  it('refuses without a credential and writes no placeholder for a later run to trust', async () => {
+    const { root, cacheDirectory } = await fixture();
+
+    await expect(
+      deployedVersion(
+        root,
+        { stage: 'staging' },
+        { runner: new RecordingRunner(), processEnv: { CLOUDFLARE_ACCOUNT_ID: 'account-1' }, cacheDirectory },
+      ),
+    ).rejects.toThrow('CLOUDFLARE_API_TOKEN is required.');
+    expect(
+      existsSync(
+        liveVersionCachePath(cacheDirectory, {
+          accountId: 'account-1',
+          workerName: 'fixture-worker-staging',
+          stage: 'staging',
+        }),
+      ),
+    ).toBe(false);
+  });
+
+  it('refuses to name a live version while traffic is split', async () => {
+    const { root, cacheDirectory } = await fixture();
+    const runner = new RecordingRunner([{ id: 'version-1', annotations: { 'workers/tag': `nx-${HASH}` } }], {
+      versions: [
+        { version_id: 'version-1', percentage: 50 },
+        { version_id: 'version-2', percentage: 50 },
+      ],
+    });
+
+    await expect(
+      deployedVersion(root, { stage: 'staging' }, { runner, processEnv: credentials, cacheDirectory }),
+    ).rejects.toThrow('fixture-worker-staging (staging): no single worker version is serving 100% of traffic');
+  });
+
+  it('names the pull-request worker the deploy would target, without provisioning anything', async () => {
+    const { root, cacheDirectory } = await fixture();
+    const runner = new RecordingRunner();
+
+    const report = await deployedVersion(root, { stage: 'pr123' }, { runner, processEnv: credentials, cacheDirectory });
+
+    expect(report.workerName).toBe('fixture-worker-pr123');
+    expect(runner.calls.every((args) => args[0] === 'deployments' || args[0] === 'versions')).toBe(true);
+  });
+});