@astralarium/repo-deploy-release 0.0.0-stage → 0.2.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,62 @@
-# Temporary Holding Version
+# `@astralarium/repo-deploy-release`
 
-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.
+Release deploy envs to Cloudflare Workers
+from the operator's machine via wrangler.
+
+```sh
+deploy-release --app <module> --help
+```
+
+Deploys require clean checkouts.
+
+```ts
+const site = {
+  deploy: "blue-green",
+  packages: { web: "web", worker: "worker" },
+  deployer: "deployer",
+} as const;
+
+export const release = defineReleaseApp({
+  // checkouts, secretsDir, …
+  envs: {
+    staging: site,
+    production: { ...site, bootstrapping: true },
+    translator: {
+      deploy: "in-place",
+      workers: [
+        { package: "worker", build: "wrangler" },
+        { package: "web", build: "vite" },
+      ],
+    },
+  },
+});
+```
+
+A `blue-green` env updates the idle slot,
+then the deployer (`@astralarium/repo-deploy-workflows`) cuts over as scheduled.
+Slots add `-blue`/`-green`;
+the generated deployer deploys as `<deployer>-<env>`.
+
+```sh
+# Cut over at 4 AM Pacific tomorrow
+deploy-release --app <module> deploy --env production
+# Cut over now, ending ongoing work
+deploy-release --app <module> deploy --env production --at now --force
+# Cut over in 90 minutes
+deploy-release --app <module> stage --env production
+deploy-release --app <module> cutover --env production --at 1h30m
+# Rollback to the previous build
+deploy-release --app <module> rollback --env production
+```
+
+An `in-place` env deploys immediately
+
+```sh
+deploy-release --app <module> deploy --env translator
+```
+
+New env: declare in `envs` with `bootstrapping: true`, then follow
+`check --env <env>` until provisioned.
+
+`testRelease` (`./testkit/release`) checks the release declaration
+against wrangler configs.

package/dist/bin/deploy-release.d.ts

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

package/dist/bin/deploy-release.js

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/** `deploy-release --app <module> <command>`: releases the app module's
+ *  `release` declaration; `--help` lists commands and env. */
+import { loadApp } from "@astralarium/repo-deploy-info/server";
+import { defineReleaseApp } from "../src/app.js";
+import { main } from "../src/main.js";
+await main(process.argv.slice(2), (app) => loadApp(app, "release", (value) => defineReleaseApp(value)));

package/dist/src/app.d.ts

