@pithy-sh/cli 0.1.0

package/src/capabilities/eject.ts

@@ -0,0 +1,331 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { cp, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname, join, relative, sep } from "node:path";
+import { ConflictError, InternalError, NotFoundError } from "@pithy-sh/core/src/error/pithyError";
+import { promoteDependencies } from "../project/packageManager";
+import { readOptionalFile } from "../project/readOptionalFile";
+import { ensureScaffoldPath, pathExists } from "../project/scaffold";
+import { workerEntryPath } from "../project/wrangler";
+import {
+  capabilityImportSpecifier,
+  findNamedImport,
+  importedSpecifiers,
+  isCapabilityImport,
+  isInside,
+  namedReexports,
+} from "./configImports";
+
+/**
+ * The directory an ejected capability's source is copied into, relative to the Worker's
+ * `pithy.config.ts` — so it lands in `apps/<worker>/capabilities/<cap>/`, beside the config that
+ * imports it. Ejecting is per-Worker because the wiring it forks is per-Worker.
+ */
+export const EJECT_DIR = "capabilities";
+
+/**
+ * The local import path an ejected capability is wired to, **from the Worker's own directory** — also the
+ * "this is ejected" signal for upgrade, which reads `pithy.config.ts` and nothing else.
+ *
+ * Every other file is a different distance from the fork, so a file that is not the config asks
+ * {@link ejectSpecifierFromDir} instead.
+ */
+export function ejectImportPath(capability: string): string {
+  return `./${EJECT_DIR}/${capability}`;
+}
+
+/**
+ * The fork's specifier **as written into a file in `fromDir`** — `./capabilities/<cap>` from the Worker's
+ * own directory, `../capabilities/<cap>` from the `src/` the entry usually sits in.
+ *
+ * A specifier is resolved relative to the file holding it, and eject writes one into two files at two
+ * depths: `apps/<worker>/pithy.config.ts` and whatever module that Worker's `main` names. Reusing the
+ * config's spelling in the entry produced `./capabilities/<cap>` resolved from `apps/<worker>/src/`,
+ * which is nowhere — a Worker that stopped bundling, written by the command whose job is that it still
+ * does. So each writer derives its own path from the file it is writing into.
+ *
+ * POSIX separators whatever the platform's are: this is a module specifier, not a filesystem path, and a
+ * bundler reads `\` as an escape.
+ */
+export function ejectSpecifierFromDir(workerDir: string, fromDir: string, capability: string): string {
+  const path = relative(fromDir, join(workerDir, EJECT_DIR, capability))
+    .split(sep)
+    .join("/");
+  return path.startsWith(".") ? path : `./${path}`;
+}
+
+/**
+ * The capabilities a `pithy.config.ts` source has ejected — those imported from the local
+ * `./capabilities/<name>` path rather than an `@pithy-sh/*` package. The local import **is** the
+ * ejected signal: a future `pithy upgrade` reads this to skip forks (issue #33), since ejected code
+ * no longer tracks the package.
+ */
+export function parseEjectedCapabilities(configSource: string): string[] {
+  const names: string[] = [];
+  for (const specifier of importedSpecifiers(configSource)) {
+    const name = ejectedCapabilityName(specifier);
+    if (name && !names.includes(name)) names.push(name);
+  }
+  return names;
+}
+
+/**
+ * The capability a specifier forks, or `undefined` when it does not point into the fork directory.
+ *
+ * Decided by {@link isInside} — the same call `importOrigin` makes — because these two functions
+ * answer one question and used to answer it differently: a regex here accepted
+ * `./capabilities/<name>/<anything>` while `isCapabilityImport` demanded exact equality, so a config
+ * read as ejected while the import that made it so was refused as not the capability's. The regex also
+ * captured `..` as a capability name, off a path leaving the directory entirely.
+ */
+function ejectedCapabilityName(specifier: string): string | undefined {
+  const prefix = `./${EJECT_DIR}/`;
+  if (!specifier.startsWith(prefix)) return undefined;
+  const name = specifier.slice(prefix.length).split("/")[0];
+  if (!name || name === "." || name === "..") return undefined;
+  return isInside(specifier, ejectImportPath(name)) ? name : undefined;
+}
+
+/**
+ * Read a Worker's `pithy.config.ts` and return the ejected capability names (empty if the file is
+ * unreadable). `workerDir` is `apps/<name>` — the config that wires the capability is the one that says
+ * whether it was forked.
+ */
+export async function ejectedCapabilities(workerDir: string): Promise<string[]> {
+  try {
+    return parseEjectedCapabilities(await readFile(join(workerDir, "pithy.config.ts"), "utf8"));
+  } catch {
+    return [];
+  }
+}
+
+/** Whether a specific capability has been ejected in this Worker. */
+export async function isEjected(workerDir: string, capability: string): Promise<boolean> {
+  return (await ejectedCapabilities(workerDir)).includes(capability);
+}
+
+/** Promote a forked capability's runtime deps into the project. Injected in tests. */
+export type PromoteDeps = (projectDir: string, deps: string[]) => Promise<void>;
+
+export interface EjectCapabilityOptions {
+  /** The project root — where `package.json`, the lockfile, and `node_modules` live. */
+  projectDir: string;
+  /** The Worker's directory (`apps/<name>`) — its `pithy.config.ts`, and where the fork lands. */
+  workerDir: string;
+  /** The capability's short name, e.g. `auth` — the local directory and import leaf. */
+  capability: string;
+  /** The capability's package, e.g. `@pithy-sh/auth` — the source and manifest to read. */
+  package: string;
+  /** Overwrite an existing local copy, discarding the user's edits. Off by default (refuses). */
+  force?: boolean;
+  /** Promote the package's runtime deps; defaults to the detected package manager. */
+  promoteDeps?: PromoteDeps;
+}
+
+/** What eject did: where the source landed and which deps it promoted. */
+export interface EjectResult {
+  capability: string;
+  /** The Worker-relative directory the source was copied into (`capabilities/<cap>`). */
+  path: string;
+  /** The `name@version` deps promoted into the project (workspace-internal ones excluded). */
+  promotedDependencies: string[];
+  /** Whether an existing local copy was overwritten (`--force`). */
+  forced: boolean;
+}
+
+/**
+ * The package's promotable runtime dependencies as `name@version`, read from the installed manifest.
+ * Workspace-internal versions (`workspace:*`) are dropped — they exist only inside this monorepo and a
+ * published package never carries them; an adopter's install resolves them to real ranges.
+ */
+async function promotableDependencies(projectDir: string, pkg: string): Promise<string[]> {
+  // Absent and corrupt are both answered by reinstalling; a mode bit and a directory are not, and one
+  // `try` around the read and the parse said *reinstall* to all four (#217). `readOptionalFile` owns the
+  // errno that is not absence and hedges on it, which leaves each of the other three its own sentence.
+  const path = join(projectDir, "node_modules", pkg, "package.json");
+  const raw = await readOptionalFile(path);
+  if (raw === null) {
+    throw new InternalError({
+      message: `${pkg} is not installed, so its dependencies cannot be promoted.`,
+      action: `Reinstall ${pkg}, then eject again.`,
+      detail: `No package.json at ${path}.`,
+    });
+  }
+
+  let dependencies: Record<string, string>;
+  try {
+    dependencies = (JSON.parse(raw) as { dependencies?: Record<string, string> }).dependencies ?? {};
+  } catch (cause) {
+    throw new InternalError({
+      message: `${pkg}'s package.json is not valid JSON, so its dependencies cannot be promoted.`,
+      action: `Reinstall ${pkg}, then eject again.`,
+      detail: cause instanceof Error ? cause.message : String(cause),
+    });
+  }
+  return Object.entries(dependencies)
+    .filter(([, version]) => !version.startsWith("workspace:"))
+    .map(([name, version]) => `${name}@${version}`);
+}
+
+/**
+ * Repoint the managed-region import from the package to the local copy; idempotent if already local.
+ *
+ * The import is found by its binding and repointed whatever path into the package it uses — the same
+ * set `add` writes and `remove` takes out. Matching one exact specifier meant a hand-edited deep
+ * import could not be ejected at all, and `pithy add` would not put the canonical line back, so there
+ * was no way out through the CLI.
+ */
+async function repointImport(workerDir: string, pkg: string, capability: string): Promise<void> {
+  const path = join(workerDir, "pithy.config.ts");
+  const source = await readFile(path, "utf8");
+  // Derived from the file being written, like the entry's is. For the config the answer is
+  // `ejectImportPath` itself — it sits in the Worker's own directory — and that is the string
+  // `parseEjectedCapabilities` reads back as the "this is ejected" signal.
+  const local = ejectSpecifierFromDir(workerDir, dirname(path), capability);
+  const found = findNamedImport(source, capability);
+  if (found?.specifier === local) return; // already ejected — a --force re-copy leaves it local
+  if (found && isCapabilityImport(found.specifier, pkg, local)) {
+    // The specifier is the only quoted region in the statement, so swapping it there keeps whatever
+    // spacing and quote style the adopter's config uses.
+    const repointed = found.statement.replace(found.specifier, () => local);
+    await writeFile(
+      path,
+      source.replace(found.statement, () => repointed),
+    );
+    return;
+  }
+  throw new NotFoundError({
+    message: `${path} doesn't import ${pkg}.`,
+    action: `Run pithy add ${capability} first, then eject.`,
+  });
+}
+
+/**
+ * The local path a specifier into the package becomes once the package's `src/` is a fork under
+ * `capabilities/<cap>/`.
+ *
+ * The barrel becomes the fork directory itself — `local`, the fork as the file being written reaches it,
+ * so the two halves of the wiring name one directory in each file's own spelling. Anything deeper under
+ * `src/` keeps its path below it, because `cp` preserved the structure.
+ *
+ * Anything else inside the package is **refused, by name**. Only `src/` is copied, so there is no local
+ * counterpart to point at, and quietly leaving the line alone would put the package's class back into the
+ * bundle under the fork's name — which is the failure repointing exists to prevent.
+ */
+function localSpecifier(pkg: string, local: string, specifier: string): string {
+  if (specifier === pkg || specifier === capabilityImportSpecifier(pkg)) return local;
+  const src = `${pkg}/src/`;
+  if (specifier.startsWith(src)) return `${local}/${specifier.slice(src.length)}`;
+  throw new ConflictError({
+    message: `The worker entry re-exports ${specifier}, which eject cannot fork — only ${pkg}/src is copied.`,
+    action: `Point that export at a path under ${pkg}/src, or take the line out, then eject again.`,
+  });
+}
+
+/**
+ * The Worker entry with its re-exports of the package repointed at the local fork, or `null` when there
+ * is nothing to change.
+ *
+ * **The other half of the wiring, and the half that decides which code actually runs.** `pithy add` writes
+ * `export { <Class> } from "@pithy-sh/<cap>/…"` into the entry, because wrangler resolves a Durable
+ * Object's `class_name` against the module `main` names (#428). Ejecting only `pithy.config.ts` left that
+ * line pointing at the package: Cloudflare instantiated the package's class while the adopter edited the
+ * copy, and nothing said so — it builds, it deploys, and every change to the forked actor is ignored.
+ * `docs/EJECT.md` promised the project imports nothing from the package afterwards, and this is what makes
+ * that sentence true rather than nearly true.
+ *
+ * Every re-export pointing into the package, not only the ones the CLI wrote. A line an adopter added by
+ * hand reaches the same class through the same package, and `repointImport` follows whatever path into the
+ * package a config uses for exactly this reason.
+ *
+ * A Worker whose config names no entry — a front end that joins the dev set through `pithy.worker.jsonc`
+ * alone — has nothing to repoint and is not a failure.
+ */
+async function planEntryExports(
+  workerDir: string,
+  pkg: string,
+  capability: string,
+): Promise<{ path: string; written: string } | null> {
+  const path = await workerEntryPath(workerDir).catch(() => null);
+  const source = path === null ? null : await readOptionalFile(path);
+  if (path === null || source === null) return null;
+
+  // Relative to the entry, not to `pithy.config.ts`: the two files sit at different depths and the fork
+  // is one directory. {@link ejectSpecifierFromDir} says what reusing the config's spelling here cost.
+  const local = ejectSpecifierFromDir(workerDir, dirname(path), capability);
+  // Planned as spans and applied last-first, so each splice lands where the scanner found it and no
+  // earlier edit moves a later one. Found by offset because a commented-out copy of a line contains
+  // that line verbatim, and a literal search repointed the comment while the live export kept naming
+  // the package (#428). `namedReexports` yields in source order, so reversing gives descending starts.
+  const edits: { start: number; end: number; text: string }[] = [];
+  for (const { statement, specifier, start } of namedReexports(source)) {
+    if (specifier !== pkg && !specifier.startsWith(`${pkg}/`)) continue;
+    // The specifier is the only quoted region in the statement, so swapping it there keeps whatever
+    // spacing and quote style the entry uses. Replacement functions keep any `$` in either string.
+    const text = statement.replace(specifier, () => localSpecifier(pkg, local, specifier));
+    edits.push({ start, end: start + statement.length, text });
+  }
+  if (edits.length === 0) return null;
+
+  let written = source;
+  for (const edit of edits.reverse()) {
+    written = written.slice(0, edit.start) + edit.text + written.slice(edit.end);
+  }
+  return written === source ? null : { path, written };
+}
+
+/**
+ * Eject a capability into **one Worker**: copy its entire installed `src/` into
+ * `apps/<worker>/capabilities/<cap>/`, repoint that Worker's `pithy.config.ts` import at the local copy,
+ * and promote the package's runtime deps into the project so the copy builds standalone. The capability
+ * is now the user's — nothing from `@pithy-sh/<cap>` is imported and it no longer upgrades (the
+ * principle-3 trade). Another Worker that wires the same capability keeps the package; a fork is scoped
+ * to the Worker that asked for it. Refuses to overwrite an existing local copy unless `force` is set;
+ * `force` removes it first so stale files don't linger.
+ */
+export async function ejectCapability(options: EjectCapabilityOptions): Promise<EjectResult> {
+  const { projectDir, workerDir, capability, package: pkg, force } = options;
+  const source = join(projectDir, "node_modules", pkg, "src");
+  const dest = join(workerDir, EJECT_DIR, capability);
+
+  if (!(await pathExists(source))) {
+    throw new NotFoundError({
+      message: `${pkg} is not installed (no ${pkg}/src to eject).`,
+      action: `Run pithy add ${capability} first.`,
+    });
+  }
+
+  // The fork's own path, and every segment of it Pithy composed: `apps`, `apps/<worker>`,
+  // `capabilities`, `capabilities/<cap>`. This was a local `exists()` over `stat`, which follows a link
+  // and answers about its destination — so a symlink at any of the four read as "not ejected yet" and the
+  // `cp` below wrote the capability's whole source through it, outside the project. That is the fifth
+  // producer of one escape, and it is the reason the question has exactly one implementation now.
+  await ensureScaffoldPath(projectDir, dest);
+  const alreadyEjected = await pathExists(dest);
+  if (alreadyEjected && !force) {
+    throw new ConflictError({
+      message: `${EJECT_DIR}/${capability} already exists.`,
+      action: "Edit the local copy, or re-run with --force to overwrite it (discards your changes).",
+    });
+  }
+  if (alreadyEjected) await rm(dest, { recursive: true, force: true });
+
+  // Order matters for a clean failure: copy the source, promote its deps, and only then repoint the
+  // config. If promotion fails, the config still imports the working package rather than a local copy
+  // whose dependencies were never installed.
+  await cp(source, dest, { recursive: true });
+
+  const promotedDependencies = await promotableDependencies(projectDir, pkg);
+  const promote = options.promoteDeps ?? ((dir, deps) => promoteDependencies(dir, deps).then(() => {}));
+  await promote(projectDir, promotedDependencies);
+
+  // Planned before either write, and written after both: {@link localSpecifier} refuses a re-export it
+  // cannot fork, and a refusal raised between the two would leave the config naming the fork while the
+  // entry still named the package. Same reasoning as the copy/promote/repoint order above.
+  const entry = await planEntryExports(workerDir, pkg, capability);
+  await repointImport(workerDir, pkg, capability);
+  if (entry) await writeFile(entry.path, entry.written);
+
+  return { capability, path: `${EJECT_DIR}/${capability}`, promotedDependencies, forced: Boolean(alreadyEjected) };
+}

