@pithy-sh/cli 0.1.0

package/src/capabilities/add.ts

@@ -0,0 +1,288 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFile, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { BindingSpec } from "@pithy-sh/core/src/capability/bindings";
+import {
+  type CapabilityManifest,
+  renderCapabilityImport,
+  renderCapabilityRegistration,
+  renderConfigOptionComment,
+  renderConfigOptionLine,
+} from "@pithy-sh/core/src/capability/manifest";
+import { ConflictError, InternalError } from "@pithy-sh/core/src/error/pithyError";
+import {
+  appendBinding,
+  appendDurableObjectMigrations,
+  type BindingScope,
+  envStanzas,
+  type ProposedName,
+  type WranglerStanza,
+} from "../project/bindingEntries";
+import { readOptionalFile } from "../project/readOptionalFile";
+import { readWranglerConfig, workerEntryPath, writeWranglerConfig } from "../project/wrangler";
+import { optionValue } from "./configConstants";
+import { capabilityImportSpecifier, findNamedImport, importOrigin } from "./configImports";
+import { ejectImportPath } from "./eject";
+import { durableObjectExports, withDurableObjectExports } from "./entryExports";
+import { requiredOptionRefusal } from "./requiredOptions";
+
+/** A config option's value: the JSON scalars a manifest default can be. */
+export type ConfigValue = string | number | boolean;
+
+export interface AddCapabilityOptions {
+  /**
+   * The **Worker's** directory (`apps/<name>`) — where that Worker's `pithy.config.ts` and
+   * `wrangler.jsonc` live. Capabilities are per-Worker: the composed route tree, the bindings, and the
+   * Durable Object class migrations all attach to one script, so wiring never touches the project root.
+   */
+  workerDir: string;
+  /** The capability's validated manifest (pithy.manifest.json shape). */
+  manifest: CapabilityManifest;
+  /** Per-option overrides; an unset option renders its manifest default. */
+  configValues?: Record<string, ConfigValue>;
+  /**
+   * The project name, resolved by the caller from the root `pithy.config.ts` (`requireProjectName`) and
+   * passed as a plain string. It is the first segment of every name proposed here.
+   *
+   * **A string, never a loader.** Resolving it in here would mean importing the root config live, and a
+   * live import only works under the project root — the wiring tests scaffold into the OS tmpdir, where
+   * it fails with an error about the config rather than about the test. The caller already has the
+   * config; it hands over the answer.
+   *
+   * Omitted when no project name could be resolved: nothing is proposed and the entries carry only their
+   * binding, which is exactly what `pithy add` wrote before. A guessed prefix would be worse than none —
+   * every command that later recomputes the name would compute a different one.
+   */
+  project?: string;
+}
+
+/** What {@link addCapability} wired that the config file itself cannot carry. */
+export interface AddCapabilityResult {
+  /**
+   * The KV namespace titles to give the namespaces this capability needs.
+   *
+   * **KV is reported rather than written, because wrangler has nowhere to write it.** A `kv_namespaces`
+   * entry takes `binding`, `id`, `preview_id`, and `remote` — there is no title field, so the name lives
+   * only in the account. D1 is different (`database_name` is a real key) and is written into the file.
+   * R2 is deliberately absent from both: `pithy storage provision` and `pithy media provision` write
+   * `bucket_name` themselves, and a second writer would collide with them.
+   *
+   * Empty when no project name was resolved, and empty on a re-run — a binding already present is left
+   * exactly as the adopter has it.
+   */
+  kvNamespaces: ProposedName[];
+}
+
+/** The managed-region marker each Worker's `pithy.config.ts` plants inside `capabilities: [...]`. */
+const MARKER = "// pithy:capabilities";
+
+/**
+ * Wire a capability into **one Worker** — the pure logic behind `pithy add`. Inserts the import and
+ * registration into that Worker's `pithy.config.ts` managed region and appends the manifest's required
+ * bindings to every environment of that Worker's `wrangler.jsonc`, comment-preserving. Idempotent: a
+ * second run changes nothing. A sibling Worker is never touched.
+ */
+export async function addCapability(options: AddCapabilityOptions): Promise<AddCapabilityResult> {
+  await updateConfig(options);
+  const kvNamespaces = await updateWrangler(options);
+  await updateEntry(options);
+  return { kvNamespaces };
+}
+
+/**
+ * The bindings `pithy add` actually wires into this Worker: the manifest's, minus the optional ones.
+ *
+ * An `optional` binding is one the capability needs only under a particular config. The manifest is one
+ * static file and cannot vary with config, so it declares the union and marks such a binding optional;
+ * `pithy add` runs *before* any config exists and has nothing to resolve the flag against, so it writes
+ * none of them. `createBackend` reads the same flag to decide whether a missing binding is fatal at
+ * assembly, and `pithy upgrade` — which does have the composed set — writes the ones that Worker derives.
+ *
+ * **One list, read three times**: the `wrangler.jsonc` stanzas, the Durable Object class migration tags,
+ * and the entry's exports. They were three separate filters over the same manifest and they did not
+ * agree — the tags took every declared binding — so an optional Durable Object would have been registered
+ * against the script by a `new_sqlite_classes` tag while nothing bound it and nothing exported it. A tag
+ * is applied once and never revisited, so that is not a mistake a later run repairs.
+ */
+function wiredBindings(manifest: CapabilityManifest): BindingSpec[] {
+  return manifest.requiredBindings.filter((binding) => !binding.optional);
+}
+
+/**
+ * Write the capability's Durable Object exports into the Worker's entry — the other half of a
+ * `durable_objects.bindings` entry, and the half `wrangler deploy` refuses the Worker without (#428).
+ *
+ * Silent, like the class migration tag beside it: there is nothing for the adopter to do about it, and a
+ * line of output for every file a command touches is not this CLI's voice. The entry is whatever `main`
+ * names, so a Worker that keeps its module somewhere else still gets the export where wrangler looks.
+ *
+ * Over {@link wiredBindings}, so a class is exported exactly when it is bound.
+ */
+async function updateEntry({ workerDir, manifest }: AddCapabilityOptions): Promise<void> {
+  const exports = durableObjectExports(wiredBindings(manifest));
+  if (exports.length === 0) return;
+
+  const path = await workerEntryPath(workerDir);
+  const source = path === null ? null : await readOptionalFile(path);
+  if (path === null || source === null) {
+    const classes = exports.map((entry) => entry.className).join(", ");
+    const wrangler = join(workerDir, "wrangler.jsonc");
+    // Two faults, two remedies. A config with no `main` has named no file, so there is nothing to
+    // restore and the fix is in `wrangler.jsonc`; a `main` whose file is gone is the opposite. The
+    // message already said which of the two it was, and one shared action line contradicted half of it.
+    throw new InternalError({
+      message:
+        path === null
+          ? `${wrangler} names no main, so this Worker has no entry to export ${classes} from.`
+          : `${path} is missing — this Worker's wrangler.jsonc names it as main.`,
+      action:
+        path === null
+          ? `Give ${wrangler} a main naming this Worker's entry, then run pithy add ${manifest.name} again.`
+          : `Restore that file, then run pithy add ${manifest.name} again.`,
+      detail: `${manifest.name} binds ${classes}, which wrangler resolves against the Worker's entry.`,
+    });
+  }
+  const written = withDurableObjectExports(source, exports);
+  if (written !== source) await writeFile(path, written);
+}
+
+/** Escape a capability name for use inside a `RegExp` (names are simple, but be safe). */
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Render a capability's registration. With no config options it's a one-liner
+ * (`auth(),`); with options it's a block — one commented `key: default` per
+ * option — so `pithy.config.ts` documents itself (docs/CLI.md §Config). The mount
+ * path and every other knob live here, in the user's surface; the handler stays
+ * in the package.
+ *
+ * Every line of it comes from core's renderers now, the call included. This function used to interpolate
+ * `manifest.name` into the call itself, which is how a manifest declaring `audit }) ; evil(` closed the
+ * capabilities array and opened a call of its own (#183) — the same defect as the option key #174 closed,
+ * one line up.
+ */
+function renderRegistration(
+  manifest: CapabilityManifest,
+  configValues: Record<string, ConfigValue>,
+  indent: string,
+  source: string,
+): string {
+  const inner = `${indent}  `;
+  const optionLines: string[] = [];
+  for (const option of manifest.configOptions) {
+    // The scaffold's `PUBLIC_ORIGIN` where the option names it and this config declares it, the
+    // manifest's literal otherwise, and the adopter's own value over both. See `configConstants.ts`.
+    const value = optionValue(option, source, configValues[option.key]);
+    // A required option with no value reaching here is a bug one step upstream — `runAdd` refuses before
+    // it calls this — so it fails loudly rather than rendering the word `undefined` into somebody's
+    // config. `addCapability` is called directly too, and a writer that can be reached from more than
+    // one place states its own preconditions.
+    if (value === undefined) throw requiredOptionRefusal({ capability: manifest.name, missing: [option] });
+    // The same two lines `pithy upgrade` writes, from the same two functions. Two renderers of one line
+    // is how `add` and `upgrade` came to disagree about a nested default in the first place (#171), and
+    // the comment was still built here and there separately until the manifest text going into it got a
+    // rule of its own (#174).
+    optionLines.push(renderConfigOptionComment(option.describe, inner));
+    optionLines.push(renderConfigOptionLine(option.key, value, inner));
+  }
+  return renderCapabilityRegistration({ name: manifest.name, indent, optionLines });
+}
+
+async function updateConfig({ workerDir, manifest, configValues }: AddCapabilityOptions): Promise<void> {
+  const path = join(workerDir, "pithy.config.ts");
+  let source = await readFile(path, "utf8");
+
+  const markerLine = source.split("\n").find((line) => line.trimStart().startsWith(MARKER));
+  if (markerLine === undefined) {
+    throw new InternalError({
+      message: `${path} has no "${MARKER}" marker.`,
+      action: "Restore the managed-region marker inside capabilities: []. Run pithy add again.",
+    });
+  }
+
+  const lines = source.split("\n");
+  // Idempotency on the import is keyed on the *binding*, then checked against where it comes from.
+  // Keyed on the whole line, an adopter who corrected a specifier by hand — which `pithy add secrets`
+  // required, for as long as `@pithy-sh/secrets` shipped no `src/index` — got the original line back
+  // on the next run, and two bindings of one name is a redeclaration the config never loads past.
+  // Keyed on the binding alone, an adopter's own `auth` suppressed our import while `auth()` still
+  // went into the managed region, so the config composed their middleware and said nothing. One is
+  // loud and wrong, the other is silent and wrong. So: the name identifies the import, the specifier
+  // decides what to do about it, and a name bound to something else is refused before anything is
+  // written.
+  const existing = findNamedImport(source, manifest.name);
+  const origin = existing && importOrigin(existing.specifier, manifest.package, ejectImportPath(manifest.name));
+  if (existing === undefined) {
+    source = `${renderCapabilityImport(manifest.name, capabilityImportSpecifier(manifest.package))}\n${source}`;
+  } else if (origin === "foreign") {
+    throw new ConflictError({
+      message: `${path} already imports ${manifest.name} from "${existing.specifier}".`,
+      action: `Rename that import, then run pithy add ${manifest.name} again.`,
+      detail: `Wiring ${manifest.name}() would have composed ${existing.specifier} as the capability.`,
+    });
+  } else if (origin === "unresolvable") {
+    // Ours, and dead: the package exports `./src/*` and no `.`, so this line throws the moment anything
+    // loads the config. Accepted as wiring, `add` wrote the registration against an import that could
+    // never bind and exited 0. Refused rather than rewritten — the specifier is the adopter's line to
+    // correct, and a command that silently repoints imports is one nobody can predict.
+    throw new ConflictError({
+      message: `${path} imports ${manifest.name} from "${existing.specifier}", which resolves to nothing.`,
+      action: `Point that import at "${capabilityImportSpecifier(manifest.package)}", then run pithy add ${manifest.name} again.`,
+      detail: `${manifest.package} exports ./src/* only, so the bare specifier has no entry point.`,
+    });
+  }
+
+  // Idempotency anchors on the registration *call*, not an exact line: a block
+  // form spans several lines, and `auth(` must not match an existing `myauth(`.
+  const registered = new RegExp(`^${escapeRegExp(manifest.name)}\\(`);
+  if (!lines.some((line) => registered.test(line.trim()))) {
+    const indent = markerLine.slice(0, markerLine.length - markerLine.trimStart().length);
+    const registration = renderRegistration(manifest, configValues ?? {}, indent, source);
+    // A replacement function keeps `$` in the registration literal.
+    source = source.replace(markerLine, () => `${registration}\n${markerLine}`);
+  }
+
+  await writeFile(path, source);
+}
+
+/**
+ * Append each of a capability's {@link wiredBindings} to one environment's stanza, and report the KV
+ * namespace titles the adopter has to create by hand.
+ *
+ * The entries themselves are `project/bindingEntries.ts`'s — one writer, shared with `pithy upgrade`'s
+ * reconcile, so the two commands cannot produce different configs from the same manifest.
+ */
+function appendBindings(stanza: WranglerStanza, bindings: readonly BindingSpec[], scope: BindingScope): ProposedName[] {
+  const proposed: ProposedName[] = [];
+  for (const binding of bindings) {
+    const write = appendBinding(stanza, binding, scope);
+    if (write.outcome === "written" && write.proposed) proposed.push(write.proposed);
+  }
+  return proposed;
+}
+
+async function updateWrangler({ workerDir, manifest, project }: AddCapabilityOptions): Promise<ProposedName[]> {
+  const config = (await readWranglerConfig(workerDir)) as WranglerStanza;
+
+  const bindings = wiredBindings(manifest);
+  const kvNamespaces: ProposedName[] = [];
+  for (const { env, stanza } of envStanzas(config)) {
+    kvNamespaces.push(
+      ...appendBindings(stanza, bindings, {
+        ...(project === undefined ? {} : { project }),
+        env,
+        capability: manifest.name,
+      }),
+    );
+  }
+  // DO class migrations are top-level only — they register the class against the script, not per-env. The
+  // same list the stanzas got: a tag registers a class the Worker binds, or it registers nothing.
+  appendDurableObjectMigrations(config, bindings);
+
+  await writeWranglerConfig(workerDir, config);
+  return kvNamespaces;
+}

package/src/capabilities/addBootstrap.ts

@@ -0,0 +1,275 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { join } from "node:path";
+import { parseDevVars } from "@pithy-sh/cloudflare/src/env/devVars";
+import type { BindingSpec } from "@pithy-sh/core/src/capability/bindings";
+import { isProvisionedBinding } from "@pithy-sh/core/src/capability/bindings";
+import type { DevSecret } from "@pithy-sh/core/src/capability/devSecret";
+import type { CapabilityManifest } from "@pithy-sh/core/src/capability/manifest";
+import { masterKeyRegistryEntry } from "@pithy-sh/secrets/src/capability";
+import { EncryptionConfig } from "@pithy-sh/secrets/src/crypto/envelope";
+import { type DevSecretsFile, initialDevSecret } from "@pithy-sh/secrets/src/dev/devSecretsFile";
+import { MASTER_KEY_BINDING } from "@pithy-sh/secrets/src/env/bindings";
+import { SECRETS_CAPABILITY } from "@pithy-sh/secrets/src/manager/dispatcher";
+import { mintSecretValue } from "@pithy-sh/secrets/src/mintValue";
+import { initialMasterKeyConfig } from "@pithy-sh/secrets/src/provision/provisionSecrets";
+import type { CloudflareAccountSelection } from "../cloudflare/config";
+import { type EnsureSecretsStoreIdOptions, ensureSecretsStoreId } from "../cloudflare/storeId";
+import { readBootstrapVars } from "../devSecrets/bootstrapVars";
+import { readDevVarsSource } from "../devSecrets/devVars";
+import { readDevSecrets, writeDevSecrets } from "../devSecrets/file";
+import { resolveDevSecretsFile } from "../devSecrets/location";
+import { ownProperties } from "../devSecrets/records";
+import { renderDevSecretsNotes } from "../devSecrets/report";
+import { type DevSecretsSeedReport, seedProjectDevSecrets } from "../devSecrets/seed";
+import type { StatePathOptions } from "../notifier/state";
+
+export interface AddBootstrapOptions {
+  /**
+   * The project root. A bootstrap value is recorded against the *project*, not a Worker, so one master
+   * key reaches every Worker's generated `.dev.vars` (#154) — a per-Worker mint would give a project with
+   * two Workers two divergent keys and orphan whichever secrets the loser encrypted.
+   */
+  projectDir: string;
+  /** The manifest of the capability just wired — the authority on which bindings it needs. */
+  manifest: CapabilityManifest;
+  /**
+   * Seam: seed the whole project's dev secrets. Defaults to the real seeder, with `reload` on.
+   *
+   * It is a seam because this function and the seeder can reach the *same* sentence in one run, and the
+   * only way to prove they say it once is to make both of them say it.
+   */
+  seed?: (projectDir: string) => Promise<DevSecretsSeedReport>;
+  /**
+   * Seam: resolve and record the account's `SECRETS_STORE_ID`. Defaults to the real one, which reaches
+   * Cloudflare — so a test that does not pass this would list an operator's real account.
+   */
+  ensureStoreId?: (options: EnsureSecretsStoreIdOptions) => Promise<string[]>;
+  /** Where the Pithy config directory is. Defaults to the real one; a seam so a test writes its own. */
+  paths?: StatePathOptions;
+  /**
+   * The Cloudflare account this project belongs to. One Secrets Store per account, so the store id
+   * recorded here belongs to whichever account the project uses (#206).
+   *
+   * **Required, with `null` the explicit "this project names none" (#234).** It was `account?:` until
+   * then, and its one caller — `capabilities/flow.ts` — omitted it, so `pithy add secrets` wrote the
+   * default account's `SECRETS_STORE_ID` into whichever `cloudflare.<name>.json` the project had
+   * named. An omission and a deliberate `null` are the same bytes at a call site, which is why the
+   * compiler is the only reviewer that can tell them apart.
+   */
+  account: CloudflareAccountSelection | null;
+}
+
+/**
+ * Finish `pithy add` for the values `add` itself cannot write, and say plainly what is left.
+ *
+ * Two kinds of gap, and only one of them is loud. A **binding** `add` cannot write — a Secrets Store
+ * entry, a Workflow, a Vectorize index — makes the Worker refuse its first request naming what is
+ * absent. A **registry secret** is read lazily, so the app boots healthy, `/health` is green, and the
+ * failure arrives at the first sign-in or the first tracked link as `secrets/not_found` on a name the
+ * adopter has never heard of. Both are handled here: where a *dev* value can be minted honestly, it is
+ * minted; where it cannot, the command names the provision command that creates it — at the moment the
+ * adopter is thinking about the capability rather than in a doc they read later.
+ *
+ * Returns the lines to print (`AddResult.notes`), in order. Nothing here ever prints a value.
+ */
+export async function bootstrapAdd({
+  projectDir,
+  manifest,
+  seed,
+  ensureStoreId,
+  paths,
+  account,
+}: AddBootstrapOptions): Promise<string[]> {
+  const notes: string[] = [];
+  // The account's Secrets Store id, resolved once and recorded in `<config>/cloudflare.json` — the one
+  // moment in its life anything asks Cloudflare where the store is (#182). Before the bindings loop,
+  // because the sentence it may print ("no credentials yet") is the same one that explains why the
+  // provisioning notes below are the next step. Never fatal: see {@link ensureSecretsStoreId}.
+  if (manifest.name === SECRETS_CAPABILITY) {
+    notes.push(...(await (ensureStoreId ?? ensureSecretsStoreId)({ paths: { ...paths, account } })));
+  }
+  for (const binding of manifest.requiredBindings) {
+    // Optional bindings are skipped for the same reason `validateBindings` skips them: nothing refuses
+    // a request over one, so a note would send the adopter provisioning what their app never asks for.
+    if (binding.optional || !isProvisionedBinding(binding.type)) continue;
+    if (isMasterKey(manifest, binding)) notes.push(...(await ensureDevMasterKey(projectDir)));
+    else notes.push(provisionNote(manifest.name, binding));
+  }
+  notes.push(...(await ensureDevSecrets(projectDir, manifest.devSecrets)));
+  // Last, and over the whole project rather than this capability: the value just minted has to reach the
+  // local `SECRETS` store to be worth anything, and so does every value already in the file that a
+  // previous run could not seed — `pithy add secrets` is exactly the run that makes the store openable.
+  // Never fatal. A project whose store is not wired yet gets a reason, not a failed `pithy add`.
+  //
+  // **`reload`, because this process is holding a stale config.** `pithy add` rewrote the Worker's
+  // `pithy.config.ts` several steps ago, and the module it imported before that write is the one still
+  // in the ESM cache — so the aggregate registry seeded against is the composition from *before* the
+  // add, and the secret this same run has just minted is not in it. It reached the store only on some
+  // later, unrelated command, which is what made it look like a store problem.
+  const seedProject = seed ?? ((dir: string) => seedProjectDevSecrets({ projectDir: dir, reload: true }));
+  notes.push(...renderDevSecretsNotes(await seedProject(projectDir)));
+  // **Deduplicated, in order.** Two `.dev.vars` writes happen in one run — the master key above, and
+  // the seeder's `cf-secrets-store` values — and both report delivery against the same Worker
+  // directories, so a Worker shadowing the project's file produces the same sentence twice. Both must
+  // be able to speak (a project that has not composed `secrets` has no targets, so only the first one
+  // does), and printing one sentence twice reads as two problems. An adopter counts lines.
+  return [...new Set(notes)];
+}
+
+/** The secrets capability's master-key binding — the one provisioned binding with an honest dev value. */
+function isMasterKey(manifest: CapabilityManifest, binding: BindingSpec): boolean {
+  return manifest.name === SECRETS_CAPABILITY && binding.name === MASTER_KEY_BINDING;
+}
+
+/**
+ * What a binding needs that only provisioning can supply. `pithy <capability> provision` is the command
+ * in every case — each capability that owns provisioned resources subcommands its own name.
+ */
+function provisionNote(capability: string, binding: BindingSpec): string {
+  return `${binding.name} is created by pithy ${capability} provision. Nothing local stands in for it.`;
+}
+
+/**
+ * Put this project's dev master key where every Worker's generated `.dev.vars` will pick it up, unless
+ * one is already recorded.
+ *
+ * **A fresh key per project, never a literal.** One key shipped in a template is one key across every
+ * adopter, and the first person to copy it into a deployed environment hands everyone else their
+ * secrets. `initialMasterKeyConfig` generates one.
+ *
+ * **Only when absent** — the same rule `ensureMasterKey` states for the provisioned key. Replacing the
+ * key orphans every secret already stored under it, and re-running `pithy add secrets` must be a no-op.
+ * An *empty* value is treated as absent: nothing could have been encrypted under it, so there is
+ * nothing to orphan, and leaving it would leave `pithy dev` refusing every request.
+ *
+ * **A key in a pre-#154 project's root `.dev.vars` is adopted, never re-minted.** That file used to be
+ * the store, and it is the one value whose replacement cannot be undone: every secret already encrypted
+ * under the old key becomes unreadable, with no error that names the cause. So the old key is carried
+ * into the bootstrap store as it stands, and the project keeps reading what it already wrote. Their file
+ * is not rewritten — nothing here ever rewrites an adopter's `.dev.vars`.
+ */
+async function ensureDevMasterKey(projectDir: string): Promise<string[]> {
+  const path = await resolveDevSecretsFile(projectDir);
+  if ((await readDevSecrets(path))[MASTER_KEY_BINDING]) {
+    return [`${MASTER_KEY_BINDING} is already in ${path}. Left as it is — a new key orphans every stored secret.`];
+  }
+  // Both older homes, in the order they were used: `dev.json` since #154, the project root's `.dev.vars`
+  // before it. Adopted rather than re-minted — this is the one value whose replacement cannot be undone,
+  // because every secret already encrypted under the old key becomes unreadable with no error that names
+  // the cause. Their `.dev.vars` is not rewritten; nothing here ever rewrites an adopter's.
+  //
+  // The `.dev.vars` read goes through the writer's own reader, where only `ENOENT` is "no key here".
+  // `.catch(() => "")` answered that for every errno, so an unreadable file read as absent and this
+  // minted a second key. See {@link readDevVarsSource}.
+  const recorded = (await readBootstrapVars(projectDir))[MASTER_KEY_BINDING];
+  const stranded = parseDevVars((await readDevVarsSource(join(projectDir, ".dev.vars"))) ?? "")[MASTER_KEY_BINDING];
+  const adopted = firstValue(recorded, stranded);
+  // The file states the `EncryptionConfig` itself, and nothing around it (#323) — the binding carries the
+  // bare config, and the file states the payload its destination receives. A hand-edit that breaks it is
+  // caught by the registry's own schema, naming the secret, rather than by a Worker answering every
+  // request with `secrets/crypto_failed`. An adopted value arrives as the string a binding carried, so it
+  // is parsed back into the object the file holds — which is now the same object, unwrapped, either way.
+  const config = adopted === undefined ? await initialMasterKeyConfig() : parseConfig(adopted);
+  if (config === null) {
+    return [
+      `${MASTER_KEY_BINDING} is set on this machine but is not a valid master key, so nothing was adopted.`,
+      `Put a valid one in ${path}, or delete it and run pithy add secrets again to mint a new one — a new key orphans every secret the old one encrypted.`,
+    ];
+  }
+  const wrote = await writeDevSecrets(path, { [MASTER_KEY_BINDING]: initialDevSecret(masterKeyRegistryEntry, config) });
+  if (wrote.length === 0) return [];
+  if (adopted !== undefined) {
+    return [
+      `Adopted the ${MASTER_KEY_BINDING} this machine already had, into ${path}. A new key would orphan every secret the old one encrypted.`,
+    ];
+  }
+  return [
+    `Minted a dev master key as ${MASTER_KEY_BINDING}, into ${path}. Local only, and it reaches each Worker's generated .dev.vars.`,
+    "Deployed environments get theirs from pithy secrets provision.",
+  ];
+}
+
+/** The first non-empty of the older homes, or `undefined` when this machine has no key at all. */
+function firstValue(...candidates: (string | undefined)[]): string | undefined {
+  for (const candidate of candidates) if (candidate !== undefined && candidate !== "") return candidate;
+  return undefined;
+}
+
+/** A binding's string parsed back into the `EncryptionConfig` the file states, or `null` when it is not one. */
+function parseConfig(value: string): EncryptionConfig | null {
+  try {
+    const parsed = EncryptionConfig.safeParse(JSON.parse(value));
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Mint a dev value for every secret this capability declares as generatable, unless one is already there.
+ *
+ * **The capability decides, not this file.** Each value comes from a `devSecrets` entry the capability
+ * ships in its own manifest, mirroring the `devValue` on the registry entry that owns the secret. A
+ * list of names here would drift the moment a capability shipped another one — and drift silently,
+ * because a missing lazily-read secret is invisible until the code path that reads it runs.
+ *
+ * **The secrets file, not `.dev.vars` (#149), and that file is outside the checkout (#156).** Only the
+ * destination changed; the declaration and the minting are the ones `pithy add` has always done.
+ * `.dev.vars` is wrangler's file — env bindings, `UPPER_SNAKE` — and a kebab secret name sitting in it
+ * taught every adopter that one of the two conventions was a mistake. The value is written as a full
+ * version-1 envelope, which is the shape the store actually holds, so dev stops being a shape
+ * production never sees. **Every note here names the absolute path**, because nothing in the project
+ * does: "already in the secrets file" is not actionable if the reader cannot open it.
+ *
+ * **Only when the secrets file lacks it.** A session secret replaced is every live session invalidated;
+ * a link-signing key replaced is every link already in an inbox broken.
+ *
+ * **A copy in `.dev.vars` no longer counts as having it (#153).** It used to: dev resolved every secret
+ * from its injected binding, so minting beside one produced two live values with nothing to say which
+ * signed what, and the honest answer was to refuse and say where it belonged. Dev reads the seeded row
+ * now, so that line signs nothing — refusing over it would leave the Worker with no session key at all,
+ * which is the failure this whole function exists to prevent. So the mint happens and the note names the
+ * stranded line. Nothing rewrites their `.dev.vars`; the value is still there if they want it, and
+ * `pithy doctor` repeats it every run until it is deleted.
+ *
+ * One write for the whole set, so a capability declaring several either lands them all or lands none.
+ */
+async function ensureDevSecrets(projectDir: string, declared: readonly DevSecret[]): Promise<string[]> {
+  if (declared.length === 0) return [];
+  // Prototype-free: a secret named `constructor` must not read back `Object.prototype.constructor` and
+  // be reported as sitting in a `.dev.vars` the project does not have. See {@link ownProperties}.
+  //
+  // And read honestly: `.catch(() => "")` on an unreadable file said "nothing here" for every errno, so
+  // a stranded line went unmentioned. It costs a sentence, not a value. See {@link readDevVarsSource}.
+  const source = (await readDevVarsSource(join(projectDir, ".dev.vars"))) ?? "";
+  const inDevVars = ownProperties(parseDevVars(source));
+  const path = await resolveDevSecretsFile(projectDir);
+  const stated = await readDevSecrets(path);
+  const minted: DevSecretsFile = {};
+  const notes: string[] = [];
+  for (const secret of declared) {
+    if (stated[secret.name]) {
+      notes.push(
+        `${secret.name} is already in ${path}. Left as it is — a new value invalidates what the old one signed.`,
+      );
+      continue;
+    }
+    // Not a bootstrap secret, and that is a fact rather than an assumption: `defineSecretRegistry`
+    // refuses `bootstrap` beside `devValue`, and everything here is a manifest-declared mintable value.
+    minted[secret.name] = initialDevSecret({}, mintSecretValue(secret.devValue));
+    notes.push(
+      `Minted a dev ${secret.name} into ${path}. Local only.`,
+      `Deployed environments need pithy secrets create ${secret.name}.`,
+    );
+    const stranded = inDevVars[secret.name];
+    if (stranded !== undefined && stranded !== "") {
+      notes.push(
+        `${secret.name} is also in .dev.vars, which dev no longer reads. Nothing was rewritten — delete that line, or move its value into ${path} as { "currentVersion": "1", "versions": { "1": <value> } }.`,
+      );
+    }
+  }
+  await writeDevSecrets(path, minted);
+  return notes;
+}