@@ -0,0 +1,143 @@
+import { type Checkouts } from "@astralarium/repo-deploy-info/server";
+import type { Sql, TransactionSql } from "@astralarium/repo-postgres/sql";
+import type { EnvVars } from "./process.ts";
+/** How a worker package builds for a release. */
+export type WorkerBuild = 
+/** `pnpm --filter <package> build`: Vite bakes `DEPLOY_INFO` and writes
+ *  wrangler's redirected config for `CLOUDFLARE_ENV`. */
+"vite"
+/** `wrangler deploy --dry-run` into a bundle `requireReleaseBundle`
+ *  checks, uploaded `--no-bundle`. */
+ | "wrangler";
+/** The command name, as messages cite it. */
+export declare const PROGRAM = "deploy-release";
+/** A worker an in-place env deploys: `wrangler deploy` of its build. */
+export interface WorkerSpec {
+    /** Workspace package holding the wrangler config; its `env.<env>` block
+     *  names the script, `SITE_ORIGIN` and the required secrets. */
+    package: string;
+    build: WorkerBuild;
+    /** Vars set at deploy (`--var`), beside `BUILD`. */
+    vars?: Readonly<Record<string, string>>;
+    /** Site path this worker answers `{ build }` on; the smoke test reads
+     *  it after each deploy. Default `BUILD_JSON_PATH`. */
+    buildPath?: string;
+    /** Secrets the code reads, declared from it; an env block's
+     *  `secrets.required` lacking one is a config gap. */
+    secrets?: readonly string[];
+}
+/** Packages of a blue/green release. Each env block's script (its
+ *  `name`, else wrangler's `<top-level name>-<env>`) names the deploy. */
+export interface SlotPackages {
+    /** Web worker: Vite-built, uploaded as versions to its script. */
+    web: string;
+    /** Slotted worker: wrangler-built, deployed to `<script>-blue` and
+     *  `<script>-green`. */
+    worker: string;
+}
+/** Secrets of a blue/green release, by script. */
+export interface SlotSecrets {
+    /** The web worker's. */
+    web: readonly string[];
+    /** Each slot's. */
+    slot: readonly string[];
+}
+/** Settings every env declares beside its deploy. */
+interface EnvReleaseBase {
+    /** Variable holding the env's database URL. A blue/green env defaults
+     *  to `<ENV>_DB_URL`; an in-place env has a database only when set, and
+     *  then holds the deploy lease through `deploy` and `secrets`. */
+    dbUrlVar?: string;
+    /** Still being provisioned: `check` reports its gaps and exits 0; its
+     *  commands refuse on gaps like any env's. */
+    bootstrapping?: boolean;
+}
+/** An env staging each build on its idle slot, then cutting over on its
+ *  own schedule. */
+export interface BlueGreenEnv extends EnvReleaseBase {
+    deploy: "blue-green";
+    packages: SlotPackages;
+    /** Deployer worker `deploy-release` generates
+     *  (`@astralarium/repo-deploy-workflows/deployer`): deploys as `<deployer>-<env>`,
+     *  its workflows as `<deployer>-<env>-<flow>`. */
+    deployer: string;
+    /** Secrets the code reads, declared from it; the web or worker env
+     *  block's `secrets.required` lacking one is a config gap. */
+    secrets?: SlotSecrets;
+    /** Site paths answering `{ build }` from the web worker and the live
+     *  slot; the smoke test reads them after each stage. Default
+     *  `[BUILD_JSON_PATH]`. */
+    buildPaths?: readonly string[];
+    /** Whether the slotted worker's `OpsControl` drains its build's ongoing
+     *  work (`OpsControlRpc.drain`): the deployer binds `DEPLOYER_FLOWS.drain`,
+     *  the cutover drains the live slot, `--force` on `stage`/`deploy` drains
+     *  the idle slot. Unset, `stage`/`deploy` wait out `ongoingWork` alone. */
+    drain?: boolean;
+}
+/** An env deploying its workers at once. */
+export interface InPlaceEnv extends EnvReleaseBase {
+    deploy: "in-place";
+    /** Deployed in order. */
+    workers: readonly WorkerSpec[];
+}
+/** How one env deploys. */
+export type EnvRelease = BlueGreenEnv | InPlaceEnv;
+/** Removes the app's state of builds outside `kept`, the builds the
+ *  deployment runs after the deploy (a blue/green env: the live and the
+ *  staged build; an in-place env: the deployed build). Runs in a
+ *  transaction fenced on the deploy lease. */
+export type RetireBuilds = (tx: TransactionSql, kept: readonly string[]) => Promise<void>;
+/** Counts the work items still running on `build` (players in matches,
+ *  open sessions), 0 once there are none. `stage`/`deploy` wait for 0 on
+ *  the idle slot before replacing its build, unless `--force` (with
+ *  `drain`) ends them. */
+export type OngoingWork = (sql: Sql, build: string) => Promise<number>;
+/** The app as `deploy-release` releases it. */
+export interface ReleaseApp {
+    /** Checkouts minted into every build; `pull` siblings fast-forward
+     *  as each build command starts. */
+    checkouts: Checkouts;
+    /** Every deploy env (a deployed build's `CLOUDFLARE_ENV`) and how it
+     *  deploys. */
+    envs: Readonly<Record<string, EnvRelease>>;
+    /** Absolute directory of the `.env.<env>` secrets files `secrets`
+     *  uploads, each copied from the `.tmpl` beside it. */
+    secretsDir: string;
+    /** Wrangler config file within each package; default `wrangler.jsonc`. */
+    wranglerConfig?: string;
+    /** Process environment variables the app's builds read, with a brief
+     *  for help. A build sees those `--build-env` sets (`buildEnvOf`). */
+    buildEnv?: Readonly<Record<string, string>>;
+    /** Cleans up after each deploy of an env with a database. */
+    retireBuilds?: RetireBuilds;
+    /** Work `stage`/`deploy` wait out on the idle slot; absent, they replace
+     *  the idle slot's build at once. */
+    ongoingWork?: OngoingWork;
+    /** Retries the app's queue consumers take (`@astralarium/repo-postgres/queue`
+     *  `consumeClaimed`'s `maxRetries`); `testRelease` checks each consumer's
+     *  `max_retries` against it; unset, it checks the targets declare
+     *  no consumers. */
+    queueMaxRetries?: number;
+}
+/** `app`, validated (`releaseAppSchema`); throws `ExpectedError` naming
+ *  each problem. */
+export declare function defineReleaseApp(app: ReleaseApp): ReleaseApp;
+/** Site paths a blue/green stage smoke-tests (`BlueGreenEnv.buildPaths`). */
+export declare const slotBuildPaths: (release: BlueGreenEnv) => readonly string[];
+/** Every deploy env of `app`. */
+export declare const envNames: (app: ReleaseApp) => string[];
+/** `app`'s wrangler config file name, within each package. */
+export declare const wranglerConfigName: (app: ReleaseApp) => string;
+/** `env`'s secrets file. */
+export declare const secretsFile: (app: ReleaseApp, env: string) => string;
+/** Variable holding `env`'s database URL: its `dbUrlVar`, else
+ *  `<ENV>_DB_URL` for a blue/green env; undefined for an in-place env
+ *  without one. */
+export declare function dbUrlVar(env: string, release: BlueGreenEnv): string;
+export declare function dbUrlVar(env: string, release: EnvRelease): string | undefined;
+/** `--build-env` values: `ReleaseApp.buildEnv` variables as NAME, VALUE. */
+export type BuildEnv = readonly (readonly [name: string, value: string])[];
+/** The `buildEnv` variables of a build: `given`, the operator's other
+ *  values removed. */
+export declare const buildEnvOf: (app: ReleaseApp, given?: BuildEnv) => EnvVars;
+export {};

