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

package/dist/src/target.js

@@ -0,0 +1,246 @@
+/** What `deploy-release` releases: each env's target, read from the
+ *  wrangler configs that deploy it. */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { BUILD_JSON_PATH, parseDeployEnv, } from "@astralarium/repo-deploy-info";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+import JSON5 from "json5";
+import { dbUrlVar, envNames, secretsFile, slotBuildPaths, wranglerConfigName, } from "./app.js";
+import { bindingGaps, shown } from "./provision.js";
+import { packageDir } from "./workspace.js";
+/** Workspace package `pkg`'s wrangler config path. */
+export const wranglerConfig = (app, pkg) => join(packageDir(pkg), wranglerConfigName(app));
+/** The wrangler config at `path`; undefined while the file is missing,
+ *  throws on one that is not JSON5. */
+function readWrangler(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        return JSON5.parse(readFileSync(path, "utf8"));
+    }
+    catch (e) {
+        throw new ExpectedError(`${path} is not JSON5: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+    }
+}
+/** `pkg`'s `env.<env>` block as written; undefined while its config or
+ *  the block is missing. */
+export const readEnvBlock = (app, pkg, env) => readWrangler(wranglerConfig(app, pkg))?.env?.[env];
+/** Secrets `block` requires (`secrets.required`); `declared`, the app's
+ *  declaration at `at`, must be among them, each one lacking a gap added
+ *  to `gaps`. */
+function requiredSecrets(block, declared, at, gaps) {
+    if (!block)
+        return [];
+    const required = block.env.secrets?.required ?? [];
+    const lacking = declared.filter((key) => !required.includes(key));
+    if (lacking.length) {
+        const them = lacking.length === 1 ? "it" : "them";
+        gaps.push({
+            area: "config",
+            package: block.package,
+            where: `${block.where} secrets.required`,
+            problem: `lacks ${lacking.join(", ")}, declared in ${at}`,
+            step: `Add ${them} here: secrets uploads what the env block requires.`,
+        });
+    }
+    return required;
+}
+/** `pkg`'s `env.<env>` block, its binding and name gaps added to `gaps`;
+ *  undefined, the gap added, while its config or block is missing. Each
+ *  gap names `pkg`. */
+function envBlock(app, pkg, env, gaps) {
+    const path = wranglerConfig(app, pkg);
+    const config = readWrangler(path);
+    if (!config) {
+        gaps.push({
+            area: "config",
+            package: pkg,
+            where: shown(path),
+            problem: "is missing",
+            step: `Write ${pkg}'s wrangler config with an env.${env} block.`,
+        });
+        return undefined;
+    }
+    const file = shown(path);
+    const where = `${file} env.${env}`;
+    const block = config.env?.[env];
+    if (!block) {
+        gaps.push({
+            area: "config",
+            package: pkg,
+            where,
+            problem: "is missing",
+            step: "Add it: its vars and every binding the top level declares.",
+        });
+        return undefined;
+    }
+    gaps.push(...bindingGaps(block, config, where).map((g) => ({ ...g, package: pkg })));
+    const base = text(config.name);
+    const script = text(block.name) ?? (base && `${base}-${env}`);
+    if (!script)
+        gaps.push({
+            area: "config",
+            package: pkg,
+            where,
+            problem: "lacks name",
+            step: "Name the script: the top-level name (deploying as <name>-<env>) or the env block's.",
+        });
+    return { env: block, where, package: pkg, script, top: config, file };
+}
+/** A non-empty string, else undefined. */
+const text = (value) => typeof value === "string" && value ? value : undefined;
+/** Site origin `block` names (`vars.SITE_ORIGIN`); undefined, the gap
+ *  added to `gaps`, while unset. */
+function siteOriginOf(block, gaps) {
+    const origin = text(block.env.vars?.SITE_ORIGIN);
+    if (!origin)
+        gaps.push({
+            area: "config",
+            package: block.package,
+            where: block.where,
+            problem: "lacks vars.SITE_ORIGIN",
+            step: "Set vars.SITE_ORIGIN to the site's origin (https://host).",
+        });
+    return origin;
+}
+/** Runtime `block` deploys on: its `compatibility_date` and
+ *  `compatibility_flags`, else the top level's; undefined, the gap added
+ *  to `gaps`, while the date is unset. */
+function runtimeOf(block, gaps) {
+    const compatibilityDate = text(block.env.compatibility_date ?? block.top.compatibility_date);
+    if (!compatibilityDate) {
+        gaps.push({
+            area: "config",
+            package: block.package,
+            where: block.file,
+            problem: "lacks compatibility_date",
+            step: "Set the worker's compatibility_date at the top level.",
+        });
+        return undefined;
+    }
+    return {
+        compatibilityDate,
+        compatibilityFlags: block.env.compatibility_flags ?? block.top.compatibility_flags ?? [],
+    };
+}
+/** The blue/green target of `env`, its gaps added to `gaps`; undefined
+ *  while a gap leaves a piece of it undeclared. */
+function slotTarget(app, env, release, gaps) {
+    const { packages, secrets: declared, drain } = release;
+    const webBlock = envBlock(app, packages.web, env, gaps);
+    const workerBlock = envBlock(app, packages.worker, env, gaps);
+    const secrets = {
+        web: requiredSecrets(webBlock, declared?.web ?? [], `ReleaseApp.envs.${env}.secrets.web`, gaps),
+        slot: requiredSecrets(workerBlock, declared?.slot ?? [], `ReleaseApp.envs.${env}.secrets.slot`, gaps),
+    };
+    const siteOrigin = webBlock && siteOriginOf(webBlock, gaps);
+    const runtime = workerBlock && runtimeOf(workerBlock, gaps);
+    if (!webBlock?.script || !workerBlock?.script || !siteOrigin || !runtime)
+        return undefined;
+    const slotBase = workerBlock.script;
+    const deployer = `${release.deployer}-${env}`;
+    const flow = (name) => `${deployer}-${name}`;
+    return {
+        kind: "blue-green",
+        env,
+        packages,
+        deployment: {
+            webScript: webBlock.script,
+            slotScripts: { blue: `${slotBase}-blue`, green: `${slotBase}-green` },
+            siteOrigin,
+        },
+        siteOrigin,
+        deployer,
+        runtime,
+        flows: {
+            cutover: flow("cutover"),
+            settle: flow("settle"),
+            drain: drain ? flow("drain") : undefined,
+        },
+        secrets,
+        buildPaths: slotBuildPaths(release),
+        dbUrlVar: dbUrlVar(env, release),
+        secretsFile: secretsFile(app, env),
+    };
+}
+/** `spec`, the `index`th worker of `env`, as its wrangler config deploys
+ *  it, with its site; its gaps added to `gaps`. */
+function releasedWorker(app, env, spec, index, gaps) {
+    const block = envBlock(app, spec.package, env, gaps);
+    if (!block)
+        return undefined;
+    const { script } = block;
+    const siteOrigin = siteOriginOf(block, gaps);
+    const secrets = requiredSecrets(block, spec.secrets ?? [], `ReleaseApp.envs.${env}.workers[${index}].secrets`, gaps);
+    if (!script || !siteOrigin)
+        return undefined;
+    return [
+        {
+            ...spec,
+            script,
+            secrets,
+            buildPath: spec.buildPath ?? BUILD_JSON_PATH,
+        },
+        siteOrigin,
+    ];
+}
+/** The in-place target of `env`, its gaps added to `gaps`; its workers
+ *  must agree on the site. */
+function workerTarget(app, env, release, gaps) {
+    const released = release.workers.map((spec, i) => releasedWorker(app, env, spec, i, gaps));
+    const resolved = released.filter((r) => r !== undefined);
+    if (resolved.length < released.length)
+        return undefined;
+    const [, siteOrigin] = resolved[0];
+    if (resolved.some(([, origin]) => origin !== siteOrigin)) {
+        gaps.push({
+            area: "config",
+            where: `env.${env} vars.SITE_ORIGIN`,
+            problem: `differs between workers: ${resolved
+                .map(([w, origin]) => `${w.package} ${origin}`)
+                .join(", ")}`,
+            step: "Set one site origin in every worker's env block.",
+        });
+        return undefined;
+    }
+    return {
+        kind: "in-place",
+        env,
+        workers: resolved.map(([worker]) => worker),
+        siteOrigin,
+        secretsFile: secretsFile(app, env),
+        dbUrlVar: dbUrlVar(env, release),
+    };
+}
+/** `env`'s declared release; throws on an env outside `app.envs`. */
+const envRelease = (app, env) => app.envs[parseDeployEnv(env, envNames(app))];
+/** `env`'s target as its wrangler configs declare it, and every gap in
+ *  those configs; the target is undefined while a gap leaves a piece of
+ *  it undeclared. Throws on an env outside `app.envs`. */
+export function resolveTarget(app, env) {
+    const gaps = [];
+    const release = envRelease(app, env);
+    const target = release.deploy === "in-place"
+        ? workerTarget(app, env, release, gaps)
+        : slotTarget(app, env, release, gaps);
+    return { target, gaps };
+}
+/** Each script of `target` with the secrets it holds. */
+export function secretsByScript(target) {
+    if (target.kind === "in-place")
+        return target.workers.map((w) => [w.script, w.secrets]);
+    const { webScript, slotScripts } = target.deployment;
+    const { secrets } = target;
+    return [
+        [webScript, secrets.web],
+        [slotScripts.blue, secrets.slot],
+        [slotScripts.green, secrets.slot],
+    ];
+}
+/** The scripts of `target`. */
+export const scriptsOf = (target) => target.kind === "in-place"
+    ? target.workers.map((w) => w.script)
+    : [
+        target.deployment.webScript,
+        ...Object.values(target.deployment.slotScripts),
+    ];

