@smoothbricks/cli 0.11.16 → 0.11.18

package/src/wrangler/deploy-stage.ts

@@ -1,13 +1,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 { parseDevVarsExample } from './prepare-env.js';
+import {
+  awaitLiveVersion,
+  awaitVersionEndpoint,
+  currentDeploymentVersionId,
+  findVersionIdByTag,
+  type LiveVersionProbe,
+  liveVersionCacheDirectory,
+  type VersionEndpointWaitOptions,
+  writeCachedLiveVersion,
+} from './live-version.js';
 import {
   type ConfiguredStageResourcePlan,
   type DeploymentStage,
@@ -23,6 +30,13 @@ import {
   planPullRequestResources,
   pullRequestStage,
 } from './stage.js';
+import {
+  planStageSecrets,
+  readDeclaredSecretNames,
+  readSecretStageMap,
+  type StageSecretPlan,
+  stageSecretRefusal,
+} from './stage-secrets.js';
 
 export interface ProcessResult {
   exitCode: number;
@@ -69,6 +83,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 +96,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(
@@ -101,20 +123,25 @@ export async function deployStage(
     dependencies.cloudflare ??
     new CloudflareRestClient(accountId, requiredEnvironmentValue(apiToken, 'CLOUDFLARE_API_TOKEN'));
   const runner = dependencies.runner ?? new BunProcessRunner();
-  const secretNames = readSecretNames(cwd);
+  const secretPlan = planStageSecrets(readDeclaredSecretNames(cwd), stage, readSecretStageMap(cwd));
+  // Only the stage's own secrets, and only the ones a value exists for. A secret scoped to other
+  // stages is dropped here even when this shell exports it: that is the whole permission rule.
   const secretValues: Record<string, string> = {};
-  for (const name of secretNames) {
+  for (const name of secretPlan.required) {
     const value = processEnv[name];
     if (value) secretValues[name] = value;
   }
-  const missingSecrets = secretNames.filter((name) => !processEnv[name]);
+  const gate = stageSecretGate(secretPlan, new Set(Object.keys(secretValues)), cloudflare);
   let temporaryConfigPath: string | undefined;
   let temporarySecretsPath: string | undefined;
   try {
     const prepared = options.config
-      ? await prepareFlatConfig(options.config, stage, accountId, missingSecrets, cloudflare)
-      : await prepareTomlConfig(cwd, stage, accountId, missingSecrets, cloudflare);
+      ? await prepareFlatConfig(options.config, stage, accountId, gate, cloudflare)
+      : await prepareTomlConfig(cwd, stage, accountId, gate, cloudflare);
     temporaryConfigPath = prepared.temporaryConfigPath;
+    // The pull-request path already ran this before provisioning; the gate answers once per Worker.
+    // Everything below here writes to Cloudflare.
+    await gate(prepared.plan.workerName);
     const workerExists = await reconcileStageResources(prepared.plan, cloudflare);
     const versionTag = nxTaskVersionTag(processEnv);
     const envArgs = prepared.envFlag ? ['--env', prepared.envFlag] : [];
@@ -122,18 +149,32 @@ export async function deployStage(
     // renames the worker `<name>-<CLOUDFLARE_ENV>`. The build that produced the flat config is the
     // caller that sets the variable, so the deploy would silently succeed under a name neither
     // `reconcileStageResources` nor `versions list` looks at.
-    const run: ProcessRunOptions = prepared.envFlag ? { cwd } : { cwd, unsetEnv: ['CLOUDFLARE_ENV'] };
+    //
+    // A secret this stage is scoped out of goes with it. Leaving it out of the secrets payload is
+    // what stops it being installed; withholding it from the child as well means the deploy cannot
+    // read it at all, so "this stage never sees that capability" holds at the process boundary and
+    // not merely in the file we happen to write.
+    const unsetEnv = [...(prepared.envFlag ? [] : ['CLOUDFLARE_ENV']), ...secretPlan.withheld];
+    const run: ProcessRunOptions = unsetEnv.length > 0 ? { cwd, unsetEnv } : { cwd };
     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 +204,7 @@ export async function deployStage(
         ],
         run,
       );
+      await confirmVersionIsLive(probe, versionTag, { stage, workerName, accountId }, options, dependencies, cwd);
       return { stage, workerName, action: 'activated', versionTag };
     }
 
@@ -174,6 +216,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) {
@@ -199,7 +244,7 @@ async function prepareTomlConfig(
   cwd: string,
   stage: DeploymentStage,
   accountId: string,
-  missingSecrets: string[],
+  gate: SecretGate,
   cloudflare: CloudflareClient,
 ): Promise<PreparedConfig> {
   const committedConfigPath = join(cwd, 'wrangler.toml');
@@ -214,12 +259,7 @@ async function prepareTomlConfig(
   }
   const liveNamespaces = await cloudflare.listKvNamespaces();
   const plan = planPullRequestResources(committedToml, stage, liveNamespaces);
-  const { kvNamespaceIds, d1DatabaseIds } = await provisionPullRequestResources(
-    plan,
-    missingSecrets,
-    cloudflare,
-    liveNamespaces,
-  );
+  const { kvNamespaceIds, d1DatabaseIds } = await provisionPullRequestResources(plan, gate, cloudflare, liveNamespaces);
   const derivedToml = derivePullRequestWranglerConfig(committedToml, {
     stage,
     accountId,
@@ -241,7 +281,7 @@ async function prepareFlatConfig(
   configPath: string,
   stage: DeploymentStage,
   accountId: string,
-  missingSecrets: string[],
+  gate: SecretGate,
   cloudflare: CloudflareClient,
 ): Promise<PreparedConfig> {
   const flat = parseJsonFileText(configPath, await readFile(configPath, 'utf8'), parseFlatWranglerConfig);
@@ -254,12 +294,7 @@ async function prepareFlatConfig(
   }
   const liveNamespaces = await cloudflare.listKvNamespaces();
   const plan = planPullRequestBindings(flat, stage, liveNamespaces);
-  const { kvNamespaceIds, d1DatabaseIds } = await provisionPullRequestResources(
-    plan,
-    missingSecrets,
-    cloudflare,
-    liveNamespaces,
-  );
+  const { kvNamespaceIds, d1DatabaseIds } = await provisionPullRequestResources(plan, gate, cloudflare, liveNamespaces);
   const derived = derivePullRequestStageConfig(flat, { stage, accountId, kvNamespaceIds, d1DatabaseIds });
   // Beside the original: its main/assets/migrations paths are relative to the file.
   const temporaryConfigPath = join(dirname(configPath), `.wrangler.smoo-${process.pid}-${randomUUID()}.json`);
@@ -293,27 +328,58 @@ function migrationBindings(config: FlatWranglerConfig): string[] {
     .map((database) => database.binding);
 }
 
-async function refuseFirstDeploymentWithoutSecrets(
+/**
+ * Asks, of one Worker, whether this stage may deploy at all. Called at each path's last read
+ * before its first write, so a refusal costs nothing: the pull-request path provisions KV and D1
+ * inside config preparation, and every path reconciles buckets, routes and DNS after it. A
+ * refusal arriving later would strand resources created for a deploy that was never allowed.
+ */
+type SecretGate = (workerName: string) => Promise<void>;
+
+/**
+ * One answer per Worker, reused by both call sites so the read costs one round trip.
+ *
+ * What the Worker holds comes from the account's script listing first. A Worker absent from it
+ * holds nothing — exactly the first-deployment case — and Cloudflare answers 404 rather than an
+ * empty list when asked for a missing Worker's secrets. Reading that failure as "then nothing is
+ * needed" would disarm the check at the one moment it matters most, so it is never asked.
+ */
+function stageSecretGate(
+  plan: StageSecretPlan,
+  exported: ReadonlySet<string>,
+  cloudflare: CloudflareClient,
+): SecretGate {
+  const answered = new Map<string, Promise<void>>();
+  return (workerName) => {
+    let pending = answered.get(workerName);
+    if (!pending) {
+      pending = assertStageSecrets(plan, exported, cloudflare, workerName);
+      answered.set(workerName, pending);
+    }
+    return pending;
+  };
+}
+
+async function assertStageSecrets(
+  plan: StageSecretPlan,
+  exported: ReadonlySet<string>,
   cloudflare: CloudflareClient,
   workerName: string,
-  missingSecrets: string[],
 ): Promise<void> {
-  const firstDeployment = !(await cloudflare.listWorkerScripts()).some((script) => script.id === workerName);
-  if (firstDeployment && missingSecrets.length > 0) {
-    throw new Error(
-      `First deployment of ${workerName} requires process environment values for: ${missingSecrets.join(', ')}.`,
-    );
-  }
+  const live = (await cloudflare.listWorkerScripts()).some((script) => script.id === workerName);
+  const held = new Set(live ? await cloudflare.listWorkerSecrets(workerName) : []);
+  const refusal = stageSecretRefusal(plan, exported, held, workerName);
+  if (refusal) throw new Error(refusal);
 }
 
-/** Isolation refusals already ran in the plan; this is the first Cloudflare write. */
+/** Isolation refusals already ran in the plan; the gate below is the last one before the first write. */
 async function provisionPullRequestResources(
   plan: PullRequestResourcePlan,
-  missingSecrets: string[],
+  gate: SecretGate,
   cloudflare: CloudflareClient,
   liveNamespaces: LiveKvNamespace[],
 ): Promise<{ kvNamespaceIds: Map<string, string>; d1DatabaseIds: Map<string, string> }> {
-  await refuseFirstDeploymentWithoutSecrets(cloudflare, plan.workerName, missingSecrets);
+  await gate(plan.workerName);
   const kvNamespaceIds = await ensureKvNamespaces(plan.kvNamespaces, liveNamespaces, cloudflare);
   const d1DatabaseIds =
     plan.d1Databases.length === 0
@@ -578,49 +644,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);
@@ -642,8 +706,3 @@ function requiredEnvironmentValue(value: string | undefined, name: string): stri
   if (!value) throw new Error(`${name} is required.`);
   return value;
 }
-
-function readSecretNames(cwd: string): string[] {
-  const path = join(cwd, '.dev.vars.example');
-  return existsSync(path) ? parseDevVarsExample(readFileSync(path, 'utf8')) : [];
-}

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);
+  });
+});

package/src/wrangler/deployed-version.ts

@@ -0,0 +1,130 @@
+// `smoo wrangler deployed-version --stage <stage>` — what is serving this project's worker right now.
+//
+// Read-only by construction: it resolves the worker name from the committed config and asks
+// Cloudflare. It never provisions, never derives a pull-request stage's resources, and never
+// writes anything except its own cache entry.
+
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { parseJsonFileText } from '../lib/json.js';
+import { BunProcessRunner, type ProcessRunner, type ProcessRunOptions, wranglerJson } from './deploy-stage.js';
+import { parseFlatWranglerConfig, planFlatStageResources } from './flat-config.js';
+import {
+  LIVE_VERSION_CACHE_TTL_MS,
+  type LiveVersionProbe,
+  liveVersionCacheDirectory,
+  readCachedLiveVersion,
+  readLiveVersion,
+  writeCachedLiveVersion,
+} from './live-version.js';
+import {
+  type DeploymentStage,
+  isPullRequestStage,
+  parseDeploymentStage,
+  planConfiguredStageResources,
+  stageResourceName,
+  stagingWorkerBaseName,
+} from './stage.js';
+
+export interface DeployedVersionOptions {
+  /** `staging`, `production`, or `prN`. */
+  stage: string;
+  /** The build-generated flat wrangler.json the deploy would use, when the project deploys one. */
+  config?: string;
+  /** Ask Cloudflare even when a fresh cache entry exists. */
+  refresh?: boolean;
+}
+
+export interface DeployedVersionDependencies {
+  runner?: ProcessRunner;
+  processEnv?: NodeJS.ProcessEnv;
+  cacheDirectory?: string;
+  ttlMs?: number;
+  now?: () => number;
+}
+
+export interface DeployedVersionReport {
+  workerName: string;
+  stage: DeploymentStage;
+  versionTag: string | null;
+  versionId: string;
+  source: 'cloudflare' | 'cache';
+}
+
+/**
+ * The worker `stage` deploys to, from committed configuration alone.
+ *
+ * A pull-request stage's worker name is derived from the staging name the same way the deploy
+ * derives it, but WITHOUT the account listing the deploy needs for its KV/D1/R2 isolation: a
+ * question about what is live must not be able to create anything.
+ */
+export async function stageWorkerName(cwd: string, stage: DeploymentStage, configPath?: string): Promise<string> {
+  if (configPath) {
+    const flat = parseJsonFileText(configPath, await readFile(configPath, 'utf8'), parseFlatWranglerConfig);
+    return isPullRequestStage(stage)
+      ? stageResourceName(stagingWorkerBaseName(flat.name), stage)
+      : planFlatStageResources(flat, stage).workerName;
+  }
+  const tomlPath = join(cwd, 'wrangler.toml');
+  if (!existsSync(tomlPath)) {
+    throw new Error(`${tomlPath} does not exist; pass --config for a build-generated flat configuration.`);
+  }
+  const toml = await readFile(tomlPath, 'utf8');
+  return isPullRequestStage(stage)
+    ? stageResourceName(stagingWorkerBaseName(planConfiguredStageResources(toml, 'staging').workerName), stage)
+    : planConfiguredStageResources(toml, stage).workerName;
+}
+
+/**
+ * Answers with the tag serving 100% of this worker's traffic, or refuses.
+ *
+ * Refusing is the whole contract. A missing credential, an API error, or a traffic split has no
+ * honest answer, and returning a placeholder such as `unknown` would be worse than the error: a
+ * later run comparing against that placeholder would read it as a match and conclude the desired
+ * version is already live. For the same reason nothing here is ever written to the cache except a
+ * real observation, and the answer never contains a timestamp or anything else that varies per
+ * invocation.
+ */
+export async function deployedVersion(
+  cwd: string,
+  options: DeployedVersionOptions,
+  dependencies: DeployedVersionDependencies = {},
+): Promise<DeployedVersionReport> {
+  const stage = parseDeploymentStage(options.stage);
+  const processEnv = dependencies.processEnv ?? process.env;
+  const accountId = processEnv.CLOUDFLARE_ACCOUNT_ID;
+  if (!accountId) throw new Error('CLOUDFLARE_ACCOUNT_ID is required.');
+  if (!processEnv.CLOUDFLARE_API_TOKEN) throw new Error('CLOUDFLARE_API_TOKEN is required.');
+  const workerName = await stageWorkerName(cwd, stage, options.config);
+  const cacheDirectory = dependencies.cacheDirectory ?? liveVersionCacheDirectory(cwd, processEnv);
+  const key = { accountId, workerName, stage };
+  const ttlMs = dependencies.ttlMs ?? LIVE_VERSION_CACHE_TTL_MS;
+  const now = dependencies.now ?? Date.now;
+  if (options.refresh !== true) {
+    const cached = await readCachedLiveVersion(cacheDirectory, key, ttlMs, now);
+    if (cached) {
+      return { workerName, stage, versionTag: cached.versionTag, versionId: cached.versionId, source: 'cache' };
+    }
+  }
+  const runner = dependencies.runner ?? new BunProcessRunner();
+  const run: ProcessRunOptions = { cwd, unsetEnv: ['CLOUDFLARE_ENV'] };
+  const probe: LiveVersionProbe = {
+    deployments: () => wranglerJson(runner, ['deployments', 'status', '--name', workerName, '--json'], run),
+    versions: () => wranglerJson(runner, ['versions', 'list', '--name', workerName, '--json'], run),
+  };
+  const live = await readLiveVersion(probe);
+  if (!live.ok) throw new Error(`${workerName} (${stage}): ${live.error.message}`);
+  await writeCachedLiveVersion(cacheDirectory, key, {
+    versionTag: live.value.tag,
+    versionId: live.value.versionId,
+    fetchedAt: now(),
+  });
+  return {
+    workerName,
+    stage,
+    versionTag: live.value.tag,
+    versionId: live.value.versionId,
+    source: 'cloudflare',
+  };
+}