@pithy-sh/cli 0.1.0

package/src/provision/resources.ts

@@ -0,0 +1,126 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { CloudflareClients } from "@pithy-sh/cloudflare/src/client/clients";
+import type { FeatureResourceKind } from "@pithy-sh/core/src/naming/feature";
+import { type ConfirmedAccount, findOnConfirmedAccount } from "../cloudflare/accountAnswer";
+
+/**
+ * The control-plane operations provisioning needs for one resource kind, and the Cloudflare-backed
+ * implementation of them.
+ *
+ * Separate from the orchestration above it because the orchestration is the same for every
+ * environment a project has — a branch's ephemeral one and a declared `staging` alike — while this is
+ * the one part that talks to an account. Injectable so every test above runs without credentials.
+ */
+
+/** The control-plane operations provisioning needs for one resource kind. */
+export interface ResourceProvisioner {
+  /** Find a resource by its exact name, returning its id, or null when absent (id = uuid/nsId, or the bucket name for r2). */
+  find(name: string): Promise<{ id: string } | null>;
+  /** Create the resource by name and return its id. */
+  create(name: string): Promise<{ id: string }>;
+  /** Delete the resource by id. Idempotent — a missing resource is not an error. */
+  delete(id: string): Promise<void>;
+}
+
+/** One provisioner per provisionable resource kind. */
+export type ResourceProvisioners = Record<FeatureResourceKind, ResourceProvisioner>;
+
+/**
+ * The default provisioners, backed by the `@pithy-sh/cloudflare` control-plane clients. For D1 and KV the
+ * id is the CF-assigned uuid/namespace id; for R2, which has no separate id, the bucket name is the id.
+ *
+ * **`find` is where a not-found becomes a creation, so it is where the account has to be settled (#378).**
+ * Both callers are find-or-create: `provisionEnvironment` creates whatever `find` did not return, and
+ * `destroyFeature` reconciles by expected name. An empty listing from an account nothing claims is not
+ * an absence, and reading it as one stands a real D1, KV namespace or R2 bucket up in somebody else's
+ * account — a creation no re-run can walk back, since the second run finds what the first made. So the
+ * account travels with the clients, `find` refuses instead of returning `null`, and the lookup is not
+ * even attempted: the round trip's answer could not be believed either way.
+ *
+ * **Known limitation, R2 only:** the delete here is the plain control-plane one, and R2 refuses to delete
+ * a bucket that still holds an object or a dangling multipart upload — so a feature bucket that was
+ * written to fails teardown. Emptying it first needs the S3 key pair, which the control-plane clients do
+ * not carry (`pithy storage deprovision --storage` takes it as a flag for exactly this reason). Wiring
+ * that through the feature lifecycle is the fix; until then, empty the bucket by hand.
+ */
+export function cloudflareProvisioners(clients: CloudflareClients, account: ConfirmedAccount): ResourceProvisioners {
+  const d1 = clients.d1Provisioner();
+  const kv = clients.kvProvisioner();
+  const r2 = clients.r2Provisioner();
+  return {
+    d1: {
+      find: async (name) => {
+        const found = await findOnConfirmedAccount({
+          ...account,
+          what: `the ${name} database`,
+          find: () => d1.findDatabaseByName(name),
+        });
+        return found ? { id: found.uuid } : null;
+      },
+      create: async (name) => ({ id: (await d1.createDatabase(name)).uuid }),
+      delete: (id) => d1.deleteDatabase(id),
+    },
+    kv: {
+      find: async (name) => {
+        const found = await findOnConfirmedAccount({
+          ...account,
+          what: `the ${name} KV namespace`,
+          find: () => kv.findNamespaceByTitle(name),
+        });
+        return found ? { id: found.id } : null;
+      },
+      create: async (name) => ({ id: (await kv.createNamespace(name)).id }),
+      delete: (id) => kv.deleteNamespace(id),
+    },
+    r2: {
+      find: async (name) => {
+        const found = await findOnConfirmedAccount({
+          ...account,
+          what: `the ${name} bucket`,
+          find: () => r2.findBucketByName(name),
+        });
+        return found ? { id: found.name } : null;
+      },
+      create: async (name) => ({ id: (await r2.createBucket(name)).name }),
+      delete: (id) => r2.deleteBucket(id),
+    },
+  };
+}
+
+/**
+ * Audit actions provisioning records. Creating and — especially — deleting a resource changes real
+ * infrastructure, and both run headlessly in CI, so "who deleted this, and what exactly went?" must be
+ * answerable after the fact.
+ *
+ * **Named for provisioning, not for features**, since the same two events are emitted for a declared
+ * environment. The event's own `environment` field says which one it was; a `feature/` prefix on a
+ * `staging` event would be a sentence contradicting the row it sits in.
+ */
+export const ProvisionAuditActions = {
+  /** A Cloudflare resource was created. */
+  resourceCreated: "provision/resource_created",
+  /** A Cloudflare resource was deleted during teardown. */
+  resourceDeleted: "provision/resource_deleted",
+} as const;
+
+/**
+ * Where a provisioning run's audit trail is written. **Not the environment being provisioned.**
+ *
+ * That environment's database may not exist yet — standing it up is what the command is for — so keying
+ * the trail on it would resolve nothing and silently drop every creation event. And a feature's is
+ * deleted by `destroy`, so a record written there dies with the thing it was recording. Both defeat the
+ * point of auditing a headless CI run.
+ *
+ * It is a **routing** choice and never an `actedOn` claim: each event states the environment it acted on
+ * in its own `environment` field, which is where the real answer is known.
+ */
+export const AUDIT_DESTINATION_ENV = "dev";
+
+/** The resource kind recorded on a provisioning audit event. */
+export const AUDIT_RESOURCE_TYPE: Record<FeatureResourceKind, string> = {
+  d1: "cf_d1",
+  kv: "cf_kv",
+  r2: "cf_r2",
+};