package/dist/src/web.d.ts

@@ -0,0 +1,28 @@
+/** Web versions and slot builds: which build is live, which is next. */
+import { type DeploymentRecord, type Slot, type WorkerVersion } from "@astralarium/repo-deploy-info";
+import type { SlotSession } from "./session.ts";
+/** A web version with its slot and build. */
+export interface WebVersion {
+    id: string;
+    slot: Slot;
+    build: string;
+}
+/** The live web version and the next one staged beside it. */
+export interface Staged {
+    live: WebVersion;
+    next: WebVersion;
+}
+/** Slot of web `version` (its `SLOT` var); undefined when unslotted. */
+export declare const slotOf: (version: WorkerVersion) => Slot | undefined;
+/** Build of `slot`'s version at 100%; undefined when none is deployed. */
+export declare function slotBuild(s: SlotSession, slot: Slot): Promise<string | undefined>;
+/** The 100% web version; throws unless it has a slot and build. */
+export declare function readLive(s: SlotSession): Promise<WebVersion>;
+/** `live` and the 0% web version of the latest deployment; throws unless
+ *  the 0% one is a build on the other slot, which still runs it. */
+export declare function readStaged(s: SlotSession, live: WebVersion): Promise<Staged>;
+/** Versions once at 100%, newest deployment first, other than `live`. */
+export declare function earlierLiveVersions(deployments: readonly DeploymentRecord[], live: string): string[];
+/** Version id of the `version-upload` entry in wrangler's output-file
+ *  `jsonl`; throws when absent. */
+export declare function uploadedVersionId(jsonl: string): string;

