@astralarium/repo-deploy-release 0.0.0-stage → 0.2.0

package/dist/src/cutover-at.js

@@ -0,0 +1,152 @@
+/** A cutover's time from `--at`: a timestamp, an interval from now,
+ *  `now`, or the default early-morning slot. */
+import { ExpectedError } from "@astralarium/repo-telemetry";
+/** Zone of the default cutover and of the echoed time. */
+const CUTOVER_ZONE = "America/Los_Angeles";
+/** Hour (in `CUTOVER_ZONE`) of the default cutover, on tomorrow's date. */
+const DEFAULT_HOUR = 4;
+/** Increment a distant cutover rounds to. */
+const ROUND_MS = 30 * 60_000;
+/** A cutover farther out than this rounds to `ROUND_MS`. */
+const ROUND_AFTER_MS = 90 * 60_000;
+/** Farthest a cutover schedules ahead; beyond it, the token and staged
+ *  build are stale. */
+const MAX_CUTOVER_LEAD_MS = 30 * 24 * 60 * 60_000;
+/** Ms per interval unit. */
+const UNIT_MS = { d: 24 * 60 * 60_000, h: 60 * 60_000, m: 60_000 };
+/** `1d`, `2h`, `90m`, `1h30m`: units in descending order. */
+const INTERVAL = /^(?:(\d+)d)?(?:(\d+)h)?(?:(\d+)m)?$/;
+/** An ISO 8601 date, optionally with a time (to minutes, seconds or ms)
+ *  and its zone (`Z`, `±hh:mm`). */
+const TIMESTAMP = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,3}))?)?(Z|[+-]\d{2}:\d{2})?)?$/i;
+/** Parses `--at` at `now` (ms epoch): undefined = default; `now` and
+ *  intervals relative; else ISO 8601, zone-less in `CUTOVER_ZONE`. Throws
+ *  on malformed text. */
+export function parseCutoverSpec(text, now) {
+    if (text === undefined)
+        return { kind: "fixed", at: defaultCutover(now) };
+    if (text === "now")
+        return { kind: "relative", offsetMs: 0 };
+    const interval = INTERVAL.exec(text);
+    if (interval && text !== "") {
+        const [, d = "0", h = "0", m = "0"] = interval;
+        return {
+            kind: "relative",
+            offsetMs: +d * UNIT_MS.d + +h * UNIT_MS.h + +m * UNIT_MS.m,
+        };
+    }
+    if (/^\d+$/.test(text))
+        throw new ExpectedError(`--at: "${text}" needs a unit (d, h, m)`);
+    const at = parseTimestamp(text);
+    if (at === undefined)
+        throw new ExpectedError(`--at: unreadable time "${text}"; expected now, an interval (1h30m) or an ISO timestamp (2026-10-09T04:00, Pacific unless zoned)`);
+    return { kind: "fixed", at };
+}
+/** The instant ISO timestamp `text` names, zone-less in `CUTOVER_ZONE`;
+ *  undefined when malformed. */
+function parseTimestamp(text) {
+    const match = TIMESTAMP.exec(text);
+    if (!match)
+        return undefined;
+    const [, y, mo, d, h = "0", mi = "0", sec = "0", frac = "0", zone] = match;
+    const wall = { year: +y, month: +mo, day: +d, hour: +h, minute: +mi };
+    const asUtc = Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute);
+    // Date.UTC carries overflow into the next field: a changed field was out
+    // of range.
+    const check = new Date(asUtc);
+    if (check.getUTCFullYear() !== wall.year ||
+        check.getUTCMonth() !== wall.month - 1 ||
+        check.getUTCDate() !== wall.day ||
+        check.getUTCHours() !== wall.hour ||
+        check.getUTCMinutes() !== wall.minute ||
+        +sec > 59)
+        return undefined;
+    const extraMs = +sec * 1_000 + +frac.padEnd(3, "0");
+    if (!zone)
+        return zonedInstant(wall, CUTOVER_ZONE) + extraMs;
+    const offset = /^([+-])(\d{2}):(\d{2})$/.exec(zone);
+    const offsetMs = offset
+        ? (offset[1] === "-" ? -1 : 1) * (+offset[2] * 60 + +offset[3]) * 60_000
+        : 0;
+    return asUtc + extraMs - offsetMs;
+}
+/** Cutover instant (ms epoch) of `spec` at `now`. Beyond `ROUND_AFTER_MS`
+ *  rounds to `ROUND_MS` unless `exact`. Throws on a passed fixed instant
+ *  or one beyond `MAX_CUTOVER_LEAD_MS`. */
+export function resolveCutover(spec, now, exact = false) {
+    const at = spec.kind === "fixed" ? spec.at : now + spec.offsetMs;
+    if (spec.kind === "fixed" && at <= now)
+        throw new ExpectedError(`--at: ${new Date(at).toISOString()} has passed`);
+    const resolved = exact || at - now <= ROUND_AFTER_MS
+        ? at
+        : Math.round(at / ROUND_MS) * ROUND_MS;
+    if (resolved - now > MAX_CUTOVER_LEAD_MS)
+        throw new ExpectedError(`--at: ${new Date(resolved).toISOString()} is over ${MAX_CUTOVER_LEAD_MS / (24 * 60 * 60_000)} days out, the farthest a cutover schedules`);
+    return resolved;
+}
+/** `DEFAULT_HOUR`:00 in `CUTOVER_ZONE` on the zone's date after `now`'s. */
+function defaultCutover(now) {
+    const today = zonedParts(now, CUTOVER_ZONE);
+    // Date.UTC normalizes day overflow across months and years.
+    const tomorrow = new Date(Date.UTC(today.year, today.month - 1, today.day + 1));
+    return zonedInstant({
+        year: tomorrow.getUTCFullYear(),
+        month: tomorrow.getUTCMonth() + 1,
+        day: tomorrow.getUTCDate(),
+        hour: DEFAULT_HOUR,
+        minute: 0,
+    }, CUTOVER_ZONE);
+}
+/** `at`'s wall clock in `zone`. */
+function zonedParts(at, zone) {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone: zone,
+        hourCycle: "h23",
+        year: "numeric",
+        month: "numeric",
+        day: "numeric",
+        hour: "numeric",
+        minute: "numeric",
+    }).formatToParts(at);
+    const field = (type) => Number(parts.find((p) => p.type === type)?.value);
+    return {
+        year: field("year"),
+        month: field("month"),
+        day: field("day"),
+        hour: field("hour"),
+        minute: field("minute"),
+    };
+}
+/** The instant `wall` reads in `zone`. */
+function zonedInstant(wall, zone) {
+    const asUtc = Date.UTC(wall.year, wall.month - 1, wall.day, wall.hour, wall.minute);
+    // Two passes: exact except inside a DST gap.
+    let at = asUtc;
+    for (let i = 0; i < 2; i++)
+        at = asUtc - offsetOf(at, zone);
+    return at;
+}
+/** `zone`'s UTC offset (ms) at `at`. */
+function offsetOf(at, zone) {
+    const w = zonedParts(at, zone);
+    const wallAsUtc = Date.UTC(w.year, w.month - 1, w.day, w.hour, w.minute);
+    return wallAsUtc - Math.floor(at / 60_000) * 60_000;
+}
+/** `at` for an operator: the time in `CUTOVER_ZONE` and UTC, and how far
+ *  from `now`. */
+export function describeCutover(at, now) {
+    const zoned = new Intl.DateTimeFormat("en-US", {
+        timeZone: CUTOVER_ZONE,
+        weekday: "short",
+        month: "short",
+        day: "numeric",
+        hour: "numeric",
+        minute: "2-digit",
+        timeZoneName: "short",
+    }).format(at);
+    const minutes = Math.max(0, Math.round((at - now) / 60_000));
+    const away = minutes === 0
+        ? "now"
+        : `in ${Math.floor(minutes / 60)}h ${String(minutes % 60).padStart(2, "0")}m`;
+    return `${zoned} (${new Date(at).toISOString()}), ${away}`;
+}

