@smoothbricks/cli 0.11.16 → 0.11.17

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',
+  };
+}

package/src/wrangler/live-version.ts

@@ -0,0 +1,363 @@
+// What is live right now, as opposed to what we last uploaded.
+//
+// `wrangler versions deploy` returns when Cloudflare ACCEPTS the traffic shift, not when the edge
+// serves it. A deploy that returns is therefore not yet a deploy that answers: the site that signs
+// in to its stage's backend measured the previous backend version's response about 20 s after the
+// backend's deploy step had already gone green. Everything here exists to turn "we asked" into
+// "we observed".
+
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import typia from 'typia';
+
+/** Same shape as the release tooling's Result: a known operational failure is a value, not a throw. */
+export type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };
+
+/** The version Cloudflare is serving to 100% of traffic for one worker. */
+export interface LiveVersion {
+  versionId: string;
+  /** `wrangler versions deploy --version-tag` matches on this; a version deployed outside Nx has none. */
+  tag: string | null;
+}
+
+export type LiveVersionFailure =
+  | { kind: 'never-deployed'; message: string }
+  | { kind: 'split-traffic'; message: string };
+
+/** Reads the two `wrangler` JSON payloads the live version is derived from. */
+export interface LiveVersionProbe {
+  /** `wrangler deployments status --name <worker> --json` */
+  deployments(): Promise<unknown>;
+  /** `wrangler versions list --name <worker> --json` */
+  versions(): Promise<unknown>;
+}
+
+const isUnknownRecord = typia.createIs<Record<string, unknown>>();
+
+/**
+ * Every `{ id -> tag }` pair the payload carries, in document order.
+ *
+ * Wrangler nests versions differently per subcommand and per version of itself, spells the tag
+ * three ways (`annotations['workers/tag']`, a bare `tag`, `metadata.tag`) and the id two (`id`,
+ * `version_id`). One walk collects the relation once; both directions of the lookup are then a Map
+ * read rather than a second recursive scan that could disagree with the first.
+ */
+export function collectVersionTags(value: unknown): Map<string, string> {
+  const pairs = new Map<string, string>();
+  collectInto(value, pairs);
+  return pairs;
+}
+
+function collectInto(value: unknown, pairs: Map<string, string>): void {
+  if (Array.isArray(value)) {
+    for (const entry of value) collectInto(entry, pairs);
+    return;
+  }
+  if (!isUnknownRecord(value)) return;
+  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;
+  const candidateId =
+    typeof value.id === 'string' ? value.id : typeof value.version_id === 'string' ? value.version_id : undefined;
+  if (typeof candidateTag === 'string' && candidateId !== undefined && !pairs.has(candidateId)) {
+    pairs.set(candidateId, candidateTag);
+  }
+  for (const nested of Object.values(value)) collectInto(nested, pairs);
+}
+
+/** The version id whose tag is `tag`, or null. */
+export function findVersionIdByTag(value: unknown, tag: string): string | null {
+  for (const [id, candidate] of collectVersionTags(value)) {
+    if (candidate === tag) return id;
+  }
+  return null;
+}
+
+/** One version's share of the current deployment's traffic. */
+export interface DeployedVersionShare {
+  versionId: string | null;
+  percentage: number;
+}
+
+/**
+ * The current deployment's traffic split, or null when the payload names no deployment at all.
+ *
+ * "Nothing is deployed" and "two versions share the traffic" are different facts with different
+ * remedies, and a caller that collapses them cannot tell an operator which one it hit — so the
+ * split is returned whole and both questions are answered from it.
+ */
+export function currentDeploymentVersions(value: unknown): DeployedVersionShare[] | null {
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      const found = currentDeploymentVersions(entry);
+      if (found) return found;
+    }
+    return null;
+  }
+  if (!isUnknownRecord(value)) return null;
+  if (Array.isArray(value.versions)) {
+    return value.versions.map((version) => {
+      if (!isUnknownRecord(version)) return { versionId: null, percentage: 0 };
+      const id = version.version_id ?? version.id;
+      return { versionId: typeof id === 'string' ? id : null, percentage: Number(version.percentage) };
+    });
+  }
+  for (const nested of Object.values(value)) {
+    const found = currentDeploymentVersions(nested);
+    if (found) return found;
+  }
+  return null;
+}
+
+/**
+ * The one version serving 100% of traffic, or null when there is none or the deployment is split.
+ *
+ * A split is not "close enough": with two versions live, "is our version live" has no single
+ * answer, and answering it optimistically is how a deploy reports success while part of the
+ * traffic still reaches the old code.
+ */
+export function currentDeploymentVersionId(value: unknown): string | null {
+  const shares = currentDeploymentVersions(value);
+  if (shares?.length !== 1) return null;
+  const [only] = shares;
+  return only.percentage === 100 ? only.versionId : null;
+}
+
+/** The version serving all traffic for this worker, with the tag it was uploaded under. */
+export async function readLiveVersion(probe: LiveVersionProbe): Promise<Result<LiveVersion, LiveVersionFailure>> {
+  const deployments = await probe.deployments();
+  const shares = currentDeploymentVersions(deployments);
+  const versionId = currentDeploymentVersionId(deployments);
+  if (!versionId) {
+    return shares && shares.length > 0
+      ? {
+          ok: false,
+          error: {
+            kind: 'split-traffic',
+            message: 'no single worker version is serving 100% of traffic; refusing to name one as live',
+          },
+        }
+      : { ok: false, error: { kind: 'never-deployed', message: 'this worker has no active deployment' } };
+  }
+  const tag = collectVersionTags(await probe.versions()).get(versionId) ?? null;
+  return { ok: true, value: { versionId, tag } };
+}
+
+/**
+ * How long a deploy waits for the version it just activated to become the one being served.
+ *
+ * The bound is the point: an unbounded loop turns a stuck propagation into a hung CI job nobody
+ * reads, and a fixed sleep turns it into a green job that lied. Both are worse than a red job
+ * naming what it expected and what it saw.
+ */
+export const LIVE_VERSION_WAIT_BUDGET_MS = 120_000;
+/** Cloudflare's control plane converges in seconds; polling faster than this only burns API quota. */
+export const LIVE_VERSION_POLL_INTERVAL_MS = 2_000;
+
+export interface LiveVersionWaitOptions {
+  budgetMs?: number;
+  intervalMs?: number;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+export interface LiveVersionNotObserved {
+  kind: 'not-observed';
+  message: string;
+  expected: string;
+  observed: string;
+}
+
+/** One poll's verdict: the value that ends the wait, or how the world looked this time round. */
+type Attempt<T> = { done: true; value: T } | { done: false; observed: string };
+
+/**
+ * Runs `attempt` until it succeeds or the budget expires, and reports the LAST thing it saw.
+ *
+ * Both waits below need the same deadline arithmetic and the same "what did you see instead"
+ * record; sharing it keeps the two from drifting into disagreeing about when a wait is over.
+ */
+async function pollWithinBudget<T>(
+  attempt: () => Promise<Attempt<T>>,
+  options: LiveVersionWaitOptions,
+): Promise<Result<T, { observed: string; waitedMs: number }>> {
+  const budgetMs = options.budgetMs ?? LIVE_VERSION_WAIT_BUDGET_MS;
+  const intervalMs = options.intervalMs ?? LIVE_VERSION_POLL_INTERVAL_MS;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? sleepFor;
+  const deadline = now() + budgetMs;
+  for (;;) {
+    const result = await attempt();
+    if (result.done) return { ok: true, value: result.value };
+    if (now() >= deadline) return { ok: false, error: { observed: result.observed, waitedMs: budgetMs } };
+    await sleep(intervalMs);
+  }
+}
+
+function sleepFor(ms: number): Promise<void> {
+  const { promise, resolve } = Promise.withResolvers<void>();
+  setTimeout(resolve, ms);
+  return promise;
+}
+
+/**
+ * Polls until the worker's live version carries `expectedTag`, or the budget runs out.
+ *
+ * The tag is the match, not the version id: the tag IS the desired-state identity (`nx-<task
+ * hash>`), it is what both `wrangler deploy --tag` and `wrangler versions deploy --version-tag`
+ * were told to make live, and it is the one name the caller knows before the upload has produced
+ * a version id.
+ *
+ * Returns the failure rather than throwing it: a deploy that cannot be observed is an operational
+ * outcome the caller has to report, not a broken invariant.
+ */
+export async function awaitLiveVersion(
+  probe: LiveVersionProbe,
+  expectedTag: string,
+  options: LiveVersionWaitOptions = {},
+): Promise<Result<LiveVersion, LiveVersionNotObserved>> {
+  const polled = await pollWithinBudget<LiveVersion>(async () => {
+    const live = await readLiveVersion(probe);
+    if (!live.ok) return { done: false, observed: live.error.message };
+    const { tag, versionId } = live.value;
+    if (tag === expectedTag) return { done: true, value: live.value };
+    return { done: false, observed: tag ? `${tag} (${versionId})` : `an untagged version (${versionId})` };
+  }, options);
+  if (polled.ok) return polled;
+  return {
+    ok: false,
+    error: {
+      kind: 'not-observed',
+      expected: expectedTag,
+      observed: polled.error.observed,
+      message:
+        `deployed version ${expectedTag} was not serving traffic after ` +
+        `${Math.round(polled.error.waitedMs / 1000)}s; live is ${polled.error.observed}`,
+    },
+  };
+}
+
+/**
+ * Exactly the call the wait makes. Demanding all of `typeof fetch` would force every caller — the
+ * tests included — to also supply `preconnect`, which nothing here uses.
+ */
+export type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+export interface VersionEndpointWaitOptions extends LiveVersionWaitOptions {
+  fetch?: FetchLike;
+}
+
+/**
+ * Polls a worker-served endpoint until it answers with `expectedTag`.
+ *
+ * The control plane agreeing is necessary and not sufficient — that gap is exactly what this
+ * change's predecessor measured — so a project that can prove the edge serves the new code says so
+ * with an endpoint echoing its own version tag (Workers read it from the version-metadata
+ * binding). The contract is deliberately one shape: the trimmed response body IS the tag.
+ */
+export async function awaitVersionEndpoint(
+  url: string,
+  expectedTag: string,
+  options: VersionEndpointWaitOptions = {},
+): Promise<Result<void, LiveVersionNotObserved>> {
+  const request = options.fetch ?? fetch;
+  const polled = await pollWithinBudget<void>(async () => {
+    const observed = await probeVersionEndpoint(request, url);
+    return observed === expectedTag ? { done: true, value: undefined } : { done: false, observed };
+  }, options);
+  if (polled.ok) return polled;
+  return {
+    ok: false,
+    error: {
+      kind: 'not-observed',
+      expected: expectedTag,
+      observed: polled.error.observed,
+      message:
+        `${url} did not report version ${expectedTag} after ` +
+        `${Math.round(polled.error.waitedMs / 1000)}s; it reported ${polled.error.observed}`,
+    },
+  };
+}
+
+async function probeVersionEndpoint(request: FetchLike, url: string): Promise<string> {
+  try {
+    const response = await request(url, { headers: { accept: 'text/plain' } });
+    const body = (await response.text()).trim();
+    return response.ok ? body : `HTTP ${response.status} ${body}`.trim();
+  } catch (error) {
+    // A worker mid-rollout refuses connections; that is a poll result, not a reason to abandon the
+    // wait. It only becomes the failure when it is still the answer at the deadline.
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
+/**
+ * How long `smoo wrangler deployed-version` trusts its own last answer.
+ *
+ * This TTL is a convenience for operators and repeated local queries, NOT a correctness mechanism:
+ * nothing that decides whether to deploy may read it. The deploy's own liveness check always calls
+ * Cloudflare, because a cached "live already equals the desired tag" is precisely the belief a
+ * rollback falsifies, and acting on it would skip the deploy that repairs the rollback.
+ */
+export const LIVE_VERSION_CACHE_TTL_MS = 45_000;
+
+export interface LiveVersionCacheKey {
+  accountId: string;
+  workerName: string;
+  stage: string;
+}
+
+export interface CachedLiveVersion {
+  versionTag: string | null;
+  versionId: string;
+  fetchedAt: number;
+}
+
+const parseCachedLiveVersion = typia.json.createValidateParse<CachedLiveVersion>();
+
+/**
+ * One file per key, so two deploys running in parallel cannot clobber each other's answer; a
+ * shared map would need a lock to say the same thing.
+ */
+export function liveVersionCachePath(cacheDirectory: string, key: LiveVersionCacheKey): string {
+  const name = [key.accountId, key.workerName, key.stage].map(encodeURIComponent).join('_');
+  return join(cacheDirectory, 'smoo-live-version', `${name}.json`);
+}
+
+export async function readCachedLiveVersion(
+  cacheDirectory: string,
+  key: LiveVersionCacheKey,
+  ttlMs: number,
+  now: () => number = Date.now,
+): Promise<CachedLiveVersion | null> {
+  let text: string;
+  try {
+    text = await readFile(liveVersionCachePath(cacheDirectory, key), 'utf8');
+  } catch {
+    return null;
+  }
+  const parsed = parseCachedLiveVersion(text);
+  if (!parsed.success) return null;
+  return now() - parsed.data.fetchedAt < ttlMs ? parsed.data : null;
+}
+
+export async function writeCachedLiveVersion(
+  cacheDirectory: string,
+  key: LiveVersionCacheKey,
+  entry: CachedLiveVersion,
+): Promise<void> {
+  const path = liveVersionCachePath(cacheDirectory, key);
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, `${JSON.stringify(entry)}\n`);
+}
+
+/**
+ * Where the cache lives. Nx's workspace data directory already exists, is already gitignored, and
+ * is already wiped when the workspace is reset — three properties a hand-rolled directory would
+ * each have to re-earn, and one ($HOME) that would leak one checkout's answers into another's.
+ */
+export function liveVersionCacheDirectory(workspaceRoot: string, environment: NodeJS.ProcessEnv): string {
+  return environment.NX_WORKSPACE_DATA_DIRECTORY ?? join(workspaceRoot, '.nx', 'workspace-data');
+}