@pithy-sh/cli 0.1.0

package/src/capabilities/testersProvisioner.ts

@@ -0,0 +1,236 @@
+// 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 { WorkflowHostTemplate } from "@pithy-sh/core/src/workflow/host";
+import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
+import { parse } from "comment-json";
+import type { CliAuditEmit } from "../audit/cliAudit";
+import { type ConfirmedAccount, findOnConfirmedAccount } from "../cloudflare/accountAnswer";
+import { runWrangler } from "../project/wrangler";
+import { capabilityLoadError } from "./loadFailure";
+
+/**
+ * The live testers provisioner — the Cloudflare + wrangler implementation behind `@pithy-sh/testers`'s
+ * `TestersProvisioner` seam. The account check goes through `@pithy-sh/cloudflare` (CLAUDE.md: the CF
+ * API only via that client); the worker deploy shells out to wrangler with the bootstrap token.
+ *
+ * `@pithy-sh/testers` is an **optional** capability, so the CLI must not hard-depend on it. Types come
+ * in through type-only imports (erased at build), and every runtime value comes through
+ * {@link loadTestersProvisioning} — a guarded dynamic import that turns "the package isn't installed"
+ * into an actionable error rather than an unresolved-module crash.
+ */
+
+/** The testers runtime surface provisioning needs, loaded from the project's own install. */
+type TestersProvisionModule = typeof import("@pithy-sh/testers/src/provision/provisionTesters");
+type TestersResolveModule = typeof import("@pithy-sh/testers/src/provision/resolveTestersConfig");
+type TestersSpecsModule = typeof import("@pithy-sh/testers/src/workflows/specs");
+
+/** The provisioner seams, referenced by type only so the CLI gains no dependency on the package. */
+type TestersProvisioner = import("@pithy-sh/testers/src/provision/provisionTesters").TestersProvisioner;
+type TestersDeprovisioner = import("@pithy-sh/testers/src/provision/provisionTesters").TestersDeprovisioner;
+type TestersConfig = import("@pithy-sh/testers/src/config/config").TestersConfig;
+type TestersEmailIdentity = import("@pithy-sh/testers/src/provision/resolveTestersConfig").TestersEmailIdentity;
+
+/** Everything `pithy testers provision` loads out of the optional package, in one guarded import. */
+export type TestersProvisionSurface = TestersProvisionModule & TestersResolveModule & TestersSpecsModule;
+
+/**
+ * Load the provisioning surface from the project's own install.
+ *
+ * Separate from `testersLoader.ts`'s `loadTesters`, which pulls the data-layer modules the roster
+ * commands need. Splitting them keeps `pithy testers status` from importing a wrangler template
+ * resolver it will never call.
+ */
+export async function loadTestersProvisioning(): Promise<TestersProvisionSurface> {
+  try {
+    const [provision, resolve, specs] = await Promise.all([
+      import("@pithy-sh/testers/src/provision/provisionTesters"),
+      import("@pithy-sh/testers/src/provision/resolveTestersConfig"),
+      import("@pithy-sh/testers/src/workflows/specs"),
+    ]);
+    return { ...provision, ...resolve, ...specs };
+  } catch (error) {
+    throw capabilityLoadError("testers", "@pithy-sh/testers", error);
+  }
+}
+
+/**
+ * The directory of the prebuilt daily-pass worker inside the installed package.
+ *
+ * Resolved from the module rather than assembled from a path, so it keeps working however the adopter's
+ * package manager laid `node_modules` out.
+ */
+async function testersWorkerDir(): Promise<string> {
+  try {
+    return dirname(fileURLToPath(import.meta.resolve("@pithy-sh/testers/src/workflows/worker")));
+  } catch (error) {
+    throw capabilityLoadError("testers", "@pithy-sh/testers/src/workflows/worker", error);
+  }
+}
+
+/** The per-environment resource ids the daily-pass worker binds, resolved by the caller. */
+export interface TestersEnvResources {
+  /** The app database id — the `pithy_testers_*`, `pithy_auth_*` and `pithy_email_jobs` tables. */
+  readonly appDatabaseId: string;
+  /** The global email-suppression database id, shared across environments. */
+  readonly suppressionDatabaseId: string;
+}
+
+/** Resolve the per-environment resources for the host (from the project wrangler + name lookups). */
+export type ResolveTestersEnv = (env: ManagedEnvironment) => Promise<TestersEnvResources>;
+
+export interface CloudflareTestersProvisionerOptions {
+  readonly 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 deployed host, its daily Workflow, and the suppression database name all
+   * lead with it, and a guessed value deploys a host teardown will never find.
+   */
+  readonly project: string;
+  /** The broad bootstrap token (`.dev.vars` `CLOUDFLARE_API_TOKEN`) that authenticates the worker deploy. */
+  readonly apiToken: string;
+  /** The app's resolved testers config — serialized into the host's `TESTERS_CONFIG` var. */
+  readonly testersConfig: TestersConfig;
+  /** The sending identity, or undefined when the project composes no email capability. */
+  readonly email: TestersEmailIdentity | undefined;
+  /** Resolve the per-env database ids — injected so it is testable and decoupled from wrangler parsing. */
+  readonly resolveEnv: ResolveTestersEnv;
+  /** Audit emitter. Defaults to recording nothing, so a caller without audit wiring still works. */
+  readonly audit?: CliAuditEmit;
+}
+
+/** The live provisioner. Every step is idempotent, so provisioning is safe to re-run. */
+export class CloudflareTestersProvisioner implements TestersProvisioner, TestersDeprovisioner {
+  readonly #cf: CloudflareClients;
+  readonly #account: ConfirmedAccount;
+  readonly #project: string;
+  readonly #apiToken: string;
+  readonly #testersConfig: TestersConfig;
+  readonly #email: TestersEmailIdentity | undefined;
+  readonly #resolveEnv: ResolveTestersEnv;
+  readonly #audit: CliAuditEmit;
+
+  constructor(options: CloudflareTestersProvisionerOptions) {
+    this.#cf = options.cf;
+    this.#account = options.account;
+    this.#project = options.project;
+    this.#apiToken = options.apiToken;
+    this.#testersConfig = options.testersConfig;
+    this.#email = options.email;
+    this.#resolveEnv = options.resolveEnv;
+    this.#audit = options.audit ?? (async () => {});
+  }
+
+  /** Require a registered `workers.dev` subdomain — Cloudflare needs one to deploy a Workflow host. */
+  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.",
+      });
+    }
+  }
+
+  /** Resolve the env's wrangler config from the committed template + ids, then `wrangler deploy`. */
+  async deployWorker(env: ManagedEnvironment): Promise<void> {
+    const { resolveTestersConfig, testersWorkerName } = await loadTestersProvisioning();
+    const { appDatabaseId, suppressionDatabaseId } = await this.#resolveEnv(env);
+    const dir = await testersWorkerDir();
+    const template = parse(await readFile(join(dir, "wrangler.jsonc"), "utf8")) as unknown as WorkflowHostTemplate;
+
+    const config = resolveTestersConfig(template, {
+      project: this.#project,
+      env,
+      appDatabaseId,
+      suppressionDatabaseId,
+      testersConfig: this.#testersConfig,
+      email: this.#email,
+    });
+
+    // Written beside the template and removed afterwards. Leaving a resolved config in the package
+    // directory would leave one environment's database ids sitting in `node_modules` after the command
+    // that needed them finished.
+    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: "testers/worker_deployed",
+        outcome: "success",
+        severity: "info",
+        resourceType: "cf_worker",
+        resourceId: testersWorkerName(this.#project, env),
+        metadata: { sends: this.#email !== undefined },
+      });
+    } catch (error) {
+      await this.#audit({
+        environment: env,
+        action: "testers/worker_deployed",
+        outcome: "failure",
+        severity: "warning",
+        resourceType: "cf_worker",
+        resourceId: testersWorkerName(this.#project, env),
+      });
+      throw error;
+    } finally {
+      await unlink(configPath).catch(() => {});
+    }
+  }
+
+  /**
+   * Delete this environment's host, if it is deployed.
+   *
+   * The existence check is what makes teardown idempotent, and it is not belt-and-braces: Cloudflare
+   * answers a delete for an absent script with a 404, `cloudflareRequest` rethrows that as a
+   * `CloudflareRequestError`, and `deprovisionTesters` has no per-environment catch — so an
+   * un-provisioned staging would abort the fan-out before production was attempted. Every sibling
+   * deprovisioner in this directory guards the same call for the same reason.
+   *
+   * The audit sits inside the guard too. A `worker_deleted` event for a worker that never existed is a
+   * false entry in the one log that is supposed to be the record of what actually happened.
+   *
+   * **And the guard now refuses what it cannot settle (#378).** "This account has no such worker" and "I
+   * asked an account nothing claims" arrived here as the same `null`, so a teardown pointed at the wrong
+   * account deleted nothing, audited nothing, and exited 0 — a success message over an untouched
+   * production Worker. The lookup does not even happen unless something vouches for the account.
+   */
+  async deleteWorker(env: ManagedEnvironment): Promise<void> {
+    const { testersWorkerName } = await loadTestersProvisioning();
+    const name = testersWorkerName(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: "testers/worker_deleted",
+        outcome: "success",
+        severity: "warning",
+        resourceType: "cf_worker",
+        resourceId: name,
+      });
+    }
+  }
+}