package/dist/src/cutovers.d.ts

@@ -0,0 +1,62 @@
+import { type InstanceStatus } from "./cloudflare.ts";
+import type { SlotSession } from "./session.ts";
+import { type DeployState } from "./state.ts";
+import { type WebVersion } from "./web.ts";
+/** A cutover run the API lists. */
+interface CutoverRun {
+    id: string;
+    status: InstanceStatus;
+}
+/** Id of a new cutover run for `build`: `cutover-<build>-<epoch>`. */
+export declare const cutoverRunId: (build: string) => string;
+/** Build of cutover run `id`; undefined for another shape. */
+export declare const buildOfRun: (id: string) => string | undefined;
+/** What a command found after taking the lease. */
+export interface Cutovers {
+    /** The 100% web version. */
+    live: WebVersion;
+    /** The deploy state; `noticed` once the update is due. */
+    state: DeployState;
+    /** Runs past their sleep, or owning a due update whatever their
+     *  status (the API reports `waiting` during step retries). */
+    inFlight: CutoverRun[];
+    /** Waiting runs of the live build: released, retrying the tail (old
+     *  slot's cron clear, a publish). Commands wait them out: the clear
+     *  would strip crons a new `cutover` or `rollback` adds to that slot. */
+    finishing: CutoverRun[];
+    /** Waiting runs ahead of their release: owning no update, or one still
+     *  ahead. */
+    terminable: string[];
+    /** The update once no listed run owns it: its run ended. */
+    orphan: {
+        run: string;
+        at: Date;
+    } | undefined;
+}
+/** Classifies `runs` against `state`. */
+export declare function classify(live: WebVersion, state: DeployState, runs: readonly CutoverRun[]): Cutovers;
+/** Reads the live web version, the deploy state and the cutover runs,
+ *  classified. */
+export declare function readCutovers(s: SlotSession): Promise<Cutovers>;
+/** `requireIdle`'s options. */
+interface IdleOptions {
+    /** What follows the run's end, for the operator. */
+    then?: string;
+    /** Ends finishing runs along with terminable ones: the command's own
+     *  steps redo their tail (`settle`). */
+    endFinishing?: boolean;
+}
+/** Throws while a cutover is in flight, or finishing unless
+ *  `endFinishing`. */
+export declare function requireIdle(c: Cutovers, { then, endFinishing }?: IdleOptions): void;
+/** Throws while the deploy state names a live build other than the live
+ *  web version's: `settle` realigns them. */
+export declare function requireLiveAligned(s: SlotSession, c: Cutovers): void;
+/** Terminates terminable runs (finishing ones too with `endFinishing`),
+ *  withdrawing each one's update: a dead run's update closes the app ahead
+ *  of nothing. Re-reads first: an update may have turned due since the
+ *  command's read. Resolves to the fresh classification. */
+export declare function terminateCutovers(s: SlotSession, options?: IdleOptions): Promise<Cutovers>;
+/** Withdraws the orphaned update, fenced. Resolves whether one was there. */
+export declare function withdrawOrphan(s: SlotSession, c: Cutovers): Promise<boolean>;
+export {};