package/src/provision/secretBindings.ts

@@ -0,0 +1,149 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
+import type { ProvisionScope, SecretNameScope } from "@pithy-sh/core/src/naming/provisionScope";
+import { isSecretsCapability } from "@pithy-sh/secrets/src/capability";
+import { isMintableSecret, type SecretRegistry, type SecretRegistryEntry } from "@pithy-sh/secrets/src/registry";
+import { aggregateSecretRegistries } from "@pithy-sh/secrets/src/sharedSecretsStore";
+
+/**
+ * **The `secrets_store_secrets` stanza nothing wrote.**
+ *
+ * `pithy add` deliberately does not write a `secret` binding, and the reason in
+ * `core/src/capability/bindings.ts` is sound: the entry needs a `store_id` and a `secret_name` that do
+ * not exist until an account has been reached, so "telling anyone to add one of these to
+ * `wrangler.jsonc` sends them somewhere the value does not exist". The defect was that having deferred
+ * it, nothing came back — the skip was a decision about *when* and was implemented as a decision about
+ * *whether*. A Worker deployed without `SECRETS_ENCRYPTION_KEYS` and failed at its first request.
+ *
+ * Provisioning is the step being deferred to: it is when the store id is in hand and the entry
+ * certainly exists. The entry **name** comes from the scope, so a feature binds its own master key and
+ * `staging` binds staging's — the join key is the binding, and the binding never changes.
+ *
+ * **`dev` never gets a stanza, and that is deliberate rather than an omission.** Local dev materialises
+ * every `cf-secrets-store` secret into the generated `.dev.vars` (#179), so a stanza there would name
+ * store entries a local run never reads. Provisioning only ever writes `scope.stanza`, which is a
+ * deployed or feature environment and never `dev`.
+ */
+
+/** One `secrets_store_secrets` entry, complete — wrangler rejects an entry missing any of the three. */
+export interface SecretStoreBinding {
+  /** The Worker binding name, which is the registry key: the same name every read site uses. */
+  binding: string;
+  /** The account's one Secrets Store. */
+  store_id: string;
+  /** The entry inside it, named for this scope. */
+  secret_name: string;
+}
+
+/**
+ * The secret registry a Worker composes, or `null` when it composes no secrets capability at all.
+ *
+ * **The aggregate, not the secrets capability's own slice.** `aggregateSecretRegistries` is the exact
+ * call the Worker makes at composition: every capability contributes the secrets it owns, and
+ * `CONNECTION_KEY_ENCRYPTION_KEY` is the adopter's `app` declaration rather than something re-typed into
+ * `secrets({ registry })`. Reading the slice bound the master key and nothing else — so a
+ * `cf-secrets-store` secret declared by auth, or by the adopter's own capability, got a binding from no
+ * command at all, and the Worker booted healthy and failed at the first read of it. That is the half of
+ * #238 the master key hid, and it is the same resolution `pithy seed` already uses (`devSecrets/targets`).
+ *
+ * The `secrets` capability stays the gate. A Worker that declares a `cf-secrets-store` secret and
+ * composes no `secrets` has no store to read it from and no `SECRETS` binding to reach one, so there is
+ * nothing there to bind.
+ */
+export function workerSecretRegistry(capabilities: readonly Capability[]): SecretRegistry | null {
+  if (!capabilities.some(isSecretsCapability)) return null;
+  return aggregateSecretRegistries(capabilities);
+}
+
+/**
+ * The registry entries that need a `secrets_store_secrets` binding — one predicate, so a stanza writer
+ * and a stanza reader cannot disagree about what belongs in one.
+ *
+ * **A keyspace is skipped.** It has no single value and therefore no single entry; its members are
+ * written one key at a time by the application that mints them, and a binding under the bare name would
+ * address an entry nothing ever writes.
+ */
+export function boundSecretNames(registry: SecretRegistry): string[] {
+  return Object.entries(registry)
+    .filter(([, entry]) => entry.backend === "cf-secrets-store" && !entry.keyed)
+    .map(([binding]) => binding);
+}
+
+/** One secret a run is about to create: what the Worker binds it as, what it is called here, what it is. */
+export interface MintTarget {
+  /** The Worker binding name, which is the registry key. */
+  binding: string;
+  /** The store entry to write, named for this scope. */
+  secretName: string;
+  /** The registry entry — carries how the value is minted. */
+  entry: SecretRegistryEntry;
+}
+
+/**
+ * Create one declared-but-absent secret. Injected, so the orchestration here is tested without an
+ * account, and so a caller with no store credentials simply passes nothing and mints nothing.
+ *
+ * It resolves once the value is written and readable. It never returns the value, and nothing here ever
+ * sees one.
+ */
+export type MintStoreSecret = (target: MintTarget) => Promise<void>;
+
+/**
+ * Every `cf-secrets-store` secret a registry declares, as a complete binding named for `scope`.
+ *
+ * Which secrets those are is {@link boundSecretNames}' answer, shared with the reader that reports a
+ * stanza missing one — the writer and the check cannot disagree about what belongs in a stanza.
+ *
+ * `exists` decides what is bound rather than what is declared. Cloudflare rejects a deploy whose
+ * `secrets_store_secrets` entry names a secret that is not there, so binding a declared-but-unwritten
+ * secret would turn a missing value into a failed deploy of the whole Worker. The caller reports what
+ * it left out.
+ *
+ * **`mint` is what stops provisioning asking a human to generate random bytes (#321).** A secret whose
+ * registry entry says its value is arbitrary has no decision in it, and this is the moment the tool
+ * already knows the value is absent. So it is created here and bound in the same pass. Three properties
+ * hold it in place, and each has a test:
+ *
+ * - **Absent first.** `exists` is consulted before `mint`, always. Replacing a live key-encryption key
+ *   orphans every value sealed under it, so creating a missing secret and replacing an existing one are
+ *   different acts and only the first happens here. A re-run mints nothing.
+ * - **Declared first.** {@link isMintableSecret} gates it. A supplied secret stays in `missing`, named
+ *   on its own line, because a random string there authenticates against nothing.
+ * - **This backend only.** The Secrets Store answers *does this exist* authoritatively, which is what
+ *   makes "never regenerate" checkable. A `d1` secret's value is sealed under the master key inside the
+ *   manager Worker, and the CLI has no such check for one — so nothing here mints one.
+ */
+export async function secretsStoreBindings(options: {
+  /** The registry to read — one Worker's own, so a Worker gets only what it declares. */
+  registry: SecretRegistry;
+  /** The scope: what each entry is called in this environment. */
+  scope: ProvisionScope;
+  /** The account's one Secrets Store id. */
+  storeId: string;
+  /** Whether an entry of that name is in the store. */
+  exists: (name: string) => Promise<boolean>;
+  /** Creates a declared-but-absent mintable secret. Omitted means create nothing, and report as before. */
+  mint?: MintStoreSecret;
+}): Promise<{ bound: SecretStoreBinding[]; missing: string[]; minted: string[] }> {
+  const bound: SecretStoreBinding[] = [];
+  const missing: string[] = [];
+  const minted: string[] = [];
+  for (const binding of boundSecretNames(options.registry)) {
+    const entry = options.registry[binding] as SecretRegistry[string];
+    const secretName = options.scope.secretEntry(binding, entry.scope as SecretNameScope);
+    let present = await options.exists(secretName);
+    if (!present && options.mint && isMintableSecret(entry)) {
+      await options.mint({ binding, secretName, entry });
+      minted.push(binding);
+      present = true;
+    }
+    if (present) {
+      bound.push({ binding, store_id: options.storeId, secret_name: secretName });
+    } else {
+      missing.push(binding);
+    }
+  }
+  return { bound, missing, minted };
+}