package/dist/src/app.js

@@ -0,0 +1,102 @@
+/** The app as `deploy-release` releases it: its declaration and the
+ *  validation every command starts from. */
+import { isAbsolute, join } from "node:path";
+import { BUILD_JSON_PATH, BUILD_VAR } from "@astralarium/repo-deploy-info";
+import { checkoutsSchema, } from "@astralarium/repo-deploy-info/server";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+import { z } from "zod";
+/** The command name, as messages cite it. */
+export const PROGRAM = "deploy-release";
+/** A non-empty string. */
+const text = z.string().min(1);
+/** A site path: starts with `/`, free of `?` and `#`. */
+const sitePath = z.string().regex(/^\/[^?#]*$/, "expected a path like /x");
+/** A hook as declared: a function. */
+const hook = () => z.custom((value) => typeof value === "function", "expected a function");
+/** Fields every env declares beside its deploy. */
+const envBase = {
+    dbUrlVar: text.optional(),
+    bootstrapping: z.boolean().optional(),
+};
+/** Vars `deploy` sets on every worker itself. */
+const RESERVED_VARS = [BUILD_VAR];
+/** `ReleaseApp` as declared. */
+const releaseAppSchema = z
+    .strictObject({
+    checkouts: checkoutsSchema,
+    envs: z
+        .record(text, z.discriminatedUnion("deploy", [
+        z.strictObject({
+            deploy: z.literal("blue-green"),
+            packages: z.strictObject({ web: text, worker: text }),
+            deployer: text,
+            secrets: z
+                .strictObject({ web: z.array(text), slot: z.array(text) })
+                .optional(),
+            buildPaths: z.array(sitePath).min(1).optional(),
+            drain: z.boolean().optional(),
+            ...envBase,
+        }),
+        z.strictObject({
+            deploy: z.literal("in-place"),
+            workers: z
+                .array(z.strictObject({
+                package: text,
+                build: z.enum(["vite", "wrangler"]),
+                vars: z.record(text, z.string()).optional(),
+                buildPath: sitePath.optional(),
+                secrets: z.array(text).optional(),
+            }))
+                .min(1),
+            ...envBase,
+        }),
+    ]))
+        .refine((envs) => Object.keys(envs).length > 0, "expected an env"),
+    secretsDir: text.refine(isAbsolute, "expected an absolute path"),
+    wranglerConfig: text.optional(),
+    buildEnv: z.record(text, text).optional(),
+    retireBuilds: hook().optional(),
+    ongoingWork: hook().optional(),
+    queueMaxRetries: z.number().int().nonnegative().optional(),
+})
+    .check((ctx) => {
+    for (const [env, release] of Object.entries(ctx.value.envs))
+        if (release.deploy === "in-place")
+            for (const [i, { vars = {} }] of release.workers.entries())
+                for (const name of Object.keys(vars))
+                    if (RESERVED_VARS.includes(name))
+                        ctx.issues.push({
+                            code: "custom",
+                            input: name,
+                            path: ["envs", env, "workers", i, "vars", name],
+                            message: "set by deploy",
+                        });
+});
+/** `app`, validated (`releaseAppSchema`); throws `ExpectedError` naming
+ *  each problem. */
+export function defineReleaseApp(app) {
+    const result = releaseAppSchema.safeParse(app);
+    if (!result.success)
+        throw new ExpectedError(`ReleaseApp:\n${z.prettifyError(result.error)}`);
+    return app;
+}
+/** Site paths a blue/green stage smoke-tests (`BlueGreenEnv.buildPaths`). */
+export const slotBuildPaths = (release) => release.buildPaths ?? [BUILD_JSON_PATH];
+/** Every deploy env of `app`. */
+export const envNames = (app) => Object.keys(app.envs);
+/** `app`'s wrangler config file name, within each package. */
+export const wranglerConfigName = (app) => app.wranglerConfig ?? "wrangler.jsonc";
+/** `env`'s secrets file. */
+export const secretsFile = (app, env) => join(app.secretsDir, `.env.${env}`);
+export function dbUrlVar(env, release) {
+    return (release.dbUrlVar ??
+        (release.deploy === "blue-green"
+            ? `${env.toUpperCase()}_DB_URL`
+            : undefined));
+}
+/** The `buildEnv` variables of a build: `given`, the operator's other
+ *  values removed. */
+export const buildEnvOf = (app, given = []) => ({
+    ...Object.fromEntries(Object.keys(app.buildEnv ?? {}).map((name) => [name, undefined])),
+    ...Object.fromEntries(given),
+});

package/dist/src/bundle.d.ts

@@ -0,0 +1,18 @@
+/** A deployed env's bundle build inputs. */
+export interface ReleaseBundle {
+    env: string;
+    /** JSON `DeployInfo` the bundle bakes in; a worker reading none
+     *  (the deployer) leaves it out. */
+    deployInfo?: string;
+}
+/** `wrangler` args building the minified worker bundle into `outdir`:
+ *  for `release`'s env, else the top-level dev config. */
+export declare function workerBundleArgs(outdir: string, release?: ReleaseBundle): string[];
+/** The sources a source map in `mapDir` lists, as absolute paths. */
+export declare function bundleSources(sourceMap: string, mapDir: string): string[];
+/** The dev-only and test support sources a source map in `mapDir`
+ *  lists, relative to the workspace root. */
+export declare function devTestSources(sourceMap: string, mapDir: string): string[];
+/** Throws when the worker bundle in `outdir` lists dev-only or test
+ *  support sources in its source map. */
+export declare function requireReleaseBundle(outdir: string): Promise<void>;

package/dist/src/bundle.js

@@ -0,0 +1,41 @@
+/** Release checks of a built worker bundle. */
+import { readFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { isDevFile, isTestFile } from "@astralarium/repo-package-files";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+import { ownWorkspaceRoot } from "./workspace.js";
+/** `wrangler` args building the minified worker bundle into `outdir`:
+ *  for `release`'s env, else the top-level dev config. */
+export function workerBundleArgs(outdir, release) {
+    return [
+        "deploy",
+        "--dry-run",
+        "--outdir",
+        outdir,
+        "--minify",
+        ...(release ? ["--env", release.env] : []),
+        ...(release?.deployInfo !== undefined
+            ? ["--define", `__DEPLOY_INFO__:${release.deployInfo}`]
+            : []),
+    ];
+}
+/** The sources a source map in `mapDir` lists, as absolute paths. */
+export function bundleSources(sourceMap, mapDir) {
+    const { sources, sourceRoot = "" } = JSON.parse(sourceMap);
+    return sources.map((source) => resolve(mapDir, sourceRoot, source));
+}
+/** The dev-only and test support sources a source map in `mapDir`
+ *  lists, relative to the workspace root. */
+export function devTestSources(sourceMap, mapDir) {
+    return bundleSources(sourceMap, mapDir)
+        .filter((path) => isDevFile(path) || isTestFile(path))
+        .map((path) => relative(ownWorkspaceRoot(), path));
+}
+/** Throws when the worker bundle in `outdir` lists dev-only or test
+ *  support sources in its source map. */
+export async function requireReleaseBundle(outdir) {
+    const map = await readFile(join(outdir, "index.js.map"), "utf8");
+    const found = devTestSources(map, outdir);
+    if (found.length)
+        throw new ExpectedError(`The worker bundle carries dev or test code (${found.join(", ")}); its env must define import.meta.env.DEV false in the worker's wrangler config, and shipped code loads dev modules only through import() under it.`);
+}

package/dist/src/check.d.ts

@@ -0,0 +1,44 @@
+import { type ReleaseApp } from "./app.ts";
+import type { EnvVars } from "./process.ts";
+import { type Gap } from "./provision.ts";
+import { type Target } from "./target.ts";
+/** What holds a command up; its env's other gaps warn. */
+export interface Needs {
+    /** Gap areas holding it up. */
+    readonly areas: readonly Gap["area"][];
+    /** Packages of `target` the command deploys from: config gaps of other
+     *  packages warn. Default: every package. */
+    readonly deploys?: (target: Target) => readonly string[];
+}
+/** Needs of a command deploying builds (`init`, `stage`, `deploy`):
+ *  every package's config and the deploy state's database. */
+export declare const BUILDS: Needs;
+/** Needs of a command deploying the generated deployer alone
+ *  (`cutover`, `rollback`): a resolved target and the deploy state's
+ *  database; package config gaps warn. */
+export declare const DEPLOYER: Needs;
+/** Needs of `settle`: the worker's config (its crons deploy from it)
+ *  and the deploy state's database. */
+export declare const DEPLOYER_AND_WORKER: Needs;
+/** Needs of a command on the deploy state alone. */
+export declare const STATE: Needs;
+/** Needs of `secrets`: the secrets file and the deploy state's database. */
+export declare const UPLOADS: Needs;
+/** Needs of a command reading alone (`status`): none. */
+export declare const READS: Needs;
+/** Every gap of `env` (`provisioning`). */
+export declare const envGaps: (app: ReleaseApp, env: string, environment?: EnvVars) => Gap[];
+/** True for an env `app` marks bootstrapping. */
+export declare const isBootstrapping: (app: ReleaseApp, env: string) => boolean;
+/** The app's test of its declaration against what the repo commits:
+ *  throws `ExpectedError` listing each config gap of a required env, each
+ *  template gap of any env, and each bootstrapping env whose configs hold
+ *  no gap. Secrets files and the process environment stay unread. */
+export declare function assertReleaseConfig(app: ReleaseApp): void;
+/** `env`'s target for a command held up by gaps in `needs`: logs every
+ *  other gap as a warning. Throws `unprovisioned` while a gap in `needs`
+ *  holds it up, or a config gap leaves the target undeclared. */
+export declare function provisionedTarget(app: ReleaseApp, invocation: string, env: string, needs: Needs, environment?: EnvVars): Target;
+/** `check`: prints every gap of `envs`; returns the exit status, 1 on a
+ *  gap of an env other than a bootstrapping one. */
+export declare function runCheck(app: ReleaseApp, envs: readonly string[], environment?: EnvVars): number;

package/dist/src/check.js

@@ -0,0 +1,128 @@
+/** Each env's provisioning gaps, read from its wrangler configs, secrets
+ *  files and the process environment: `deploy-release check`, and the
+ *  gate every other command passes. */
+import { ExpectedError, log } from "@astralarium/repo-telemetry";
+import { envNames } from "./app.js";
+import { databaseGap, secretsGaps, templateGaps, unprovisioned, } from "./provision.js";
+import { resolveTarget, secretsByScript } from "./target.js";
+/** Needs of a command deploying builds (`init`, `stage`, `deploy`):
+ *  every package's config and the deploy state's database. */
+export const BUILDS = { areas: ["config", "database"] };
+/** Needs of a command deploying the generated deployer alone
+ *  (`cutover`, `rollback`): a resolved target and the deploy state's
+ *  database; package config gaps warn. */
+export const DEPLOYER = {
+    areas: ["config", "database"],
+    deploys: () => [],
+};
+/** Needs of `settle`: the worker's config (its crons deploy from it)
+ *  and the deploy state's database. */
+export const DEPLOYER_AND_WORKER = {
+    areas: ["config", "database"],
+    deploys: (target) => target.kind === "blue-green" ? [target.packages.worker] : [],
+};
+/** Needs of a command on the deploy state alone. */
+export const STATE = { areas: ["database"] };
+/** Needs of `secrets`: the secrets file and the deploy state's database. */
+export const UPLOADS = { areas: ["secrets", "database"] };
+/** Needs of a command reading alone (`status`): none. */
+export const READS = { areas: [] };
+/** Every secret `target`'s scripts hold, once each. */
+const secretKeys = (target) => [
+    ...new Set(secretsByScript(target).flatMap(([, keys]) => keys)),
+];
+/** `env`'s target (`resolveTarget`) and every gap: its wrangler configs',
+ *  then, once those declare its target, its secrets template's, its
+ *  secrets file's and its database variable's in `environment`. */
+function provisioning(app, env, environment = process.env) {
+    const { target, gaps } = resolveTarget(app, env);
+    if (!target)
+        return { gaps };
+    const keys = secretKeys(target);
+    gaps.push(...templateGaps(target.secretsFile, keys), ...secretsGaps(target.secretsFile, keys));
+    if (target.dbUrlVar && !environment[target.dbUrlVar])
+        gaps.push(databaseGap(env, target.dbUrlVar));
+    return { target, gaps };
+}
+/** Every gap of `env` (`provisioning`). */
+export const envGaps = (app, env, environment = process.env) => provisioning(app, env, environment).gaps;
+/** True for an env `app` marks bootstrapping. */
+export const isBootstrapping = (app, env) => app.envs[env]?.bootstrapping ?? false;
+/** The app's test of its declaration against what the repo commits:
+ *  throws `ExpectedError` listing each config gap of a required env, each
+ *  template gap of any env, and each bootstrapping env whose configs hold
+ *  no gap. Secrets files and the process environment stay unread. */
+export function assertReleaseConfig(app) {
+    const problems = [];
+    for (const env of envNames(app)) {
+        const bootstrapping = isBootstrapping(app, env);
+        const { target, gaps } = resolveTarget(app, env);
+        if (bootstrapping && !gaps.length)
+            problems.push(`${env}: provisioned; drop ReleaseApp.envs.${env}.bootstrapping`);
+        const reported = [
+            ...(bootstrapping ? [] : gaps),
+            ...(target ? templateGaps(target.secretsFile, secretKeys(target)) : []),
+        ];
+        for (const g of reported)
+            problems.push(`${env}: ${g.where} ${g.problem}`, `  next: ${g.step}`);
+    }
+    if (problems.length)
+        throw new ExpectedError(["ReleaseApp disagrees with the repo:", ...problems].join("\n"));
+}
+/** True when `gap` holds up a command with `needs` on `target`. */
+function holds(gap, needs, target) {
+    if (!needs.areas.includes(gap.area))
+        return false;
+    const deployed = needs.deploys?.(target);
+    return (gap.area !== "config" ||
+        !gap.package ||
+        !deployed ||
+        deployed.includes(gap.package));
+}
+/** `env`'s target for a command held up by gaps in `needs`: logs every
+ *  other gap as a warning. Throws `unprovisioned` while a gap in `needs`
+ *  holds it up, or a config gap leaves the target undeclared. */
+export function provisionedTarget(app, invocation, env, needs, environment = process.env) {
+    const { target, gaps } = provisioning(app, env, environment);
+    const holding = gaps.filter((g) => target ? holds(g, needs, target) : g.area === "config");
+    for (const { where, problem } of gaps.filter((g) => !holding.includes(g)))
+        log.warn("deploy_release.gap", "{env}: {where} {problem}", {
+            env,
+            where,
+            problem,
+        });
+    if (!target || holding.length)
+        throw unprovisioned(invocation, env, holding);
+    if (gaps.length)
+        log.warn("deploy_release.gap_steps", "{check} lists each next step", { check: `${invocation} check --env ${env}` });
+    return target;
+}
+/** `env`'s gaps as `check` prints them: a heading, marking a
+ *  bootstrapping env, then each gap over its next step. */
+function formatGaps(env, gaps, bootstrapping = false) {
+    if (!gaps.length)
+        return [
+            bootstrapping
+                ? `${env}: provisioned; drop ReleaseApp.envs.${env}.bootstrapping`
+                : `${env}: provisioned`,
+        ];
+    const count = `${gaps.length} ${gaps.length === 1 ? "gap" : "gaps"}`;
+    return [
+        bootstrapping ? `${env}: bootstrapping, ${count}` : `${env}: ${count}`,
+        ...gaps.flatMap((g) => [
+            `  ${g.where} ${g.problem}`,
+            `    next: ${g.step}`,
+        ]),
+    ];
+}
+/** `check`: prints every gap of `envs`; returns the exit status, 1 on a
+ *  gap of an env other than a bootstrapping one. */
+export function runCheck(app, envs, environment = process.env) {
+    const reports = envs.map((env) => ({
+        env,
+        gaps: envGaps(app, env, environment),
+        bootstrapping: isBootstrapping(app, env),
+    }));
+    process.stdout.write(`${reports.flatMap((r) => formatGaps(r.env, r.gaps, r.bootstrapping)).join("\n")}\n`);
+    return reports.some((r) => r.gaps.length && !r.bootstrapping) ? 1 : 0;
+}

package/dist/src/cloudflare.d.ts

@@ -0,0 +1,70 @@
+/** Cloudflare as `deploy-release` reaches it: reads and simple writes
+ *  through the API under wrangler's login; bundling and config-driven
+ *  writes through wrangler. */
+import { type DeploymentRecord, type DeploymentVersion, type WorkerVersion } from "@astralarium/repo-deploy-info";
+import { type RunOptions } from "./process.ts";
+/** A workflow instance status. */
+export type InstanceStatus = "queued" | "running" | "paused" | "errored" | "terminated" | "complete" | "waiting" | "waitingForPause";
+/** A workflow instance as the API reports it. */
+export interface InstanceRecord {
+    status: InstanceStatus;
+    /** What the run returned, once complete. */
+    output?: unknown;
+}
+/** Statuses of a cutover past its sleep: it finishes or compensates. */
+export declare const RUNNING: readonly InstanceStatus[];
+/** Statuses of a cutover waiting for its time, or retrying a step. */
+export declare const WAITING: readonly InstanceStatus[];
+/** Unix seconds, for workflow instance ids. */
+export declare const epoch: () => number;
+/** Version id at `percentage` in `deployment`. */
+export declare const idAt: (deployment: DeploymentRecord | undefined, percentage: number) => string | undefined;
+/** How `Cloudflare.wrangler` runs wrangler. */
+export interface WranglerOptions extends RunOptions {
+    /** Reads the config a Vite build redirected wrangler to
+     *  (`.wrangler/deploy/config.json`) over the package's own. */
+    redirected?: boolean;
+    /** Config file path over the package's own. */
+    config?: string;
+}
+/** The account wrangler is logged into. */
+export declare class Cloudflare {
+    #private;
+    constructor(signal: AbortSignal, pkg: string, config: string);
+    /** Runs wrangler in workspace package `pkg`'s directory on its config
+     *  file (`--config`): an entry path in `args` would move wrangler's
+     *  lookup to the entry's directory. */
+    wrangler(pkg: string, args: readonly string[], { redirected, config, ...options }?: WranglerOptions): Promise<string>;
+    /** The id of the one account wrangler reaches. */
+    accountId(): Promise<string>;
+    /** Wrangler's OAuth token, reused `TOKEN_REUSE_MS`; a failed read is
+     *  retried by the next call. */
+    token(): Promise<string>;
+    /** One API call, as `CfApi`. */
+    api<T>(method: "GET" | "PUT" | "POST" | "PATCH", path: string, body?: unknown): Promise<T>;
+    /** `script`'s deployments, newest first; none when it is absent. */
+    deployments(script: string): Promise<DeploymentRecord[]>;
+    /** Version of `script` at `percentage` in its latest deployment. */
+    versionAt(script: string, percentage: number): Promise<string | undefined>;
+    /** Version `id` of `script`. */
+    version(script: string, id: string): Promise<WorkerVersion>;
+    /** `script`'s recent deployable versions; none when it is absent. */
+    versions(script: string): Promise<WorkerVersion[]>;
+    /** Names of `script`'s secrets; none when it is absent. */
+    secretNames(script: string): Promise<string[]>;
+    /** `script`'s cron expressions. */
+    crons(script: string): Promise<string[]>;
+    /** Clears `script`'s crons. */
+    clearCrons(script: string): Promise<void>;
+    /** Deploys `versions` of `script`. */
+    deploy(script: string, versions: readonly DeploymentVersion[], message: string): Promise<void>;
+    /** Ids of workflow `flow`'s instances in `status`; none while the
+     *  workflow is absent. */
+    instances(flow: string, status: InstanceStatus): Promise<string[]>;
+    /** Starts workflow `flow` as instance `id` with `params`. */
+    trigger(flow: string, id: string, params: unknown): Promise<void>;
+    /** Instance `id` of workflow `flow`. */
+    instance(flow: string, id: string): Promise<InstanceRecord>;
+    /** Terminates instance `id` of workflow `flow`. */
+    terminate(flow: string, id: string): Promise<void>;
+}