package/dist/src/cutovers.js

@@ -0,0 +1,112 @@
+/** Cutover runs and the scheduled update, classified against the deploy
+ *  state and the live web version. */
+import { ExpectedError, log } from "@astralarium/repo-telemetry";
+import { epoch, RUNNING, WAITING } from "./cloudflare.js";
+import { abortReason } from "./process.js";
+import { readDeployState, withdrawUpdateIn, } from "./state.js";
+import { readLive } from "./web.js";
+/** Id of a new cutover run for `build`: `cutover-<build>-<epoch>`. */
+export const cutoverRunId = (build) => `cutover-${build}-${epoch()}`;
+/** Build of cutover run `id`; undefined for another shape. */
+export const buildOfRun = (id) => /^cutover-(.+)-\d+$/.exec(id)?.[1];
+/** Statuses a listing covers: every unfinished run. */
+const LISTED = [...RUNNING, ...WAITING];
+/** Every unfinished cutover run; throws naming `settle` when the listing
+ *  fails. */
+async function listRuns(s) {
+    const flow = s.target.flows.cutover;
+    try {
+        const listed = await Promise.all(LISTED.map(async (status) => (await s.cf.instances(flow, status)).map((id) => ({ id, status }))));
+        return listed.flat();
+    }
+    catch (e) {
+        if (s.signal.aborted)
+            throw abortReason(s.signal);
+        throw new ExpectedError(`The cutover runs are unreadable (${e instanceof Error ? e.message : String(e)}): retry; ${s.cli("settle")} realigns the deployment once they read.`, { cause: e });
+    }
+}
+/** Classifies `runs` against `state`. */
+export function classify(live, state, runs) {
+    const inFlight = [];
+    const finishing = [];
+    const terminable = [];
+    for (const run of runs) {
+        const owner = run.id === state.update_run;
+        if (RUNNING.includes(run.status) || (owner && state.noticed))
+            inFlight.push(run);
+        else if (buildOfRun(run.id) === state.live_build)
+            finishing.push(run);
+        else
+            terminable.push(run.id);
+    }
+    const owned = runs.some((run) => run.id === state.update_run);
+    const orphan = state.update_run !== null && state.update_at !== null && !owned
+        ? { run: state.update_run, at: state.update_at }
+        : undefined;
+    return { live, state, inFlight, finishing, terminable, orphan };
+}
+/** Reads the live web version, the deploy state and the cutover runs,
+ *  classified. */
+export async function readCutovers(s) {
+    const live = await readLive(s);
+    const [state, runs] = await Promise.all([
+        readDeployState(s.sql, 0),
+        listRuns(s),
+    ]);
+    return classify(live, state, runs);
+}
+/** `runs` grouped by status: `running: a b; waiting: c`. */
+function describeRuns(runs) {
+    const byStatus = new Map();
+    for (const { id, status } of runs) {
+        const ids = byStatus.get(status) ?? [];
+        ids.push(id);
+        byStatus.set(status, ids);
+    }
+    return [...byStatus]
+        .map(([status, ids]) => `${status}: ${ids.join(" ")}`)
+        .join("; ");
+}
+/** Throws while a cutover is in flight, or finishing unless
+ *  `endFinishing`. */
+export function requireIdle(c, { then = "retry once it ends.", endFinishing = false } = {}) {
+    if (c.inFlight.length)
+        throw new ExpectedError(`A cutover is in progress (${describeRuns(c.inFlight)}); ${then}`);
+    if (c.finishing.length && !endFinishing)
+        throw new ExpectedError(`A cutover is finishing (${describeRuns(c.finishing)}); ${then}`);
+}
+/** Throws while the deploy state names a live build other than the live
+ *  web version's: `settle` realigns them. */
+export function requireLiveAligned(s, c) {
+    const { live_build } = c.state;
+    if (live_build !== null && live_build !== c.live.build)
+        throw new ExpectedError(`The deploy state names build '${live_build}' live but the live web version is build '${c.live.build}'; run ${s.cli("settle")} first.`);
+}
+/** Terminates terminable runs (finishing ones too with `endFinishing`),
+ *  withdrawing each one's update: a dead run's update closes the app ahead
+ *  of nothing. Re-reads first: an update may have turned due since the
+ *  command's read. Resolves to the fresh classification. */
+export async function terminateCutovers(s, options = {}) {
+    const c = await readCutovers(s);
+    requireIdle(c, options);
+    const ending = options.endFinishing
+        ? [...c.terminable, ...c.finishing.map((run) => run.id)]
+        : c.terminable;
+    for (const id of ending) {
+        await s.cf.terminate(s.target.flows.cutover, id);
+        const outcome = await s.lease.fenced((tx) => withdrawUpdateIn(tx, id));
+        if (outcome === "withdrawn")
+            log.info("deploy_release.update_withdrawn", "Withdrew the update of terminated cutover run {run}", { run: id });
+    }
+    return c;
+}
+/** Withdraws the orphaned update, fenced. Resolves whether one was there. */
+export async function withdrawOrphan(s, c) {
+    if (!c.orphan)
+        return false;
+    const { run } = c.orphan;
+    const outcome = await s.lease.fenced((tx) => withdrawUpdateIn(tx, run));
+    if (outcome === "withdrawn")
+        log.info("deploy_release.orphan_withdrawn", "Withdrew the update at {at} of ended cutover run {run}", { at: c.orphan.at.toISOString(), run: c.orphan.run });
+    return true;
+}