package/src/provision/store.ts

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { CloudflareClients } from "@pithy-sh/cloudflare/src/client/clients";
+
+/**
+ * The account's one Secrets Store, as provisioning needs it.
+ *
+ * A Cloudflare account has exactly one, flat and unpartitionable, so the entry name is the only
+ * partition there is — which is why every name here comes from a {@link ProvisionScope} and never from
+ * a caller's string. Behind a seam so the orchestration above is tested without credentials.
+ */
+export interface SecretsStore {
+  /** The store's id — the `store_id` every `secrets_store_secrets` entry carries. */
+  readonly storeId: string;
+  /** Is there an entry of this name? */
+  exists(name: string): Promise<boolean>;
+  /** Write a value under `name`. Overwrites in place; never deletes first. */
+  put(name: string, value: string): Promise<void>;
+  /** Delete an entry if it is there. Resolves `true` when something was removed. */
+  remove(name: string): Promise<boolean>;
+}
+
+/** The live store, over the `@pithy-sh/cloudflare` control-plane client. */
+export function cloudflareSecretsStore(clients: CloudflareClients, storeId: string): SecretsStore {
+  const store = clients.secrets(storeId);
+  return {
+    storeId,
+    exists: (name) => store.exists(name),
+    put: (name, value) => store.putSecret(name, value),
+    remove: (name) => store.deleteSecretIfPresent(name),
+  };
+}