package/dist/src/web.js

@@ -0,0 +1,70 @@
+/** Web versions and slot builds: which build is live, which is next. */
+import { buildOf, isSlot, SLOT_VAR, varOf, } from "@astralarium/repo-deploy-info";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+import { idAt } from "./cloudflare.js";
+/** Slot of web `version` (its `SLOT` var); undefined when unslotted. */
+export const slotOf = (version) => {
+    const slot = varOf(version, SLOT_VAR);
+    return isSlot(slot) ? slot : undefined;
+};
+/** Build of `slot`'s version at 100%; undefined when none is deployed. */
+export async function slotBuild(s, slot) {
+    const script = s.target.deployment.slotScripts[slot];
+    const id = await s.cf.versionAt(script, 100);
+    return id && buildOf(await s.cf.version(script, id));
+}
+/** The web script's latest deployment. */
+const latestWeb = async (s) => (await s.cf.deployments(s.target.deployment.webScript))[0];
+/** The 100% web version; throws unless it has a slot and build. */
+export async function readLive(s) {
+    const web = s.target.deployment.webScript;
+    const id = idAt(await latestWeb(s), 100);
+    if (!id)
+        throw new ExpectedError(`No version of ${web} is live: run ${s.cli("init")}.`);
+    const version = await s.cf.version(web, id);
+    const slot = slotOf(version);
+    const build = buildOf(version);
+    if (!slot || !build)
+        throw new ExpectedError(`No slotted build is live: run ${s.cli("init")}.`);
+    return { id, slot, build };
+}
+/** `live` and the 0% web version of the latest deployment; throws unless
+ *  the 0% one is a build on the other slot, which still runs it. */
+export async function readStaged(s, live) {
+    const web = s.target.deployment.webScript;
+    const id = idAt(await latestWeb(s), 0);
+    if (!id)
+        throw new ExpectedError(`No next build: run ${s.cli("stage")}.`);
+    const version = await s.cf.version(web, id);
+    const slot = slotOf(version);
+    const build = buildOf(version);
+    if (!slot || !build)
+        throw new ExpectedError(`The 0% version (${id}) is not a valid next build: slot '${slot ?? ""}', build '${build ?? ""}'.`);
+    if (slot === live.slot)
+        throw new ExpectedError(`The 0% version (${id}) is on the live slot (${slot}): run ${s.cli("stage")}.`);
+    const held = await slotBuild(s, slot);
+    if (held !== build)
+        throw new ExpectedError(`${s.target.deployment.slotScripts[slot]} runs build '${held ?? ""}', not the staged '${build}': run ${s.cli("stage")}.`);
+    return { live, next: { id, slot, build } };
+}
+/** Versions once at 100%, newest deployment first, other than `live`. */
+export function earlierLiveVersions(deployments, live) {
+    const ids = deployments
+        .toSorted((a, b) => Date.parse(b.created_on) - Date.parse(a.created_on))
+        .flatMap((d) => d.versions.filter((v) => v.percentage === 100))
+        .map((v) => v.version_id)
+        .filter((id) => id !== live);
+    return [...new Set(ids)];
+}
+/** Version id of the `version-upload` entry in wrangler's output-file
+ *  `jsonl`; throws when absent. */
+export function uploadedVersionId(jsonl) {
+    const upload = jsonl
+        .split("\n")
+        .filter((line) => line.trim())
+        .map((line) => JSON.parse(line))
+        .find((entry) => entry.type === "version-upload");
+    if (!upload?.version_id)
+        throw new Error("versions upload reported no version id");
+    return upload.version_id;
+}

