cursedops 0.4.0 → 0.5.0

package/src/workerDeploy.ts

@@ -0,0 +1,268 @@
+/**
+ * `cursedops/worker-deploy` — the SEQUENCE that ships a Cloudflare Worker, and the small readers
+ * every step of it needs. Per-app things stay data: the Worker's name, its database, its stamp
+ * variables, and the commands that build, stage, attach secrets and smoke.
+ *
+ * ```ts
+ * import { cloudflareCredential, parseWorkerEnv, runWorkerDeploy, wranglerEnvArgs } from "cursedops/worker-deploy";
+ *
+ * const env = parseWorkerEnv(process.argv.slice(2));
+ * const result = runWorkerDeploy({
+ *   app: "music", env, workerName: d.workerName, databaseName: d.databaseName,
+ *   stampVars: { commit: "MUSIC_BUILD_COMMIT", dirty: "MUSIC_BUILD_DIRTY" },
+ *   build: ["bun", "run", "build"],
+ *   stageFirst: [["bun", "run", "scripts/worker-deploy.ts", "--env", "stage"], ["bun", "run", "scripts/worker-stage-walk.ts"]],
+ *   secrets: ["bun", "run", "scripts/worker-secrets.ts", ...wranglerEnvArgs(env)],
+ *   smoke: ["bun", "run", "scripts/worker-smoke.ts"],
+ *   credential: cloudflareCredential(file),
+ * }, workerDeployDeps(ROOT));
+ * process.exit(result.code);
+ * ```
+ *
+ * ## Why a library entry
+ *
+ * Measured 2026-09-23 (task 2097): the Worker toolkit was in FOUR apps — `collections`, `vault`,
+ * `patterns`, and `music` (copied from `vault`'s that day) — ~3,000 lines each, in `scripts/`,
+ * which `check-copies` did not scan. The copies had already drifted in ways that cost something:
+ * `patterns`' deploy never refused a dirty tree and never stamped the commit, so its `/healthz`
+ * could not say what it was running; `music`'s smoke was the only one that waited for a settled
+ * version (see `steadyHealth` in `cursedops/smoke`). Each order below is a step some app shipped
+ * without and paid for:
+ *
+ *   1. **a readable HEAD** — nothing to stamp is nothing that could prove the deploy;
+ *   2. **a clean tree for production** — a dirty one would report one commit and run another;
+ *   3. **the app's own refusals** (data) — e.g. its Mac host still loaded while the config routes
+ *      the hostname to the Worker: two writers, two databases;
+ *   4. **the STAGE first, for production** — `collections` went live 2026-09-22 with every anonymous
+ *      check green and its owner unable to sign in; the stage walk is what found why, and a step
+ *      in the sequence is one a person in a hurry cannot skip;
+ *   5. build → 6. **schema** (`IF NOT EXISTS`, the database named explicitly, never the binding a
+ *      forgotten `--env` would resolve) → 7. **deploy with the `--var` stamp** (commit AND dirty
+ *      flag, so `/healthz` publishes what is running) → 8. **secrets** (after the deploy: a secret
+ *      needs a script to attach to) → 9. **smoke**.
+ *
+ * 🔴 A failed smoke does NOT roll back here: a Worker deploy is a version and `bunx wrangler
+ * rollback` puts the previous one back in one command — the message says so. The Mac-side
+ * rollback, which is a different thing, is `cursedops/worker-rollback`.
+ *
+ * Everything that shells out is behind {@link DeployDeps}, so the suite proves the order and every
+ * refusal without wrangler, git or a network.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+
+/** The two deployments every Worker app here has. */
+export type WorkerEnv = "production" | "stage";
+
+/**
+ * `--env stage` / `--env=stage` → stage; no flag → production; anything else THROWS.
+ *
+ * 🔴 Both spellings, and the second is not politeness: wrangler itself takes `--env=stage`, so
+ * that is what a hand types after a week of wrangler — and an `indexOf("--env")` that only knew
+ * the two-argument form returned `production` for it. A typo that silently meant production
+ * points the command at the owner's data and reports success (`apps/collections/scripts/workerEnvs.ts`).
+ */
+export function parseWorkerEnv(argv: readonly string[]): WorkerEnv {
+	const joined = argv.find((arg) => arg.startsWith("--env="));
+	const index = argv.indexOf("--env");
+	if (joined === undefined && index < 0) return "production";
+	const value = (joined !== undefined ? joined.slice("--env=".length) : argv[index + 1])?.trim();
+	if (value === "production" || value === "stage") return value;
+	throw new Error(
+		`unrecognised --env ${JSON.stringify(value ?? "")} — production (no flag) or stage. ` +
+			"This refuses rather than defaulting: a typo that meant production would report success against the owner's data.",
+	);
+}
+
+/** What wrangler needs on its command line: `--env=` (the top-level block) or `--env=stage`. */
+export function wranglerEnvArgs(env: WorkerEnv): string[] {
+	return [env === "production" ? "--env=" : `--env=${env}`];
+}
+
+/** `wrangler.jsonc` as JSON — whole-line `//` comments removed, which is the shape every app's config has. */
+export function readWranglerJsonc(text: string): Record<string, unknown> {
+	const stripped = text
+		.split("\n")
+		.map((line) => (/^\s*\/\//.test(line) ? "" : line))
+		.join("\n");
+	return JSON.parse(stripped) as Record<string, unknown>;
+}
+
+/**
+ * `KEY=value` lines — `export ` tolerated, one layer of surrounding quotes removed (and a POSIX
+ * `'\''` inside single quotes read back as `'`), `#` lines and blanks skipped. The reader every
+ * Worker app's secrets and credential files share.
+ */
+export function readEnvFile(text: string): Record<string, string> {
+	const found: Record<string, string> = {};
+	for (const raw of text.split("\n")) {
+		const line = raw.trim();
+		if (!line || line.startsWith("#")) continue;
+		const eq = line.indexOf("=");
+		if (eq < 0) continue;
+		let value = line.slice(eq + 1).trim();
+		if (value.length > 1 && value.startsWith("'") && value.endsWith("'")) {
+			// `'\''` is how a writer spells a `'` inside single quotes (`envFileLines` in
+			// `cursedops/worker-secrets`); undoing it is what makes the two round-trip.
+			value = value.slice(1, -1).replaceAll("'\\''", "'");
+		} else if (value.length > 1 && value.startsWith('"') && value.endsWith('"')) {
+			value = value.slice(1, -1);
+		}
+		found[line.slice(0, eq).replace(/^export\s+/, "").trim()] = value;
+	}
+	return found;
+}
+
+/**
+ * The Cloudflare credential in `file` (usually `$FORGE_STATE/secrets/cloudflare.env`), as an env
+ * overlay for a spawned wrangler. THROWS, naming the file, when it or its token is missing.
+ *
+ * 🔴 **A file, never `wrangler login`.** An interactive OAuth session is a credential nobody can
+ * rotate, that expires while nobody looks, and that a launchd job does not have — a deploy path
+ * built on one works from a terminal a person sits at and from nowhere else. And a deploy must
+ * fail in FRONT of the work, not three minutes in with wrangler's own opaque auth error, or —
+ * worse — succeed against whatever account an inherited variable names.
+ */
+export function cloudflareCredential(file: string, read: (path: string) => string | null = readIfThere): Record<string, string> {
+	const text = read(file);
+	if (text === null) throw new Error(`no Cloudflare credential at ${file}`);
+	const found = readEnvFile(text);
+	if (!found.CLOUDFLARE_API_TOKEN) throw new Error(`${file} has no CLOUDFLARE_API_TOKEN`);
+	return found;
+}
+
+function readIfThere(path: string): string | null {
+	return existsSync(path) ? readFileSync(path, "utf8") : null;
+}
+
+/** A refusal an app adds to the sequence: a sentence saying why not, or `null` to proceed. */
+export type Refusal = () => string | null;
+
+export interface WorkerDeploySpec {
+	/** For the messages: `[music] …`. */
+	app: string;
+	env: WorkerEnv;
+	workerName: string;
+	/** The D1 database the schema is applied to, by NAME. `null` for a Worker with no D1. */
+	databaseName: string | null;
+	/** Default `db/schema.sql`. Must be `IF NOT EXISTS` throughout — it runs on every deploy. */
+	schemaFile?: string;
+	/** The two `vars` `/healthz` publishes as the build stamp. `null` only for a Worker that has none yet. */
+	stampVars: { commit: string; dirty: string } | null;
+	/** The build command, or `null` to skip (`--no-build`). */
+	build: readonly string[] | null;
+	/** Run in order BEFORE a production deploy; any red and production is not touched. Ignored for the stage. */
+	stageFirst?: readonly (readonly string[])[];
+	/** Before the stage (and before anything is built): the app's own refusals. */
+	beforeStage?: readonly Refusal[];
+	/** After the build, before anything ships — e.g. "the build output is really there". */
+	beforeShip?: readonly Refusal[];
+	/** Attaches this deployment's secrets. Run after the deploy. */
+	secrets: readonly string[] | null;
+	/** Smokes this deployment. */
+	smoke: readonly string[] | null;
+	/** The env overlay every wrangler-touching step is run with — {@link cloudflareCredential}. */
+	credential: Record<string, string>;
+}
+
+export interface DeployDeps {
+	/** Run a command, inheriting stdio; returns its exit code. */
+	run: (argv: readonly string[], env: Record<string, string>) => number;
+	/** `git <args>` in the checkout; trimmed stdout, `""` on failure. */
+	git: (args: readonly string[]) => string;
+	log?: (line: string) => void;
+	error?: (line: string) => void;
+}
+
+export interface DeployResult {
+	/** 0 shipped and smoked; 1 refused or failed — the step says where. */
+	code: 0 | 1;
+	/** The step it stopped at, or `"done"`. */
+	step: string;
+	/** Why it stopped, or the success line. */
+	detail: string;
+	commit: string;
+	dirty: boolean;
+}
+
+/** The real {@link DeployDeps}, rooted at the app's checkout. */
+export function workerDeployDeps(cwd: string): DeployDeps {
+	return {
+		run: (argv, env) => {
+			console.log(`  $ ${argv.join(" ")}`);
+			return spawnSync(argv[0] as string, argv.slice(1), { cwd, stdio: "inherit", env: { ...process.env, ...env } }).status ?? 1;
+		},
+		git: (args) => (spawnSync("git", [...args], { cwd, encoding: "utf8" }).stdout ?? "").trim(),
+	};
+}
+
+/**
+ * Run the sequence in the header's order, stopping at the first red with a sentence. Never
+ * exits — the caller does, with {@link DeployResult.code}.
+ */
+export function runWorkerDeploy(spec: WorkerDeploySpec, deps: DeployDeps): DeployResult {
+	const log = deps.log ?? ((line: string) => console.log(line));
+	const error = deps.error ?? ((line: string) => console.error(line));
+	const tag = `[${spec.app}]`;
+	const commit = deps.git(["rev-parse", "HEAD"]);
+	const porcelain = deps.git(["status", "--porcelain"]);
+	const dirty = porcelain.length > 0;
+	const stop = (step: string, detail: string): DeployResult => {
+		error(`\n🔴 ${tag} ${detail}`);
+		return { code: 1, step, detail, commit, dirty };
+	};
+	const step = (message: string): void => log(`\n▸ ${message}`);
+
+	if (!commit) return stop("head", "this checkout has no readable HEAD — there is no commit to stamp, so nothing could prove the deploy.");
+	if (spec.env === "production" && dirty) {
+		return stop("clean-tree", `the tree is dirty — production would report ${commit.slice(0, 8)} and run something else:\n${porcelain}`);
+	}
+	for (const refusal of spec.beforeStage ?? []) {
+		const why = refusal();
+		if (why) return stop("refusal", why);
+	}
+	if (spec.env === "production") {
+		for (const command of spec.stageFirst ?? []) {
+			step(`the stage first — production waits on it: ${command.join(" ")}`);
+			if (deps.run(command, {}) !== 0) return stop("stage", `\`${command.join(" ")}\` failed — production was NOT touched.`);
+		}
+	}
+	if (spec.build) {
+		step("build");
+		if (deps.run(spec.build, {}) !== 0) return stop("build", "the build failed — nothing was deployed.");
+	}
+	for (const refusal of spec.beforeShip ?? []) {
+		const why = refusal();
+		if (why) return stop("refusal", `${why} — nothing was deployed.`);
+	}
+	const envArgs = wranglerEnvArgs(spec.env);
+	if (spec.databaseName) {
+		const schema = spec.schemaFile ?? "db/schema.sql";
+		step(`apply ${schema} to D1 \`${spec.databaseName}\``);
+		const applied = deps.run(["bunx", "wrangler", "d1", "execute", spec.databaseName, "--remote", "--file", schema, "-y", ...envArgs], spec.credential);
+		if (applied !== 0) return stop("schema", "the schema did not apply — nothing was deployed.");
+	}
+	step(`deploy ${spec.workerName} @ ${commit.slice(0, 8)}${dirty ? " (dirty — stage only)" : ""}`);
+	const stamp = spec.stampVars
+		? ["--var", `${spec.stampVars.commit}:${commit}`, "--var", `${spec.stampVars.dirty}:${dirty ? "true" : "false"}`]
+		: [];
+	if (deps.run(["bunx", "wrangler", "deploy", ...envArgs, ...stamp], spec.credential) !== 0) return stop("deploy", "wrangler deploy failed.");
+	if (spec.secrets) {
+		step("attach the secrets — exactly this deployment's set, over a pipe");
+		if (deps.run(spec.secrets, spec.credential) !== 0) {
+			return stop("secrets", "the Worker is deployed and its secrets are NOT attached — it serves nothing until they are.");
+		}
+	}
+	if (spec.smoke) {
+		step("smoke every address this deployment answers on");
+		if (deps.run(spec.smoke, {}) !== 0) {
+			return stop(
+				"smoke",
+				"the Worker is deployed and its smoke FAILED. Nothing was rolled back: `bunx wrangler rollback` puts the previous version back in one command.",
+			);
+		}
+	}
+	const detail = `${spec.workerName} deployed${spec.secrets ? ", attached" : ""}${spec.smoke ? " and smoked" : ""} @ ${commit.slice(0, 8)}.`;
+	log(`\n✅ ${detail}`);
+	return { code: 0, step: "done", detail, commit, dirty };
+}

package/src/workerRollback.ts

@@ -0,0 +1,133 @@
+/**
+ * `cursedops/worker-rollback` — put a hostname served by a Worker back on its Mac origin, in the
+ * one order that cannot leave the hostname pointing at nothing: **origin first, route second.**
+ *
+ * ```ts
+ * import { findWorkerRoute, loopbackHealthy, rollbackToOrigin } from "cursedops/worker-rollback";
+ *
+ * const found = await findWorkerRoute(api, host);                 // read off the account, never typed
+ * const result = await rollbackToOrigin({
+ *   startOrigin: () => spawnSync("bun", ["run", "scripts/service.ts", "install", "--rollback"], …).status ?? 1,
+ *   originUp: () => loopbackHealthy(livePort(LABEL) ?? DEPLOY_PORT),
+ *   removeRoute: () => deleteWorkerRoute(api, found),
+ * });
+ * ```
+ *
+ * ## Why this order, and why it is a library entry
+ *
+ * `patterns` wrote it first (2026-09-19) because the owner required the rollback to be ONE
+ * command — a launchd invocation nobody runs monthly and a route id nobody has memorised are not
+ * cheap at the moment somebody needs them — and `collections`, `vault` and `music` copied it.
+ * Deleting the route while nothing listens on the Mac points the household's hostname at a dead
+ * box; so this starts the origin, WAITS for it to answer, and refuses to touch the route if it
+ * never does. A hostname served by a Worker that works beats one pointing at a Mac that does not.
+ *
+ * 🔴 The route is FOUND, never typed. `patterns`' copy carried its zone and route ids as literals,
+ * which is correct exactly until the route is re-created — and the moment that matters is the one
+ * where somebody has just been changing routes. {@link findWorkerRoute} reads them off the account
+ * by the hostname's `<host>/*` pattern.
+ *
+ * 🔴 What a rollback does NOT undo is the app's to say, and each app's script says it: writes made
+ * to D1 since the cutover stay in D1. `cursedops/d1-import`'s row-for-row comparison is how an app
+ * prints the size of that loss before anybody decides.
+ */
+
+/** The Cloudflare v4 API's envelope — only what is read here. Structural, so any caller fits. */
+export interface ApiResult {
+	success?: boolean;
+	result?: unknown;
+	errors?: unknown;
+}
+
+export type CloudflareApi = (path: string, init?: RequestInit) => Promise<ApiResult>;
+
+export interface WorkerRoute {
+	zone: string;
+	/** The route's id, or `null` when no route serves the hostname (it already falls through). */
+	route: string | null;
+	/** The Worker script the route names, when there is one. */
+	script: string | null;
+	pattern: string;
+}
+
+/**
+ * The zone and the route serving `<hostname>/*`, read off the account. THROWS when the account has
+ * no zone for the hostname — a rollback that cannot see the zone cannot know what it would change.
+ *
+ * The zone is the hostname's last two labels, which is every zone this fleet has; `zoneName`
+ * overrides it for one that is not.
+ */
+export async function findWorkerRoute(api: CloudflareApi, hostname: string, zoneName?: string): Promise<WorkerRoute> {
+	const pattern = `${hostname}/*`;
+	const name = zoneName ?? hostname.split(".").slice(-2).join(".");
+	const zones = await api(`/zones?name=${encodeURIComponent(name)}`);
+	const zone = (zones.result as Array<{ id: string }> | undefined)?.[0]?.id;
+	if (!zone) throw new Error(`no zone ${name} for ${hostname} on this account: ${JSON.stringify(zones.errors ?? [])}`);
+	const routes = await api(`/zones/${zone}/workers/routes`);
+	const hit = (routes.result as Array<{ id: string; pattern: string; script?: string }> | undefined)?.find((r) => r.pattern === pattern);
+	return { zone, route: hit?.id ?? null, script: hit?.script ?? null, pattern };
+}
+
+/** Delete `found`'s route. `true` when it is gone or there was none to delete. */
+export async function deleteWorkerRoute(api: CloudflareApi, found: WorkerRoute): Promise<boolean> {
+	if (!found.route) return true;
+	return (await api(`/zones/${found.zone}/workers/routes/${found.route}`, { method: "DELETE" })).success === true;
+}
+
+/** Does `http://127.0.0.1:<port><path>` answer `2xx` right now? Loopback, so no cache can answer for it. */
+export async function loopbackHealthy(port: number, path = "/healthz", send: typeof fetch = fetch): Promise<boolean> {
+	try {
+		return (await send(`http://127.0.0.1:${port}${path}`, { signal: AbortSignal.timeout(2_000), redirect: "manual" })).ok;
+	} catch {
+		return false;
+	}
+}
+
+export interface RollbackSteps {
+	/** Start (reinstall) the Mac origin. Returns an exit code. */
+	startOrigin: () => number | Promise<number>;
+	/** Is the origin answering? Asked until it is, or the attempts run out. */
+	originUp: () => Promise<boolean>;
+	/** Take the Worker off the hostname. Only ever called once the origin answers. */
+	removeRoute: () => Promise<boolean>;
+	/** How many times to ask {@link originUp}. Default 60. */
+	attempts?: number;
+	/** Pause between asks. Default 1 s. */
+	intervalMs?: number;
+	sleep?: (ms: number) => Promise<void>;
+}
+
+export interface RollbackResult {
+	ok: boolean;
+	/** Where it stopped: the origin never came up, the route would not delete, or done. */
+	stage: "origin" | "route" | "done";
+	detail: string;
+}
+
+/**
+ * Origin first, route second. The route is NOT touched unless the start succeeded AND the origin
+ * answered — see the header.
+ */
+export async function rollbackToOrigin(steps: RollbackSteps): Promise<RollbackResult> {
+	const sleep = steps.sleep ?? ((ms: number) => new Promise<void>((done) => setTimeout(done, ms)));
+	const attempts = steps.attempts ?? 60;
+	const started = await steps.startOrigin();
+	let up = false;
+	for (let attempt = 0; attempt < attempts && !up; attempt++) {
+		up = await steps.originUp();
+		if (!up && attempt + 1 < attempts) await sleep(steps.intervalMs ?? 1_000);
+	}
+	if (started !== 0 || !up) {
+		return {
+			ok: false,
+			stage: "origin",
+			detail:
+				`the origin ${started !== 0 ? `failed to start (exit ${started})` : "never answered"}. The route was NOT touched — ` +
+				"the hostname is still served by the Worker, which is the safer of the two. Fix the origin, then run this again.",
+		};
+	}
+	if (!(await steps.removeRoute())) {
+		return { ok: false, stage: "route", detail: "the origin is answering, and the route was NOT deleted — the Worker still serves the hostname." };
+	}
+	return { ok: true, stage: "done", detail: "the origin answers and the route is gone — prove it with a cache-busted /healthz, because a cached 200 is not a working origin." };
+}

package/src/workerSecrets.ts

@@ -0,0 +1,195 @@
+/**
+ * `cursedops/worker-secrets` — make a Worker hold EXACTLY the secrets its deployment names,
+ * uploaded over a pipe, and nothing else. The deployment's secret map, and which file it reads,
+ * stay data in the app.
+ *
+ * ```ts
+ * import { planSecrets, syncSecrets, restSecretOps, cloudflareApi, wranglerSecretPut } from "cursedops/worker-secrets";
+ *
+ * const api = cloudflareApi(cf.CLOUDFLARE_API_TOKEN);
+ * const ops = restSecretOps({ api, account: cf.CLOUDFLARE_ACCOUNT_ID, script: d.workerName,
+ *   put: (name, value) => wranglerSecretPut(name, value, { cwd: ROOT, envArgs: wranglerEnvArgs(d.env), env: cf }) });
+ * const plan = planSecrets(d.secrets, await ops.held(), readEnvFile(readFileSync(file, "utf8")));
+ * if (plan.absent.length) refuse(`${file} has no ${plan.absent.join(", ")}`);
+ * const { ok, lines } = await syncSecrets(plan, ops);
+ * ```
+ *
+ * ## The two halves, and what each one cost
+ *
+ * 🔴 **Over a PIPE, never a command line.** `collections`' `MASTER_LOCK_SEED` is JSON carrying an
+ * argon2id PHC string (`$argon2id$v=19$m=65536,…`); anything that sources, interpolates or
+ * word-splits it produces valid JSON that verifies no password — the pilot lost its first upload
+ * to exactly that. A value on stdin has no shell, no `$` expansion, no argv limit, and stays out
+ * of `ps`. {@link wranglerSecretPut} is the only spelling here.
+ *
+ * 🔴 **"Nothing else" is the half that matters.** A secret left on the account from an earlier
+ * configuration is a credential nobody reads any more and anybody could still use — on `vault`
+ * it would have been a static SSO key beside the accounts service, a second door. So every name
+ * outside the set is DELETED and the run ends by READING THE ACCOUNT BACK and refusing unless it
+ * holds exactly the set. `vault` and `music` wrote that; `collections`' copy only ever put, and
+ * never noticed an extra — the drift this module ends.
+ *
+ * 🔴 **A value that is already single-quoted is written as is.** {@link envFileLines}:
+ * `collections`' seed serialiser returns `'{"kdf":…}'`, quoting it again wrote an escaped pair
+ * around it, `readEnvFile` stripped one layer, and the stage's master lock came up asking to
+ * ENROLL a new password (found 2026-09-22 by the stage walk, one step past sign-in).
+ */
+import { spawnSync } from "node:child_process";
+import { chmodSync, writeFileSync } from "node:fs";
+
+/** Worker secret name → the key it is read from in the secrets file. A list means "same name". */
+export type SecretMap = Readonly<Record<string, string>> | readonly string[];
+
+export interface SecretPlan {
+	/** Every secret to put, with the value it will be given. */
+	put: Array<{ name: string; from: string; value: string }>;
+	/** Names the account holds that the set does not — to be DELETED. */
+	remove: string[];
+	/** Keys the file lacks. Non-empty means refuse before touching the account. */
+	absent: string[];
+	/** The set, by Worker name. */
+	wanted: string[];
+}
+
+function entries(map: SecretMap): Array<[name: string, from: string]> {
+	return Array.isArray(map) ? map.map((name) => [name, name]) : Object.entries(map as Record<string, string>);
+}
+
+/** What has to change for the account to hold exactly `map`, given what it `held` and the file's `values`. Pure. */
+export function planSecrets(map: SecretMap, held: readonly string[], values: Readonly<Record<string, string>>): SecretPlan {
+	const pairs = entries(map);
+	const wanted = pairs.map(([name]) => name);
+	return {
+		put: pairs.filter(([, from]) => values[from]).map(([name, from]) => ({ name, from, value: values[from] as string })),
+		remove: held.filter((name) => !wanted.includes(name)),
+		absent: pairs.filter(([, from]) => !values[from]).map(([, from]) => from),
+		wanted,
+	};
+}
+
+/** How {@link syncSecrets} reaches the account. Injectable, so the exact-set rule is proved without one. */
+export interface SecretOps {
+	/** The secret NAMES the deployed script holds — `[]` when there is no script yet. */
+	held: () => Promise<string[]>;
+	/** Put one secret, its value on stdin. */
+	put: (name: string, value: string) => boolean | Promise<boolean>;
+	/** Delete one secret. */
+	remove: (name: string) => Promise<boolean>;
+}
+
+export interface SecretSync {
+	ok: boolean;
+	/** One line per action, then the read-back verdict. */
+	lines: string[];
+	/** What the account holds afterwards. */
+	after: string[];
+}
+
+/**
+ * Apply `plan`: put every value, delete every extra, then READ THE ACCOUNT BACK and fail unless it
+ * holds exactly the set. Refuses without touching anything when the plan has `absent` keys.
+ */
+export async function syncSecrets(plan: SecretPlan, ops: SecretOps): Promise<SecretSync> {
+	const lines: string[] = [];
+	if (plan.absent.length > 0) {
+		return { ok: false, lines: [`the secrets file has no ${plan.absent.join(" and no ")} — nothing was changed`], after: await ops.held() };
+	}
+	let bad = 0;
+	for (const { name, from, value } of plan.put) {
+		const ok = await ops.put(name, value);
+		lines.push(`put ${name}${from === name ? "" : ` (from ${from})`} (${value.length} bytes) — ${ok ? "ok" : "FAILED"}`);
+		if (!ok) bad++;
+	}
+	for (const name of plan.remove) {
+		const ok = await ops.remove(name);
+		lines.push(`DELETE ${name} — not in the set — ${ok ? "gone" : "FAILED"}`);
+		if (!ok) bad++;
+	}
+	const after = await ops.held();
+	const exact = after.length === plan.wanted.length && plan.wanted.every((name) => after.includes(name));
+	lines.push(exact ? `holds exactly: ${after.join(", ")}` : `🔴 holds ${after.join(", ") || "(nothing)"} — not exactly ${plan.wanted.join(", ")}`);
+	return { ok: exact && bad === 0, lines, after };
+}
+
+/** The Cloudflare v4 API's envelope — only what the callers here read. */
+export interface ApiResult {
+	success?: boolean;
+	result?: unknown;
+	errors?: unknown;
+}
+
+export type CloudflareApi = (path: string, init?: RequestInit) => Promise<ApiResult>;
+
+/** A Cloudflare v4 API caller for `token`. `fetch` injectable for tests. */
+export function cloudflareApi(token: string, send: typeof fetch = fetch): CloudflareApi {
+	return async (path, init = {}) => {
+		const response = await send(`https://api.cloudflare.com/client/v4${path}`, {
+			...init,
+			headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+			signal: init.signal ?? AbortSignal.timeout(30_000),
+		});
+		return (await response.json().catch(() => ({ success: false, errors: [`HTTP ${response.status}, not JSON`] }))) as ApiResult;
+	};
+}
+
+/**
+ * {@link SecretOps} over the REST API (list and delete) plus a `put` the caller supplies —
+ * normally {@link wranglerSecretPut}, because wrangler is what creates a version for a secret.
+ */
+export function restSecretOps(options: { api: CloudflareApi; account: string; script: string; put: SecretOps["put"] }): SecretOps {
+	const base = `/accounts/${options.account}/workers/scripts/${options.script}/secrets`;
+	return {
+		held: async () => {
+			const res = await options.api(base);
+			return res.success ? ((res.result as Array<{ name: string }> | undefined) ?? []).map((s) => s.name) : [];
+		},
+		put: options.put,
+		remove: async (name) => (await options.api(`${base}/${encodeURIComponent(name)}`, { method: "DELETE" })).success === true,
+	};
+}
+
+/**
+ * `wrangler secret put <name>` with the value on STDIN. See the header. `spawn` injectable.
+ */
+export function wranglerSecretPut(
+	name: string,
+	value: string,
+	options: {
+		cwd: string;
+		envArgs: readonly string[];
+		env?: Record<string, string>;
+		spawn?: (argv: readonly string[], input: string) => { status: number | null; stderr?: string };
+	},
+): boolean {
+	const argv = ["bunx", "wrangler", "secret", "put", name, ...options.envArgs];
+	const spawn =
+		options.spawn ??
+		((a: readonly string[], input: string) =>
+			spawnSync(a[0] as string, a.slice(1), { cwd: options.cwd, input, encoding: "utf8", env: { ...process.env, ...(options.env ?? {}) } }));
+	const ran = spawn(argv, value);
+	if ((ran.status ?? 1) !== 0 && ran.stderr) console.error(ran.stderr);
+	return (ran.status ?? 1) === 0;
+}
+
+/**
+ * `KEY='value'` lines for a 0600 env file. A value that already carries its own single quotes is
+ * written AS IS; any other `'` is escaped the POSIX way. See the header for what double-quoting cost.
+ */
+export function envFileLines(values: Readonly<Record<string, string>>): string {
+	return `${Object.entries(values)
+		.map(([key, value]) =>
+			value.length > 1 && value.startsWith("'") && value.endsWith("'") ? `${key}=${value}` : `${key}='${value.replaceAll("'", "'\\''")}'`,
+		)
+		.join("\n")}\n`;
+}
+
+/** Write a secrets file 0600 — `header` lines become `# ` comments. Never committed, never world-readable. */
+export function writeSecretsFile(path: string, header: readonly string[], values: Readonly<Record<string, string>>): void {
+	writeFileSync(path, `${header.map((line) => `# ${line}`.trimEnd()).join("\n")}\n${envFileLines(values)}`, { encoding: "utf8", mode: 0o600 });
+	chmodSync(path, 0o600);
+}
+
+/** A throwaway secret: 256 bits, hex. For a session key that opens nothing the owner owns. */
+export function throwawaySecret(): string {
+	return Buffer.from(crypto.getRandomValues(new Uint8Array(32))).toString("hex");
+}