package/src/provision/unprovisioned.ts

@@ -0,0 +1,114 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { basename } from "node:path";
+import { ValidationError } from "@pithy-sh/core/src/error/pithyError";
+import type { FeatureResourceKind } from "@pithy-sh/core/src/naming/feature";
+import { discoverWorkers } from "../project/workers";
+import { readOptionalWranglerConfig } from "../project/wrangler";
+
+/**
+ * **Which of an environment's declared bindings still have no resource behind them.**
+ *
+ * The state this reads is the one #240 was reported from: a project scaffolded, wired and migrated by
+ * pithy, whose `wrangler.jsonc` declares `"database_name": "<project>-staging-db"` and no
+ * `database_id`, in every environment. `pithy deploy --env staging` used to hand that straight to
+ * wrangler, which failed on a binding the adopter never knew they were meant to create — after `init`,
+ * `add`, `migrate` and `dev` had all succeeded.
+ *
+ * So the answer is read from files, offline, and used twice: `pithy deploy` refuses with the command to
+ * run, and `pithy doctor` reports it without being asked. One reader, so the two can never disagree
+ * about what "provisioned" means.
+ */
+
+/** One binding an environment declares and has no resource for. */
+export interface UnprovisionedBinding {
+  /** The Worker's `apps/<name>` directory. */
+  worker: string;
+  /** The Cloudflare resource kind the binding needs. */
+  kind: FeatureResourceKind;
+  /** The binding name in the Worker env, e.g. `DB`. */
+  binding: string;
+}
+
+/** One binding entry as it appears in a wrangler binding array; only its kind's id field is populated. */
+interface RawBinding {
+  binding?: string;
+  database_id?: string;
+  id?: string;
+  bucket_name?: string;
+}
+
+/** The slice of a `wrangler.jsonc` this reads: the environment stanzas and their binding arrays. */
+interface RawWrangler {
+  env?: Record<
+    string,
+    | {
+        d1_databases?: RawBinding[];
+        kv_namespaces?: RawBinding[];
+        r2_buckets?: RawBinding[];
+      }
+    | undefined
+  >;
+}
+
+/**
+ * A value is an id only if it is a non-empty, non-placeholder string.
+ *
+ * The same rule `pithy env` reports `provisioned` by. A scaffold leaves `<database_id>` behind and an
+ * adopter leaves `""`; both look filled in to a truthiness check and neither is something wrangler will
+ * deploy against.
+ */
+function isId(value: string | undefined): boolean {
+  if (value === undefined) return false;
+  const trimmed = value.trim();
+  return trimmed !== "" && !/^<.+>$/.test(trimmed) && !/placeholder/i.test(trimmed);
+}
+
+/**
+ * Every binding one environment declares across the project's Workers that has no id yet, in worker
+ * then binding order. A Worker with no stanza for that environment declares nothing there and is
+ * skipped; a `wrangler.jsonc` that will not open is skipped too, because this reader gates a deploy and
+ * a config that cannot be read has its own, better error waiting one step later.
+ */
+export async function unprovisionedBindings(projectDir: string, env: string): Promise<UnprovisionedBinding[]> {
+  const missing: UnprovisionedBinding[] = [];
+  for (const target of await discoverWorkers(projectDir)) {
+    if (target.hasWrangler === false) continue;
+    const raw = (await readOptionalWranglerConfig(target.dir).catch(() => null)) as RawWrangler | null;
+    const stanza = raw?.env?.[env];
+    if (!stanza) continue;
+    const worker = basename(target.dir);
+    for (const entry of stanza.d1_databases ?? [])
+      if (!isId(entry.database_id)) missing.push({ worker, kind: "d1", binding: entry.binding ?? "" });
+    for (const entry of stanza.kv_namespaces ?? [])
+      if (!isId(entry.id)) missing.push({ worker, kind: "kv", binding: entry.binding ?? "" });
+    for (const entry of stanza.r2_buckets ?? [])
+      if (!isId(entry.bucket_name)) missing.push({ worker, kind: "r2", binding: entry.binding ?? "" });
+  }
+  return missing;
+}
+
+/** How a report names one unprovisioned binding: the Worker, the binding, and the kind behind it. */
+export function describeUnprovisioned(missing: readonly UnprovisionedBinding[]): string {
+  return missing.map((entry) => `${entry.worker}.${entry.binding} (${entry.kind})`).join(", ");
+}
+
+/**
+ * Refuse to deploy into an environment whose bindings have no resources, naming the command that
+ * creates them.
+ *
+ * **Deploy refuses; it does not provision.** A deploy that silently creates account resources is hard
+ * to review, and the resources it would create are the long-lived ones. The refusal is the whole
+ * improvement: the failure moves from inside wrangler, on a field nobody wrote, to one sentence naming
+ * the missing binding and the command that fills it.
+ */
+export async function assertEnvironmentProvisioned(projectDir: string, env: string): Promise<void> {
+  const missing = await unprovisionedBindings(projectDir, env);
+  if (missing.length === 0) return;
+  throw new ValidationError({
+    message: `${env} declares bindings with no Cloudflare resource behind them: ${describeUnprovisioned(missing)}.`,
+    action: `Run pithy provision --env ${env} --yes, then deploy.`,
+    detail: "wrangler validates a binding's id before it deploys, so this would have failed inside wrangler.",
+  });
+}