package/dist/src/workspace.d.ts

@@ -0,0 +1,11 @@
+/** Nearest directory at or above `from` holding `pnpm-workspace.yaml`;
+ *  throws `ExpectedError` outside a workspace. */
+export declare function requireWorkspaceRoot(from: string): string;
+/** Root of the workspace holding this package: linked from its
+ *  `packages/`, or installed under its `node_modules/`. Found on first
+ *  use, so a package outside a workspace fails inside a command, where
+ *  `main` reports it. */
+export declare function ownWorkspaceRoot(): string;
+/** Directory of package `name` of the workspace at `root` (this
+ *  package's by default); throws when the workspace lacks it. */
+export declare function packageDir(name: string, root?: string): string;

package/dist/src/workspace.js

@@ -0,0 +1,40 @@
+/** The pnpm workspace this package is installed in: its root and its
+ *  packages' directories by name. */
+import { workspacePackages, workspaceRoot, } from "@astralarium/repo-package-files";
+import { ExpectedError } from "@astralarium/repo-telemetry";
+/** Nearest directory at or above `from` holding `pnpm-workspace.yaml`;
+ *  throws `ExpectedError` outside a workspace. */
+export function requireWorkspaceRoot(from) {
+    const root = workspaceRoot(from);
+    if (root === undefined)
+        throw new ExpectedError(`${from} is outside a pnpm workspace`);
+    return root;
+}
+/** `ownWorkspaceRoot()` once found. */
+let ownRoot;
+/** Root of the workspace holding this package: linked from its
+ *  `packages/`, or installed under its `node_modules/`. Found on first
+ *  use, so a package outside a workspace fails inside a command, where
+ *  `main` reports it. */
+export function ownWorkspaceRoot() {
+    return (ownRoot ??= requireWorkspaceRoot(import.meta.dirname));
+}
+/** Directory of each named package, by workspace root; read once per
+ *  root. */
+const packagesByRoot = new Map();
+/** Directory of package `name` of the workspace at `root` (this
+ *  package's by default); throws when the workspace lacks it. */
+export function packageDir(name, root = ownWorkspaceRoot()) {
+    let packages = packagesByRoot.get(root);
+    if (!packages) {
+        packages = new Map();
+        for (const { dir, manifest } of workspacePackages(root))
+            if (typeof manifest.name === "string")
+                packages.set(manifest.name, dir);
+        packagesByRoot.set(root, packages);
+    }
+    const dir = packages.get(name);
+    if (!dir)
+        throw new ExpectedError(`${name} is not a package of the workspace at ${root}.`);
+    return dir;
+}

