@saastemly/voidcommerce 0.1.0

package/src/cli.ts

@@ -0,0 +1,78 @@
+import { deployCommand, deployHelp, preflightCommand, preflightHelp } from "./deploy/index";
+import { distCommand, distHelp } from "./dist";
+import { importCommand, importHelp } from "./import";
+import { fullHelp, initHelp, version } from "./help";
+import { init } from "./init";
+import { ensureGenerated, findProject } from "./project";
+import { generateCommand, generateHelp } from "./regenerate";
+import { appScript, appScriptHelp } from "./scripts";
+import { runVoid } from "./void";
+
+/**
+ * `vc` — Void, with a shop in it.
+ *
+ * vc extends parts of void; it replaces none of it. Every command not named
+ * below goes to `void` verbatim — same arguments, same terminal, same exit
+ * code — so a person who knows Void already knows vc. The named ones run
+ * void's version first and add vc's part after: `vc init` is void init then
+ * the shop form; `vc --help` is void's help with a `shop` group merged in.
+ * `dev`, `build` and `preview` are not void's at all — they are the app's
+ * own scripts — so vc only decides where they run.
+ *
+ * The one thing vc changes about a pass-through is WHERE it runs: at a
+ * strict root the Void app is the artifact under .vc/app, so void's commands
+ * run there, after generating it if it is not there yet; at a monorepo root
+ * they run in api/.
+ */
+
+interface Extended {
+	run: (args: string[]) => Promise<number>;
+	help: () => Promise<number>;
+}
+
+/** The commands vc extends or adds. Add one here and it is dispatched, helped, and tested. */
+export const EXTENDED: Record<string, Extended> = {
+	init: { run: init, help: initHelp },
+	generate: { run: generateCommand, help: generateHelp },
+	dist: { run: distCommand, help: distHelp },
+	import: { run: importCommand, help: importHelp },
+	deploy: { run: deployCommand, help: deployHelp },
+	preflight: { run: preflightCommand, help: preflightHelp },
+	dev: { run: appScript("dev"), help: appScriptHelp("dev") },
+	build: { run: appScript("build"), help: appScriptHelp("build") },
+	preview: { run: appScript("preview"), help: appScriptHelp("preview") },
+};
+
+const HELP = new Set(["help", "--help", "-h"]);
+const VERSION = new Set(["--version", "-v", "-V"]);
+
+async function passthrough(argv: string[]): Promise<number> {
+	const project = await findProject();
+	if (!project) return runVoid(argv);
+	const code = await ensureGenerated(project);
+	if (code !== 0) return code;
+	return runVoid(argv, project.appDir);
+}
+
+export async function main(argv: string[]): Promise<number> {
+	const [command, ...rest] = argv;
+
+	if (command === undefined || (HELP.has(command) && rest.length === 0)) return fullHelp();
+	if (VERSION.has(command) && rest.length === 0) return version();
+
+	if (HELP.has(command)) {
+		// `vc help init` is vc's to answer; `vc help db execute` is void's.
+		const target = EXTENDED[rest[0] ?? ""];
+		return target ? target.help() : passthrough(argv);
+	}
+
+	const extended = EXTENDED[command];
+	if (extended) {
+		if (rest.some((arg) => arg === "--help" || arg === "-h")) return extended.help();
+		return extended.run(rest);
+	}
+
+	return passthrough(argv);
+}
+
+process.exit(await main(process.argv.slice(2)));

package/src/deploy/cloudflare.ts