package/dist/src/deployer.d.ts

@@ -0,0 +1,36 @@
+import type { SlotTarget } from "./target.ts";
+/** `target`'s deployer wrangler config, entry `main`, on the slotted
+ *  worker's runtime; its `env.<env>` block holds the workflows,
+ *  `DEPLOYMENT` and each slot's control. */
+export declare function deployerConfig(target: SlotTarget, main: string): {
+    name: string;
+    main: string;
+    compatibility_date: string;
+    compatibility_flags: string[];
+    observability: {
+        enabled: boolean;
+    };
+    workers_dev: boolean;
+    preview_urls: boolean;
+    env: {
+        [x: string]: {
+            name: string;
+            workflows: {
+                name: string;
+                binding: "CUTOVER" | "SETTLE" | "DRAIN";
+                class_name: string;
+            }[];
+            vars: {
+                DEPLOYMENT: import("@astralarium/repo-deploy-info").Deployment;
+            };
+            services: {
+                binding: "CONTROL_BLUE" | "CONTROL_GREEN";
+                service: string;
+                entrypoint: string;
+            }[];
+        };
+    };
+};
+/** Writes `target`'s deployer into `dir`: `DEPLOYER_ENTRY` and
+ *  `wrangler.json` (`deployerConfig`); returns the config's path. */
+export declare function writeDeployer(dir: string, target: SlotTarget): Promise<string>;