package/dist/testkit/index.d.ts

@@ -0,0 +1,4 @@
+/** Holds the deploy state's row of the database at `connectionString` for
+ *  the enclosing suite via an advisory lock; each test starts with it
+ *  clear, and the suite leaves it clear. */
+export declare function holdDeployState(connectionString: string): void;

package/dist/testkit/index.js

@@ -0,0 +1,36 @@
+/** Test support: the deploy state's one row (`deploy.state`), shared
+ *  by every suite writing it. */
+import postgres from "postgres";
+import { afterAll, beforeAll, beforeEach } from "vitest";
+/** Advisory-lock name the suites writing `deploy.state` take turns on. */
+const DEPLOY_STATE_LOCK = "deploy.state";
+/** Ceiling on a suite's wait for the deploy state while another holds it. */
+const HOLD_TIMEOUT_MS = 600_000;
+/** Clears the deploy state: no live build, update or lease. */
+async function clearDeployState(sql) {
+    await sql `
+    UPDATE deploy.state
+    SET live_build = NULL, update_at = NULL, update_run = NULL,
+      version = version + 1,
+      lease_holder = NULL, lease_operation = NULL, lease_expires_at = NULL
+  `;
+}
+/** Holds the deploy state's row of the database at `connectionString` for
+ *  the enclosing suite via an advisory lock; each test starts with it
+ *  clear, and the suite leaves it clear. */
+export function holdDeployState(connectionString) {
+    let sql;
+    let lock;
+    beforeAll(async () => {
+        sql = postgres(connectionString);
+        lock = await sql.reserve();
+        await lock `SELECT pg_advisory_lock(hashtextextended(${DEPLOY_STATE_LOCK}, 0))`;
+    }, HOLD_TIMEOUT_MS);
+    beforeEach(() => clearDeployState(sql));
+    afterAll(async () => {
+        await clearDeployState(sql);
+        await lock `SELECT pg_advisory_unlock(hashtextextended(${DEPLOY_STATE_LOCK}, 0))`;
+        lock.release();
+        await sql.end({ timeout: 5 });
+    });
+}

package/dist/testkit/release-bundles.d.ts

@@ -0,0 +1,16 @@
+import type { ReleaseApp } from "../src/app.ts";
+/** What `testReleaseBundles` builds. */
+export interface ReleaseBundlesSuite {
+    /** The release declaration naming the worker's envs. */
+    app: ReleaseApp;
+    /** The wrangler-built worker's workspace package; each env whose
+     *  target deploys it bundles with `--env`. */
+    package: string;
+    /** A dev-only source the top-level (dev) bundle carries, relative to
+     *  the workspace root: shows the check sees dev code. */
+    devSource: string;
+}
+/** Tests of `package`'s minified dry-run bundles: the dev bundle carries
+ *  `devSource`; the bundle of each env deploying it carries no dev or
+ *  test code. Throws while no env deploys `package`. */
+export declare function testReleaseBundles({ app, package: pkg, devSource, }: ReleaseBundlesSuite): void;

package/dist/testkit/release-bundles.js