@@ -0,0 +1,166 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import color from "picocolors";
+import { allEnvKeys } from "../generate/env";
+import { hasFrontend, workerHosts, writeManifest } from "../manifest";
+import type { Project } from "../project";
+import { parseJsonc, upsertJsonc } from "./jsonc";
+import { preflight, printPreflight } from "./preflight";
+import { ensureD1, ensureQueue, findWrangler, whoami, wrangler } from "./wrangler";
+
+/**
+ * `vc deploy --cloudflare` — the shop to your own Cloudflare account, with
+ * wrangler, and nothing else. No Void account, no linked project.
+ *
+ * It is Void's documented manual path, automated:
+ *
+ *   1. wrangler is installed and logged in; the account is pinned
+ *   2. preflight — every required key is a worker secret or a committed
+ *      plaintext value; the hostnames are the shop's
+ *   3. --provision: the D1 database and the queue exist and are recorded
+ *   4. build
+ *   5. SCRUB the emitted config. Void's build bakes every .env* value into
+ *      the worker's vars as plaintext — a dev cron secret, `unset` for each
+ *      credential — and a var shadows the secret of the same name. So every
+ *      secret-class key and every `unset` is removed from dist/ssr/wrangler.json
+ *      before it is uploaded; the worker reads those from `wrangler secret`.
+ *   6. apply the committed migrations to the remote D1
+ *   7. wrangler deploy, on exactly the config that was scrubbed
+ */
+
+export interface CloudflareOptions {
+	provision: boolean;
+	force: boolean;
+}
+
+interface WranglerConfig {
+	name?: string;
+	account_id?: string;
+	d1_databases?: Array<{ binding: string; database_name: string; database_id: string; migrations_dir?: string }>;
+	queues?: { producers?: Array<{ queue: string }>; consumers?: Array<{ queue: string }> };
+	vars?: Record<string, string>;
+}
+
+const fail = (message: string): number => {
+	console.error(`\n${color.red("✗")} ${message}\n`);
+	return 1;
+};
+
+function readConfig(path: string): WranglerConfig {
+	return parseJsonc<WranglerConfig>(readFileSync(path, "utf8"));
+}
+
+/** A build tool the app has: vite-plus first, then vite. */
+function findBuilder(from: string): { cmd: string; label: string } | null {
+	let dir = from;
+	for (;;) {
+		for (const [bin, label] of [
+			["vp", "vp build"],
+			["vite", "vite build"],
+		] as const) {
+			const path = join(dir, "node_modules", ".bin", bin);
+			if (existsSync(path)) return { cmd: path, label };
+		}
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+export async function deployCloudflare(project: Project, opts: CloudflareOptions): Promise<number> {
+	const app = project.appDir;
+	const configPath = join(app, "wrangler.jsonc");
+	if (!existsSync(configPath)) return fail("wrangler.jsonc is missing — `vc generate` writes it.");
+
+	// 1. wrangler, logged in, account pinned.
+	const bin = findWrangler(app);
+	if (!bin) return fail("wrangler is not installed. `bun add -d wrangler`, then `wrangler login`.");
+	const who = await whoami(bin, app);
+	if (who.state === "logged-out") return fail("wrangler is not logged in. Run `wrangler login` (or export CLOUDFLARE_API_TOKEN).");
+	if (who.state === "unknown") return fail(`wrangler could not confirm who you are:\n${who.raw.trim().split("\n").slice(-4).join("\n")}`);
+	console.log(`${color.green("✓")} wrangler is logged in`);
+
+	let config = readConfig(configPath);
+	let accountId = config.account_id || process.env["CLOUDFLARE_ACCOUNT_ID"] || "";
+	if (!accountId) {
+		if (who.accounts.length === 1) {
+			accountId = who.accounts[0]!.id;
+			writeFileSync(configPath, upsertJsonc(readFileSync(configPath, "utf8"), "account_id", accountId));
+			project.manifest.cloudflare = { ...project.manifest.cloudflare, accountId };
+			await writeManifest(project.root, project.manifest);
+			console.log(`${color.green("✓")} pinned the account "${who.accounts[0]!.name}" in wrangler.jsonc`);
+		} else {
+			return fail(
+				`the account is not pinned and wrangler sees ${who.accounts.length}. Set account_id in wrangler.jsonc to one of:\n${who.accounts.map((a) => `    ${a.id}  ${a.name}`).join("\n")}`,
+			);
+		}
+	}
+
+	// 2. preflight.
+	const check = await preflight(project, "wrangler");
+	printPreflight(project, check, "wrangler");
+	if (!check.ready) {
+		if (!opts.force) return fail("refusing to deploy a shop that is not ready for customers. Fix the above, or pass --force for a deliberate partial deploy.");
+		console.error(color.yellow("--force: deploying a shop that is NOT ready for customers.\n"));
+	}
+
+	// 3. resources.
+	const worker = config.name || project.manifest.shop.domain.split(".")[0]!;
+	const d1 = config.d1_databases?.find((db) => db.binding === "DB");
+	const provisioned = Boolean(d1?.database_id && d1.database_id !== "local");
+	if (!provisioned) {
+		if (!opts.provision) return fail("the D1 database is not provisioned. Run once with --provision to create it and record its id.");
+		const db = await ensureD1(bin, app, `${worker}-db`);
+		const entry = { binding: "DB", database_name: db.name, database_id: db.uuid, migrations_dir: "./db/migrations" };
+		writeFileSync(configPath, upsertJsonc(readFileSync(configPath, "utf8"), "d1_databases", [entry]));
+		project.manifest.cloudflare = { ...project.manifest.cloudflare, accountId, d1: { name: db.name, id: db.uuid } };
+		await writeManifest(project.root, project.manifest);
+		console.log(`${color.green("✓")} D1 "${db.name}" recorded in wrangler.jsonc and voidcommerce.json`);
+		config = readConfig(configPath);
+	}
+	if (opts.provision) {
+		// Void names the queue after the consumer file; a queue is account-wide.
+		await ensureQueue(bin, app, "commerce");
+		console.log(`${color.green("✓")} queue "commerce"`);
+	}
+
+	// 4. build.
+	const builder = findBuilder(app);
+	if (!builder) return fail("no build tool: neither vite-plus nor vite is installed.");
+	console.log(`\n▸ ${builder.label}`);
+	const built = await wrangler(builder.cmd, ["build"], app, true);
+	if (built.code !== 0) return fail(`the build failed (exit ${built.code}).`);
+
+	// 5. scrub.
+	const emittedPath = join(app, "dist", "ssr", "wrangler.json");
+	if (!existsSync(emittedPath)) return fail(`the build emitted no ${emittedPath} — is this a Void app on the Cloudflare target?`);
+	const emitted = JSON.parse(readFileSync(emittedPath, "utf8")) as WranglerConfig;
+	const secretKeys = new Set(allEnvKeys(project.manifest).filter((key) => !key.plaintext).map((key) => key.key));
+	const scrubbed: string[] = [];
+	for (const [key, value] of Object.entries(emitted.vars ?? {})) {
+		if (secretKeys.has(key) || value === "unset") {
+			delete emitted.vars![key];
+			scrubbed.push(key);
+		}
+	}
+	const emittedD1 = emitted.d1_databases?.find((db) => db.binding === "DB");
+	if (!emittedD1 || emittedD1.database_id === "local") return fail("the emitted config still carries a placeholder D1 id; wrangler.jsonc's DB binding was not picked up by the build.");
+	writeFileSync(emittedPath, JSON.stringify(emitted, null, 2));
+	console.log(`${color.green("✓")} scrubbed ${scrubbed.length} baked value${scrubbed.length === 1 ? "" : "s"} from the worker's vars${scrubbed.length ? `: ${scrubbed.join(", ")}` : ""}`);
+
+	// 6. migrations, with the root config — its migrations_dir is the committed one.
+	console.log(`\n▸ wrangler d1 migrations apply ${emittedD1.database_name} --remote`);
+	const migrated = await wrangler(bin, ["d1", "migrations", "apply", emittedD1.database_name, "--remote"], app, true);
+	if (migrated.code !== 0) return fail(`applying migrations failed (exit ${migrated.code}); nothing was deployed.`);
+
+	// 7. deploy exactly what was scrubbed.
+	console.log("\n▸ wrangler deploy -c dist/ssr/wrangler.json");
+	const deployed = await wrangler(bin, ["deploy", "-c", join("dist", "ssr", "wrangler.json")], app, true);
+	if (deployed.code !== 0) return fail(`wrangler deploy failed (exit ${deployed.code}).`);
+
+	const domain = project.manifest.shop.domain;
+	const url = `https://${workerHosts(project.manifest)[0]}`;
+	console.log(`\n${color.green("Live:")} ${url}`);
+	if (hasFrontend(project.manifest.layout)) console.log(color.dim("The storefront deploys itself from GitHub Actions on push."));
+	return 0;
+}

package/src/deploy/index.ts

@@ -0,0 +1,101 @@
+import color from "picocolors";
+import { box, line, row } from "../help";
+import { findProject } from "../project";
+import { captureVoid, runVoid } from "../void";
+import { deployCloudflare } from "./cloudflare";
+import { preflight, printPreflight } from "./preflight";
+
+/**
+ * `vc deploy` extends `void deploy`: vc's preflight first, then void's
+ * deploy, verbatim. `--cloudflare` is the other road — wrangler, your own
+ * account, no Void login — and takes vc's own flags:
+ *
+ *   --cloudflare    deploy with wrangler to your Cloudflare account
+ *   --provision     create the D1 database and the queue on first deploy
+ *   --force         deploy even when preflight says the shop is not ready
+ *
+ * Everything else after `deploy` is void's, untouched.
+ */
+export async function deployCommand(args: string[]): Promise<number> {
+	const own = new Set(["--cloudflare", "--provision", "--force"]);
+	const cloudflare = args.includes("--cloudflare");
+	const voids = args.filter((arg) => !own.has(arg));
+	const project = await findProject();
+	if (!project) {
+		if (cloudflare) {
+			console.error("vc: no voidcommerce.json here — the Cloudflare deploy needs the manifest to know what the shop requires.");
+			return 1;
+		}
+		return runVoid(["deploy", ...voids]);
+	}
+
+	if (cloudflare) {
+		if (voids.length > 0) {
+			console.error(`vc: --cloudflare takes only --provision and --force; ${voids.join(" ")} is void's and does not apply.`);
+			return 1;
+		}
+		return deployCloudflare(project, { provision: args.includes("--provision"), force: args.includes("--force") });
+	}
+
+	// void's own deploy — the managed platform, void's login — after vc's gate.
+	const check = await preflight(project, "void");
+	printPreflight(project, check, "void");
+	if (!check.ready && check.remote !== null && !args.includes("--force")) {
+		console.error(`${color.red("✗")} refusing to deploy a shop that is not ready for customers. Fix the above, or pass --force.\n`);
+		return 1;
+	}
+	if (!check.ready && check.remote === null) {
+		console.log(color.dim("Secrets could not be verified here; void's own deploy gate is the next check.\n"));
+	}
+	return runVoid(["deploy", ...voids], project.appDir);
+}
+
+export async function preflightCommand(args: string[]): Promise<number> {
+	const project = await findProject();
+	if (!project) {
+		console.error("vc: no voidcommerce.json here.");
+		return 1;
+	}
+	const source = args.includes("--cloudflare") ? "wrangler" : "void";
+	const result = await preflight(project, source);
+	printPreflight(project, result, source);
+	return result.ready ? 0 : 1;
+}
+
+/** void's deploy help, then what vc adds. */
+export async function deployHelp(): Promise<number> {
+	const captured = await captureVoid(["deploy", "--help"]);
+	const width = 80;
+	const ours = box("vc deploy", [
+		line("vc's preflight — every required key set, the hostnames right — then", width),
+		line("void deploy, untouched. Or, with --cloudflare, your own account via wrangler.", width),
+		line("", width),
+		line(color.bold("Usage"), width),
+		...row("vc deploy [void's flags]", "preflight, then void deploy — the Void platform, void's login", width, 2),
+		...row("vc deploy --cloudflare", "wrangler, your Cloudflare account, no Void login: preflight, build, scrub baked secrets, migrate D1, deploy", width, 2),
+		...row("vc deploy --cloudflare --provision", "first time: create the D1 database and the queue, record them", width, 2),
+		...row("vc deploy --cloudflare --force", "deploy a shop preflight says is not ready — deliberately", width, 2),
+		line("", width),
+		line(color.bold("Needs, for --cloudflare"), width),
+		...row("wrangler login", "or CLOUDFLARE_API_TOKEN; the account is pinned for you when there is one", width, 2),
+		...row("wrangler secret put <KEY>", "each secret, on the worker — preflight lists them", width, 2),
+	], width);
+	if (captured) process.stdout.write(captured.out.replace(/\n*$/, "\n"));
+	console.log(ours);
+	return captured?.code ?? 0;
+}
+
+export async function preflightHelp(): Promise<number> {
+	const width = 80;
+	console.log(
+		box("vc preflight", [
+			line("Is this shop ready to advertise on? Every required key, and what breaks without it.", width),
+			line("", width),
+			...row("vc preflight", "secrets from the Void platform", width, 2),
+			...row("vc preflight --cloudflare", "secrets from the worker, via wrangler", width, 2),
+			line("", width),
+			line("Exit 0 when ready. `vc deploy` runs this first and refuses otherwise.", width),
+		], width),
+	);
+	return 0;
+}

package/src/deploy/jsonc.ts

@@ -0,0 +1,148 @@
+/**
+ * Enough JSONC to read and edit a `wrangler.jsonc` without losing its
+ * comments. Wrangler's own edits normalise the whole file; these do not.
+ */
+
+/** Parse JSON with `//` and `/* *\/` comments and trailing commas. */
+export function parseJsonc<T = unknown>(text: string): T {
+	let out = "";
+	let inString = false;
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i]!;
+		const next = text[i + 1];
+		if (inString) {
+			out += ch;
+			if (ch === "\\") {
+				out += next ?? "";
+				i++;
+			} else if (ch === '"') inString = false;
+			continue;
+		}
+		if (ch === '"') {
+			inString = true;
+			out += ch;
+		} else if (ch === "/" && next === "/") {
+			while (i < text.length && text[i] !== "\n") i++;
+			out += "\n";
+		} else if (ch === "/" && next === "*") {
+			i += 2;
+			while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++;
+			i++;
+		} else out += ch;
+	}
+	// Trailing commas, outside strings.
+	let cleaned = "";
+	inString = false;
+	for (let i = 0; i < out.length; i++) {
+		const ch = out[i]!;
+		if (inString) {
+			cleaned += ch;
+			if (ch === "\\") {
+				cleaned += out[i + 1] ?? "";
+				i++;
+			} else if (ch === '"') inString = false;
+			continue;
+		}
+		if (ch === '"') inString = true;
+		if (ch === ",") {
+			let j = i + 1;
+			while (j < out.length && /\s/.test(out[j]!)) j++;
+			if (out[j] === "}" || out[j] === "]") continue;
+		}
+		cleaned += ch;
+	}
+	return JSON.parse(cleaned) as T;
+}
+
+/** Positions in the ORIGINAL text of a top-level key's value, or null. */
+function findTopLevel(text: string, key: string): { keyStart: number; valueStart: number; valueEnd: number } | null {
+	let depth = 0;
+	let inString = false;
+	let stringStart = -1;
+	let lastKey: { text: string; start: number } | null = null;
+	for (let i = 0; i < text.length; i++) {
+		const ch = text[i]!;
+		const next = text[i + 1];
+		if (inString) {
+			if (ch === "\\") i++;
+			else if (ch === '"') {
+				inString = false;
+				if (depth === 1) lastKey = { text: text.slice(stringStart + 1, i), start: stringStart };
+			}
+			continue;
+		}
+		if (ch === "/" && next === "/") {
+			while (i < text.length && text[i] !== "\n") i++;
+			continue;
+		}
+		if (ch === "/" && next === "*") {
+			i += 2;
+			while (i < text.length && !(text[i] === "*" && text[i + 1] === "/")) i++;
+			i++;
+			continue;
+		}
+		if (ch === '"') {
+			inString = true;
+			stringStart = i;
+			continue;
+		}
+		if (ch === ":" && depth === 1 && lastKey?.text === key) {
+			let j = i + 1;
+			while (j < text.length && /\s/.test(text[j]!)) j++;
+			return { keyStart: lastKey.start, valueStart: j, valueEnd: valueEnd(text, j) };
+		}
+		if (ch === "{" || ch === "[") depth++;
+		else if (ch === "}" || ch === "]") depth--;
+	}
+	return null;
+}
+
+/** Where the value starting at `from` ends (exclusive). */
+function valueEnd(text: string, from: number): number {
+	const open = text[from];
+	if (open === '"') {
+		for (let i = from + 1; i < text.length; i++) {
+			if (text[i] === "\\") i++;
+			else if (text[i] === '"') return i + 1;
+		}
+		return text.length;
+	}
+	if (open === "{" || open === "[") {
+		let depth = 0;
+		let inString = false;
+		for (let i = from; i < text.length; i++) {
+			const ch = text[i]!;
+			if (inString) {
+				if (ch === "\\") i++;
+				else if (ch === '"') inString = false;
+				continue;
+			}
+			if (ch === '"') inString = true;
+			else if (ch === "/" && text[i + 1] === "/") {
+				while (i < text.length && text[i] !== "\n") i++;
+			} else if (ch === "{" || ch === "[") depth++;
+			else if (ch === "}" || ch === "]") {
+				depth--;
+				if (depth === 0) return i + 1;
+			}
+		}
+		return text.length;
+	}
+	let i = from;
+	while (i < text.length && !/[,}\]\s]/.test(text[i]!)) i++;
+	return i;
+}
+
+/** Set a top-level key, replacing its value or adding it last. Comments and the rest of the file are kept. */
+export function upsertJsonc(text: string, key: string, value: unknown, indent = "  "): string {
+	const rendered = JSON.stringify(value, null, indent).replace(/\n/g, `\n${indent}`);
+	const found = findTopLevel(text, key);
+	if (found) return text.slice(0, found.valueStart) + rendered + text.slice(found.valueEnd);
+	const close = text.lastIndexOf("}");
+	if (close < 0) return `{\n${indent}${JSON.stringify(key)}: ${rendered}\n}\n`;
+	// Does a property precede the closing brace? Then a comma is needed.
+	let k = close - 1;
+	while (k >= 0 && /\s/.test(text[k]!)) k--;
+	const needsComma = text[k] !== "{" && text[k] !== ",";
+	return `${text.slice(0, close).replace(/\s*$/, "")}${needsComma ? "," : ""}\n${indent}${JSON.stringify(key)}: ${rendered}\n${text.slice(close)}`;
+}