package/dist/src/deployer.js

@@ -0,0 +1,63 @@
+/** The deployer worker of a blue/green env: `@astralarium/repo-deploy-workflows/deployer`
+ *  under a wrangler config `deploy-release` generates from the target. */
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CONTROL_ENTRYPOINT, controlBinding, DEPLOYER_CLASSES, DEPLOYER_FLOWS, DEPLOYMENT_VAR, SLOTS, } from "@astralarium/repo-deploy-info";
+/** Entry file of the generated deployer, beside its config: re-exports
+ *  `@astralarium/repo-deploy-workflows/deployer`, so the bundle lands as `index.js`. */
+const DEPLOYER_ENTRY = "index.js";
+/** Flag the deployer adds to the slotted worker's: the site check
+ *  reaches the site through its public routing. */
+const PUBLIC_FETCH_FLAG = "global_fetch_strictly_public";
+/** `target`'s deployer wrangler config, entry `main`, on the slotted
+ *  worker's runtime; its `env.<env>` block holds the workflows,
+ *  `DEPLOYMENT` and each slot's control. */
+export function deployerConfig(target, main) {
+    const { env, deployer, deployment, flows, runtime } = target;
+    return {
+        name: deployer,
+        main,
+        compatibility_date: runtime.compatibilityDate,
+        compatibility_flags: [
+            ...new Set([...runtime.compatibilityFlags, PUBLIC_FETCH_FLAG]),
+        ],
+        observability: { enabled: true },
+        // Reached only through the Workflows API.
+        workers_dev: false,
+        preview_urls: false,
+        env: {
+            [env]: {
+                name: deployer,
+                workflows: Object.keys(flows).flatMap((flow) => {
+                    const name = flows[flow];
+                    return name
+                        ? [
+                            {
+                                name,
+                                binding: DEPLOYER_FLOWS[flow],
+                                class_name: DEPLOYER_CLASSES[flow],
+                            },
+                        ]
+                        : [];
+                }),
+                vars: { [DEPLOYMENT_VAR]: deployment },
+                services: SLOTS.map((slot) => ({
+                    binding: controlBinding(slot),
+                    service: deployment.slotScripts[slot],
+                    entrypoint: CONTROL_ENTRYPOINT,
+                })),
+            },
+        },
+    };
+}
+/** Writes `target`'s deployer into `dir`: `DEPLOYER_ENTRY` and
+ *  `wrangler.json` (`deployerConfig`); returns the config's path. */
+export async function writeDeployer(dir, target) {
+    const config = join(dir, "wrangler.json");
+    const module = JSON.stringify(fileURLToPath(import.meta.resolve("@astralarium/repo-deploy-workflows/deployer")));
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, DEPLOYER_ENTRY), `export * from ${module};\nexport { default } from ${module};\n`);
+    await writeFile(config, JSON.stringify(deployerConfig(target, DEPLOYER_ENTRY)));
+    return config;
+}