@@ -0,0 +1,56 @@
+/** Test suite of a wrangler-bundled worker's deploy bundles, built as
+ *  `deploy-release` builds them. */
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { afterAll, describe, expect, it } from "vitest";
+import { devTestSources, requireReleaseBundle, workerBundleArgs, } from "../src/bundle.js";
+import { wranglerConfig } from "../src/target.js";
+import { packageDir } from "../src/workspace.js";
+import { releasedTargets } from "./release.js";
+import { bundledEnvs } from "./release-checks.js";
+/** Tests of `package`'s minified dry-run bundles: the dev bundle carries
+ *  `devSource`; the bundle of each env deploying it carries no dev or
+ *  test code. Throws while no env deploys `package`. */
+export function testReleaseBundles({ app, package: pkg, devSource, }) {
+    const envs = bundledEnvs(releasedTargets(app), pkg);
+    if (!envs.length)
+        throw new Error(`No env of the release wrangler-bundles ${pkg}.`);
+    const appDir = packageDir(pkg);
+    const config = wranglerConfig(app, pkg);
+    const wrangler = join(appDir, "node_modules/.bin/wrangler");
+    const dirs = [];
+    afterAll(() => Promise.all(dirs.map((d) => rm(d, { recursive: true, force: true }))));
+    /** The directory of the bundle for `env` (top level when absent). */
+    async function bundle(env) {
+        const outdir = await mkdtemp(join(tmpdir(), "release-bundle-"));
+        dirs.push(outdir);
+        await promisify(execFile)(wrangler, [
+            ...workerBundleArgs(outdir, env === undefined
+                ? undefined
+                : {
+                    env,
+                    deployInfo: JSON.stringify({
+                        build: "bundle-test",
+                        components: {},
+                        env,
+                    }),
+                }),
+            "--config",
+            config,
+        ], { cwd: appDir });
+        return outdir;
+    }
+    describe("worker deploy bundle", () => {
+        it(`carries ${devSource} in the dev bundle`, async () => {
+            const outdir = await bundle();
+            const map = await readFile(join(outdir, "index.js.map"), "utf8");
+            expect(devTestSources(map, outdir)).toContain(devSource);
+        });
+        it.each(envs)("ships an --env %s bundle free of dev and test code", async (env) => {
+            await expect(requireReleaseBundle(await bundle(env))).resolves.toBeUndefined();
+        });
+    });
+}

package/dist/testkit/release-checks.d.ts

@@ -0,0 +1,19 @@
+import type { ReleasedTarget } from "./release.ts";
+/** Every package of `released` names the target's site; the web worker
+ *  (a blue/green target's `web`, an in-place target's any) routes
+ *  its host. */
+export declare function checkSite({ target, blocks, packages }: ReleasedTarget): void;
+/** The packages of `released` bind one Hyperdrive config; once
+ *  provisioned, a real id none of `others` binds. A target without a
+ *  database (`dbUrlVar`) binds none. */
+export declare function checkDatabase(released: ReleasedTarget, others: readonly ReleasedTarget[]): void;
+/** Every queue consumer of `released` declares `max_retries` of
+ *  `maxRetries`; with `maxRetries` undefined, `released` declares none. */
+export declare function checkQueueRetries({ blocks, packages }: ReleasedTarget, maxRetries: number | undefined): void;
+/** A blue/green target's web worker binds both slot scripts. */
+export declare function checkSlotBindings({ target, blocks }: ReleasedTarget): void;
+/** Each script of `targets` belongs to one target. */
+export declare function checkScripts(targets: readonly ReleasedTarget[]): void;
+/** Envs of `targets` that wrangler-bundle `pkg`: a blue/green env's
+ *  slotted worker, an in-place env's `wrangler` worker. */
+export declare const bundledEnvs: (targets: readonly ReleasedTarget[], pkg: string) => string[];

package/dist/testkit/release-checks.js

