@astralarium/repo-deploy-info 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Astralarium
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,13 @@
-# Temporary Holding Version
+# `@astralarium/repo-deploy-info`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Build identity and metadata.
+Detects stale clients and routes blue/green slots.
+
+```ts
+// app module, loaded by bins as `--app <module>`
+export const checkouts = async () =>
+  (await import("./src/checkouts.server.ts")).CHECKOUTS; // defineCheckouts
+```
+
+`./vite` bakes the build's `DeployInfo` and serves `/build.json`.
+A server-function call from another build answers 409.

package/dist/bin/siblings-pull.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/siblings-pull.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+/** `siblings-pull --app <module>`: fast-forwards the app's upstream-fed
+ *  siblings (`Checkouts` `pull`); a dirty checkout warns. */
+import { log } from "@astralarium/repo-telemetry";
+import { appArgs, loadCheckouts } from "../src/server/app-module.server.js";
+import { pullSiblings } from "../src/server/siblings.server.js";
+const USAGE = "Usage: siblings-pull --app <module>";
+try {
+    const { app } = appArgs(process.argv.slice(2), USAGE, { positionals: 0 });
+    pullSiblings(await loadCheckouts(app));
+}
+catch (exception) {
+    log.error("siblings_pull.failed", "siblings-pull failed", { exception });
+    process.exitCode = 1;
+}

package/dist/src/build-fetch.d.ts

@@ -0,0 +1,10 @@
+/** The answering worker runs another build than this bundle. */
+export declare class VersionMismatchError extends Error {
+    constructor();
+}
+/** `fetch` naming this bundle's build. */
+export type BuildHeaderFetch = (input: string, init?: RequestInit) => Promise<Response>;
+/** `fetch` naming this bundle's build in `header`; a 409 answer whose
+ *  JSON `error` is `VERSION_MISMATCH` raises stale and throws
+ *  `VersionMismatchError`. Other answers pass through. */
+export declare function buildHeaderFetch(header: string): BuildHeaderFetch;

package/dist/src/build-fetch.js

@@ -0,0 +1,32 @@
+/** Plain `fetch` of a versioned app: requests name this bundle's build. */
+import { deployInfo } from "./info.js";
+import { raiseStale } from "./stale-build.js";
+import { VERSION_MISMATCH } from "./version-check.js";
+/** The answering worker runs another build than this bundle. */
+export class VersionMismatchError extends Error {
+    constructor() {
+        super(VERSION_MISMATCH);
+        this.name = "VersionMismatchError";
+    }
+}
+/** `fetch` naming this bundle's build in `header`; a 409 answer whose
+ *  JSON `error` is `VERSION_MISMATCH` raises stale and throws
+ *  `VersionMismatchError`. Other answers pass through. */
+export function buildHeaderFetch(header) {
+    return async (input, init) => {
+        const headers = new Headers(init?.headers);
+        headers.set(header, deployInfo.build);
+        const res = await fetch(input, { ...init, headers });
+        if (res.status === 409) {
+            const body = (await res
+                .clone()
+                .json()
+                .catch(() => null));
+            if (body?.error === VERSION_MISMATCH) {
+                raiseStale();
+                throw new VersionMismatchError();
+            }
+        }
+        return res;
+    };
+}

package/dist/src/checkout/index.d.ts

@@ -0,0 +1,18 @@
+/** Drift between a recorded build and the dev server's checkouts. */
+import type { DeployComponent } from "../info.ts";
+/** Path the dev server serves the checkouts' current commits at. */
+export declare const CHECKOUT_JSON_PATH = "/checkout.json";
+/** A recorded component the checkout holds at another rev, or lacks. */
+interface ComponentDrift {
+    name: string;
+    /** Rev the build recorded. */
+    recorded: string;
+    /** Rev the checkout holds; undefined when it lacks the component. */
+    checkout: string | undefined;
+}
+/** Components of `recorded` that `checkout` holds at another rev or
+ *  lacks. */
+export declare function checkDrift(recorded: Record<string, DeployComponent>, checkout: Record<string, DeployComponent>): ComponentDrift[];
+/** The dev server's checkouts' current commits by component name. */
+export declare function fetchCheckout(): Promise<Record<string, DeployComponent>>;
+export {};

package/dist/src/checkout/index.js

