void 0.20.1 → 0.20.3

package/dist/email-Bj7Cvdwp.mjs

@@ -0,0 +1,795 @@
+import { o as join } from "./dist-BrsS7cai.mjs";
+import { D as log, I as isCancel, c as import_picocolors, i as createSpinner, j as password, k as note, w as confirm } from "./output-B0cfNSx5.mjs";
+import { C as renderAddressMap, S as preflightEmail, a as isWranglerNonInteractiveOrCI, b as createNodeEmailDns, i as discoverRootWranglerConfig, o as loadProvisionModule, r as deriveWorkerName, s as resolveDeployTransport, t as createDeployWranglerRunner, u as runWranglerAuthToken, w as renderEmailChecklist, x as findEmailConfigConflicts, y as applyEmailSetup } from "./deploy-BAhhcg5q.mjs";
+import { n as readProjectPaths } from "./project-paths-SK8nMHPp.mjs";
+import { S as readProjectConfig, f as openBrowser, l as getToken } from "./auth-DPl6kck4.mjs";
+import { k as writeProvisionedWranglerConfig } from "./wrangler--imS8n0d.mjs";
+import { f as readConfig } from "./config-uNGuFsI2.mjs";
+import { a as scanEmailHandlersSync } from "./email-Ce6SQq-i.mjs";
+import { n as PlatformClient, t as PlatformApiError } from "./client-BQBrZoCX.mjs";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { execSync } from "node:child_process";
+import { parseRootWranglerConfig, readWranglerTopLevelString } from "@void/deploy-cloudflare";
+//#region src/cli/email.ts
+async function runEmailCommand(root, args) {
+	if (args.platform === "cloudflare") return runEmailCloudflareCommand(root, args);
+	if (args.subcommand === "setup") {
+		log.error("email: `void email setup` sets email up on your OWN Cloudflare account — run it with `--platform cloudflare`. The Void platform needs no setup: deploy, and `void email usage` shows your address.");
+		process.exit(1);
+	}
+	if (args.subcommand === "status") {
+		log.error("email: `void email status` is available with `--platform cloudflare` today. On the Void platform use `void email usage` and `void email destinations`.");
+		process.exit(1);
+	}
+	const token = getToken(root);
+	if (!token) {
+		log.error("Not logged in. Run `void auth login` first.");
+		process.exit(1);
+	}
+	const client = new PlatformClient(token, { root });
+	const requestedSlug = args.projectSlug ?? process.env.VOID_PROJECT?.trim();
+	let projectId;
+	if (requestedSlug) {
+		const project = (await client.listProjects()).find((p) => p.slug === requestedSlug);
+		if (!project) {
+			log.error(`project: No project found with slug '${requestedSlug}'.`);
+			process.exit(1);
+		}
+		projectId = project.id;
+	} else {
+		const config = readProjectConfig(root);
+		if (!config) {
+			log.error("No linked project. Run `void project link` or pass --project <name>.");
+			process.exit(1);
+		}
+		projectId = config.projectId;
+	}
+	switch (args.subcommand) {
+		case "usage": return emailUsage(client, projectId);
+		case "logs": return emailLogs(client, projectId, args.limit);
+		case "destinations": return emailDestinations(client, projectId);
+		case "allow": return emailAllow(client, projectId, args.address);
+		case "disallow": return emailDisallow(client, projectId, args.address);
+		case "domain": return runEmailDomainCommand(client, projectId, args);
+	}
+}
+async function emailUsage(client, projectId) {
+	const usage = await client.getEmailUsage(projectId);
+	const status = usage.suspended ? import_picocolors.default.red("SUSPENDED") : import_picocolors.default.green("active");
+	const lines = [
+		`Month:              ${usage.month}`,
+		`Status:             ${status}`,
+		`Recipient attempts: ${usage.attempts} / ${usage.limit} (${usage.remaining} remaining)`,
+		`Inbound receipts:   ${usage.received}`
+	];
+	note(lines.join("\n"), "Email Usage");
+}
+async function emailDestinations(client, projectId) {
+	const rows = await client.listEmailDestinations(projectId);
+	if (rows.length === 0) {
+		log.info("No verified destinations. Run `void email allow <address>` to add one — Cloudflare will email the recipient with a verification link.");
+		return;
+	}
+	const lines = rows.map((d) => {
+		const status = d.status === "verified" ? import_picocolors.default.green("verified") : d.status === "pending" ? import_picocolors.default.yellow("pending") : import_picocolors.default.red("failed");
+		return `  ${d.address.padEnd(40)} ${status}`;
+	});
+	note(lines.join("\n"), "Email Destinations");
+}
+async function emailAllow(client, projectId, address) {
+	const dest = await client.addEmailDestination(projectId, address);
+	const sent = dest.verificationSent !== false && (dest.created || dest.platformVerificationPending);
+	if (dest.status === "verified") log.success(`${dest.address} is already verified.`);
+	else if (sent) {
+		log.success(`Verification email sent to ${dest.address}.`);
+		log.info("They click the link in their inbox — no Void or Cloudflare account needed. `void email destinations` to poll status.");
+	} else if (dest.created) log.warn(`${dest.address} is on this project's list now, but Cloudflare already had the address pending (added by another project, or by hand), so no new verification email was sent — the link it mailed when the address was first added is the one to click. ${freshLinkHint(dest.address)}`);
+	else log.info(`${dest.address} is still pending — Cloudflare emailed them a verification link when the address was first added, and a repeat add sends nothing new. ${freshLinkHint(dest.address)}`);
+}
+/**
+* Cloudflare has no API to resend its verification mail; the only fresh link
+* is a fresh registration, and the platform deletes the Cloudflare-side
+* address only once no project still lists it.
+*/
+function freshLinkHint(address) {
+	return `For a fresh link, remove the address from every project that lists it (\`void email disallow ${address}\`), then \`void email allow ${address}\` — Cloudflare mails a new link only when it registers the address anew.`;
+}
+async function emailDisallow(client, projectId, address) {
+	const dest = (await client.listEmailDestinations(projectId)).find((d) => d.address.toLowerCase() === address.toLowerCase());
+	if (!dest) {
+		log.error(`destination: '${address}' is not in the project's allowlist.`);
+		process.exit(1);
+	}
+	await client.removeEmailDestination(projectId, dest.id);
+	log.success(`Removed ${dest.address}. New sends to it are refused immediately; already admitted attempts may finish.`);
+}
+async function emailLogs(client, projectId, limit) {
+	const result = await client.getEmailLogs(projectId, limit);
+	if (result.logs.length === 0) {
+		log.info("No email activity recorded.");
+		return;
+	}
+	const lines = result.logs.map((entry) => {
+		return `${new Date(entry.timestamp).toISOString()}  ${entry.direction === "sent" ? "→" : "←"}  ${entry.operationId}  ${entry.recipient ?? "—"}  ${entry.status}${entry.errorCode ? ` (${entry.errorCode})` : ""}`;
+	});
+	note(lines.join("\n"), "Email Logs");
+}
+/**
+* The dashboard template link's permission groups (contract 8). Every key
+* rides every link — there is no apex-only key, because `Zone Settings Edit`
+* gates the routing POST on both paths; `zone: read` is what the zone lookup
+* needs. URL-encoded by `URL.searchParams`.
+*/
+const CF_TOKEN_TEMPLATE_PERMISSION_GROUPS = [
+	{
+		key: "zone",
+		type: "read"
+	},
+	{
+		key: "email_routing_rule",
+		type: "edit"
+	},
+	{
+		key: "email_sending",
+		type: "edit"
+	},
+	{
+		key: "workers_scripts",
+		type: "edit"
+	},
+	{
+		key: "zone_settings",
+		type: "edit"
+	}
+];
+/** The three-click template link — the scoped token path (0078, "Creating the token in three clicks"). */
+function buildCfApiTokenTemplateUrl(domain) {
+	const url = new URL("https://dash.cloudflare.com/profile/api-tokens");
+	url.searchParams.set("permissionGroupKeys", JSON.stringify(CF_TOKEN_TEMPLATE_PERMISSION_GROUPS));
+	url.searchParams.set("accountId", "*");
+	url.searchParams.set("zoneId", "all");
+	url.searchParams.set("name", `Void email — ${domain}`);
+	return url.href;
+}
+const CFUT_TOKEN_PATTERN = /^cfut_[A-Za-z0-9_-]{44,64}$/;
+const LEGACY_CF_TOKEN_PATTERN = /^[A-Za-z0-9_-]{40}$/;
+const REFUSED_TOKEN_PREFIXES = [
+	"ghp_",
+	"github_pat_",
+	"sk-",
+	"xox",
+	"cfk_"
+];
+/** Shape-only classification of a clipboard or pasted value. Never logs the value. */
+function classifyCfApiTokenShape(value) {
+	const token = value.trim();
+	if (REFUSED_TOKEN_PREFIXES.some((prefix) => token.startsWith(prefix))) return "refused";
+	if (CFUT_TOKEN_PATTERN.test(token)) return "cfut";
+	if (LEGACY_CF_TOKEN_PATTERN.test(token)) return "legacy";
+	return "unknown";
+}
+function readClipboard() {
+	const platform = process.platform;
+	const command = platform === "darwin" ? "pbpaste" : platform === "win32" ? "powershell -NoProfile -Command Get-Clipboard" : "xclip -o -selection clipboard";
+	try {
+		return execSync(command, {
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			]
+		});
+	} catch {
+		if (platform !== "darwin" && platform !== "win32") try {
+			return execSync("wl-paste", {
+				encoding: "utf8",
+				stdio: [
+					"ignore",
+					"pipe",
+					"ignore"
+				]
+			});
+		} catch {}
+		return null;
+	}
+}
+/** `pbcopy </dev/null` and the platform equivalents — best-effort, never throws. */
+function clearClipboard() {
+	const platform = process.platform;
+	try {
+		if (platform === "darwin") execSync("pbcopy", { input: "" });
+		else if (platform === "win32") execSync("clip", { input: "" });
+		else try {
+			execSync("xclip -selection clipboard", { input: "" });
+		} catch {
+			execSync("wl-copy", { input: "" });
+		}
+	} catch {}
+}
+/**
+* The CLI-side active check from 0078's clipboard sequence. 'unknown' means
+* the check could not run (no network, a CF error) — the caller proceeds and
+* lets the platform verify authoritatively, never treating a network blip as
+* a bad token. The token itself is never logged.
+*/
+async function verifyCfApiToken(token) {
+	let res;
+	try {
+		res = await fetch("https://api.cloudflare.com/client/v4/user/tokens/verify", { headers: { authorization: `Bearer ${token}` } });
+	} catch {
+		return "unknown";
+	}
+	if (res.status === 401 || res.status === 403) return "inactive";
+	if (!res.ok) return "unknown";
+	try {
+		return (await res.json()).result?.status === "active" ? "active" : "inactive";
+	} catch {
+		return "unknown";
+	}
+}
+/** Mirror of the api's normalization (`normalizeEmailDomain`). */
+function normalizeEmailDomainInput(raw) {
+	return raw.trim().toLowerCase().replace(/\.$/, "");
+}
+/**
+* Same DNS-hostname shape the api enforces — checked here so junk fails
+* before a grant is ever requested, not after. Real validation stays the
+* platform's zone lookup.
+*/
+function isValidEmailDomainInput(domain) {
+	return /^(?!-)[a-z0-9-]{1,63}(?<!-)(\.(?!-)[a-z0-9-]{1,63}(?<!-))+$/.test(domain);
+}
+/**
+* Where `--subdomain` lands: a bare label nests under the positional domain
+* (`mx` → `mx.acme.com`), a full host is taken as-is but must stay under it.
+* Throws on anything else — the user named a domain this add cannot register.
+*/
+function resolveEmailDomainTarget(domain, subdomain) {
+	if (subdomain === void 0) return {
+		emailDomain: domain,
+		forced: false
+	};
+	const candidate = subdomain.trim().toLowerCase().replace(/\.$/, "");
+	const resolved = candidate.includes(".") ? candidate : `${candidate}.${domain}`;
+	if (!isValidEmailDomainInput(resolved)) throw new Error(`email: invalid --subdomain value '${subdomain}'.`);
+	if (resolved === domain || !resolved.endsWith(`.${domain}`)) throw new Error(`email: --subdomain must name a subdomain of ${domain} (got '${subdomain}').`);
+	return {
+		emailDomain: resolved,
+		forced: true
+	};
+}
+/**
+* Local public-DNS MX read. [] = no records, null = could not read. The
+* local answer only steers the default and the render — the platform
+* re-checks over public DNS and its answer is authoritative, so a
+* split-horizon resolver never blocks a valid setup here.
+*/
+async function lookupMxForRender(dns, name) {
+	try {
+		return (await dns.resolveMx(name)).slice().sort((a, b) => a.priority - b.priority).map((r) => r.exchange.replace(/\.$/, "").toLowerCase());
+	} catch (err) {
+		const code = err?.code;
+		return code === "ENODATA" || code === "ENOTFOUND" ? [] : null;
+	}
+}
+/**
+* The "Enter switches paths" race from 0078's flow. The default reads one
+* cooked-mode line from stdin; `stop` removes the listener so a losing race
+* cannot eat the first keystroke of a later prompt.
+*/
+function createEnterRace(waitForEnter) {
+	if (waitForEnter) return {
+		promise: waitForEnter().then(() => "enter"),
+		stop: () => {}
+	};
+	const stdin = process.stdin;
+	let onData;
+	return {
+		promise: new Promise((resolve) => {
+			if (!stdin.isTTY) return;
+			onData = () => resolve("enter");
+			stdin.on("data", onData);
+		}),
+		stop: () => {
+			if (onData) stdin.removeListener("data", onData);
+		}
+	};
+}
+async function defaultPasteToken() {
+	const result = await password({
+		message: "Paste the Cloudflare API token:",
+		mask: "*"
+	});
+	if (isCancel(result) || typeof result === "symbol") return null;
+	return result;
+}
+/**
+* Lost-answer reconcile bounds for `domain add`: attempt-count bounded (not
+* wall clock) so the worst case is finite and tests are deterministic. The
+* API's pre-insert phase is DB-only but takes tens of ms to seconds of
+* Hyperdrive RTTs, and a lost answer does not stop the API worker — a single
+* immediate status read can 404 while the POST is still committing.
+*/
+const ADD_RECONCILE_ATTEMPTS = 15;
+const ADD_RECONCILE_INTERVAL_MS = 1e3;
+async function emailDomainAdd(client, projectId, rawDomain, subdomain, deps = {}) {
+	const exit = deps.exit ?? ((code) => process.exit(code));
+	const fail = (message) => {
+		log.error(message);
+		return exit(1);
+	};
+	const domain = normalizeEmailDomainInput(rawDomain);
+	if (!isValidEmailDomainInput(domain)) return fail(`email: invalid domain '${rawDomain}'.`);
+	let target;
+	try {
+		target = resolveEmailDomainTarget(domain, subdomain);
+	} catch (err) {
+		return fail(err instanceof Error ? err.message : String(err));
+	}
+	const dns = deps.dns ?? await createNodeEmailDns();
+	const decideTarget = async () => {
+		if (target.forced) {
+			const mx = await lookupMxForRender(dns, target.emailDomain);
+			if (mx !== null && mx.length > 0) log.warn(`MX        ${target.emailDomain} already carries MX (${mx.join(", ")}) — the platform re-checks over public DNS and may refuse it.`);
+		} else {
+			const mx = await lookupMxForRender(dns, domain);
+			if (mx === null) log.info(`MX        could not read ${domain}'s MX from here — the platform decides over public DNS.`);
+			else if (mx.length > 0) {
+				target = {
+					emailDomain: `mail.${domain}`,
+					forced: false
+				};
+				log.info(`MX        ${domain} carries MX for ${mx[0]} → apex is off limits\n          using ${target.emailDomain}  [change with --subdomain]`);
+				const subMx = await lookupMxForRender(dns, target.emailDomain);
+				if (subMx !== null && subMx.length > 0) log.warn(`MX        ${target.emailDomain} also carries MX (${subMx.join(", ")}) — the platform may refuse it; pick another with --subdomain.`);
+			} else log.info(`MX        ${domain} has no MX records → using the apex`);
+		}
+	};
+	let renewal;
+	const settings = await client.getEmailSettings(projectId);
+	if (settings.domains.management === "admin") {
+		const rows = await client.listEmailDomains(projectId);
+		const existing = [target.emailDomain, ...target.forced ? [] : [`mail.${domain}`]].map((candidate) => rows.find((row) => row.domain === candidate && row.managed_by !== "admin")).find((row) => row !== void 0);
+		if (!existing) {
+			await decideTarget();
+			const project = settings.domains.projectSlug ?? projectId;
+			log.info([
+				"Email domains on this platform are managed by its administrator.",
+				"Ask them to run:",
+				"",
+				`  void platform email domain-add ${target.emailDomain} --project ${project}`,
+				"",
+				"`void email domain list` and `void email domain status` keep working here."
+			].join("\n"));
+			return exit(0);
+		}
+		renewal = existing.domain;
+		target = {
+			emailDomain: existing.domain,
+			forced: true
+		};
+	}
+	if (renewal !== void 0) log.info(`Updating ${renewal} with a scoped credential; the platform will reconcile setup.`);
+	else await decideTarget();
+	if (!(deps.isInteractive ?? !isWranglerNonInteractiveOrCI())) return fail("email: `void email domain add` needs an interactive terminal to create or paste a scoped Cloudflare API token. Run it locally.");
+	let credential;
+	{
+		log.info(`Create a Cloudflare API token restricted to the account and DNS zone containing ${target.emailDomain}. In the resource selectors, replace All accounts and All zones with those exact resources. Workers Scripts Write still applies to every Worker in the selected account.`);
+		const url = buildCfApiTokenTemplateUrl(target.emailDomain);
+		const readClip = deps.readClipboard ?? readClipboard;
+		const clearClip = deps.clearClipboard ?? clearClipboard;
+		const verify = deps.verifyToken ?? verifyCfApiToken;
+		const openUrl = deps.openUrl ?? ((u) => {
+			import("node:child_process").then(({ execFile }) => openBrowser(u, execFile));
+		});
+		const snapshot = readClip();
+		if (snapshot === null) log.info("No clipboard tool found here — paste the token instead.");
+		openUrl(url);
+		let outcome;
+		let watchSpinner;
+		if (snapshot === null) outcome = { type: "timeout" };
+		else {
+			watchSpinner = createSpinner();
+			watchSpinner.start([
+				"Create the token in three clicks: Continue to summary → Create Token → Copy.",
+				"Watching the clipboard for it — nothing is read until you copy, and it is cleared afterwards.",
+				"(Enter pastes it yourself instead.)",
+				`If the browser didn't open, visit:\n${import_picocolors.default.cyan(url)}`
+			].join("\n"));
+			const spinner = watchSpinner;
+			const deadline = Date.now() + (deps.watchTimeoutMs ?? 6e5);
+			const interval = deps.watchIntervalMs ?? 1e3;
+			const snapshotTrimmed = snapshot.trim();
+			const enterDuringWatch = createEnterRace(deps.waitForEnter);
+			let watchSettled = false;
+			let watchTimer;
+			outcome = await Promise.race([(async () => {
+				while (!watchSettled && Date.now() < deadline) {
+					await new Promise((resolve) => {
+						watchTimer = setTimeout(resolve, interval);
+					});
+					if (watchSettled) break;
+					const value = readClip()?.trim();
+					if (!value || value === snapshotTrimmed) continue;
+					const shape = classifyCfApiTokenShape(value);
+					if (shape === "refused" || shape === "unknown") continue;
+					const verdict = await verify(value);
+					if (verdict === "inactive") {
+						spinner.message("That is not an active Cloudflare token — still waiting.");
+						continue;
+					}
+					if (verdict === "unknown") log.info("Could not reach Cloudflare to check the token — the platform will verify it.");
+					return {
+						type: "token",
+						token: value
+					};
+				}
+				return { type: "timeout" };
+			})(), enterDuringWatch.promise.then(() => ({ type: "enter" }))]);
+			watchSettled = true;
+			enterDuringWatch.stop();
+			watchTimer?.unref();
+		}
+		if (outcome.type === "token") {
+			clearClip();
+			watchSpinner?.stop("Token received — the clipboard copy was cleared.");
+			log.info("A clipboard manager may keep its own history — clear it there if you run one.");
+			credential = {
+				kind: "api_token",
+				apiToken: outcome.token
+			};
+		} else {
+			watchSpinner?.stop(outcome.type === "enter" ? "Pasting instead." : "No token arrived — paste it instead.");
+			const pasted = await (deps.pasteToken ?? defaultPasteToken)();
+			if (pasted === null) {
+				log.info("Cancelled — nothing was stored anywhere.");
+				return;
+			}
+			const token = pasted.trim();
+			const shape = classifyCfApiTokenShape(token);
+			if (shape === "refused") return fail("email: that looks like a different kind of token (a GitHub, OpenAI, Slack, or Cloudflare global key) — the link above creates a scoped Cloudflare API token.");
+			if (shape === "unknown") return fail("email: that is not shaped like a Cloudflare API token (`cfut_…` or the legacy 40-character form). Create one from the link above.");
+			const verdict = await verify(token);
+			if (verdict === "inactive") return fail("email: that is not an active Cloudflare token.");
+			if (verdict === "unknown") log.info("Could not reach Cloudflare to check the token — the platform will verify it.");
+			credential = {
+				kind: "api_token",
+				apiToken: token
+			};
+		}
+	}
+	if (!await (deps.confirmScope ?? (async (domain) => {
+		const answer = await confirm({
+			message: `Is this token restricted to the Cloudflare account and DNS zone containing ${domain}?`,
+			initialValue: false
+		});
+		return !isCancel(answer) && answer === true;
+	}))(target.emailDomain)) return fail("email: restrict the token to the selected account and zone before adding the domain. Nothing was submitted to the platform.");
+	const attemptId = crypto.randomUUID();
+	log.info(`Setup operation: ${attemptId}`);
+	let row;
+	try {
+		row = await client.addEmailDomain(projectId, {
+			domain: target.emailDomain,
+			apiToken: credential.apiToken,
+			attemptId
+		});
+	} catch (error) {
+		if (error instanceof PlatformApiError && [
+			400,
+			403,
+			404,
+			409
+		].includes(error.status)) throw error;
+		const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+		for (let attempt = 0; attempt < ADD_RECONCILE_ATTEMPTS; attempt++) {
+			if (attempt > 0) await sleep(ADD_RECONCILE_INTERVAL_MS);
+			let operation;
+			try {
+				operation = await client.getEmailOperation(projectId, attemptId);
+			} catch {
+				continue;
+			}
+			note([
+				`Operation:   ${operation.operationId}`,
+				`Status:      ${operation.status}`,
+				`Inbound:     ${operation.readiness.inbound.status}`,
+				`Outbound:    ${operation.readiness.outbound.status}`,
+				`Credential:  ${operation.readiness.management.status}`
+			].join("\n"), "Email Setup");
+			if (operation.error) log.error(operation.error);
+			log.info(`Run \`void email domain status ${target.emailDomain}\` to inspect setup.`);
+			if (operation.status === "completed") return;
+			return fail(`email: setup is ${operation.status}; operation ${operation.operationId} retains its confirmed progress on the platform.`);
+		}
+		return fail(`email: setup outcome is unknown (operation ${attemptId}). Nothing was revoked. Check \`void email domain status ${target.emailDomain}\` before starting another setup.`);
+	}
+	log.success("Token stored encrypted on the platform for this zone connection — nothing is kept on this machine.");
+	printEmailDomainOutcome(row);
+	if (row.operationStatus !== "completed") return exit(1);
+}
+function emailDomainStatusText(status) {
+	if (status === "ready") return import_picocolors.default.green("ready");
+	if (status === "pending") return import_picocolors.default.yellow("pending");
+	return status === "disabled" ? import_picocolors.default.yellow("disabled") : import_picocolors.default.red(status);
+}
+function printEmailDomainOutcome(row, projectRef) {
+	const lines = [
+		`Domain:      ${row.domain}`,
+		`Managed by:  ${row.managed_by === "admin" ? "administrator" : "project owner"}`,
+		...Object.entries(row.readiness).map(([name, value]) => `${name.padEnd(12)} ${value.status}${value.reason ? " — " + value.reason : ""}${value.observedAt ? " (" + value.observedAt + ")" : ""}`)
+	];
+	if (row.operationId) lines.push(`Operation:   ${row.operationId}${row.operationStatus ? " · " + row.operationStatus : ""}`);
+	note(lines.join("\n"), "Email Domain");
+	if (row.error) log.error(row.error);
+	if (row.operationStatus === "unknown") {
+		log.warn(`Operation ${row.operationId} has an unknown outcome; inspect its status before retrying.`);
+		return;
+	}
+	if (row.readiness.management.status === "expired" || row.readiness.management.status === "revoked") log.info(row.managed_by === "admin" ? `Ask your administrator to run \`void platform email domain-add ${row.domain} --project ${projectRef ?? row.projectId}\` with a renewed credential.` : `Run \`void email domain add ${row.domain}\` with a new scoped API token.`);
+	else if (row.readiness.inbound.status === "pending" || row.readiness.inbound.status === "drifted") log.info(row.managed_by === "admin" ? `Ask your administrator to run \`void platform email domain-sync ${row.domain}\` to reconcile setup.` : `Run \`void email domain sync ${row.domain}\` to reconcile setup.`);
+}
+async function emailDomainStatus(client, projectId, rawDomain) {
+	const domain = normalizeEmailDomainInput(rawDomain);
+	const row = await client.getEmailDomain(projectId, domain);
+	printEmailDomainOutcome(row, row.managed_by === "admin" ? (await client.getEmailSettings(projectId)).domains.projectSlug ?? projectId : void 0);
+}
+async function emailDomainList(client, projectId) {
+	const rows = await client.listEmailDomains(projectId);
+	if (rows.length === 0) {
+		log.info("No email domains. Run `void email domain add <domain>` to send and receive at your own domain on a Cloudflare zone.");
+		return;
+	}
+	const width = Math.max(...rows.map((row) => row.domain.length));
+	const lines = rows.map((row) => `  ${row.domain.padEnd(width)}  ${emailDomainStatusText(row.status)}  ${row.managed_by === "admin" ? "administrator" : "project owner"}`);
+	note(lines.join("\n"), "Email Domains");
+}
+async function emailDomainSync(client, projectId, rawDomain) {
+	const domain = normalizeEmailDomainInput(rawDomain);
+	const row = await client.syncEmailDomain(projectId, domain);
+	printEmailDomainOutcome(row);
+	if (row.operationStatus !== "completed") throw new Error(`email: reconciliation ${row.operationStatus ?? "pending"}; inspect operation ${row.operationId ?? row.domain}`);
+}
+/** Rotation applies to every domain sharing this zone connection. */
+async function emailDomainRotateSecret(client, projectId, rawDomain, deps = {}) {
+	const domain = normalizeEmailDomainInput(rawDomain);
+	const attemptId = crypto.randomUUID();
+	let row;
+	try {
+		row = await client.rotateEmailDomainSecret(projectId, domain, attemptId);
+	} catch (error) {
+		if (error instanceof PlatformApiError && [
+			400,
+			403,
+			404,
+			409
+		].includes(error.status)) throw error;
+		const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+		for (let attempt = 0; attempt < ADD_RECONCILE_ATTEMPTS; attempt++) {
+			if (attempt > 0) await sleep(ADD_RECONCILE_INTERVAL_MS);
+			let operation;
+			try {
+				operation = await client.getEmailOperation(projectId, attemptId);
+			} catch {
+				continue;
+			}
+			note([
+				`Operation:   ${operation.operationId}`,
+				`Status:      ${operation.status}`,
+				`Inbound:     ${operation.readiness.inbound.status}`,
+				`Outbound:    ${operation.readiness.outbound.status}`,
+				`Credential:  ${operation.readiness.management.status}`
+			].join("\n"), "Email Secret Rotation");
+			if (operation.status !== "completed") throw new Error(`email: secret rotation ${operation.status}; inspect operation ${operation.operationId}`);
+			log.success("Zone ingress secret rotated and verified on the deployed Worker.");
+			return;
+		}
+		throw new Error(`email: secret rotation outcome is unknown (operation key ${attemptId}); inspect \`void email domain status ${domain}\` before starting another rotation.`);
+	}
+	printEmailDomainOutcome(row);
+	if (row.operationStatus !== "completed") throw new Error(`email: secret rotation ${row.operationStatus ?? "pending"}; inspect operation ${row.operationId ?? row.domain}`);
+	log.success("Zone ingress secret rotated and verified on the deployed Worker.");
+}
+async function emailDomainRemove(client, projectId, rawDomain, options = {}) {
+	const domain = normalizeEmailDomainInput(rawDomain);
+	const result = await client.removeEmailDomain(projectId, domain);
+	log.info(`Operation: ${result.operationId} · ${result.operationStatus ?? "pending"}`);
+	if (!result.removed || result.operationStatus !== "completed") {
+		log.error(result.error ?? "Email cleanup is not complete. Its operation and resources remain recorded for reconciliation.");
+		(options.exit ?? ((code) => process.exit(code)))(1);
+		return;
+	}
+	log.success(`Removed ${domain}. Zone resources still used by other domains were retained.`);
+}
+async function runEmailDomainCommand(client, projectId, args) {
+	switch (args.domainVerb) {
+		case "add": return emailDomainAdd(client, projectId, args.domain, args.subdomain);
+		case "status": return emailDomainStatus(client, projectId, args.domain);
+		case "list": return emailDomainList(client, projectId);
+		case "sync": return emailDomainSync(client, projectId, args.domain);
+		case "rotate-secret": return emailDomainRotateSecret(client, projectId, args.domain);
+		case "remove": return emailDomainRemove(client, projectId, args.domain);
+	}
+}
+/**
+* Wrangler discovers config files by walking parent directories. A standalone email command in
+* an app with no root config must still run in an explicit empty config context, otherwise an
+* unrelated ancestor config can select the wrong account. The real project path remains separate:
+* setup writes there only after it succeeds, while status leaves the project untouched.
+*/
+function createEmailWranglerConfigContext(configPath) {
+	if (existsSync(configPath)) return {
+		path: configPath,
+		cleanup: () => {}
+	};
+	const directory = mkdtempSync(join(tmpdir(), "void-email-wrangler-"));
+	const path = join(directory, "wrangler.jsonc");
+	try {
+		writeFileSync(path, "{}\n", {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 384
+		});
+	} catch (error) {
+		rmSync(directory, {
+			recursive: true,
+			force: true
+		});
+		throw error;
+	}
+	return {
+		path,
+		cleanup: () => rmSync(directory, {
+			recursive: true,
+			force: true
+		})
+	};
+}
+/**
+* `void email setup --platform cloudflare` and `void email status --platform cloudflare`.
+*
+* `setup` is the deploy's step 3b-ii on its own: preflight → checklist → the one Enter →
+* apply → write the root wrangler.jsonc. It exists for CI: a non-interactive deploy that
+* finds email not ready prints the checklist and says to run this once, commit
+* wrangler.jsonc, and redeploy. Rules and the catch-all stay wrangler's job — the next
+* `void deploy --platform cloudflare` applies the plan from the written `addresses`. It
+* is also the ONLY place a sending onboarding the committed binding remembers as refused
+* (Workers Free) is retried — on its own prompt, after a Workers Paid upgrade; the deploy
+* reads that row as settled and never retries it.
+*
+* `status` is the preflight alone, printed, exit 1 when not ready.
+*/
+async function runEmailCloudflareCommand(root, args, deps = {}) {
+	const rawExit = deps.exit ?? ((code) => process.exit(code));
+	const from = readConfig(root).email?.from;
+	if (!from) {
+		log.error("email: no sender configured. Add \"email\": { \"from\": \"you@mail.acme.com\" } to void.json — its host is the domain email is set up on.");
+		return rawExit(1);
+	}
+	const paths = readProjectPaths(root);
+	const handlers = scanEmailHandlersSync(paths.sourceRoot);
+	const configPath = discoverRootWranglerConfig(root);
+	const wranglerConfig = createEmailWranglerConfigContext(configPath);
+	try {
+		return await runEmailCloudflareCommandInConfig(root, args, {
+			from,
+			handlers
+		}, configPath, wranglerConfig.path, {
+			...deps,
+			exit: (code) => {
+				wranglerConfig.cleanup();
+				return rawExit(code);
+			}
+		});
+	} finally {
+		wranglerConfig.cleanup();
+	}
+}
+async function runEmailCloudflareCommandInConfig(root, args, project, configPath, wranglerConfigPath, deps) {
+	const exit = deps.exit ?? ((code) => process.exit(code));
+	const print = deps.print ?? ((block) => log.message(block));
+	const fail = (message) => {
+		log.error(message);
+		return exit(1);
+	};
+	const { from, handlers } = project;
+	const rootConfig = parseRootWranglerConfig(configPath);
+	await loadProvisionModule();
+	let apiBaseUrl;
+	try {
+		apiBaseUrl = resolveDeployTransport(root, rootConfig);
+	} catch (err) {
+		return fail(`email: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	const accountId = readWranglerTopLevelString(rootConfig, "account_id") ?? (process.env.CLOUDFLARE_ACCOUNT_ID?.trim() || void 0);
+	if (!accountId) return fail([
+		"email: no Cloudflare account is pinned.",
+		"Set `account_id` in your root wrangler.jsonc, or export CLOUDFLARE_ACCOUNT_ID —",
+		"the same pin `void deploy --platform cloudflare` needs."
+	].join("\n"));
+	const workerName = readWranglerTopLevelString(rootConfig, "name") ?? deriveWorkerName(root);
+	const runWrangler = deps.runWrangler ?? createDeployWranglerRunner(root, accountId, apiBaseUrl);
+	const getSessionBearer = deps.getSessionBearer ?? (() => runWranglerAuthToken(runWrangler, wranglerConfigPath));
+	const sendEmail = rootConfig.send_email;
+	const inputs = {
+		handlers,
+		from,
+		workerName,
+		accountId,
+		existingSendEmail: Array.isArray(sendEmail) ? sendEmail : null,
+		existingAddresses: rootConfig.addresses,
+		existingVars: rootConfig.vars && typeof rootConfig.vars === "object" && !Array.isArray(rootConfig.vars) ? rootConfig.vars : null,
+		configConflicts: findEmailConfigConflicts(rootConfig),
+		wranglerArgs: [
+			"-c",
+			wranglerConfigPath,
+			"--env="
+		],
+		apiBaseUrl,
+		runWrangler,
+		getSessionBearer,
+		fetchImpl: deps.fetchImpl ?? fetch,
+		dns: deps.dns ?? await createNodeEmailDns()
+	};
+	let pre;
+	try {
+		pre = await preflightEmail(inputs);
+	} catch (err) {
+		return fail(`email: ${err instanceof Error ? err.message : String(err)}`);
+	}
+	print(renderEmailChecklist(pre));
+	if (args.subcommand === "status") {
+		print(renderAddressMap({
+			from,
+			routes: pre.derived.routes,
+			addresses: pre.rules.mine,
+			sendingReady: pre.sending.state === "ready",
+			pendingLabel: "(no rule yet)"
+		}));
+		if (pre.ready) {
+			log.success(`Email is set up on ${pre.domain}.`);
+			return;
+		}
+		log.warn(`Email is not set up on ${pre.domain} yet — run \`void email setup --platform cloudflare\`.`);
+		return exit(1);
+	}
+	if (pre.blockers.some((b) => b.scope === "all")) return fail("email: nothing was changed — fix the ✘ rows above and rerun.");
+	if (!pre.ready || pre.sendingRetryable) {
+		if (!(deps.isInteractive ?? !isWranglerNonInteractiveOrCI())) return fail("email: `void email setup` changes your Cloudflare account, so it needs an interactive terminal. Run it locally once, commit wrangler.jsonc, then redeploy.");
+		if (!await (deps.confirm ?? (async (message) => {
+			const answer = await confirm({
+				message,
+				initialValue: true
+			});
+			return !isCancel(answer) && answer === true;
+		}))(pre.ready ? `Onboard ${pre.domain} for Email Sending? Inbound already works; onboarding needs Workers Paid.` : `Set up email on ${pre.domain}?`)) {
+			log.info("Nothing changed.");
+			return;
+		}
+	}
+	const out = await applyEmailSetup(pre, inputs);
+	if (out.lines.length > 0) print(out.lines.join("\n"));
+	try {
+		writeProvisionedWranglerConfig(root, out.patch, { configPath });
+	} catch (err) {
+		return fail(`email: could not update ${configPath} — ${err instanceof Error ? err.message : String(err)}`);
+	}
+	print(renderAddressMap({
+		from,
+		routes: pre.derived.routes,
+		addresses: out.patch.addresses ?? [],
+		sendingReady: out.sendingReady,
+		pendingLabel: "(no rule yet)"
+	}));
+	if (!out.inboundReady) {
+		const missing = !out.routingReady ? `Email Routing on ${pre.domain} is not ready` : !out.subaddressingReady ? `subaddressing on ${pre.apex} is still off (support+anything@ would not reach support@)` : "`addresses` was withheld";
+		log.warn(`Email is not set up on ${pre.domain} yet — ${missing}; no routing rule is created until it is. Finish the step above, then rerun \`void email setup --platform cloudflare\`.`);
+		return exit(1);
+	}
+	if ((out.patch.addresses ?? []).length > 0) log.info("Routing rules are created by the next `void deploy --platform cloudflare`, which applies the Email Routing plan from `addresses`.");
+	log.success(`Email set up on ${pre.domain}.`);
+}
+//#endregion
+export { runEmailCommand };