package/src/deploy/preflight.ts

@@ -0,0 +1,137 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import color from "picocolors";
+import type { EnvKey } from "../catalog";
+import { allEnvKeys } from "../generate/env";
+import { workerHosts } from "../manifest";
+import type { Project } from "../project";
+import { captureVoid } from "../void";
+import { parseJsonc } from "./jsonc";
+import { findWrangler, secretNames } from "./wrangler";
+
+/**
+ * Is this deployment ready to advertise on?
+ *
+ * Every key in env.ts is required, which stops one being silently absent.
+ * It cannot stop one being PRESENT and meaningless: the `unset` sentinel
+ * lets a developer run the app without an Adyen account, and a deployment
+ * carrying it would start perfectly, take an order, and never charge
+ * anyone. This is the gate that says WHY each thing matters.
+ */
+
+export const UNSET = "unset";
+
+export interface Preflight {
+	/** What is set, from .env.production and the worker's secrets. */
+	present: Map<string, string>;
+	/** Secret names on the worker; null when they could not be read. */
+	remote: Set<string> | null;
+	missing: EnvKey[];
+	routeProblem: string | null;
+	ready: boolean;
+}
+
+export type SecretSource = "wrangler" | "void";
+
+/** Keys committed in .env.production — safe values only, by construction. */
+export function productionEnv(appDir: string): Map<string, string> {
+	const out = new Map<string, string>();
+	const path = join(appDir, ".env.production");
+	if (!existsSync(path)) return out;
+	for (const line of readFileSync(path, "utf8").split("\n")) {
+		const match = /^\s*([A-Z0-9_]+)\s*=\s*(.*)$/.exec(line);
+		if (!match) continue;
+		const value = (match[2] ?? "").trim().replace(/^['"]|['"]$/g, "");
+		if (value) out.set(match[1]!, value);
+	}
+	return out;
+}
+
+/** Secret names from the Void platform's `void secret list`, best effort. */
+async function voidSecretNames(appDir: string): Promise<Set<string> | null> {
+	const captured = await captureVoid(["secret", "list"], appDir);
+	if (!captured || captured.code !== 0) return null;
+	const names = new Set<string>();
+	for (const line of captured.out.split("\n")) {
+		const match = /\b([A-Z][A-Z0-9_]{2,})\b/.exec(line.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, ""));
+		if (match) names.add(match[1]!);
+	}
+	return names;
+}
+
+/** The worker's hostnames must be what the layout says. */
+export function routeProblem(project: Project): string | null {
+	const path = join(project.appDir, "wrangler.jsonc");
+	if (!existsSync(path)) return "wrangler.jsonc is missing";
+	let routes: Array<{ pattern?: string }> = [];
+	try {
+		routes = parseJsonc<{ routes?: Array<{ pattern?: string }> }>(readFileSync(path, "utf8")).routes ?? [];
+	} catch {
+		return "wrangler.jsonc cannot be parsed";
+	}
+	const expected = workerHosts(project.manifest);
+	const found = routes.map((r) => r.pattern ?? "");
+	const absent = expected.filter((host) => !found.includes(host));
+	return absent.length === 0 ? null : `wrangler.jsonc routes to [${found.join(", ")}] but the shop needs ${absent.join(", ")}`;
+}
+
+export async function preflight(project: Project, source: SecretSource): Promise<Preflight> {
+	const present = productionEnv(project.appDir);
+	let remote: Set<string> | null = null;
+	if (source === "wrangler") {
+		const bin = findWrangler(project.appDir);
+		remote = bin ? await secretNames(bin, project.appDir) : null;
+	} else {
+		remote = await voidSecretNames(project.appDir);
+	}
+	for (const name of remote ?? []) present.set(name, "<secret>");
+
+	const missing = allEnvKeys(project.manifest).filter((key) => {
+		const value = present.get(key.key);
+		return value === undefined || value === "" || value === UNSET;
+	});
+	const problem = routeProblem(project);
+	return { present, remote, missing, routeProblem: problem, ready: missing.length === 0 && problem === null };
+}
+
+/** Print the report a person can act on. */
+export function printPreflight(project: Project, result: Preflight, source: SecretSource): void {
+	const keys = allEnvKeys(project.manifest);
+	if (result.remote === null) {
+		console.log(
+			color.dim(
+				source === "wrangler"
+					? "Could not read the worker's secrets — not deployed yet, or wrangler is not logged in.\nAnything not in .env.production is reported as missing.\n"
+					: "Could not read the project's secrets from Void — not logged in, or no linked project.\nAnything not in .env.production is reported as missing.\n",
+			),
+		);
+	}
+	console.log("REQUIRED — the shop cannot trade without these");
+	for (const key of keys) {
+		const value = result.present.get(key.key);
+		const set = value !== undefined && value !== "" && value !== UNSET;
+		console.log(`  ${set ? color.green("set  ") : color.dim("unset")}  ${key.key}${key.plaintext ? color.dim("  (plaintext)") : ""}`);
+	}
+	if (result.ready) {
+		console.log(`\n${color.green("Ready to go live.")}\n`);
+		return;
+	}
+	console.log(`\n${color.red("NOT ready to go live.")}\n`);
+	if (result.routeProblem) {
+		console.log(`${color.red("✗")} the worker's hostname\n    ${result.routeProblem}\n`);
+	}
+	for (const key of result.missing) {
+		console.log(`${color.red("✗")} ${key.key}`);
+		console.log(`    ${key.breaks}`);
+		if (key.where) console.log(`    ${color.dim(`from: ${key.where}`)}`);
+		console.log("");
+	}
+	const secrets = result.missing.filter((key) => !key.plaintext);
+	if (secrets.length > 0) {
+		console.log(source === "wrangler" ? "Set each secret on the worker (this also creates the draft worker on a first deploy):" : "Set each secret on the project:");
+		for (const key of secrets) console.log(`  ${source === "wrangler" ? "wrangler secret put" : "void secret put"} ${key.key}`);
+	}
+	const plain = result.missing.filter((key) => key.plaintext);
+	if (plain.length > 0) console.log(`Values safe to commit go in .env.production: ${plain.map((k) => k.key).join(", ")}`);
+	console.log("");
+}