package/src/capabilities/turnstileProvisioner.ts

@@ -0,0 +1,347 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { CloudflareClients } from "@pithy-sh/cloudflare/src/client/clients";
+import { InternalError, ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { DeclaredEnvironments } from "@pithy-sh/core/src/naming/environment";
+import { dispatchSecretWrite, type SecretDispatcher } from "@pithy-sh/secrets/src/cli/dispatch";
+import { initialDevSecret } from "@pithy-sh/secrets/src/dev/devSecretsFile";
+import type { SecretRegistryEntry } from "@pithy-sh/secrets/src/registry";
+import type { ManagedEnvironment } from "@pithy-sh/secrets/src/scope";
+import { TurnstileMode } from "@pithy-sh/turnstile/src/config/config";
+import {
+  type ManagedTurnstileEnv,
+  productionWidgetName,
+  sitekeyVarName,
+  type TurnstileDeprovisioner,
+  type TurnstileProvisioner,
+} from "@pithy-sh/turnstile/src/provision/provisionTurnstile";
+import { TURNSTILE_SECRET_NAME, turnstileSecretsRegistry } from "@pithy-sh/turnstile/src/secret/registry";
+import type { CliAuditEmit } from "../audit/cliAudit";
+import { answerOnConfirmedAccount, type ConfirmedAccount, unconfirmedAccount } from "../cloudflare/accountAnswer";
+import { removeBootstrapVars } from "../devSecrets/bootstrapVars";
+import { writeDevVars } from "../devSecrets/devVars";
+import { removeDevSecrets, writeDevSecrets } from "../devSecrets/file";
+import { resolveDevSecretsFile } from "../devSecrets/location";
+import { renderDevVarsNotes } from "../devSecrets/report";
+import { readWranglerConfig, type WranglerEnvVars, writeWranglerConfig } from "../project/wrangler";
+
+/** The message of an unknown thrown value, for surfacing both legs of a failed upsert. */
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** A Cloudflare *managed* (visible) or *invisible* widget — the CF API's terms for our two modes. */
+function cloudflareMode(mode: TurnstileMode): "managed" | "invisible" {
+  return mode === "visible" ? "managed" : "invisible";
+}
+
+/**
+ * Every widget name this project can own — one per mode, whether or not config enables both.
+ *
+ * The domain guard subtracts this set rather than matching the one mode being provisioned: a project
+ * running a visible *and* an invisible widget has two of its own widgets on the domain, and the second
+ * pass must not read the first as a squatter. Deriving it from `TurnstileMode` keeps it whole even when
+ * config later enables a mode a previous run already created.
+ */
+function ourWidgetNames(project: string): Set<string> {
+  return new Set(TurnstileMode.options.map((mode) => productionWidgetName(project, mode)));
+}
+
+/** The routing facts the turnstile secret carries — a `d1`, per-environment, rotatable JSON value. */
+const SECRET_FACTS = { backend: "d1", scope: "environment", rotatable: true, valueType: "json" } as const;
+
+export interface CloudflareTurnstileProvisionerOptions {
+  cf: CloudflareClients;
+  /**
+   * The account the production widget is created in, and what vouches for it (#378).
+   *
+   * `assertDomainAvailable` reads an empty listing as "the domain is free" and provisioning then mints a
+   * real widget. Against an account nothing claims, that listing is empty because the widgets it would
+   * have named are somewhere else — so the guard passes for the wrong reason and a live widget lands in a
+   * stranger's account.
+   */
+  account: ConfirmedAccount;
+  /**
+   * The project name from the root `pithy.config.ts`, resolved by `requireProjectName` and never
+   * guessed. It is the leading segment of every widget name, so a wrong value here reuses — and on
+   * teardown deletes — another project's widget (docs/NAMING.md).
+   */
+  project: string;
+  /**
+   * The project root — owner of the one shared `.dev.vars` every worker symlinks to, so a dev sitekey
+   * written here reaches every worker at once.
+   */
+  projectDir: string;
+  /**
+   * The web-facing Worker's directory — its `wrangler.jsonc` is where the per-environment sitekey vars are
+   * written. Per-Worker, because the widget is bound to the domain *that* Worker serves (`BASE_URL`).
+   */
+  workerDir: string;
+  /** The secrets manager dispatcher — writes/deletes the secret in a deployed env's managed store. */
+  dispatcher: SecretDispatcher;
+  /** Audit emitter. Defaults to recording nothing, so a caller without audit wiring still works. */
+  audit?: CliAuditEmit;
+  /**
+   * Where a delivery note goes. Defaults to **stderr**, one line at a time.
+   *
+   * `writeDev` returns `void` — the interface in `@pithy-sh/turnstile` says so — and that is precisely
+   * how the report got dropped: there was nowhere to return it to, so it was discarded and the provision
+   * reported a delivery that had not happened. A seam, so a test can read the lines; stderr by default,
+   * because the alternative to a default is silence, and because `--json` writes its one line to stdout
+   * and a diagnostic must not land in the middle of it.
+   *
+   * Never a value. See `renderDevVarsNotes`.
+   */
+  notes?: (line: string) => void;
+  /** Every environment this project declares, from the root `pithy.config.ts` — the fan-out set for a `global` secret. */
+  environments: DeclaredEnvironments | readonly string[];
+}
+
+/**
+ * The live {@link TurnstileProvisioner}. The widget secret is written like any other secret — `.dev.vars`
+ * for dev, the per-environment manager Workflow for staging/prod (CLAUDE.md §secrets) — and the real
+ * production widget is created through `@pithy-sh/cloudflare`. dev/managed-sitekey writes are idempotent
+ * file upserts; the managed secret write upserts (create, else update); widget creation reuses by name.
+ */
+export class CloudflareTurnstileProvisioner implements TurnstileProvisioner {
+  readonly #cf: CloudflareClients;
+  readonly #account: ConfirmedAccount;
+  readonly #project: string;
+  readonly #projectDir: string;
+  readonly #workerDir: string;
+  readonly #dispatcher: SecretDispatcher;
+  /**
+   * The project's declared environments (#241) — what a `global` secret write fans out across. Carried
+   * rather than assumed, so a shared secret reaches every environment the project deploys to.
+   */
+  readonly #environments: DeclaredEnvironments | readonly string[];
+  readonly #audit: CliAuditEmit;
+  readonly #notes: (line: string) => void;
+
+  constructor(options: CloudflareTurnstileProvisionerOptions) {
+    this.#cf = options.cf;
+    this.#account = options.account;
+    this.#project = options.project;
+    this.#projectDir = options.projectDir;
+    this.#workerDir = options.workerDir;
+    this.#dispatcher = options.dispatcher;
+    this.#environments = options.environments;
+    this.#audit = options.audit ?? (async () => {});
+    this.#notes = options.notes ?? ((line: string) => void process.stderr.write(`${line}\n`));
+  }
+
+  /**
+   * Refuse the domain if a widget that is not ours already covers it — and refuse the *question* if the
+   * account that would answer it is one nothing claims (#378).
+   *
+   * The two failures are opposite in shape and identical on the wire. A foreign widget is a listing with
+   * an entry in it; an unconfirmed account is a listing with nothing in it, which is the same thing "the
+   * domain is free" looks like. Only one of those two empties is a fact, and the other one ends with a
+   * live production widget in an account this project never named.
+   */
+  async assertDomainAvailable(domain: string): Promise<void> {
+    const ours = ourWidgetNames(this.#project);
+    const answer = await answerOnConfirmedAccount({
+      ...this.#account,
+      what: `Turnstile widgets covering ${domain}`,
+      find: () => this.#cf.turnstile().listTurnstilesByDomain(domain),
+    });
+    if (answer.state === "unconfirmed")
+      throw unconfirmedAccount(answer.accountId, `Turnstile widgets covering ${domain}`);
+    const claimants = answer.state === "found" ? answer.value : [];
+    const foreign = claimants.find((widget) => !ours.has(widget.name));
+    if (!foreign) return;
+    throw new ValidationError({
+      message: `A Turnstile widget named "${foreign.name}" already covers ${domain}.`,
+      action: "Bind this project to a different domain, delete that widget, or re-run with --allow-shared-domain.",
+      detail: `sitekey ${foreign.sitekey} claims ${domain}; this project's widgets are ${[...ours].join(", ")}`,
+    });
+  }
+
+  /**
+   * The dev widget's secret and its public sitekeys, each into the file its namespace belongs to.
+   *
+   * **The secret is a `d1` registry secret, so it goes into the dev secrets file (#149)** — through
+   * `writeDevSecrets`, the one funnel every dev secret passes through, at `<config>/<project>/` since
+   * #156. Writing it straight into `.dev.vars` bypassed the format and the mode both, and made this the
+   * fifth producer of the same defect. `replace`, because Cloudflare issued this value: keeping an older
+   * one because a value is already there leaves the project verifying against a widget it no longer has.
+   *
+   * The sitekeys are public, `UPPER_SNAKE`, and wrangler's — they stay in `.dev.vars`, and they are now
+   * the only thing this writes there. The secret itself was copied alongside them until #153, because
+   * dev resolved every secret from its binding whatever its backend; dev reads the seeded row now, so
+   * the copy is gone and a public sitekey no longer shares a file with a widget secret.
+   *
+   * **And what that write says is said, not dropped.** This call took no result at all, so a provision
+   * announced a delivery that may never have happened: a Worker with a `.dev.vars` of its own gets no
+   * sitekey and no secret, and `pithy turnstile provision` still printed "Test secret wired for dev".
+   * The same defect fixed at `pithy add`'s two call sites, in the third one nobody checked — three
+   * producers again, so it goes through the one renderer they share.
+   */
+  async writeDev(secret: string, sitekeys: Record<string, string>): Promise<void> {
+    // Through the registry entry, like every other writer: the entry is what says whether this
+    // secret's destination takes an envelope or the value itself (#323).
+    const entry: SecretRegistryEntry | undefined = turnstileSecretsRegistry[TURNSTILE_SECRET_NAME];
+    const envelope = initialDevSecret(entry ?? {}, secret);
+    const path = await resolveDevSecretsFile(this.#projectDir);
+    await writeDevSecrets(path, { [TURNSTILE_SECRET_NAME]: envelope }, { replace: true });
+    // The sitekeys alone, through `writeDevVars` — so each is quoted for dotenv and reaches the Worker's
+    // own directory rather than the project root alone. The secret goes to the store, on the next seed.
+    const wrote = await writeDevVars({ projectDir: this.#projectDir, values: { ...sitekeys } });
+    for (const note of renderDevVarsNotes(wrote)) this.#notes(note);
+  }
+
+  async writeManagedSecret(env: ManagedTurnstileEnv, secret: string): Promise<void> {
+    // Upsert: create on first provision, update on a re-run (create rejects an existing secret) — so the
+    // write is idempotent. If create fails for a real reason, the update almost always fails too; surface
+    // BOTH causes (create as `cause`) so the true failure isn't masked by the fallback's error.
+    const write = { name: TURNSTILE_SECRET_NAME, ...SECRET_FACTS, value: secret, requested: env as ManagedEnvironment };
+    try {
+      await dispatchSecretWrite(this.#dispatcher, { mode: "create", ...write }, this.#environments);
+    } catch (createError) {
+      try {
+        await dispatchSecretWrite(this.#dispatcher, { mode: "update", ...write }, this.#environments);
+      } catch (updateError) {
+        throw new InternalError(
+          {
+            message: `Could not write the turnstile secret to ${env}.`,
+            detail: `create failed: ${errorMessage(createError)}; update failed: ${errorMessage(updateError)}`,
+          },
+          { cause: createError },
+        );
+      }
+    }
+  }
+
+  async writeManagedSitekeys(env: ManagedTurnstileEnv, sitekeys: Record<string, string>): Promise<void> {
+    await editEnvVars(this.#workerDir, env, (vars) => Object.assign(vars, sitekeys));
+  }
+
+  async ensureProductionWidget(
+    mode: TurnstileMode,
+    domain: string,
+  ): Promise<{ sitekey: string; secret: string | null }> {
+    const name = productionWidgetName(this.#project, mode);
+    const existing = await this.#cf.turnstile().getTurnstile(name);
+    if (existing) return { sitekey: existing.sitekey, secret: null };
+    const created = await this.#cf.turnstile().addTurnstile(name, [domain], cloudflareMode(mode));
+    await this.#audit({
+      action: "turnstile/widget_created",
+      outcome: "success",
+      severity: "info",
+      resourceType: "turnstile_widget",
+      resourceId: created.sitekey,
+      metadata: { name, mode, domain },
+    });
+    return { sitekey: created.sitekey, secret: created.secret };
+  }
+}
+
+/**
+ * The live {@link TurnstileDeprovisioner} — deletes each production widget, the managed secret in every
+ * deployed environment, and every config entry (dev-vars + managed sitekey vars). Each step is guarded so
+ * a missing resource is a no-op: teardown is idempotent.
+ */
+export class CloudflareTurnstileDeprovisioner implements TurnstileDeprovisioner {
+  readonly #cf: CloudflareClients;
+  readonly #project: string;
+  readonly #projectDir: string;
+  readonly #workerDir: string;
+  readonly #dispatcher: SecretDispatcher;
+  /**
+   * The project's declared environments (#241) — what a `global` secret write fans out across. Carried
+   * rather than assumed, so a shared secret reaches every environment the project deploys to.
+   */
+  readonly #environments: DeclaredEnvironments | readonly string[];
+  readonly #audit: CliAuditEmit;
+
+  constructor(options: CloudflareTurnstileProvisionerOptions) {
+    this.#cf = options.cf;
+    this.#project = options.project;
+    this.#projectDir = options.projectDir;
+    this.#workerDir = options.workerDir;
+    this.#dispatcher = options.dispatcher;
+    this.#environments = options.environments;
+    this.#audit = options.audit ?? (async () => {});
+  }
+
+  async deleteProductionWidget(mode: TurnstileMode): Promise<void> {
+    const name = productionWidgetName(this.#project, mode);
+    const existing = await this.#cf.turnstile().getTurnstile(name);
+    if (!existing) return;
+    await this.#cf.turnstile().deleteTurnstile(existing.sitekey);
+    await this.#audit({
+      action: "turnstile/widget_deleted",
+      outcome: "success",
+      severity: "warning",
+      resourceType: "turnstile_widget",
+      resourceId: existing.sitekey,
+      metadata: { name, mode },
+    });
+  }
+
+  async deleteManagedSecret(): Promise<void> {
+    // The project's declaration, not a hardcoded pair: a project that deploys to `live` had its secret
+    // written there and would have kept it forever, because teardown only ever looked at two names.
+    for (const env of this.#environments) {
+      // Delete is idempotent in the manager (a missing name is a no-op), so this is safe to re-run.
+      await dispatchSecretWrite(
+        this.#dispatcher,
+        {
+          mode: "delete",
+          name: TURNSTILE_SECRET_NAME,
+          ...SECRET_FACTS,
+          requested: env,
+        },
+        this.#environments,
+      );
+    }
+  }
+
+  /**
+   * Both halves of what {@link CloudflareTurnstileProvisioner.writeDev} wrote — the secret in the dev
+   * secrets file, and the sitekeys in `.dev.vars`. Leaving the value in the secrets file would have the
+   * next `pithy dev` seed a key for a widget that no longer exists.
+   *
+   * The secret's name is still passed to the removal, and that is deliberate: a project provisioned
+   * before #153 recorded the transitional copy, and teardown is the run that should take it. A name that
+   * is not recorded is a no-op.
+   *
+   * **The adopter's own `.dev.vars` is not touched.** Each Worker's is generated from the bootstrap set,
+   * so taking the names out of that set is what drops the lines — and the project root's file, if there
+   * is one, is theirs. See #154.
+   */
+  async clearDev(modes: TurnstileMode[]): Promise<void> {
+    const keys = [TURNSTILE_SECRET_NAME, ...modes.map((mode) => sitekeyVarName(mode))];
+    await removeBootstrapVars(this.#projectDir, keys);
+    await writeDevVars({ projectDir: this.#projectDir, values: {} });
+    await removeDevSecrets(await resolveDevSecretsFile(this.#projectDir), [TURNSTILE_SECRET_NAME]);
+  }
+
+  async clearManagedSitekeys(modes: TurnstileMode[]): Promise<void> {
+    const keys = modes.map((mode) => sitekeyVarName(mode));
+    for (const env of ["staging", "prod"] as const) {
+      await editEnvVars(this.#workerDir, env, (vars) => {
+        for (const key of keys) delete vars[key];
+      });
+    }
+  }
+}
+
+/** Read the Worker's `wrangler.jsonc`, mutate its `env.<env>.vars` map, and write it back comment-preserving. */
+async function editEnvVars(
+  workerDir: string,
+  env: ManagedTurnstileEnv,
+  mutate: (vars: Record<string, string>) => void,
+): Promise<void> {
+  const config = (await readWranglerConfig(workerDir)) as WranglerEnvVars;
+  config.env ??= {};
+  config.env[env] ??= {};
+  const stanza = config.env[env];
+  if (stanza) {
+    stanza.vars ??= {};
+    mutate(stanza.vars);
+  }
+  await writeWranglerConfig(workerDir, config);
+}