@pithy-sh/cli 0.1.0

package/src/commands/token.ts

@@ -0,0 +1,364 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { CloudflareClients } from "@pithy-sh/cloudflare/src/client/clients";
+import { isPermissionKey, PERMISSION_GROUPS, type PermissionKey } from "@pithy-sh/cloudflare/src/tokens/permissions";
+import {
+  resolveTokenProfiles,
+  TOKEN_STORES,
+  type TokenProfile,
+  type TokenStore,
+} from "@pithy-sh/cloudflare/src/tokens/profiles";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { SecretRegistry } from "@pithy-sh/secrets/src/registry";
+import { defineCommand } from "citty";
+import { createCliAudit } from "../audit/cliAudit";
+import { resolveSecretRegistry } from "../capabilities/secrets";
+import { type CloudflareAccountSelection, cloudflareEnv } from "../cloudflare/config";
+import { loadProject, loadProjectCloudflare, requireProjectName } from "../project/config";
+import { ENV_ARG, requireEnvironment } from "../project/environment";
+import {
+  type CapabilitySet,
+  capabilitySetOf,
+  isUnknown,
+  projectCapabilities,
+  type ResolvedWorker,
+  resolveWorkerSet,
+  type WorkerSet,
+} from "../project/workerScope";
+import { formatDone, formatJsonLine, formatList, withErrorReporting } from "../terminal/output";
+import { tokenOverrideResolver } from "../tokens/config";
+import {
+  listProfileTokens,
+  mintProfileToken,
+  revokeProfileToken,
+  rotateProfileToken,
+  type TokenAudit,
+  type TokenEngine,
+  type TokenResult,
+} from "../tokens/engine";
+
+// `resolveAppDatabaseId` used to be this file's own copy of the app-database lookup, before
+// `createCliAudit` centralized it. Re-exported under its original name — same behavior, same
+// signature — so `token.test.ts`'s direct tests of it keep passing unchanged.
+export { resolveAuditDatabaseId as resolveAppDatabaseId } from "../audit/cliAudit";
+
+/**
+ * The CF credentials the token engine needs, for the account the project belongs to.
+ *
+ * **The account is a parameter, so this cannot run before the project is loaded.** `pithy token mint`
+ * writes real credentials into a real account; resolving them from a file the project did not select
+ * would mint another company's token under this project's name (#206).
+ */
+function loadCreds(account: CloudflareAccountSelection | null): {
+  accountId: string;
+  apiToken: string;
+  storeId: string;
+} {
+  const vars = cloudflareEnv({ account });
+  const accountId = vars.CLOUDFLARE_ACCOUNT_ID ?? "";
+  const apiToken = vars.CLOUDFLARE_API_TOKEN ?? "";
+  if (!accountId || !apiToken) {
+    throw new ValidationError({
+      message: "Cloudflare credentials are missing.",
+      action: "Set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN (the bootstrap token) to mint tokens.",
+    });
+  }
+  return { accountId, apiToken, storeId: vars.SECRETS_STORE_ID ?? "" };
+}
+
+/**
+ * Collect every `--permission` from the raw argv. citty keeps only the last occurrence of a repeated
+ * string flag, so a multi-permission run would otherwise silently drop all but the last — the same
+ * reason `--set` is read from rawArgs. Handles both `--permission key` and `--permission=key`.
+ */
+export function collectPermissionFlags(rawArgs: string[]): string[] {
+  const found: string[] = [];
+  for (let i = 0; i < rawArgs.length; i++) {
+    const arg = rawArgs[i];
+    if (arg === "--permission") {
+      const value = rawArgs[i + 1];
+      if (value !== undefined) {
+        found.push(value);
+        i++;
+      }
+    } else if (arg?.startsWith("--permission=")) {
+      found.push(arg.slice("--permission=".length));
+    }
+  }
+  return found;
+}
+
+/** Validate collected `--permission` keys, or `undefined` when none were given. */
+export function parsePermissions(value: string | string[] | undefined): PermissionKey[] | undefined {
+  const keys = value === undefined ? [] : Array.isArray(value) ? value : [value];
+  if (keys.length === 0) return undefined;
+  for (const key of keys) {
+    if (!isPermissionKey(key)) {
+      throw new ValidationError({
+        message: `Unknown token permission key: ${key}.`,
+        action: `Use one of: ${Object.keys(PERMISSION_GROUPS).join(", ")}.`,
+      });
+    }
+  }
+  return keys as PermissionKey[];
+}
+
+/** Parse a `--store` flag into a validated store, or `undefined` when absent. */
+export function parseStore(value: string | undefined): TokenStore | undefined {
+  if (value === undefined) return undefined;
+  if (!(TOKEN_STORES as readonly string[]).includes(value)) {
+    throw new ValidationError({
+      message: `Unknown token store: ${value}.`,
+      action: `Use one of: ${TOKEN_STORES.join(", ")}.`,
+    });
+  }
+  return value as TokenStore;
+}
+
+/** Project a mint/rotate result to the safe fields for output — everything except the secret `value`. */
+export function publicToken(result: TokenResult): {
+  profile: string;
+  env: string;
+  tokenId: string;
+  store: TokenStore;
+  location: string;
+} {
+  return {
+    profile: result.profile,
+    env: result.env,
+    tokenId: result.tokenId,
+    store: result.sink.sink,
+    location: result.sink.location,
+  };
+}
+
+/**
+ * Build the token engine's audit sink from the shared `createCliAudit` helper — the one place every
+ * CLI command resolves whether/where to record. `createCliAudit` already handles every reason there
+ * might be nowhere to write (audit not composed, package not installed, no app database for the env)
+ * by returning an always-callable no-op, so `TokenAudit` here is just a thin adapter from its event
+ * shape to the generic `CliAuditEvent` — never the token value, only its id and where it went.
+ */
+async function buildAudit(
+  capabilities: CapabilitySet,
+  cf: CloudflareClients,
+  projectDir: string,
+  env: string,
+  apiToken: string,
+): Promise<TokenAudit> {
+  // `env` is both the audit destination and the environment acted on for a token operation.
+  const emit = await createCliAudit({ projectDir, env, actedOn: env, capabilities, clients: cf, apiToken });
+  return async (event) => {
+    await emit({
+      action: event.action,
+      outcome: event.outcome,
+      severity: "warning",
+      resourceType: "cf_api_token",
+      resourceId: event.tokenId ?? `${event.profile}:${event.env}`,
+      metadata: { profile: event.profile, store: event.store ?? null },
+    });
+  };
+}
+
+/**
+ * Every secret backend declared anywhere in the project, merged by name. The name is the join key, so a
+ * Worker that composes `secrets` contributes its registry and one that does not contributes nothing —
+ * a project with no secrets capability at all resolves to `{}` rather than failing a mint.
+ */
+function mergedSecretRegistry(workers: readonly ResolvedWorker[]): SecretRegistry {
+  const registries: SecretRegistry[] = [];
+  for (const worker of workers) {
+    try {
+      registries.push(resolveSecretRegistry(worker.config));
+    } catch {
+      // This Worker composes no secrets capability — nothing to contribute.
+    }
+  }
+  return Object.assign({}, ...registries) as SecretRegistry;
+}
+
+/**
+ * The profile registry a token operation derives from — **refused when the capability set cannot be read,
+ * never derived from an emptied one** (#455).
+ *
+ * {@link buildEngine} already insists the *root* config is required and never guessed, because `revoke`
+ * deletes every account token of the name it computes. The Worker half was best-effort, and that is the
+ * same mistake one level down: `resolveTokenProfiles([])` returns only `ci-system` and drops every
+ * capability's `ciPermissions`, so `pithy token list <env>` told an operator auditing live credentials that
+ * capability-profile tokens do not exist and exited 0, and `pithy token rotate ci-system <env>` minted a
+ * replacement carrying only the base permissions before deleting the fully-permissioned one it replaced.
+ * CI lost permissions silently, with nothing in the run saying the capability set was unknown.
+ *
+ * A project with genuinely **no** Workers still resolves normally: `ci-system` is a project-level profile
+ * and mints fine before the first `pithy worker add`. See {@link resolveWorkerSet} for the difference.
+ *
+ * The refusal quotes the set's own diagnosis rather than inventing one, so it names the worker.
+ */
+export function tokenProfiles(workers: WorkerSet): Record<string, TokenProfile> {
+  if (!isUnknown(workers)) return resolveTokenProfiles(projectCapabilities(workers));
+  throw new ValidationError({
+    message: "This project's capability set is unknown, so token permissions cannot be derived.",
+    action:
+      `${workers.unknown} Fix it — pithy doctor names the fault — and re-run. Token permissions come from ` +
+      "the composed capabilities, so minting from a partial set narrows what CI can do.",
+  });
+}
+
+/** Assemble the token engine: the aggregated profiles, the secret-registry backends, and the audit sink. */
+async function buildEngine(projectDir: string, env: string): Promise<TokenEngine> {
+  // Identity/policy comes from the root config; what the project is *made of* comes from each Worker's.
+  // The root config is required here, not best-effort: every token name and Secrets Store entry starts
+  // with the project name, and `revoke` deletes every account token of the name it computes. Guessing
+  // it would point that sweep at another project's credentials.
+  //
+  // Read *before* the credentials, because it is also what says which account they come from.
+  const config = await loadProject(projectDir);
+  const { accountId, apiToken, storeId } = loadCreds(loadProjectCloudflare(config) ?? null);
+  const cf = new CloudflareClients({ accountId, apiToken });
+  // Never best-effort. See {@link tokenProfiles}: an emptied capability set is a silently narrowed credential.
+  const workerSet = await resolveWorkerSet({ projectDir });
+  const workers = isUnknown(workerSet) ? [] : workerSet;
+  const registry = mergedSecretRegistry(workers);
+  return {
+    accountId,
+    project: requireProjectName(config),
+    projectDir,
+    tokens: cf.accountTokens(),
+    /*
+      **A getter, so the refusal lands on the operations that actually need the registry.**
+
+      `mint`, `rotate` and `list` each read `profiles` on their first line — the first two to resolve a
+      profile's permissions, the third to recover a profile name by reverse lookup — so an unknown
+      capability set makes all three wrong, and they refuse here. `revoke` reads it never: it deletes
+      every account token of `tokenName(project, env, profile)`, a name composed from the root config
+      alone. Refusing it too would take `#454`'s lesson and repeat it — the one command you need in a
+      credential leak, unavailable because an unrelated Worker's config is broken on this checkout, with
+      no `--local-only` to fall back to.
+    */
+    get profiles() {
+      return tokenProfiles(workerSet);
+    },
+    secretBackend: (name) => registry[name]?.backend,
+    putSecret: storeId ? (name, value) => cf.secrets(storeId).putSecret(name, value) : undefined,
+    // The set itself when it is unknowable, so the emitter says which worker rather than falling silent.
+    audit: await buildAudit(capabilitySetOf(workerSet), cf, projectDir, env, apiToken),
+    override: tokenOverrideResolver(config),
+  };
+}
+
+const profileArg = {
+  profile: {
+    type: "positional",
+    required: true,
+    description: "Token profile: ci-system (the CI credential), or a capability's worker-consumer profile",
+  },
+} as const;
+const envArgs = { env: ENV_ARG } as const;
+const jsonArg = { json: { type: "boolean", default: false, description: "Machine-readable output" } } as const;
+const overrideArgs = {
+  store: { type: "string", description: `Override where the value is written: ${TOKEN_STORES.join(" | ")}` },
+  permission: {
+    type: "string",
+    description: `Override permissions (repeatable): ${Object.keys(PERMISSION_GROUPS).join(", ")}`,
+  },
+} as const;
+
+const mint = defineCommand({
+  meta: { name: "mint", description: "Mint a scoped account token for a profile (rolls to the current scope)" },
+  args: { ...profileArg, ...envArgs, ...overrideArgs, ...jsonArg },
+  run: ({ args, rawArgs }) =>
+    withErrorReporting(args.json, async () => {
+      const env = requireEnvironment(args.env);
+      const engine = await buildEngine(process.cwd(), env);
+      const result = await mintProfileToken(engine, args.profile, env, {
+        store: parseStore(args.store),
+        permissions: parsePermissions(collectPermissionFlags(rawArgs)),
+      });
+      if (args.json) {
+        process.stdout.write(`${formatJsonLine({ command: "token mint", ...publicToken(result) })}\n`);
+        return;
+      }
+      process.stdout.write(`${result.profile}: minted → ${result.sink.location}.\n`);
+      process.stdout.write(`${formatDone()}\n`);
+    }),
+});
+
+const list = defineCommand({
+  meta: { name: "list", description: "List minted tokens for an environment (ids and profiles, never values)" },
+  args: { ...envArgs, ...jsonArg },
+  run: ({ args }) =>
+    withErrorReporting(args.json, async () => {
+      const env = requireEnvironment(args.env);
+      const engine = await buildEngine(process.cwd(), env);
+      const tokens = await listProfileTokens(engine, env);
+      if (args.json) {
+        process.stdout.write(`${formatJsonLine({ command: "token list", env, tokens })}\n`);
+        return;
+      }
+      if (tokens.length === 0) {
+        process.stdout.write(`No minted tokens for ${env}.\n`);
+        return;
+      }
+      process.stdout.write(
+        `${formatList(tokens.map((token) => ({ name: token.profile, description: `${token.tokenId}${token.status ? ` · ${token.status}` : ""}` })))}\n`,
+      );
+    }),
+});
+
+const rotate = defineCommand({
+  meta: { name: "rotate", description: "Rotate a profile's token (create new, delete old)" },
+  args: {
+    ...profileArg,
+    ...envArgs,
+    ...overrideArgs,
+    "keep-previous": { type: "boolean", default: false, description: "Keep the old token as a grace window" },
+    ...jsonArg,
+  },
+  run: ({ args, rawArgs }) =>
+    withErrorReporting(args.json, async () => {
+      const env = requireEnvironment(args.env);
+      const engine = await buildEngine(process.cwd(), env);
+      const result = await rotateProfileToken(engine, args.profile, env, {
+        store: parseStore(args.store),
+        permissions: parsePermissions(collectPermissionFlags(rawArgs)),
+        keepPrevious: args["keep-previous"],
+      });
+      if (args.json) {
+        process.stdout.write(`${formatJsonLine({ command: "token rotate", ...publicToken(result) })}\n`);
+        return;
+      }
+      process.stdout.write(`${result.profile}: rotated → ${result.sink.location}.\n`);
+      process.stdout.write(`${formatDone()}\n`);
+    }),
+});
+
+const revoke = defineCommand({
+  meta: { name: "revoke", description: "Revoke a profile's token for an environment" },
+  args: { ...profileArg, ...envArgs, ...jsonArg },
+  run: ({ args }) =>
+    withErrorReporting(args.json, async () => {
+      const env = requireEnvironment(args.env);
+      const engine = await buildEngine(process.cwd(), env);
+      const result = await revokeProfileToken(engine, args.profile, env);
+      if (args.json) {
+        // **A count is published as `revokedCount` (#235).** `pithy dashboard revoke-key` emits
+        // `revoked` as a `boolean` — did that key come out — and this one is "how many tokens of that
+        // name were deleted", where `0` is an ordinary answer. So `revoked` was a yes/no in one command
+        // and a number in another, and the number's falsy value is the one that means "nothing was
+        // revoked" in both readings while `revoked: 0` and `revoked: false` are not the same claim. The
+        // count is the outlier — every other `<verb>ed` key in this CLI is a boolean — so it takes the
+        // suffix. `RevokeResult` keeps `revoked`: the published name is decided here.
+        const { revoked: revokedCount, ...rest } = result;
+        process.stdout.write(`${formatJsonLine({ command: "token revoke", ...rest, revokedCount })}\n`);
+        return;
+      }
+      process.stdout.write(`${result.profile}: revoked ${result.revoked} token${result.revoked === 1 ? "" : "s"}.\n`);
+      process.stdout.write(`${formatDone()}\n`);
+    }),
+});
+
+export default defineCommand({
+  meta: { name: "token", description: "Mint and manage scoped Cloudflare API tokens" },
+  subCommands: { mint, list, rotate, revoke },
+});