package/src/provision/wranglerEnv.ts

@@ -0,0 +1,220 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { ProvisionScope } from "@pithy-sh/core/src/naming/provisionScope";
+import { parse } from "comment-json";
+import type { FeatureResource } from "../feature/manifest";
+import { writeJsonc } from "../project/jsonc";
+import { absolutizePaths, provisionConfigPath } from "./featureConfig";
+import type { SecretStoreBinding } from "./secretBindings";
+
+/**
+ * After provisioning stands up an environment's D1/KV/R2 resources, their ids must land in each
+ * Worker's `wrangler.jsonc` under `env.<name>` — that is exactly where the shared `migrate`/`seed`
+ * remote drivers, and `wrangler deploy --env <name>`, read each binding's id from. This writes them
+ * there, upserting by binding name and preserving every comment in the JSONC (a `pithy.config` output,
+ * per CLAUDE.md).
+ *
+ * **One writer, taking the scope.** The stanza key is `scope.stanza` and every name is the same
+ * scope's, so the file this writes into and the names it writes cannot come from two different
+ * decisions — which is how a feature-named resource could once be written into a declared environment's
+ * stanza.
+ */
+
+/** One binding-id entry keyed by binding, plus the id field that resource kind uses in wrangler.jsonc. */
+interface BindingEntry {
+  binding: string;
+  [field: string]: string;
+}
+
+/** One `services` entry: the binding name and the Worker script it resolves to in this environment. */
+export interface ServiceEntry {
+  /** The binding name in the Worker env (e.g. `BOARD`). */
+  binding: string;
+  /** The script name that binding reaches in this scope. */
+  service: string;
+}
+
+/** The env stanza slice provisioning writes: the Worker's own name, its binding arrays, and its services. */
+interface EnvBindings {
+  name?: string;
+  d1_databases?: BindingEntry[];
+  kv_namespaces?: BindingEntry[];
+  r2_buckets?: BindingEntry[];
+  services?: ServiceEntry[];
+  secrets_store_secrets?: SecretStoreBinding[];
+}
+
+/**
+ * Upsert a binding's fields into a binding array **in place**, so comment-json's array-internal
+ * comments (stored as symbol-keyed properties on the array object) survive — a `filter()` would return
+ * a plain array and silently drop them. A matching binding's fields are updated on the existing entry;
+ * otherwise the entry is pushed.
+ */
+function upsertByBinding(entries: BindingEntry[], binding: string, fields: Record<string, string>): void {
+  const existing = entries.find((entry) => entry.binding === binding);
+  if (existing) Object.assign(existing, fields);
+  else entries.push({ binding, ...fields });
+}
+
+/** The `EnvBindings` keys holding a binding array — the only ones an id is upserted into. */
+type BindingArrayKey = "d1_databases" | "kv_namespaces" | "r2_buckets";
+
+/**
+ * The wrangler key and the fields provisioning owns for each resource kind.
+ *
+ * **D1 carries its name as well as its id**, and that is not decoration: `pithy add` proposes a
+ * `database_name` offline, before any account has been reached, and provisioning is the step that makes
+ * the proposal true. Writing only the id would leave a stanza asserting one name while addressing a
+ * database that may carry another — the two must be written by the same step or they drift.
+ */
+const KIND_TO_WRANGLER: Record<
+  FeatureResource["kind"],
+  { array: BindingArrayKey; fields: (r: FeatureResource) => Record<string, string> }
+> = {
+  d1: { array: "d1_databases", fields: (r) => ({ database_name: r.name, database_id: r.id }) },
+  kv: { array: "kv_namespaces", fields: (r) => ({ id: r.id }) },
+  r2: { array: "r2_buckets", fields: (r) => ({ bucket_name: r.id }) },
+};
+
+/**
+ * Write one Worker's whole `env.<scope.stanza>` stanza: the resource ids it declares, the script name it
+ * deploys under in this scope, and each of its `service` bindings retargeted at this scope's copy of the
+ * callee.
+ *
+ * The stanza is created when absent and reused when present, so this is also what makes provisioning the
+ * creator of a stanza for an environment declared after the project was scaffolded. Idempotent, and every
+ * comment in the file survives the round trip.
+ */
+async function editStanza(
+  workerDir: string,
+  stanzaKey: string,
+  /**
+   * **`source` decides the file, not the caller.** A declared environment's ids are read in a pull
+   * request, so they go into the tracked `wrangler.jsonc`. A feature's are one job's output, so they go
+   * into the generated config under the already-ignored `.wrangler/` — regenerated from the tracked
+   * file every run, so it can never drift from it, and never making it dirty. That is what makes "a CI
+   * run never commits back" a property of the code rather than a note in a runbook.
+   */
+  source: boolean,
+  mutate: (stanza: EnvBindings) => void,
+): Promise<string> {
+  const raw = await readFile(join(workerDir, "wrangler.jsonc"), "utf8");
+  const config = parse(raw) as unknown as { env?: Record<string, EnvBindings | undefined> };
+
+  config.env ??= {};
+  const stanza: EnvBindings = config.env[stanzaKey] ?? {};
+  config.env[stanzaKey] = stanza;
+
+  mutate(stanza);
+
+  // One resolver for "which file?", shared with what the command reports (#251). A run states where it
+  // wrote and whether that file is committed; a report computing the path a second time is a sentence
+  // that can disagree with the write it describes.
+  const destination = provisionConfigPath(workerDir, source);
+  if (!source) {
+    // Generated, so every path in it is rewritten against the directory it came from — wrangler
+    // resolves a config's paths relative to the config, and this one lives two levels deeper.
+    absolutizePaths(config as Record<string, unknown>, workerDir);
+    await mkdir(dirname(destination), { recursive: true });
+    await writeJsonc(destination, config);
+    return destination;
+  }
+
+  // Through the one JSONC printer (#249), never a raw `stringify`. `comment-json` puts every array
+  // element on its own line; the project's own scaffolded Biome collapses a short one — so a config
+  // written the other way fails the pre-commit hook this CLI installed. `writeJsonc` also keeps an
+  // adopter's hand-expanded objects expanded, which matters most here: this file is edited in place on
+  // every provision, and a two-line change buried in a whole-file reformat is a change nobody reviewed.
+  await writeJsonc(destination, config);
+  return destination;
+}
+
+/**
+ * Upsert the `secrets_store_secrets` entries provisioning owns into one Worker's `env.<stanza>`.
+ *
+ * Separate from {@link applyProvisionedEnv} because two commands reach it for different reasons.
+ * `pithy provision` writes the whole stanza in either mode; `pithy secrets provision`
+ * writes only this, for a project whose resources are already in place and whose store entries have
+ * just been created — the five cases `ensureSecretsStoreId` cannot resolve at `add` time, and every
+ * project that predates the stanza existing at all.
+ *
+ * **Only the entries it owns.** An adopter's hand-added binding this registry does not declare is left
+ * exactly where it is.
+ */
+export async function applySecretBindings(
+  workerDir: string,
+  stanzaKey: string,
+  entries: readonly SecretStoreBinding[],
+): Promise<void> {
+  if (entries.length === 0) return;
+  // Always the tracked file: only `pithy secrets provision` calls this directly, and it acts on the
+  // environments a project deploys to. A feature's stanza is written by the scope-driven writer below.
+  await editStanza(workerDir, stanzaKey, true, (stanza) => {
+    stanza.secrets_store_secrets ??= [];
+    for (const entry of entries) {
+      const existing = stanza.secrets_store_secrets.find((candidate) => candidate.binding === entry.binding);
+      if (existing) Object.assign(existing, entry);
+      else stanza.secrets_store_secrets.push({ ...entry });
+    }
+  });
+}
+
+/**
+ * Write one Worker's stanza, and hand back **the path that was written** — the tracked `wrangler.jsonc`
+ * or the generated artifact, as the scope decided. The caller reports it, so what a run says it wrote is
+ * what the writer wrote rather than a second computation of the same rule (#251).
+ */
+export async function applyProvisionedEnv(options: {
+  /** The Worker's directory — the one holding the `wrangler.jsonc` to edit. */
+  workerDir: string;
+  /** The Worker's deploy name, from its own `wrangler.jsonc`. `scope.worker` turns it into this scope's. */
+  worker: string;
+  /** The scope: both the stanza written into and the names written in. */
+  scope: ProvisionScope;
+  /** Only the resources this Worker's own config declares. */
+  resources: readonly FeatureResource[];
+  /** Only the service bindings this Worker's own config declares, already resolved to this scope. */
+  services: readonly ServiceEntry[];
+  /**
+   * The `secrets_store_secrets` entries this Worker's own registry declares, named for this scope.
+   *
+   * This is the stanza `pithy add` deliberately could not write and nothing came back for (#238, #239).
+   * It is complete by construction — every entry carries its `store_id` and `secret_name` — because a
+   * partial one does not degrade: wrangler refuses the whole config.
+   */
+  secrets: readonly SecretStoreBinding[];
+}): Promise<string> {
+  const destination = await editStanza(options.workerDir, options.scope.stanza, options.scope.source, (stanza) => {
+    stanza.name = options.scope.worker(options.worker);
+    for (const resource of options.resources) {
+      const { array, fields } = KIND_TO_WRANGLER[resource.kind];
+      // Reuse the existing comment-json array (preserving its comments) or start a fresh one, then
+      // mutate in place — never replace it with a filtered plain array, which would strip
+      // comment-json's symbols.
+      stanza[array] ??= [];
+      upsertByBinding(stanza[array], resource.binding, fields(resource));
+    }
+    if (options.services.length > 0) {
+      stanza.services ??= [];
+      for (const entry of options.services) {
+        const existing = stanza.services.find((candidate) => candidate.binding === entry.binding);
+        if (existing) existing.service = entry.service;
+        else stanza.services.push({ ...entry });
+      }
+    }
+  });
+  if (options.secrets.length > 0) {
+    await editStanza(options.workerDir, options.scope.stanza, options.scope.source, (stanza) => {
+      stanza.secrets_store_secrets ??= [];
+      for (const entry of options.secrets) {
+        const existing = stanza.secrets_store_secrets.find((candidate) => candidate.binding === entry.binding);
+        if (existing) Object.assign(existing, entry);
+        else stanza.secrets_store_secrets.push({ ...entry });
+      }
+    });
+  }
+  return destination;
+}