@@ -0,0 +1,17 @@
+/** Path the dev server serves the checkouts' current commits at. */
+export const CHECKOUT_JSON_PATH = "/checkout.json";
+/** Components of `recorded` that `checkout` holds at another rev or
+ *  lacks. */
+export function checkDrift(recorded, checkout) {
+    return Object.entries(recorded).flatMap(([name, { rev }]) => {
+        const held = checkout[name]?.rev;
+        return held === rev ? [] : [{ name, recorded: rev, checkout: held }];
+    });
+}
+/** The dev server's checkouts' current commits by component name. */
+export async function fetchCheckout() {
+    const res = await fetch(CHECKOUT_JSON_PATH);
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+    return (await res.json());
+}

package/dist/src/checkout/vite.d.ts

@@ -0,0 +1,5 @@
+/** Vite plugin serving the dev server's checkouts' current commits. */
+import type { Plugin } from "vite";
+/** Serves `dirs`' current commits (`checkoutComponents`) at
+ *  `CHECKOUT_JSON_PATH` on dev servers, read per request. */
+export declare function checkoutInfo(dirs: Record<string, string>): Plugin;

package/dist/src/checkout/vite.js

@@ -0,0 +1,25 @@
+import { serveJson } from "../serve-json.js";
+import { componentOf } from "../server/mint.server.js";
+import { CHECKOUT_JSON_PATH } from "./index.js";
+/** Each checkout's current commit by component name, per `dirs`
+ *  (`componentDirs`); checkouts git can't read are left out. */
+function checkoutComponents(dirs) {
+    return Object.fromEntries(Object.entries(dirs).flatMap(([name, dir]) => {
+        try {
+            return [[name, componentOf(dir)]];
+        }
+        catch {
+            return [];
+        }
+    }));
+}
+/** Serves `dirs`' current commits (`checkoutComponents`) at
+ *  `CHECKOUT_JSON_PATH` on dev servers, read per request. */
+export function checkoutInfo(dirs) {
+    return {
+        name: "checkout-info",
+        configureServer(server) {
+            serveJson(server, CHECKOUT_JSON_PATH, () => JSON.stringify(checkoutComponents(dirs)));
+        },
+    };
+}

package/dist/src/cloudflare.d.ts

@@ -0,0 +1,49 @@
+/** One Cloudflare API call under the account: `path` is account-relative.
+ *  Resolves to the response's `result`. */
+export type CfApi = <T>(method: "GET" | "PUT" | "POST" | "PATCH", path: string, body?: unknown) => Promise<T>;
+/** A failed `CfApi` call. */
+export declare class CfApiError extends Error {
+    /** HTTP status of the response. */
+    readonly status: number;
+    constructor(message: string, status: number);
+}
+/** `CfApi` over `fetchFn` with a bearer `token`; throws `CfApiError` on an
+ *  HTTP or API failure. */
+export declare function cfApi(token: string, accountId: string, fetchFn?: typeof fetch): CfApi;
+/** A deployment's version split. */
+export interface DeploymentVersion {
+    version_id: string;
+    percentage: number;
+}
+/** One deployment of a script: its version split. */
+export interface DeploymentRecord {
+    created_on: string;
+    versions: DeploymentVersion[];
+}
+/** One uploaded version of a script. */
+export interface WorkerVersion {
+    id: string;
+    number: number;
+    resources?: {
+        bindings?: {
+            type: string;
+            name: string;
+            text?: string;
+        }[];
+    };
+}
+/** Plain-text var `name` of `version`; undefined when unset. */
+export declare const varOf: (version: WorkerVersion, name: string) => string | undefined;
+/** Build of `version` (its `BUILD_VAR`, which secret changes keep);
+ *  undefined when unset. */
+export declare const buildOf: (version: WorkerVersion) => string | undefined;
+/** `script`'s deployments, newest first. */
+export declare function scriptDeployments(api: CfApi, script: string): Promise<DeploymentRecord[]>;
+/** Version `id` of `script`. */
+export declare const scriptVersion: (api: CfApi, script: string, id: string) => Promise<WorkerVersion>;
+/** `script`'s cron expressions. */
+export declare function scriptCrons(api: CfApi, script: string): Promise<string[]>;
+/** Sets `script`'s crons to `crons`, replacing any. */
+export declare function putScriptCrons(api: CfApi, script: string, crons: readonly string[]): Promise<void>;
+/** Deploys `versions` of `script`, split by percentage. */
+export declare function deployScript(api: CfApi, script: string, versions: readonly DeploymentVersion[], message: string): Promise<void>;

package/dist/src/cloudflare.js