package/dist/src/index.d.ts

@@ -0,0 +1,2 @@
+/** `deploy-release`'s app declaration: `defineReleaseApp` and its types. */
+export { type BlueGreenEnv, defineReleaseApp, type EnvRelease, type InPlaceEnv, type OngoingWork, type ReleaseApp, type RetireBuilds, type SlotPackages, type SlotSecrets, type WorkerBuild, type WorkerSpec, } from "./app.ts";

package/dist/src/index.js

@@ -0,0 +1,2 @@
+/** `deploy-release`'s app declaration: `defineReleaseApp` and its types. */
+export { defineReleaseApp, } from "./app.js";

package/dist/src/lease.d.ts

@@ -0,0 +1,36 @@
+import { type Sql, type TransactionSql } from "@astralarium/repo-postgres/sql";
+/** The commands that change the deployment, as their lease names them:
+ *  the `deploy.operation` values. Keep in step with `sql/schema.sql`. */
+export declare const DEPLOY_OPERATIONS: readonly ["init", "stage", "deploy", "cutover", "rollback", "settle", "cancel", "secrets"];
+/** A command that changes the deployment (`DEPLOY_OPERATIONS`). */
+export type DeployOperation = (typeof DEPLOY_OPERATIONS)[number];
+/** The lease as it stands. */
+export interface LeaseRow {
+    holder: string;
+    operation: DeployOperation;
+    expires_at: Date;
+}
+/** `row` for an operator: holder, operation, expiry. */
+export declare const describeLease: (row: LeaseRow) => string;
+/** A held lease. */
+export declare class Lease {
+    #private;
+    readonly holder: string;
+    private constructor();
+    /** Takes the lease for `operation`, renewing it while held; `onLost`
+     *  hears of it lapsing or passing to another holder. Throws while
+     *  another holds it, naming `unlock`, the command line that breaks it. */
+    static take(sql: Sql, operation: DeployOperation, { onLost, unlock }: {
+        onLost: (error: Error) => void;
+        unlock: string;
+    }): Promise<Lease>;
+    /** Runs `fn` in a transaction locked behind the lease; throws once it is
+     *  lost. */
+    fenced<T>(fn: (tx: TransactionSql) => Promise<T>): Promise<T>;
+    /** Stops renewing and drops the lease. */
+    release(): Promise<void>;
+}
+/** The lease; undefined while free. */
+export declare function readLease(sql: Sql): Promise<LeaseRow | undefined>;
+/** Drops `holder`'s lease; false when another holds it now. */
+export declare function breakLease(sql: Sql, holder: string): Promise<boolean>;

package/dist/src/lease.js