@@ -0,0 +1,71 @@
+/** Assertions the release suites run on an app's released targets:
+ *  site, database, queue retries, slot bindings, scripts and
+ *  wrangler-bundled envs. */
+import { expect } from "vitest";
+import { scriptsOf } from "../src/target.js";
+/** A Hyperdrive id. */
+const HYPERDRIVE_ID = /^[0-9a-f]{32}$/;
+/** Hosts `block`'s routes serve. */
+const routedHosts = (block) => (block?.routes ?? []).map((route) => (typeof route === "string" ? route : route.pattern).split("/")[0]);
+/** Services `block` binds. */
+const servicesOf = (block) => (block?.services ?? []).map((s) => s.service);
+/** Hyperdrive ids `block` binds. */
+const hyperdriveIds = (block) => (block?.hyperdrive ?? []).map((h) => h.id);
+/** Every package of `released` names the target's site; the web worker
+ *  (a blue/green target's `web`, an in-place target's any) routes
+ *  its host. */
+export function checkSite({ target, blocks, packages }) {
+    for (const pkg of packages)
+        expect(blocks[pkg]?.vars?.SITE_ORIGIN, `${pkg} SITE_ORIGIN`).toBe(target.siteOrigin);
+    const routing = target.kind === "blue-green" ? [target.packages.web] : packages;
+    expect(routing.flatMap((pkg) => routedHosts(blocks[pkg]))).toContain(new URL(target.siteOrigin).host);
+}
+/** The packages of `released` bind one Hyperdrive config; once
+ *  provisioned, a real id none of `others` binds. A target without a
+ *  database (`dbUrlVar`) binds none. */
+export function checkDatabase(released, others) {
+    const ids = (t) => t.packages.flatMap((pkg) => hyperdriveIds(t.blocks[pkg]));
+    const own = [...new Set(ids(released))];
+    if (released.target.dbUrlVar === undefined) {
+        expect(own, "Hyperdrive ids bound without a database").toEqual([]);
+        return;
+    }
+    expect(own, "Hyperdrive ids bound").toHaveLength(1);
+    if (released.bootstrapping)
+        return;
+    expect(own[0]).toMatch(HYPERDRIVE_ID);
+    expect(others.flatMap(ids)).not.toContain(own[0]);
+}
+/** Every queue consumer of `released` declares `max_retries` of
+ *  `maxRetries`; with `maxRetries` undefined, `released` declares none. */
+export function checkQueueRetries({ blocks, packages }, maxRetries) {
+    for (const pkg of packages) {
+        const consumers = blocks[pkg]?.queues?.consumers ?? [];
+        if (maxRetries === undefined) {
+            expect(consumers.map(({ queue }) => queue), `${pkg} queue consumers without queueMaxRetries`).toEqual([]);
+            continue;
+        }
+        for (const { queue, max_retries } of consumers)
+            expect(max_retries, `${pkg} ${queue} max_retries`).toBe(maxRetries);
+    }
+}
+/** A blue/green target's web worker binds both slot scripts. */
+export function checkSlotBindings({ target, blocks }) {
+    if (target.kind !== "blue-green")
+        return;
+    const { web } = target.packages;
+    for (const script of Object.values(target.deployment.slotScripts))
+        expect(servicesOf(blocks[web]), `${web} services`).toContain(script);
+}
+/** Each script of `targets` belongs to one target. */
+export function checkScripts(targets) {
+    const scripts = targets.flatMap((t) => scriptsOf(t.target));
+    expect(scripts.filter((s, i) => scripts.indexOf(s) !== i)).toEqual([]);
+}
+/** Envs of `targets` that wrangler-bundle `pkg`: a blue/green env's
+ *  slotted worker, an in-place env's `wrangler` worker. */
+export const bundledEnvs = (targets, pkg) => targets
+    .filter(({ target }) => target.kind === "in-place"
+    ? target.workers.some((w) => w.package === pkg && w.build === "wrangler")
+    : target.packages.worker === pkg)
+    .map(({ env }) => env);

package/dist/testkit/release.d.ts

@@ -0,0 +1,44 @@
+import { type ReleaseApp } from "../src/app.ts";
+import { type Target, type WranglerEnv } from "../src/target.ts";
+/** An `env.<env>` block: the keys the suite reads, typed. */
+export interface ReleasedBlock extends WranglerEnv {
+    routes?: (string | {
+        pattern: string;
+    })[];
+    services?: {
+        binding: string;
+        service: string;
+        entrypoint?: string;
+    }[];
+    hyperdrive?: {
+        binding: string;
+        id: string;
+    }[];
+    workflows?: {
+        binding: string;
+        name: string;
+        class_name?: string;
+    }[];
+    queues?: {
+        consumers?: {
+            queue: string;
+            max_retries?: number;
+        }[];
+    };
+}
+/** A target with the env blocks of its packages. */
+export interface ReleasedTarget {
+    env: string;
+    target: Target;
+    bootstrapping: boolean;
+    /** Each package's `env.<env>` block; undefined while missing. */
+    blocks: Readonly<Record<string, ReleasedBlock | undefined>>;
+    /** Packages serving the site (`packagesOf`). */
+    packages: readonly string[];
+}
+/** Every target of `app` its configs declare, with their env blocks;
+ *  an env whose target is undeclared is left out. */
+export declare function releasedTargets(app: ReleaseApp): ReleasedTarget[];
+/** Tests of `app`'s declaration against the repo's wrangler configs and
+ *  secrets templates, every declared target's. */
+export declare function testRelease(app: ReleaseApp): void;