package/src/capabilities/emailProvisioner.ts

@@ -0,0 +1,346 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFile, unlink, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { CloudflareClients } from "@pithy-sh/cloudflare/src/client/clients";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { LocaleCatalogs } from "@pithy-sh/core/src/i18n/catalog";
+import { createMigrationRegistry } from "@pithy-sh/core/src/migrations/registry";
+import { runMigrations } from "@pithy-sh/core/src/migrations/runner";
+import { email_0001_suppressions } from "@pithy-sh/email/src/migrations/0001_suppressions";
+import {
+  bounceRoutingRuleName,
+  type EmailDeprovisioner,
+  type EmailProvisioner,
+  emailWorkerName,
+  suppressionDatabaseName,
+} from "@pithy-sh/email/src/provision/provisionEmail";
+import { type EmailWorkerWranglerTemplate, resolveEmailConfig } from "@pithy-sh/email/src/provision/resolveEmailConfig";
+import type { EmailTheme } from "@pithy-sh/email/src/templates/theme";
+import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
+import { parse } from "comment-json";
+import type { MigrationProvider } from "kysely/migration";
+import type { CliAuditEmit } from "../audit/cliAudit";
+import { type ConfirmedAccount, findOnConfirmedAccount } from "../cloudflare/accountAnswer";
+import { runWrangler } from "../project/wrangler";
+
+/** The suppression migration set, as provisioning runs it against the shared suppression D1. */
+function suppressionMigrationProvider(): MigrationProvider {
+  const registry = createMigrationRegistry([
+    {
+      database: "emailSuppressions",
+      namespace: "email",
+      order: 100,
+      migrations: { "0001_suppressions": email_0001_suppressions },
+    },
+  ]);
+  const provider = registry.emailSuppressions;
+  if (!provider) throw new Error("missing email suppression migration provider");
+  return provider;
+}
+
+/** The per-environment resource ids + base URL the email worker deploy needs, resolved by the caller. */
+export interface EmailEnvResources {
+  /** The app database id for this environment — where jobs/events live. */
+  appDatabaseId: string;
+  /** This environment's secrets database id (`<project>-<env>-secrets`) — holds the signing key. */
+  secretsDatabaseId: string;
+  /** The app worker's public base URL for this environment — callback links are built against it. */
+  baseUrl: string;
+}
+
+/** Resolve the per-environment resources for the email worker (from the project wrangler + name lookups). */
+export type ResolveEmailEnv = (env: ManagedEnvironment) => Promise<EmailEnvResources>;
+
+export interface CloudflareEmailProvisionerOptions {
+  cf: CloudflareClients;
+  /**
+   * The account this provisions into, and what vouches for it (#378).
+   *
+   * Replaces a bare `accountId`, and the replacement is the point: an id on its own is what six sites
+   * already held while a find-or-create read an empty listing as "this account has none" and minted a
+   * real resource in whichever account the shell had named. The id is still here — `account.accountId` —
+   * and it now travels with the answer to "who says so".
+   */
+  account: ConfirmedAccount;
+  /**
+   * The project name, from `requireProjectName(await loadProject(projectDir))` — never
+   * `resolveProjectName`. The worker, both Workflows, the suppression database, and the inbound routing
+   * rule all lead with it, and the suppression database is *found by name and reused*: a guessed value
+   * would adopt another project's opt-out list.
+   */
+  project: string;
+  /** The broad bootstrap token (`.dev.vars` `CLOUDFLARE_API_TOKEN`) that authenticates the worker deploy. */
+  apiToken: string;
+  /** The CF Secrets Store id holding the per-env master keys (the email worker decrypts its signing key). */
+  storeId: string;
+  /** The resolved brand theme (from the app's `email()` config), serialized into the worker's `EMAIL_THEME` var. */
+  theme: EmailTheme;
+  /**
+   * The project's email catalogs, from the composed capabilities' `hostCatalogs()` — serialized into
+   * the worker's `EMAIL_MESSAGES` var.
+   *
+   * The same journey the theme makes, because the host worker composes nothing and both are things
+   * only a provision run can hand it. Empty for a project that composed no i18n capability, and then
+   * no var is written.
+   */
+  messages: LocaleCatalogs;
+  /** Resolve the per-env app DB id, secrets DB id, and base URL — injected so it is testable + decoupled. */
+  resolveEnv: ResolveEmailEnv;
+  /**
+   * Optional inbound routing: the zone, the address to match, and the production app worker to deliver to.
+   * Absent → the routing step is skipped (the operator wires it later, on a subdomain that won't disturb
+   * the apex MX). Email Routing must already be enabled on the zone.
+   */
+  routing?: { zoneId: string; address: string; appWorkerName: string };
+  /** Audit emitter. Defaults to recording nothing, so a caller without audit wiring still works. */
+  audit?: CliAuditEmit;
+}
+
+/**
+ * The live {@link EmailProvisioner} — the CF + wrangler implementation of email provisioning. The
+ * control-plane steps go through `@pithy-sh/cloudflare` (CLAUDE.md: CF API only via that client) and are
+ * each idempotent; the worker deploy shells out to wrangler with the bootstrap token. No CF API token is
+ * minted — the email worker sends through the `send_email` binding and reads its signing key through the
+ * `SECRETS` bindings, neither of which uses a token. The live steps are exercised by the integration suite.
+ */
+export class CloudflareEmailProvisioner implements EmailProvisioner {
+  readonly #cf: CloudflareClients;
+  readonly #account: ConfirmedAccount;
+  readonly #project: string;
+  readonly #apiToken: string;
+  readonly #storeId: string;
+  readonly #theme: EmailTheme;
+  readonly #messages: LocaleCatalogs;
+  readonly #resolveEnv: ResolveEmailEnv;
+  readonly #routing?: { zoneId: string; address: string; appWorkerName: string };
+  readonly #audit: CliAuditEmit;
+
+  constructor(options: CloudflareEmailProvisionerOptions) {
+    this.#cf = options.cf;
+    this.#account = options.account;
+    this.#project = options.project;
+    this.#apiToken = options.apiToken;
+    this.#storeId = options.storeId;
+    this.#theme = options.theme;
+    this.#messages = options.messages;
+    this.#resolveEnv = options.resolveEnv;
+    this.#routing = options.routing;
+    this.#audit = options.audit ?? (async () => {});
+  }
+
+  /** Require a registered `workers.dev` subdomain — Cloudflare needs one to deploy the Workflow-hosting worker. */
+  async preflight(): Promise<void> {
+    if (!(await this.#cf.workers().accountSubdomain())) {
+      throw new ValidationError({
+        message: "This Cloudflare account has no workers.dev subdomain, which Workflows require.",
+        action: "Open Workers & Pages in the dashboard once to create one, then re-run.",
+      });
+    }
+  }
+
+  /**
+   * Reuse the project's suppression D1 if it exists, otherwise create it.
+   *
+   * Find-then-create is safe only because the name carries the project. D1's namespace is
+   * account-wide, so the old fixed `pithy-email-suppressions` meant a second, unrelated product in the
+   * same account silently inherited the first's opt-out list — one product's unsubscribe suppressing
+   * another's transactional mail. D1 exposes no tags through the API, so the name is the whole
+   * ownership record, and the audit event writes the project down beside it.
+   *
+   * Which is also why the miss refuses on an unconfirmed account (#378): "no database of that name" and
+   * "I asked an account nobody claims" arrive as the same empty listing, and creating on the second one
+   * puts this project's opt-out list in somebody else's account.
+   */
+  async ensureSuppressionDatabase(): Promise<{ databaseId: string }> {
+    const name = suppressionDatabaseName(this.#project);
+    const existing = await findOnConfirmedAccount({
+      ...this.#account,
+      what: `the ${name} database`,
+      find: () => this.#cf.d1Provisioner().findDatabaseByName(name),
+    });
+    if (existing) return { databaseId: existing.uuid };
+    const db = await this.#cf.d1Provisioner().createDatabase(name);
+    await this.#audit({
+      environment: "global",
+      action: "email/suppression_db_created",
+      outcome: "success",
+      severity: "info",
+      resourceType: "cf_d1",
+      resourceId: db.uuid,
+      metadata: { name },
+    });
+    return { databaseId: db.uuid };
+  }
+
+  /** Run the suppression migration against the shared D1 over REST (idempotent — applied ones skip). */
+  async migrateSuppression(databaseId: string): Promise<void> {
+    await runMigrations(this.#cf.d1(databaseId), suppressionMigrationProvider());
+  }
+
+  /** Resolve the env's wrangler config from the committed template + provisioned ids, then `wrangler deploy`. */
+  async deployWorker(env: ManagedEnvironment, suppressionDatabaseId: string): Promise<void> {
+    const { appDatabaseId, secretsDatabaseId, baseUrl } = await this.#resolveEnv(env);
+    const dir = emailWorkerDir();
+    const template = parse(
+      await readFile(join(dir, "wrangler.jsonc"), "utf8"),
+    ) as unknown as EmailWorkerWranglerTemplate;
+    const config = resolveEmailConfig(template, {
+      project: this.#project,
+      env,
+      appDatabaseId,
+      suppressionDatabaseId,
+      secretsDatabaseId,
+      storeId: this.#storeId,
+      baseUrl,
+      theme: this.#theme,
+      messages: this.#messages,
+    });
+    const configPath = join(dir, `.wrangler.${env}.json`);
+    await writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`);
+    try {
+      await runWrangler(["deploy", "--config", configPath], {
+        cwd: dir,
+        env: { CLOUDFLARE_API_TOKEN: this.#apiToken, CLOUDFLARE_ACCOUNT_ID: this.#account.accountId },
+      });
+      await this.#audit({
+        environment: env,
+        action: "email/worker_deployed",
+        outcome: "success",
+        severity: "info",
+        resourceType: "cf_worker",
+        resourceId: emailWorkerName(this.#project, env),
+      });
+    } catch (error) {
+      await this.#audit({
+        environment: env,
+        action: "email/worker_deployed",
+        outcome: "failure",
+        severity: "info",
+        resourceType: "cf_worker",
+        resourceId: emailWorkerName(this.#project, env),
+      });
+      throw error;
+    } finally {
+      await unlink(configPath).catch(() => {});
+    }
+  }
+
+  /** Create the inbound routing rule (production app worker) when routing is configured; otherwise skip. */
+  async ensureRoutingRule(): Promise<{ created: boolean; skipped: boolean }> {
+    if (!this.#routing) return { created: false, skipped: true };
+    const { created } = await this.#cf.emailRouting().ensureWorkerRoute({
+      zoneId: this.#routing.zoneId,
+      address: this.#routing.address,
+      workerName: this.#routing.appWorkerName,
+      // Project-scoped, and distinct from `@pithy-sh/support`'s inbound rule. `ensureWorkerRoute` keys
+      // idempotency on the rule name, so two projects sharing a zone and an unscoped name would each
+      // believe the other's rule was their own — and one project's bounce mail would be delivered to
+      // the other project's Worker.
+      ruleName: bounceRoutingRuleName(this.#project),
+    });
+    if (created) {
+      await this.#audit({
+        environment: "global",
+        action: "email/routing_rule_created",
+        outcome: "success",
+        severity: "info",
+        resourceType: "cf_email_routing_rule",
+        resourceId: this.#routing.address,
+        metadata: {
+          zoneId: this.#routing.zoneId,
+          address: this.#routing.address,
+          workerName: this.#routing.appWorkerName,
+          ruleName: bounceRoutingRuleName(this.#project),
+        },
+      });
+    }
+    return { created, skipped: false };
+  }
+}
+
+/**
+ * The directory of the prebuilt email worker inside the installed `@pithy-sh/email` package (holds
+ * wrangler.jsonc). Exported so the template test resolves the same file the deploy reads — a copy of
+ * this resolution in the test would be a copy free to drift from the path it is meant to guard.
+ */
+export function emailWorkerDir(): string {
+  return dirname(fileURLToPath(import.meta.resolve("@pithy-sh/email/src/workflows/worker")));
+}
+
+export interface CloudflareEmailDeprovisionerOptions {
+  cf: CloudflareClients;
+  /** The project name, from `requireProjectName` — teardown finds resources by no other key. */
+  project: string;
+  /**
+   * The account this teardown deletes from, and what vouches for it (#378).
+   *
+   * Required, and required for the reason `CloudflareConfigOptions.account` is: the guard below reads a
+   * miss as "already gone", so against an account nothing claims it deletes nothing, audits nothing, and
+   * exits 0. A caller that has not decided which account it is tearing down cannot compile.
+   */
+  account: ConfirmedAccount;
+  /** Audit emitter. Defaults to recording nothing, so a caller without audit wiring still works. */
+  audit?: CliAuditEmit;
+}
+
+/**
+ * The live {@link EmailDeprovisioner} — removes each environment's email worker and, when asked, the
+ * shared suppression D1, through `@pithy-sh/cloudflare`. Every step is guarded so a missing resource is a
+ * no-op: teardown is idempotent. The integration suite exercises the provision → teardown round trip.
+ */
+export class CloudflareEmailDeprovisioner implements EmailDeprovisioner {
+  readonly #cf: CloudflareClients;
+  readonly #project: string;
+  readonly #account: ConfirmedAccount;
+  readonly #audit: CliAuditEmit;
+
+  constructor(options: CloudflareEmailDeprovisionerOptions) {
+    this.#cf = options.cf;
+    this.#project = options.project;
+    this.#account = options.account;
+    this.#audit = options.audit ?? (async () => {});
+  }
+
+  /** Delete the env's email worker if it is deployed — and refuse if "deployed" cannot be settled (#378). */
+  async deleteWorker(env: ManagedEnvironment): Promise<void> {
+    const name = emailWorkerName(this.#project, env);
+    if (
+      await findOnConfirmedAccount({
+        ...this.#account,
+        what: `the ${name} Worker`,
+        find: () => this.#cf.workers().getWorker(name),
+      })
+    ) {
+      await this.#cf.workers().deleteWorker(name);
+      await this.#audit({
+        environment: env,
+        action: "email/worker_removed",
+        outcome: "success",
+        severity: "warning",
+        resourceType: "cf_worker",
+        resourceId: name,
+      });
+    }
+  }
+
+  /** Delete this project's suppression D1 if it exists — destructive, called only on a full destroy. */
+  async deleteSuppressionDatabase(): Promise<void> {
+    const name = suppressionDatabaseName(this.#project);
+    const db = await this.#cf.d1Provisioner().findDatabaseByName(name);
+    if (db) {
+      await this.#cf.d1Provisioner().deleteDatabase(db.uuid);
+      await this.#audit({
+        environment: "global",
+        action: "email/suppression_db_removed",
+        outcome: "success",
+        severity: "warning",
+        resourceType: "cf_d1",
+        resourceId: db.uuid,
+        metadata: { name },
+      });
+    }
+  }
+}