package/src/commands/turnstile.ts

@@ -0,0 +1,271 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { CloudflareClients } from "@pithy-sh/cloudflare/src/client/clients";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { WorkerDomains } from "@pithy-sh/core/src/naming/domains";
+import { isTurnstileCapability } from "@pithy-sh/turnstile/src/capability";
+import type { TurnstileConfig, TurnstileMode } from "@pithy-sh/turnstile/src/config/config";
+import {
+  deprovisionTurnstile,
+  enabledModes,
+  provisionTurnstile,
+} from "@pithy-sh/turnstile/src/provision/provisionTurnstile";
+import { defineCommand } from "citty";
+import { createProjectCliAudit } from "../audit/cliAudit";
+import { buildSecretDispatcher } from "../capabilities/secretsDispatcher";
+import { CloudflareTurnstileDeprovisioner, CloudflareTurnstileProvisioner } from "../capabilities/turnstileProvisioner";
+import type { ConfirmedAccount } from "../cloudflare/accountAnswer";
+import { type CloudflareAccountSelection, cloudflareAccountConfirmation, cloudflareEnv } from "../cloudflare/config";
+import {
+  loadProject,
+  loadProjectEnvironments,
+  loadWorkerConfig,
+  loadWorkerDomains,
+  projectCloudflareAccount,
+  requireProjectName,
+} from "../project/config";
+import { type AddressStanza, resolveWorkerAddress } from "../project/workerAddress";
+import { projectCapabilities, type ResolvedWorker, resolveSingleWorker, resolveWorkers } from "../project/workerScope";
+import { readWranglerConfig } from "../project/wrangler";
+import { formatDone, formatJsonLine, withErrorReporting } from "../terminal/output";
+
+/**
+ * The audit emitter for a turnstile command. Provisioning spans every managed environment at once, so
+ * there is no single target env to key the audit database on — `"dev"` is the fallback (mirrors
+ * `pithy feature`'s convention for env-spanning commands). A no-op when creds or the audit capability
+ * aren't there.
+ */
+async function buildAudit(projectDir: string, accountId: string, apiToken: string) {
+  // `env` selects the audit database only, and defaults to `dev`: this command spans environments, so no
+  // single value is true for the run; each event states the environment it acted on.
+  return createProjectCliAudit({ projectDir, accountId, apiToken });
+}
+
+/**
+ * Load the turnstile capability's resolved config. Capabilities live in each Worker's
+ * `apps/<name>/pithy.config.ts`; the widget set is one project-wide decision, so the first Worker composing
+ * `turnstile` provides it.
+ */
+async function loadTurnstileConfig(projectDir: string): Promise<TurnstileConfig> {
+  const capabilities = await resolveWorkers({ projectDir }).then(projectCapabilities);
+  const cap = capabilities.find(isTurnstileCapability);
+  if (!cap) {
+    throw new ValidationError({
+      message: "The turnstile capability is not configured.",
+      action: "Add `turnstile({ ... })` to a worker's pithy.config.ts (run `pithy add turnstile`).",
+    });
+  }
+  return cap.turnstileConfig;
+}
+
+/** The widget modes declared in config, or an actionable error when none are. */
+function resolveModes(config: TurnstileConfig): TurnstileMode[] {
+  const modes = enabledModes(config);
+  if (modes.length === 0) {
+    throw new ValidationError({
+      message: "No Turnstile widgets are declared.",
+      action: "Add a `widgets.visible` or `widgets.invisible` entry to turnstile({ ... }) in pithy.config.ts.",
+    });
+  }
+  return modes;
+}
+
+/**
+ * The Cloudflare credentials this command provisions with, for **the account the project belongs to**.
+ *
+ * The account is a parameter rather than an ambient, so this cannot resolve before something has
+ * established which account the project is for (#206).
+ *
+ * It also carries **what vouches for the account** (#378). A bare id is what every destructive and
+ * creative site here used to hold, and an id alone cannot tell "this account has no such Worker" from
+ * "I asked an account nothing claims" — the two arrive as one empty listing.
+ */
+function loadCloudflareCreds(account: CloudflareAccountSelection | null): {
+  account: ConfirmedAccount;
+  accountId: string;
+  apiToken: string;
+} {
+  const vars = cloudflareEnv({ account });
+  const confirmation = cloudflareAccountConfirmation({ account });
+  const accountId = vars.CLOUDFLARE_ACCOUNT_ID ?? "";
+  const apiToken = vars.CLOUDFLARE_API_TOKEN ?? "";
+  if (!accountId || !apiToken) {
+    throw new ValidationError({
+      message: "Cloudflare credentials are missing.",
+      action: "Run pithy init to record CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN, or export them.",
+    });
+  }
+  return { account: { accountId, confirmation }, accountId, apiToken };
+}
+
+/**
+ * Resolve the production hostname the real widget binds to, through the one address resolver.
+ *
+ * A Turnstile widget is bound to the domain a human loads it on, so this needs a hostname rather than a
+ * URL — the resolver returns both and this takes the `hostname` half.
+ *
+ * Single-environment by design: a widget binds to production, so `prod` is not a parameter. Every Worker
+ * has its own address, so a project with several names one with `--worker` rather than have a widget
+ * silently bound to the wrong host.
+ *
+ * This used to read `env.prod.vars.BASE_URL` directly, with its own parser and its own two errors — one
+ * of the three unreconciled derivations #89 replaced. The resolver now prefers the `domains` declaration
+ * and falls back to the route and then to that same var, so an adopter who set it by hand still works and
+ * one who declared a domain is no longer told to set a var that would duplicate it.
+ */
+async function resolveProductionDomain(worker: ResolvedWorker): Promise<string> {
+  const stanza = ((await readWranglerConfig(worker.dir)) as { env?: Record<string, AddressStanza | undefined> }).env
+    ?.prod;
+  let domains: WorkerDomains | undefined;
+  try {
+    domains = loadWorkerDomains(await loadWorkerConfig(worker.dir));
+  } catch {
+    // A malformed declaration must not stop a widget being provisioned off a perfectly good route or
+    // var. `pithy env` and `pithy deploy` are where a bad `domains` block gets reported.
+    domains = undefined;
+  }
+
+  const address = resolveWorkerAddress({ environment: "prod", domains, stanza });
+  if (!address) {
+    throw new ValidationError({
+      message: `${worker.name} has no production address.`,
+      action:
+        'Declare it in the Worker\'s pithy.config.ts — `domains: { prod: { pattern: "app.example.com", zone: "example.com" } }`. The Turnstile widget binds to that domain.',
+      detail: `no domains declaration, route, or vars.BASE_URL resolved for env.prod in ${worker.dir}`,
+    });
+  }
+  return address.hostname;
+}
+
+/** The Worker whose `wrangler.jsonc` carries the production `BASE_URL` and the per-env sitekey vars. */
+const workerArg = {
+  type: "string",
+  description: "The web-facing worker whose wrangler.jsonc holds BASE_URL (default: the project's only worker)",
+} as const;
+
+const provision = defineCommand({
+  meta: {
+    name: "provision",
+    description: "Wire Turnstile test keys (dev/staging) and provision the production widget",
+  },
+  args: {
+    json: { type: "boolean", default: false, description: "Machine-readable output" },
+    worker: { ...workerArg },
+    "allow-shared-domain": {
+      type: "boolean",
+      default: false,
+      description: "Provision even though another Turnstile widget already covers the domain",
+    },
+  },
+  run: ({ args }) =>
+    withErrorReporting(args.json, async () => {
+      const projectDir = process.cwd();
+      const config = await loadTurnstileConfig(projectDir);
+      const modes = resolveModes(config);
+      const { account, accountId, apiToken } = loadCloudflareCreds(await projectCloudflareAccount(projectDir));
+      const worker = await resolveSingleWorker({
+        projectDir,
+        ...(args.worker !== undefined ? { worker: args.worker } : {}),
+      });
+      const productionDomain = await resolveProductionDomain(worker);
+      const cf = new CloudflareClients({ accountId, apiToken });
+      // The project name scopes both the widget names (`<project>-prod-turnstile-<mode>`) and the
+      // dispatcher's `<project>-<env>-secrets-write` target — and it is `requireProjectName`, because a
+      // guessed one reuses another project's widget and dispatches into its manager (docs/NAMING.md).
+      const projectConfig = await loadProject(projectDir);
+      const project = requireProjectName(projectConfig);
+      // The project's own environment set (#241): what this command fans out across, rather than a
+      // pair the CLI assumed. A project declaring `live` gets `live` provisioned and torn down too.
+      const environments = loadProjectEnvironments(projectConfig);
+      const dispatcher = buildSecretDispatcher(accountId, apiToken, project);
+      const audit = await buildAudit(projectDir, accountId, apiToken);
+      const provisioner = new CloudflareTurnstileProvisioner({
+        cf,
+        account,
+        project,
+        projectDir,
+        workerDir: worker.dir,
+        dispatcher,
+        environments,
+        audit,
+      });
+
+      const result = await provisionTurnstile(provisioner, {
+        modes,
+        productionDomain,
+        allowSharedDomain: args["allow-shared-domain"],
+      });
+
+      if (args.json) {
+        process.stdout.write(`${formatJsonLine({ command: "turnstile provision", ...result })}\n`);
+        return;
+      }
+      const created = result.widgets.filter((w) => w.created).length;
+      process.stdout.write(
+        `Test secret wired for dev and staging. ${result.widgets.length} production widget(s) ready (${created} new).\n`,
+      );
+      if (result.widgets.length > 0 && !result.productionSecretWritten) {
+        // All production widgets already existed, so their secret can't be recomposed (Cloudflare never
+        // returns it) and was left as-is. If it was never stored, re-running won't heal it — say so.
+        process.stdout.write(
+          "Production widgets already existed; their secret was left as-is. If the production gate returns turnstile/config, run `pithy turnstile deprovision` then provision again.\n",
+        );
+      }
+      process.stdout.write(`${formatDone()}\n`);
+    }),
+});
+
+const deprovision = defineCommand({
+  meta: { name: "deprovision", description: "Delete the production widget(s) and clear Turnstile config" },
+  args: {
+    json: { type: "boolean", default: false, description: "Machine-readable output" },
+    worker: { ...workerArg },
+  },
+  run: ({ args }) =>
+    withErrorReporting(args.json, async () => {
+      const projectDir = process.cwd();
+      const config = await loadTurnstileConfig(projectDir);
+      const modes = resolveModes(config);
+      const { account, accountId, apiToken } = loadCloudflareCreds(await projectCloudflareAccount(projectDir));
+      const worker = await resolveSingleWorker({
+        projectDir,
+        ...(args.worker !== undefined ? { worker: args.worker } : {}),
+      });
+      const cf = new CloudflareClients({ accountId, apiToken });
+      // The project name scopes both the widget names teardown recomputes and the dispatcher's
+      // `<project>-<env>-secrets-write` target — and it is `requireProjectName`, because a guessed one
+      // would delete a neighboring project's widget (docs/NAMING.md).
+      const projectConfig = await loadProject(projectDir);
+      const project = requireProjectName(projectConfig);
+      // The project's own environment set (#241): what this command fans out across, rather than a
+      // pair the CLI assumed. A project declaring `live` gets `live` provisioned and torn down too.
+      const environments = loadProjectEnvironments(projectConfig);
+      const dispatcher = buildSecretDispatcher(accountId, apiToken, project);
+      const audit = await buildAudit(projectDir, accountId, apiToken);
+      const deprovisioner = new CloudflareTurnstileDeprovisioner({
+        cf,
+        account,
+        project,
+        projectDir,
+        workerDir: worker.dir,
+        dispatcher,
+        environments,
+        audit,
+      });
+
+      const result = await deprovisionTurnstile(deprovisioner, modes);
+
+      if (args.json) {
+        process.stdout.write(`${formatJsonLine({ command: "turnstile deprovision", ...result })}\n`);
+        return;
+      }
+      process.stdout.write(`Production widget(s) removed and config cleared.\n`);
+      process.stdout.write(`${formatDone()}\n`);
+    }),
+});
+
+export default defineCommand({
+  meta: { name: "turnstile", description: "Provision and manage Turnstile widgets" },
+  subCommands: { provision, deprovision },
+});