@@ -0,0 +1,112 @@
+/** The deploy lease (`deploy.state`): one mutating command at a time.
+ *  A heartbeat renews it; a lapse loses it, failing fenced writes. */
+import { hostname, userInfo } from "node:os";
+import { isSqlstate, SQLSTATE, } from "@astralarium/repo-postgres/sql";
+import { ExpectedError, log } from "@astralarium/repo-telemetry";
+/** The commands that change the deployment, as their lease names them:
+ *  the `deploy.operation` values. Keep in step with `sql/schema.sql`. */
+export const DEPLOY_OPERATIONS = [
+    "init",
+    "stage",
+    "deploy",
+    "cutover",
+    "rollback",
+    "settle",
+    "cancel",
+    "secrets",
+];
+/** Between heartbeat renewals. */
+const RENEW_MS = 5 * 60_000;
+/** How long a lease holds past its last renewal. */
+const LEASE_TTL = "1 hour";
+/** `row` for an operator: holder, operation, expiry. */
+export const describeLease = (row) => `${row.holder} (${row.operation}, until ${row.expires_at.toISOString()})`;
+/** This invocation as a lease holder: `user@host pid N`. */
+const leaseHolder = () => `${userInfo().username}@${hostname().split(".")[0]} pid ${process.pid}`;
+/** A held lease. */
+export class Lease {
+    #sql;
+    #heartbeat;
+    /** The heartbeat's renewal in flight; `release` awaits it. */
+    #renewal = Promise.resolve();
+    holder;
+    constructor(sql, holder, onLost) {
+        this.#sql = sql;
+        this.holder = holder;
+        this.#heartbeat = setInterval(() => {
+            this.#renewal = renewLease(sql, holder).then(({ renewed, lease }) => {
+                if (renewed)
+                    return;
+                clearInterval(this.#heartbeat);
+                onLost(new ExpectedError(lease
+                    ? `Lost the deploy lease to ${describeLease(lease)}.`
+                    : "Lost the deploy lease: it lapsed or was broken."));
+            }, (e) => log.warn("deploy_release.lease_renewal_failed", "deploy lease renewal failed; retrying", { exception: e }));
+        }, RENEW_MS).unref();
+    }
+    /** Takes the lease for `operation`, renewing it while held; `onLost`
+     *  hears of it lapsing or passing to another holder. Throws while
+     *  another holds it, naming `unlock`, the command line that breaks it. */
+    static async take(sql, operation, { onLost, unlock }) {
+        const holder = leaseHolder();
+        let row;
+        try {
+            row = await takeLease(sql, holder, operation);
+        }
+        catch (e) {
+            throw new ExpectedError(isSqlstate(e, SQLSTATE.insufficientPrivilege)
+                ? "The database role may not take the deploy lease: it needs EXECUTE on the deploy.*_lease functions and UPDATE on deploy.state, both granted to app_service."
+                : "Could not take the deploy lease.", { cause: e });
+        }
+        if (!row.taken)
+            throw new ExpectedError(`The deployment is leased: ${describeLease(row)}. Wait for it, or run ${unlock} if that command died.`);
+        return new Lease(sql, holder, onLost);
+    }
+    /** Runs `fn` in a transaction locked behind the lease; throws once it is
+     *  lost. */
+    fenced(fn) {
+        return this.#sql.begin(async (tx) => {
+            await tx `SELECT deploy.fence_lease(${this.holder})`;
+            return fn(tx);
+        });
+    }
+    /** Stops renewing and drops the lease. */
+    async release() {
+        clearInterval(this.#heartbeat);
+        await this.#renewal;
+        await this.#sql `SELECT deploy.drop_lease(${this.holder})`;
+    }
+}
+/** Takes the lease or renews `holder`'s, keeping its operation; reports
+ *  it as it stands. */
+async function takeLease(sql, holder, operation) {
+    const [row] = await sql `
+    SELECT * FROM deploy.take_lease(
+      ${holder}, ${operation}::deploy.operation, ${LEASE_TTL}::interval)
+  `;
+    return row;
+}
+/** Extends `holder`'s unexpired lease; reports the lease as it stands,
+ *  undefined while free. */
+async function renewLease(sql, holder) {
+    const [{ renewed, ...row }] = await sql `
+    SELECT * FROM deploy.renew_lease(${holder}, ${LEASE_TTL}::interval)
+  `;
+    return { renewed, lease: row.holder ? row : undefined };
+}
+/** The lease; undefined while free. */
+export async function readLease(sql) {
+    const [row] = await sql `
+    SELECT lease_holder AS holder, lease_operation AS operation,
+      lease_expires_at AS expires_at
+    FROM deploy.state
+  `;
+    return row.holder ? row : undefined;
+}
+/** Drops `holder`'s lease; false when another holds it now. */
+export async function breakLease(sql, holder) {
+    const [{ dropped }] = await sql `
+    SELECT deploy.drop_lease(${holder}) AS dropped
+  `;
+    return dropped !== null;
+}