@@ -0,0 +1,62 @@
+/** The Cloudflare API under one account: script deployments, versions
+ *  and crons. */
+import { BUILD_VAR } from "./deployer.js";
+/** A failed `CfApi` call. */
+export class CfApiError extends Error {
+    /** HTTP status of the response. */
+    status;
+    constructor(message, status) {
+        super(message);
+        this.name = "CfApiError";
+        this.status = status;
+    }
+}
+/** `CfApi` over `fetchFn` with a bearer `token`; throws `CfApiError` on an
+ *  HTTP or API failure. */
+export function cfApi(token, accountId, fetchFn = fetch) {
+    return async (method, path, body) => {
+        const res = await fetchFn(`https://api.cloudflare.com/client/v4/accounts/${accountId}/${path}`, {
+            method,
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "Content-Type": "application/json",
+            },
+            body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const json = (await res.json().catch(() => null));
+        if (!res.ok || !json?.success)
+            throw new CfApiError(`${method} ${path}: ${res.status} ${json?.errors?.map((e) => e.message).join("; ") ?? ""}`, res.status);
+        return json.result;
+    };
+}
+/** Plain-text var `name` of `version`; undefined when unset. */
+export const varOf = (version, name) => version.resources?.bindings?.find((b) => b.type === "plain_text" && b.name === name)?.text;
+/** Build of `version` (its `BUILD_VAR`, which secret changes keep);
+ *  undefined when unset. */
+export const buildOf = (version) => varOf(version, BUILD_VAR);
+/** `script`'s deployments, newest first. */
+export async function scriptDeployments(api, script) {
+    const { deployments } = await api("GET", `workers/scripts/${script}/deployments`);
+    return deployments;
+}
+/** Version `id` of `script`. */
+export const scriptVersion = (api, script, id) => api("GET", `workers/scripts/${script}/versions/${id}`);
+/** `script`'s cron expressions. */
+export async function scriptCrons(api, script) {
+    const { schedules } = await api("GET", `workers/scripts/${script}/schedules`);
+    return schedules.map((s) => s.cron);
+}
+/** Sets `script`'s crons to `crons`, replacing any. */
+export async function putScriptCrons(api, script, crons) {
+    await api("PUT", `workers/scripts/${script}/schedules`, crons.map((cron) => ({ cron })));
+}
+/** Body of a deployment of `versions`. */
+const deploymentBody = (versions, message) => ({
+    strategy: "percentage",
+    versions,
+    annotations: { "workers/message": message },
+});
+/** Deploys `versions` of `script`, split by percentage. */
+export async function deployScript(api, script, versions, message) {
+    await api("POST", `workers/scripts/${script}/deployments`, deploymentBody(versions, message));
+}

package/dist/src/control.d.ts

@@ -0,0 +1,45 @@
+/** The ops contract between the deployer and a slotted worker. */
+/** A scheduled update reaches clients this long before it takes over, on
+ *  the database clock. */
+export declare const UPDATE_NOTICE_LEAD_MS: number;
+/** RPC a slotted worker offers the deployer. `run` names the cutover run
+ *  owning the scheduled update (one at a time); times are ms epochs. */
+export interface OpsControlRpc {
+    /** Schedules `run`'s update at `updateAt`, closing each queue its lead
+     *  ahead and replacing another run's pending update. Refused while
+     *  another run's update is due; resolves whether it landed. */
+    close(run: string, updateAt: number): Promise<boolean>;
+    /** Withdraws the scheduled update and reopens its queues, fenced to
+     *  `run` owning it or none (null: unconditional). Resolves whether the
+     *  fence held. */
+    reopen(run: string | null): Promise<boolean>;
+    /** True while `run` owns the scheduled update. */
+    scheduledFor(run: string): Promise<boolean>;
+    /** True while `run` owns the scheduled update and its notice is out
+     *  (`UPDATE_NOTICE_LEAD_MS` ahead, database clock). */
+    noticed(run: string): Promise<boolean>;
+    /** True while `run` owns the scheduled update and the database clock
+     *  has reached it. */
+    due(run: string): Promise<boolean>;
+    /** The build this slot runs. */
+    build(): Promise<string>;
+    /** Names `build` live and reopens as `reopen(run)` in one transaction;
+     *  the build lands either way. Resolves whether the fence held; rejects
+     *  with `ForeignBuildError` for another slot's build. */
+    release(build: string, run: string | null): Promise<boolean>;
+    /** Pushes the deploy state to every user present on this slot's build;
+     *  resolves to the count pushed. */
+    publish(): Promise<number>;
+    /** Ends the ongoing work of this slot's build (the cutover's drain step;
+     *  `--force` on `stage`/`deploy`); resolves to the count ended. A slot whose
+     *  builds hold no ongoing work leaves it out (`BlueGreenEnv.drain` unset). */
+    drain?(): Promise<number>;
+}
+/** `release` of a build other than the slot's. RPC carries an error's
+ *  `name`; `isForeignBuild` matches on it. */
+export declare class ForeignBuildError extends Error {
+    static readonly NAME = "ForeignBuildError";
+    constructor(slotBuild: string, build: string);
+}
+/** True for a `ForeignBuildError`, an RPC-carried one included. */
+export declare const isForeignBuild: (e: unknown) => e is Error;

package/dist/src/control.js

@@ -0,0 +1,15 @@
+/** The ops contract between the deployer and a slotted worker. */
+/** A scheduled update reaches clients this long before it takes over, on
+ *  the database clock. */
+export const UPDATE_NOTICE_LEAD_MS = 4 * 60 * 60_000;
+/** `release` of a build other than the slot's. RPC carries an error's
+ *  `name`; `isForeignBuild` matches on it. */
+export class ForeignBuildError extends Error {
+    static NAME = "ForeignBuildError";
+    constructor(slotBuild, build) {
+        super(`release: slot runs ${slotBuild}, not ${build}`);
+        this.name = ForeignBuildError.NAME;
+    }
+}
+/** True for a `ForeignBuildError`, an RPC-carried one included. */
+export const isForeignBuild = (e) => e instanceof Error && e.name === ForeignBuildError.NAME;

package/dist/src/deployer.d.ts

@@ -0,0 +1,89 @@
+/** The contract between `deploy-release` and the deployer's
+ *  workflows: slots, the scripts acted on, and each workflow's params. */
+/** A slotted-worker slot. */
+export type Slot = "blue" | "green";
+/** Every slot. */
+export declare const SLOTS: readonly Slot[];
+/** True for a slot name. */
+export declare const isSlot: (value: unknown) => value is Slot;
+/** The slot other than `slot`. */
+export declare const otherSlot: (slot: Slot) => Slot;
+/** Var naming a web version's slot; `deploy-release` sets it at upload,
+ *  the web worker routes slot requests by it. */
+export declare const SLOT_VAR = "SLOT";
+/** Var naming a version's build; `deploy-release` sets it at upload. */
+export declare const BUILD_VAR = "BUILD";
+/** The deployer's var holding its `Deployment`. */
+export declare const DEPLOYMENT_VAR = "DEPLOYMENT";
+/** The deployer's workflow bindings, by timeline. `drain` is bound only
+ *  by an env whose slots drain (`BlueGreenEnv.drain`). */
+export declare const DEPLOYER_FLOWS: {
+    readonly cutover: "CUTOVER";
+    readonly settle: "SETTLE";
+    readonly drain: "DRAIN";
+};
+/** A deployer timeline. */
+export type DeployerFlow = keyof typeof DEPLOYER_FLOWS;
+/** Workflow class behind each binding (`@astralarium/repo-deploy-workflows/deployer`
+ *  exports them). */
+export declare const DEPLOYER_CLASSES: Record<DeployerFlow, string>;
+/** Entrypoint of a slotted worker the deployer's slot controls bind. */
+export declare const CONTROL_ENTRYPOINT = "OpsControl";
+/** Service binding of `slot`'s `CONTROL_ENTRYPOINT`: `CONTROL_<SLOT>`. */
+export type ControlBinding = `CONTROL_${Uppercase<Slot>}`;
+/** The deployer's service binding of `slot`'s control. */
+export declare const controlBinding: (slot: Slot) => ControlBinding;
+/** Scripts and site a deploy acts on (the deployer's `DEPLOYMENT_VAR`). */
+export interface Deployment {
+    /** Web worker script. */
+    webScript: string;
+    /** Slotted worker script of each slot. */
+    slotScripts: Record<Slot, string>;
+    /** The site the web script serves; checked after the switch. */
+    siteOrigin: string;
+}
+/** One scheduled cutover. */
+export interface CutoverParams {
+    /** Cloudflare account holding the scripts. */
+    accountId: string;
+    /** Live web version, at 100%. */
+    liveVersion: string;
+    /** Web version of the next build, at 0%; goes live alone at the cutover. */
+    nextVersion: string;
+    /** Slot of the live build. */
+    liveSlot: Slot;
+    /** Idle slot, holding the next build. */
+    idleSlot: Slot;
+    /** Next build: the next version's `BUILD_VAR`. */
+    build: string;
+    /** ISO time the next build takes over. */
+    cutoverAt: string;
+    /** Site paths answering `{ build }` from the web worker and the live
+     *  slot; the cutover checks each (`BlueGreenEnv.buildPaths`). */
+    buildPaths: readonly string[];
+    /** Whether the cutover ends the live slot's ongoing work
+     *  (`OpsControlRpc.drain`) before the switch (`BlueGreenEnv.drain`). */
+    drain: boolean;
+}
+/** A settle onto the live build. */
+export interface SettleParams {
+    /** Slot of the live build. */
+    slot: Slot;
+    /** Live build: the 100% web version's `BUILD_VAR`. */
+    build: string;
+}
+/** A drain of one slot's ongoing work (`--force` on `stage`/`deploy`). */
+export interface DrainParams {
+    /** Slot whose build's work ends. */
+    slot: Slot;
+}
+/** Cutover run's workflow output: `released` named its build live;
+ *  `refused` (another run's update due at close) and `superseded` (another
+ *  run took over) end unchanged. */
+export type CutoverOutcome = "released" | "refused" | "superseded";
+/** Worst-case summed retry budget of a cutover's token-bound steps,
+ *  compensation included. */
+export declare const CUTOVER_TOKEN_BUDGET_MS: number;
+/** API token lifetime past the scheduled cutover: `CUTOVER_TOKEN_BUDGET_MS`
+ *  plus slack for a late cutover (staging overrunning its time). */
+export declare const CUTOVER_TOKEN_MARGIN_MS: number;

package/dist/src/deployer.js

@@ -0,0 +1,39 @@
+/** The contract between `deploy-release` and the deployer's
+ *  workflows: slots, the scripts acted on, and each workflow's params. */
+/** Every slot. */
+export const SLOTS = ["blue", "green"];
+/** True for a slot name. */
+export const isSlot = (value) => SLOTS.includes(value);
+/** The slot other than `slot`. */
+export const otherSlot = (slot) => slot === "blue" ? "green" : "blue";
+/** Var naming a web version's slot; `deploy-release` sets it at upload,
+ *  the web worker routes slot requests by it. */
+export const SLOT_VAR = "SLOT";
+/** Var naming a version's build; `deploy-release` sets it at upload. */
+export const BUILD_VAR = "BUILD";
+/** The deployer's var holding its `Deployment`. */
+export const DEPLOYMENT_VAR = "DEPLOYMENT";
+/** The deployer's workflow bindings, by timeline. `drain` is bound only
+ *  by an env whose slots drain (`BlueGreenEnv.drain`). */
+export const DEPLOYER_FLOWS = {
+    cutover: "CUTOVER",
+    settle: "SETTLE",
+    drain: "DRAIN",
+};
+/** Workflow class behind each binding (`@astralarium/repo-deploy-workflows/deployer`
+ *  exports them). */
+export const DEPLOYER_CLASSES = {
+    cutover: "CutoverWorkflow",
+    settle: "SettleWorkflow",
+    drain: "DrainWorkflow",
+};
+/** Entrypoint of a slotted worker the deployer's slot controls bind. */
+export const CONTROL_ENTRYPOINT = "OpsControl";
+/** The deployer's service binding of `slot`'s control. */
+export const controlBinding = (slot) => `CONTROL_${slot.toUpperCase()}`;
+/** Worst-case summed retry budget of a cutover's token-bound steps,
+ *  compensation included. */
+export const CUTOVER_TOKEN_BUDGET_MS = 2 * 60 * 60_000;
+/** API token lifetime past the scheduled cutover: `CUTOVER_TOKEN_BUDGET_MS`
+ *  plus slack for a late cutover (staging overrunning its time). */
+export const CUTOVER_TOKEN_MARGIN_MS = 6 * 60 * 60_000;

package/dist/src/index.d.ts

@@ -0,0 +1,10 @@
+/** A build's identity and the deploy contract bundles share: version
+ *  checks, stale builds and the blue/green deployer. */
+export * from "./build-fetch.ts";
+export * from "./cloudflare.ts";
+export * from "./control.ts";
+export * from "./deployer.ts";
+export * from "./info.ts";
+export * from "./live-build.ts";
+export * from "./stale-build.ts";
+export * from "./version-check.ts";

package/dist/src/index.js

@@ -0,0 +1,10 @@
+/** A build's identity and the deploy contract bundles share: version
+ *  checks, stale builds and the blue/green deployer. */
+export * from "./build-fetch.js";
+export * from "./cloudflare.js";
+export * from "./control.js";
+export * from "./deployer.js";
+export * from "./info.js";
+export * from "./live-build.js";
+export * from "./stale-build.js";
+export * from "./version-check.js";

package/dist/src/info.d.ts

@@ -0,0 +1,26 @@
+/** Site path serving this bundle's `DeployInfo`. */
+export declare const BUILD_JSON_PATH = "/build.json";
+/** One bundled repo checkout. */
+export interface DeployComponent {
+    /** Full commit hash. */
+    rev: string;
+}
+/** One build's identity; fields hold opaque values. */
+export interface DeployInfo {
+    /** Per-deploy id the version check compares; "dev" outside deploys. */
+    build: string;
+    /** One entry per bundled checkout (`Checkouts`), by component name;
+     *  empty in dev. */
+    components: Record<string, DeployComponent>;
+    /** Deploy env the build targets; "dev" outside deploys. */
+    env: string;
+}
+/** Deploy info of dev servers and tests. */
+export declare const DEV_DEPLOY_INFO: DeployInfo;
+/** `value` as one of the app's deploy `envs`; throws on others. */
+export declare function parseDeployEnv<E extends string>(value: string, envs: readonly E[]): E;
+/** Parses minted `DeployInfo` JSON naming one of `envs`; throws
+ *  `ExpectedError` on a malformed shape. */
+export declare function parseDeployInfo(text: string, envs: readonly string[]): DeployInfo;
+/** This bundle's deploy info. */
+export declare const deployInfo: DeployInfo;

package/dist/src/info.js

@@ -0,0 +1,42 @@
+/** This build's identity, shared by every bundle of an app. */
+import { ExpectedError } from "@astralarium/repo-telemetry";
+/** Site path serving this bundle's `DeployInfo`. */
+export const BUILD_JSON_PATH = "/build.json";
+/** Deploy info of dev servers and tests. */
+export const DEV_DEPLOY_INFO = {
+    build: "dev",
+    components: {},
+    env: "dev",
+};
+/** `value` as one of the app's deploy `envs`; throws on others. */
+export function parseDeployEnv(value, envs) {
+    if (envs.includes(value))
+        return value;
+    throw new ExpectedError(`Unknown deploy env "${value}"; expected one of ${envs.join(", ")}`);
+}
+/** Parses minted `DeployInfo` JSON naming one of `envs`; throws
+ *  `ExpectedError` on a malformed shape. */
+export function parseDeployInfo(text, envs) {
+    const value = JSON.parse(text);
+    if (typeof value !== "object" || value === null)
+        throw new ExpectedError("DeployInfo: expected an object");
+    const { build, components, env } = value;
+    if (typeof build !== "string" || build === "")
+        throw new ExpectedError("DeployInfo: expected a build id");
+    if (typeof components !== "object" || components === null)
+        throw new ExpectedError("DeployInfo: expected components");
+    for (const [name, component] of Object.entries(components)) {
+        const { rev } = (component ?? {});
+        if (typeof rev !== "string")
+            throw new ExpectedError(`DeployInfo: malformed component "${name}"`);
+    }
+    if (typeof env !== "string")
+        throw new ExpectedError("DeployInfo: expected an env");
+    return {
+        build,
+        components: components,
+        env: parseDeployEnv(env, envs),
+    };
+}
+/** This bundle's deploy info. */
+export const deployInfo = typeof __DEPLOY_INFO__ === "undefined" ? DEV_DEPLOY_INFO : __DEPLOY_INFO__;

package/dist/src/live-build.d.ts

@@ -0,0 +1,16 @@
+/** `watchLiveBuild`: served-build checks driven by deploy writes. */
+import { type ServedCheck } from "./stale-build.ts";
+/** Rechecks of the site's build across deploy writes. */
+export interface LiveBuildWatch {
+    /** Takes a deploy write's `live_build` and `version`. */
+    update(liveBuild: string | null, version: number): void;
+    /** Cancels the running check; the next `update` starts afresh. */
+    cancel(): void;
+}
+/**
+ * Checks the site's build on deploy writes naming a live build other than
+ * `check.build`. One check per live build; writes during it coalesce into
+ * one follow-up once it settles current. A settled check reruns on a newer
+ * version (a compensated cutover's switch back keeps `live_build`).
+ */
+export declare function watchLiveBuild(onStale: () => void, check: ServedCheck): LiveBuildWatch;