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

package/dist/src/commands.js

@@ -0,0 +1,651 @@
+/** `deploy-release`'s commands and their help. */
+import { readFileSync } from "node:fs";
+import { parseEnv } from "node:util";
+import { buildOf, otherSlot, parseDeployEnv, } from "@astralarium/repo-deploy-info";
+import { ExpectedError, log } from "@astralarium/repo-telemetry";
+import { buildCommand, buildRouteMap } from "@stricli/core";
+import { dbUrlVar, envNames, secretsFile, } from "./app.js";
+import { BUILDS, DEPLOYER, DEPLOYER_AND_WORKER, READS, runCheck, STATE, UPLOADS, } from "./check.js";
+import { epoch } from "./cloudflare.js";
+import { readCutovers, requireIdle, requireLiveAligned, terminateCutovers, withdrawOrphan, } from "./cutovers.js";
+import { breakLease, describeLease, readLease, } from "./lease.js";
+import { reportFailure } from "./process.js";
+import { shown } from "./provision.js";
+import { inSession, inSlots, slotSession, } from "./session.js";
+import { checkFacts, formatCheck, readFacts, summarize } from "./status.js";
+import { deployDeployer, deployNext, deployWorkers, installToken, pinCutover, preflightSecrets, promptToken, publishState, recordLiveBuild, retireBuilds, runFlow, scheduleCutover, smokeTest, TOKEN_MARGIN, tokenExpiry, triggerCutover, } from "./steps.js";
+import { secretsByScript } from "./target.js";
+import { earlierLiveVersions, readStaged, slotBuild, slotOf, } from "./web.js";
+/** Between ongoing-work checks while `stage` waits. */
+const WORK_POLL_MS = 30_000;
+/** A boolean flag; default false. */
+const toggle = (brief) => ({ kind: "boolean", brief, default: false, withNegated: false });
+/** `--force` of `stage`, `deploy`. */
+const FORCE = toggle("End the idle slot's ongoing work now, through the deployer's drain workflow");
+/** `--at` of `cutover`, `deploy`. */
+const AT = {
+    kind: "parsed",
+    parse: String,
+    optional: true,
+    placeholder: "T",
+    brief: "When the next build takes over, at most 30 days out: an ISO timestamp (2026-10-09T04:00, Pacific unless zoned), an interval (1h, 1h30m, 1d) or now; default 4 AM Pacific tomorrow",
+};
+/** `--exact-time` of `cutover`, `deploy`. */
+const EXACT_TIME = toggle("Keep T as given; T over 90 minutes out rounds to the half hour otherwise");
+/** `--build-env` of `init`, `stage`, `deploy`: one of `app`'s `buildEnv`
+ *  variables, repeatable. */
+const buildEnvFlag = (app) => {
+    const names = Object.keys(app.buildEnv ?? {});
+    return {
+        kind: "parsed",
+        parse: (value) => {
+            const at = value.indexOf("=");
+            const name = value.slice(0, at);
+            if (at >= 1 && names.includes(name))
+                return [name, value.slice(at + 1)];
+            throw new ExpectedError(`--build-env takes NAME=VALUE, NAME one of: ${names.join(", ") || "none declared"}`);
+        },
+        variadic: true,
+        optional: true,
+        placeholder: "NAME=VALUE",
+        brief: "Set a build environment variable (Build environment, below); builds see these alone",
+    };
+};
+/** Help paragraphs, then examples as summary and command line. */
+const describe = (paragraphs, examples = []) => [
+    ...paragraphs,
+    ...(examples.length
+        ? [
+            `Examples:\n${examples.map(([summary, line]) => `  # ${summary}\n  ${line}`).join("\n\n")}`,
+        ]
+        : []),
+].join("\n\n");
+/** `init`: deploys the next build to blue, its web version live alone,
+ *  and names it the live build. Refuses once a slot is live. */
+export async function runInit(s, { buildEnv } = {}) {
+    const { deployment } = s.target;
+    s.ready();
+    await s.takeLease("init");
+    await preflightSecrets(s);
+    const live = await s.cf.versionAt(deployment.webScript, 100);
+    const slot = live && slotOf(await s.cf.version(deployment.webScript, live));
+    if (slot)
+        throw new ExpectedError(`Slot ${slot} is live: already initialized.`);
+    // Blue keeps its crons and goes live at 100%; slots read the live
+    // build from the deploy state.
+    const next = await deployNext(s, "blue", buildEnv);
+    await s.cf.deploy(deployment.webScript, [{ version_id: next.version, percentage: 100 }], `init: ${next.build} on blue`);
+    await recordLiveBuild(s, next.build);
+    await retireBuilds(s, [next.build]);
+    await smokeTest(s, next.build, s.target.buildPaths, {
+        script: deployment.webScript,
+        id: next.version,
+    });
+    log.info("deploy_release.live", "Live: build {build} on {script} as web version {version}", {
+        build: next.build,
+        script: deployment.slotScripts.blue,
+        version: next.version,
+    });
+}
+/** `stage`'s checks before any change; resolves to the cutovers read.
+ *  Live alignment keeps staging off the slot the deploy state names live. */
+async function stagePreflight(s, operation) {
+    s.ready();
+    await s.takeLease(operation);
+    await preflightSecrets(s);
+    const c = await readCutovers(s);
+    requireIdle(c);
+    // A new next build would fail a scheduled cutover's verify step.
+    if (c.terminable.length)
+        throw new ExpectedError(`A cutover is scheduled (${c.terminable.join(" ")}); run ${s.cli("cancel")} first.`);
+    if (c.orphan)
+        throw new ExpectedError(`An update at ${c.orphan.at.toISOString()} belongs to ended cutover run ${c.orphan.run}; run ${s.cli("cancel")} first.`);
+    requireLiveAligned(s, c);
+    return c;
+}
+/** Deploys the next build to the idle slot at 0% beside `live`. */
+async function stageBuild(s, live, { force, buildEnv }) {
+    const idle = otherSlot(live.slot);
+    const idleScript = s.target.deployment.slotScripts[idle];
+    // The idle slot's ongoing work ends first: --force ends it through the
+    // deployer's drain workflow.
+    const idleBuild = await slotBuild(s, idle);
+    const { ongoingWork } = s.app;
+    const { drain } = s.target.flows;
+    if (idleBuild && force && drain) {
+        await deployDeployer(s);
+        await runFlow(s, drain, `drain-${idle}-${epoch()}`, { slot: idle });
+    }
+    else if (idleBuild && ongoingWork)
+        for (;;) {
+            const count = await ongoingWork(s.sql, idleBuild);
+            if (!count)
+                break;
+            log.info("deploy_release.work_wait", "{script} runs {count, plural, one {# ongoing work item} other {# ongoing work items}}; waiting{drain, select, true { (--force ends them)} other {}}", { count, script: idleScript, drain: drain !== undefined });
+            await s.sleep(WORK_POLL_MS);
+        }
+    const next = await deployNext(s, idle, buildEnv);
+    // Crons run only on the live slot; the cutover moves them.
+    await s.cf.clearCrons(idleScript);
+    // Keyed on the slots' builds, so a rerun clears leftovers.
+    await retireBuilds(s, [live.build, next.build]);
+    await s.cf.deploy(s.target.deployment.webScript, [
+        { version_id: live.id, percentage: 100 },
+        { version_id: next.version, percentage: 0 },
+    ], `stage build ${next.build} on ${idle}`);
+    await smokeTest(s, next.build, s.target.buildPaths, {
+        script: s.target.deployment.webScript,
+        id: next.version,
+    });
+    log.info("deploy_release.staged", "Next build {build} on {script} as web version {version}", { build: next.build, script: idleScript, version: next.version });
+}
+/** Throws on `--force` while `s`'s target has no drain workflow. */
+function requireDrainForForce(s, force) {
+    if (force && !s.target.flows.drain)
+        throw new ExpectedError(`--force needs a drain workflow: declare ReleaseApp.envs.${s.target.env}.drain.`);
+}
+/** `stage`: deploys the next build to the idle slot at 0%. */
+export async function runStage(s, flags) {
+    requireDrainForForce(s, flags.force);
+    const { live } = await stagePreflight(s, "stage");
+    await stageBuild(s, live, flags);
+    // Both slots now hold code, so the deployer binds both.
+    await deployDeployer(s);
+    log.info("deploy_release.next_step", "Next: {command} [--at <T>]", {
+        command: s.cli("cutover"),
+    });
+}
+/** `cutover`: schedules the switch to the staged build at `--at`. */
+export async function runCutover(s, flags) {
+    const at = pinCutover(flags.at, flags.exactTime);
+    s.requireClean();
+    await s.takeLease("cutover");
+    const c = await readCutovers(s);
+    requireIdle(c);
+    requireLiveAligned(s, c);
+    const staged = await readStaged(s, c.live);
+    const token = await promptToken(s, tokenExpiry(at));
+    await scheduleCutover(s, staged, at, token);
+}
+/** `deploy` of an in-place target: builds and deploys its workers;
+ *  an env with a database names the build live and retires older builds'
+ *  state under the deploy lease; then checks every worker serves the
+ *  build. */
+async function runDeployWorkers(s, { buildEnv }) {
+    s.ready();
+    const { workers, dbUrlVar: db } = s.target;
+    if (db)
+        await s.takeLease("deploy");
+    await preflightSecrets(s);
+    const build = await deployWorkers(s, buildEnv);
+    if (db) {
+        await recordLiveBuild(s, build);
+        await retireBuilds(s, [build]);
+    }
+    await smokeTest(s, build, [...new Set(workers.map((w) => w.buildPath))]);
+    log.info("deploy_release.live", "Live: build {build} on {scripts}", { build, scripts: workers.map((w) => w.script) });
+}
+/** `deploy`: `stage`, then `cutover`, unattended after the token prompt.
+ *  An in-place target deploys at once (`runDeployWorkers`); its
+ *  cutover flags refuse. */
+export async function runDeploy(session, flags) {
+    if (session.target.kind === "in-place") {
+        if (flags.at !== undefined || flags.exactTime || flags.force)
+            throw new ExpectedError(`${session.target.env} deploys at once: --at, --exact-time and --force apply to blue/green targets.`);
+        return runDeployWorkers(session, flags);
+    }
+    const s = slotSession(session);
+    requireDrainForForce(s, flags.force);
+    const at = pinCutover(flags.at, flags.exactTime);
+    const c = await stagePreflight(s, "deploy");
+    if (at - Date.now() < 60 * 60_000)
+        log.warn("deploy_release.cutover_soon", "the cutover is under an hour away; if staging runs past it, cuts over immediately");
+    // The token first: staging then runs unattended.
+    const token = await promptToken(s, tokenExpiry(at));
+    await stageBuild(s, c.live, flags);
+    const staged = await readStaged(s, c.live);
+    await scheduleCutover(s, staged, at, token);
+}
+/** `rollback`: switches back to the previous build now, through the
+ *  cutover workflow. Previous = the newest earlier live web version on
+ *  the other slot, while that slot still holds its build. */
+export async function runRollback(s) {
+    const { webScript, slotScripts } = s.target.deployment;
+    s.requireClean();
+    await s.takeLease("rollback");
+    const c = await readCutovers(s);
+    requireIdle(c);
+    requireLiveAligned(s, c);
+    const { live } = c;
+    const previousSlot = otherSlot(live.slot);
+    let previous;
+    for (const id of earlierLiveVersions(await s.cf.deployments(webScript), live.id)) {
+        const version = await s.cf.version(webScript, id);
+        const build = buildOf(version);
+        if (build && slotOf(version) === previousSlot) {
+            previous = { id, build };
+            break;
+        }
+    }
+    if (!previous)
+        throw new ExpectedError(`No previous version on ${previousSlot}.`);
+    if ((await slotBuild(s, previousSlot)) !== previous.build)
+        throw new ExpectedError(`${slotScripts[previousSlot]} no longer holds build '${previous.build}'.`);
+    // Token first: an abandoned prompt changes nothing. The previous version
+    // goes to 0% after the trigger's fresh read.
+    await installToken(s, await promptToken(s, tokenExpiry(Date.now())));
+    const released = await triggerCutover(s, {
+        liveVersion: live.id,
+        nextVersion: previous.id,
+        liveSlot: live.slot,
+        idleSlot: previousSlot,
+        build: previous.build,
+        cutoverAt: new Date().toISOString(),
+    }, () => s.cf.deploy(webScript, [
+        { version_id: live.id, percentage: 100 },
+        { version_id: previous.id, percentage: 0 },
+    ], `roll back to ${previous.build} on ${previousSlot}`));
+    if (released)
+        log.info("deploy_release.rolled_back", "Rolled back: build {build} is live", { build: previous.build });
+    else
+        log.info("deploy_release.rollback", "Rolling back: build {build} takes over now", {
+            build: previous.build,
+        });
+}
+/** Throws unless the live slot runs `live`'s build. */
+async function requireLiveSlotHolds(s, live) {
+    if ((await slotBuild(s, live.slot)) !== live.build)
+        throw new ExpectedError(`${s.target.deployment.slotScripts[live.slot]} no longer holds the live build '${live.build}'.`);
+}
+/** `cancel`: terminates waiting cutover runs, withdrawing their updates
+ *  and one left by an ended run, and publishes the deploy state. Resolves
+ *  whether an update or a waiting run was there to cancel. */
+export async function cancelUpdate(s) {
+    await s.takeLease("cancel");
+    const c = await readCutovers(s);
+    const then = `once it ends, ${s.cli("rollback")} switches back.`;
+    requireIdle(c, { then });
+    const { live } = c;
+    await requireLiveSlotHolds(s, live);
+    if (!c.terminable.length && !c.orphan) {
+        log.info("deploy_release.nothing_scheduled", "No update scheduled");
+        return false;
+    }
+    // Fresh read at act time: a run whose update turned due is in flight.
+    const fresh = await terminateCutovers(s, { then });
+    await withdrawOrphan(s, fresh);
+    // Publishes through settle so clients drop the notice; a failed publish
+    // warns and names settle.
+    await publishState(s, live);
+    log.info("deploy_release.cancelled", "Cancelled: no update scheduled; build {build} stays live", { build: live.build });
+    return true;
+}
+/** `settle`: aligns the deployment to the live web version. Ends finishing
+ *  cutover runs too; the steps below redo their tail. */
+export async function runSettle(s) {
+    const { slotScripts } = s.target.deployment;
+    s.requireClean();
+    await s.takeLease("settle");
+    const c = await readCutovers(s);
+    requireIdle(c, { endFinishing: true });
+    const { live } = c;
+    await requireLiveSlotHolds(s, live);
+    await terminateCutovers(s, { endFinishing: true });
+    // Live slot's crons first, then the other's clear; the live-build gate
+    // keeps one slot's crons active meanwhile.
+    await s.cf.wrangler(s.target.packages.worker, [
+        "triggers",
+        "deploy",
+        "--env",
+        s.target.env,
+        "--name",
+        slotScripts[live.slot],
+    ]);
+    await s.cf.clearCrons(slotScripts[otherSlot(live.slot)]);
+    await deployDeployer(s);
+    await runFlow(s, s.target.flows.settle, `settle-${epoch()}`, {
+        slot: live.slot,
+        build: live.build,
+    });
+    log.info("deploy_release.settled", "Settled: build {build} is live on {script}", { build: live.build, script: slotScripts[live.slot] });
+}
+/** `status`: prints the deployment's facts and checks; resolves to the
+ *  exit status, 1 on any failed check. */
+export async function runStatus(s) {
+    const facts = await readFacts(s);
+    const checks = checkFacts(facts, (c) => s.cli(c), s.target.dbUrlVar);
+    process.stdout.write([
+        ...summarize(facts, s.target.deployment.webScript),
+        "Checks:",
+        ...checks.map(formatCheck),
+        "",
+    ].join("\n"));
+    return checks.some((c) => c.level === "fail") ? 1 : 0;
+}
+/** `unlock`: breaks the deploy lease once the operator confirms (`yes`
+ *  skips the question). */
+export async function runUnlock(s, flags) {
+    const lease = await readLease(s.sql);
+    if (!lease)
+        return log.info("deploy_release.lease_free", "No lease held");
+    const held = describeLease(lease);
+    if (!flags.yes &&
+        !(await s.confirm(`Break the lease of ${held}? Its command may still run. [y/N] `)))
+        return log.info("deploy_release.lease_kept", "Left in place");
+    if (!(await breakLease(s.sql, lease.holder)))
+        throw new ExpectedError("The lease changed hands meanwhile; left in place.");
+    log.info("deploy_release.lease_broken", "Broke the lease of {holder} ({operation}, until {expires})", {
+        holder: lease.holder,
+        operation: lease.operation,
+        expires: lease.expires_at,
+    });
+}
+/** The target's secrets file by script (`secretsByScript`); the
+ *  `secrets` gate (`UPLOADS`) has checked it holds every value. */
+function readSecrets(s) {
+    const values = parseEnv(readFileSync(s.target.secretsFile, "utf8"));
+    return new Map(secretsByScript(s.target).map(([script, keys]) => [
+        script,
+        Object.fromEntries(keys.map((key) => [key, values[key]])),
+    ]));
+}
+/** `secrets` of a blue/green target: uploads to the web worker and both
+ *  slots (`SlotTarget.secrets`), web first. */
+async function uploadSlotSecrets(s, secrets) {
+    const { env, deployment, packages } = s.target;
+    await s.takeLease("secrets");
+    // A secret change deploys the latest web version at 100%, so it must
+    // be the live one.
+    const latest = (await s.cf.versions(deployment.webScript)).reduce((a, v) => (!a || v.number > a.number ? v : a), undefined);
+    const live = await s.cf.versionAt(deployment.webScript, 100);
+    if (latest && latest.id !== live)
+        throw new ExpectedError(`The latest web version (${latest.id}) is not live: stage and cut over a new build (${s.cli("deploy")}).`);
+    // Web first: only it can refuse (undeployed latest version), and a
+    // refusal leaves the slots untouched.
+    await s.cf.wrangler(packages.web, ["secret", "bulk", "--env", env], {
+        input: JSON.stringify(secrets.get(deployment.webScript)),
+    });
+    for (const script of Object.values(deployment.slotScripts))
+        await s.cf.wrangler(packages.worker, ["secret", "bulk", "--env", env, "--name", script], { input: JSON.stringify(secrets.get(script)) });
+}
+/** `secrets`: uploads the target's secrets file to each of its scripts. */
+export async function runSecrets(s) {
+    const secrets = readSecrets(s);
+    if (s.target.kind === "in-place") {
+        if (s.target.dbUrlVar)
+            await s.takeLease("secrets");
+        for (const { package: pkg, script } of s.target.workers)
+            await s.cf.wrangler(pkg, ["secret", "bulk", "--env", s.target.env], {
+                input: JSON.stringify(secrets.get(script)),
+            });
+    }
+    else
+        await uploadSlotSecrets(slotSession(s), secrets);
+    log.info("deploy_release.secrets_uploaded", "Secrets uploaded to {scripts}", { scripts: [...secrets.keys()] });
+}
+/** `--env` of every command: one of the app's `envs`. */
+const envFlag = (envs) => ({
+    kind: "parsed",
+    parse: (value) => parseDeployEnv(value, envs),
+    placeholder: "env",
+    brief: `Target environment: ${envs.join(", ")}`,
+});
+/** Help examples: each summary with its command line for `env`; none
+ *  while the app has no env of the kind. */
+const examplesFor = (env, examples) => env === undefined
+    ? []
+    : examples.map(([summary, line]) => [summary, line(env)]);
+/** Help lines of the variables the commands read: each env's database
+ *  URL, then the app's build variables. */
+function environmentHelp(app) {
+    const databases = Object.entries(app.envs).map(([env, release]) => {
+        const variable = dbUrlVar(env, release);
+        if (!variable)
+            return `  ${env}: no database`;
+        const needs = release.deploy === "blue-green"
+            ? "every command but status and check needs it"
+            : "deploy, secrets and unlock need it";
+        return `  ${variable}   ${env} database URL; ${needs}`;
+    });
+    const builds = Object.entries(app.buildEnv ?? {}).map(([name, brief]) => `  ${name}   ${brief}`);
+    return [
+        `Environment:\n${databases.join("\n")}`,
+        ...(builds.length
+            ? [`Build environment, set by --build-env:\n${builds.join("\n")}`]
+            : []),
+    ];
+}
+/** `deploy-release`'s commands against `app`'s targets; `invocation`
+ *  starts each printed command line. */
+export function commands(app, invocation) {
+    const envs = envNames(app);
+    const ENV = envFlag(envs);
+    const BUILD_ENV = buildEnvFlag(app);
+    const deploying = (deploy) => envs.find((env) => app.envs[env].deploy === deploy);
+    const slotEnv = deploying("blue-green");
+    const workerEnv = deploying("in-place");
+    const drainEnv = envs.find((env) => {
+        const release = app.envs[env];
+        return release.deploy === "blue-green" && release.drain;
+    });
+    const bootstrapping = envs.filter((env) => app.envs[env].bootstrapping).join(", ") || "none";
+    const secretsPath = shown(secretsFile(app, "<env>"));
+    const init = buildCommand({
+        docs: {
+            brief: "Deploy the first build to blue and make it live",
+            fullDescription: describe([
+                "First deploy, while no slotted version is live: deploys the next build to blue, makes it live, and records it as the live build.",
+            ]),
+        },
+        parameters: { flags: { env: ENV, buildEnv: BUILD_ENV } },
+        func: inSlots(app, invocation, BUILDS, (flags, s) => runInit(s, flags)),
+    });
+    const stage = buildCommand({
+        docs: {
+            brief: "Deploy the next build to the idle slot at 0%",
+            fullDescription: describe([
+                "Deploys the next build to the idle slot and uploads its web version at 0%. Clients see no change.",
+                "Waits out the idle slot's ongoing work first (the app's ongoingWork hook). Refuses while a cutover is scheduled.",
+            ]),
+        },
+        parameters: { flags: { env: ENV, force: FORCE, buildEnv: BUILD_ENV } },
+        func: inSlots(app, invocation, BUILDS, (flags, s) => runStage(s, flags)),
+    });
+    const cutover = buildCommand({
+        docs: {
+            brief: "Schedule the switch to the staged build",
+            fullDescription: describe([
+                "Schedules the switch to the staged build at T; the deployer's cutover workflow runs it. Rerun to reschedule.",
+                "The app shows clients the update ahead of T and closes to new work by its own lead times; with `drain`, the live slot's ongoing work ends at T.",
+                `Resolves T when the command starts (intervals and now count from then) and prompts for an API token with Workers Scripts: Edit, valid until ${TOKEN_MARGIN} past T. If T passes during the prompt, cuts over immediately; a prompt so late that the token would expire before the cutover's budget refuses. Times print in Pacific and UTC.`,
+                "Waits until the cutover run schedules the update; exits 1 when the run ends without a change (another cutover's update is due, or a later run took over).",
+            ], examplesFor(slotEnv, [
+                [
+                    "Cut over at 4 AM Pacific tomorrow",
+                    (env) => `${invocation} cutover --env ${env}`,
+                ],
+                [
+                    "Cut over 90 minutes from now",
+                    (env) => `${invocation} cutover --env ${env} --at 1h30m`,
+                ],
+                [
+                    "Cut over at 6:05 PM Pacific on Oct 9, unrounded",
+                    (env) => `${invocation} cutover --env ${env} --at 2026-10-09T18:05 --exact-time`,
+                ],
+            ])),
+        },
+        parameters: { flags: { env: ENV, at: AT, exactTime: EXACT_TIME } },
+        func: inSlots(app, invocation, DEPLOYER, (flags, s) => runCutover(s, flags)),
+    });
+    const deploy = buildCommand({
+        docs: {
+            brief: "Stage the next build, then schedule its cutover",
+            fullDescription: describe([
+                "A blue/green env: runs stage, then cutover. Resolves T when the command starts (intervals and now count from then), prompts for the token after its checks, then stages and schedules unattended.",
+                `The token is valid until ${TOKEN_MARGIN} past T, like cutover's. Warns when T is under an hour away; if staging runs past T, cuts over immediately. Staging run so late that the token would expire before the cutover's budget leaves the build staged; cutover then schedules it with a fresh token.`,
+                "An in-place env: builds every worker, deploys them in order, names the build live and retires older builds' state (an env with a database), then checks each worker serves the build; a first deploy's custom domain may take minutes to serve. A deploy failing midway leaves the earlier workers on the new build and the rest on the old one; the failure names both, and a rerun redeploys every worker.",
+            ], [
+                ...examplesFor(slotEnv, [
+                    [
+                        "Ship at 4 AM Pacific tomorrow",
+                        (env) => `${invocation} deploy --env ${env}`,
+                    ],
+                ]),
+                ...examplesFor(drainEnv, [
+                    [
+                        "Ship a hotfix now, ending the idle slot's ongoing work",
+                        (env) => `${invocation} deploy --env ${env} --at now --force`,
+                    ],
+                ]),
+                ...examplesFor(workerEnv, [
+                    ["Deploy at once", (env) => `${invocation} deploy --env ${env}`],
+                ]),
+            ]),
+        },
+        parameters: {
+            flags: {
+                env: ENV,
+                at: AT,
+                exactTime: EXACT_TIME,
+                force: FORCE,
+                buildEnv: BUILD_ENV,
+            },
+        },
+        func: inSession(app, invocation, BUILDS, (flags, s) => runDeploy(s, flags)),
+    });
+    const rollback = buildCommand({
+        docs: {
+            brief: "Switch back to the previous build now",
+            fullDescription: describe([
+                "Switches back to the previous build now, through the cutover workflow. Its slot must still hold it. With `drain`, the live slot's ongoing work ends now.",
+                "Prompts for an API token like cutover.",
+            ]),
+        },
+        parameters: { flags: { env: ENV } },
+        func: inSlots(app, invocation, DEPLOYER, (_flags, s) => runRollback(s)),
+    });
+    const cancel = buildCommand({
+        docs: {
+            brief: "Cancel the scheduled update",
+            fullDescription: describe([
+                "Cancels the scheduled update before its cutover runs: ends the waiting cutover run, withdraws the update and clears the notice; when that publish fails, settle republishes. The staged build stays staged; cutover reschedules it.",
+                "Refuses while a cutover is in progress; rollback is the path once it ends. Exits 0 when nothing is scheduled.",
+            ]),
+        },
+        parameters: { flags: { env: ENV } },
+        func: inSlots(app, invocation, STATE, async (_flags, s) => {
+            await cancelUpdate(s);
+        }),
+    });
+    const settle = buildCommand({
+        docs: {
+            brief: "Sync the deployment to the live web version",
+            fullDescription: describe([
+                "Syncs the deployment to the live (100%) web version: cancels a waiting cutover (one finishing its release included), withdraws the update notice, records the live build, and puts crons on its slot only.",
+            ]),
+        },
+        parameters: { flags: { env: ENV } },
+        func: inSlots(app, invocation, DEPLOYER_AND_WORKER, (_flags, s) => runSettle(s)),
+    });
+    const status = buildCommand({
+        docs: {
+            brief: "Check the deployment's invariants",
+            fullDescription: describe([
+                "Prints web versions and each slot's build and crons, then checks: the live slot runs the live build; the public site serves it; only the live slot holds crons (both while a cutover hands them over); the deploy state names the live build; a scheduled update has a cutover run.",
+                "Prints a fix per failure; exits 1 on any. Skips the deploy state without the database URL.",
+            ]),
+        },
+        parameters: { flags: { env: ENV } },
+        func: inSlots(app, invocation, READS, (_flags, s) => runStatus(s)),
+    });
+    const unlock = buildCommand({
+        docs: {
+            brief: "Break a deploy lease left by a dead command",
+            fullDescription: describe([
+                "Breaks the deploy lease after asking. Its command may still run. Any env with a database.",
+                "A lease expires an hour after its last renewal; the next command takes an expired lease over.",
+            ], examplesFor(slotEnv ?? workerEnv, [
+                [
+                    "Break a dead command's lease",
+                    (env) => `${invocation} unlock --env ${env}`,
+                ],
+                [
+                    "Break it from a script",
+                    (env) => `${invocation} unlock --env ${env} --yes`,
+                ],
+            ])),
+        },
+        parameters: { flags: { env: ENV, yes: toggle("Skip the confirmation") } },
+        func: inSession(app, invocation, STATE, (flags, s) => runUnlock(s, flags)),
+    });
+    const secrets = buildCommand({
+        docs: {
+            brief: "Upload the secrets file to the env's scripts",
+            fullDescription: describe([
+                `Uploads ${secretsPath} (template: ${secretsPath}.tmpl). Each script gets the keys its wrangler config's env block requires (secrets.required); a blue/green env's slots share the worker's. Creates missing scripts.`,
+                "A blue/green env requires the latest web version to be live, since a secret change deploys it: fails while a build is staged or after a rollback.",
+                "Rotating a shared session secret signs everyone out. Workers disagree on it until every upload lands; rerun after a failure.",
+            ]),
+        },
+        parameters: { flags: { env: ENV } },
+        func: inSession(app, invocation, UPLOADS, (_flags, s) => runSecrets(s)),
+    });
+    const check = buildCommand({
+        docs: {
+            brief: "List what an env still needs before deploying",
+            fullDescription: describe([
+                "Lists every provisioning gap of the env (default: every env) with its next step: env blocks, a target's fields, binding resources left malformed or at a placeholder id, bindings the top level declares and the env block lacks, secrets the app declares and the env block lacks, the secrets file and its template, the database URL variable. Reads files and the process environment only.",
+                "A placeholder id is its kind's shape with every digit zero (Hyperdrive and KV 00000000000000000000000000000000, D1 00000000-0000-0000-0000-000000000000, rate limits 0); a placeholder secret is xxxx. Other commands warn of the env's gaps and refuse on those they act on: commands deploying from config on a config gap of a package they deploy (init, stage and deploy every package; cutover and rollback the deployer; settle the deployer and the slotted worker), secrets on a secrets file gap, commands on the deploy state on an unset database URL; every command on an undeclared target.",
+                `Exits 1 on a gap of a required env; a bootstrapping env's gaps report alone (bootstrapping: ${bootstrapping}).`,
+            ], [
+                ["Check every env", `${invocation} check`],
+                ...examplesFor(workerEnv ?? slotEnv, [
+                    ["Check one env", (env) => `${invocation} check --env ${env}`],
+                ]),
+            ]),
+        },
+        parameters: {
+            flags: {
+                env: {
+                    ...ENV,
+                    optional: true,
+                    brief: `${ENV.brief}; default every env`,
+                },
+            },
+        },
+        func: (flags) => {
+            try {
+                process.exitCode = runCheck(app, flags.env ? [flags.env] : envs);
+            }
+            catch (error) {
+                reportFailure(error);
+            }
+        },
+    });
+    return buildRouteMap({
+        routes: {
+            check,
+            deploy,
+            stage,
+            cutover,
+            cancel,
+            rollback,
+            status,
+            settle,
+            unlock,
+            secrets,
+            init,
+        },
+        docs: {
+            brief: "Release each deploy env: blue/green envs stage each build on the idle worker slot, then cut over on schedule; in-place envs deploy at once.",
+            fullDescription: [
+                "Release each deploy env, as ReleaseApp.envs declares it. A blue/green env deploys each build to its idle worker slot (blue or green), then takes over at a scheduled cutover; an in-place env deploys its workers at once, through deploy, secrets, unlock and check alone.",
+                "With a blue/green env's `drain`, `--force` ends the idle slot's ongoing work through the deployer's drain workflow; cutover and rollback end the live slot's at the switch.",
+                `check lists what each env still needs (resources, secrets, database URL) with the next step; other commands warn of their env's gaps and refuse on those they act on. Bootstrapping envs, whose gaps check reports without failing: ${bootstrapping}.`,
+                ...environmentHelp(app),
+                "Changing commands of an env with a database hold the deploy lease and exit while another holds it. While a cutover runs, every blue/green command but init, status, unlock and secrets exits; while one finishes its release (clearing the old slot's crons), settle alone proceeds, ending it.",
+                "Builds need clean checkouts of every bundled repo; cutover, rollback and settle, a clean app checkout (the deployer bundles it).",
+            ].join("\n\n"),
+        },
+    });
+}

package/dist/src/cutover-at.d.ts

@@ -0,0 +1,23 @@
+/** A parsed `--at`. */
+export type AtSpec = 
+/** An instant (ms epoch): a timestamp or the default. */
+{
+    kind: "fixed";
+    at: number;
+}
+/** An offset (ms) from the moment the cutover is scheduled. */
+ | {
+    kind: "relative";
+    offsetMs: number;
+};
+/** 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 declare function parseCutoverSpec(text: string | undefined, now: number): AtSpec;
+/** 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 declare function resolveCutover(spec: AtSpec, now: number, exact?: boolean): number;
+/** `at` for an operator: the time in `CUTOVER_ZONE` and UTC, and how far
+ *  from `now`. */
+export declare function describeCutover(at: number, now: number): string;