package/dist/src/main.d.ts

@@ -0,0 +1,6 @@
+import { type ReleaseApp } from "./app.ts";
+/** Runs `argv` (after the program name, carrying `--app <module>`)
+ *  against the app `load` resolves the module path to, setting
+ *  `process.exitCode`; a failure to load the app or read its targets
+ *  logs like a command's. */
+export declare function main(argv: readonly string[], load: (app: string) => ReleaseApp | Promise<ReleaseApp>): Promise<void>;

package/dist/src/main.js

@@ -0,0 +1,43 @@
+/** Runs one `deploy-release` command line for an app. */
+import { appArgs } from "@astralarium/repo-deploy-info/server";
+import { buildApplication, ExitCode, run } from "@stricli/core";
+import { PROGRAM } from "./app.js";
+import { commands } from "./commands.js";
+import { reportFailure } from "./process.js";
+/** Exit status of a usage error. */
+const USAGE_EXIT = 2;
+/** What a command line lacking `--app` reports. */
+const USAGE = `Usage: ${PROGRAM} --app <module> <command> [options]`;
+/** Runs `argv` (after the program name, carrying `--app <module>`)
+ *  against the app `load` resolves the module path to, setting
+ *  `process.exitCode`; a failure to load the app or read its targets
+ *  logs like a command's. */
+export async function main(argv, load) {
+    let args;
+    let routes;
+    try {
+        args = appArgs(argv, USAGE);
+    }
+    catch (error) {
+        reportFailure(error);
+        process.exitCode = USAGE_EXIT;
+        return;
+    }
+    const invocation = `${PROGRAM} --app ${args.app}`;
+    try {
+        routes = commands(await load(args.app), invocation);
+    }
+    catch (error) {
+        reportFailure(error);
+        return;
+    }
+    const application = buildApplication(routes, {
+        name: invocation,
+        scanner: { caseStyle: "allow-kebab-for-camel" },
+        documentation: { caseStyle: "convert-camel-to-kebab" },
+    });
+    await run(application, args.argv, { process });
+    if (process.exitCode === ExitCode.InvalidArgument ||
+        process.exitCode === ExitCode.UnknownCommand)
+        process.exitCode = USAGE_EXIT;
+}

package/dist/src/process.d.ts

@@ -0,0 +1,34 @@
+import { ExpectedError } from "@astralarium/repo-telemetry";
+/** Exit status after Ctrl-C. */
+export declare const INTERRUPT_EXIT = 130;
+/** Ctrl-C: exits `INTERRUPT_EXIT`. */
+export declare class Interrupted extends ExpectedError {
+    constructor();
+}
+/** SIGKILLs every running child. */
+export declare function killChildren(): void;
+/** Logs `error` as the command's failure and sets the exit status:
+ *  `INTERRUPT_EXIT` after Ctrl-C, else 1. */
+export declare function reportFailure(error: unknown): void;
+/** Why `signal` aborted, as an error. */
+export declare const abortReason: (signal: AbortSignal) => Error;
+/** Variables over a child's inherited environment; an undefined value
+ *  removes one. */
+export type EnvVars = Readonly<Record<string, string | undefined>>;
+/** How `run` wires a child. */
+export interface RunOptions {
+    cwd?: string;
+    env?: EnvVars;
+    /** Written to stdin; stdin is inherited otherwise. */
+    input?: string;
+    /** Resolve to stdout instead of passing it through. */
+    capture?: boolean;
+    /** Hold stderr, showing it only on failure. */
+    quiet?: boolean;
+}
+/** Runs `cmd` with `args` until it exits; resolves to its stdout when
+ *  captured. Throws on a nonzero exit, and with `signal`'s reason once it
+ *  aborts (killing the child). */
+export declare function run(cmd: string, args: readonly string[], signal: AbortSignal, { cwd, env, input, capture, quiet }?: RunOptions): Promise<string>;
+/** Resolves after `ms`; throws `signal`'s reason once it aborts. */
+export declare const sleep: (ms: number, signal: AbortSignal) => Promise<undefined>;