@pithy-sh/cli 0.1.0

package/src/devSecrets/bootstrapVars.ts

@@ -0,0 +1,265 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFile } from "node:fs/promises";
+import { ConflictError } from "@pithy-sh/core/src/error/pithyError";
+import { z } from "zod";
+import type { StatePathOptions } from "../notifier/state";
+import { writeFileAtomic } from "../project/atomic";
+import { loadProject, requireProjectName } from "../project/config";
+import { type MergeBase, readMergeBase } from "../project/readOptionalFile";
+import { devPreferencesPath } from "../seed/prepare";
+import { ensureDevSecretsDir } from "./location";
+import { tightenMode } from "./mode";
+
+/**
+ * The bootstrap half of a generated `.dev.vars`: the values a Worker reads from an **env binding** rather
+ * than from a secrets store — the dev master key, a `cf-secrets-store` secret, a Turnstile sitekey.
+ *
+ * **It lives in `dev.json`, as a second tenant (#154).** `<config>/<project>/dev.json` was already there
+ * for dev-login preferences (#131), it is already machine-local, already outside every checkout, and
+ * already the file `pithy doctor` names. Inventing a second location for "the machine's dev values" would
+ * have been a third convention for the same directory.
+ *
+ * **Why it has to persist anywhere at all.** `.dev.vars` used to be the store: `pithy add secrets` minted
+ * a master key into it and every later run read it back from there. A generated file cannot be its own
+ * source of truth — regenerating it would mean reading what the last generation wrote, which is the
+ * accumulating file this change exists to end. So the values move one level out, to the place the
+ * secrets file already went, and the generated file becomes a pure function of them.
+ *
+ * **Not a second copy of the secrets file.** `secrets.jsonc` holds application secrets as versioned
+ * envelopes, seeded into a Worker's local `SECRETS` store. This holds the flat `KEY=value` set that has
+ * to be a binding, because dev has no Secrets Store to read one from. A `d1` secret is never here.
+ *
+ * Same directory, same 0700, same 0600 as its neighbor — for the same reason: the dev master key is in
+ * it, and the umask is not a permission policy for a credential.
+ */
+
+/** The `dev.json` key this set lives under. Namespaced, because the file has other tenants. */
+export const BOOTSTRAP_VARS_KEY = "vars";
+
+/**
+ * The bootstrap set as it appears in `dev.json` — a flat map of `.dev.vars` variable names to values.
+ *
+ * Validated because it is read off disk and hand-editable, and it decides what a Worker's bindings are.
+ * A non-string value would reach {@link import("./devVars").encodeDevVarsValue} as an object and be
+ * written as `[object Object]`.
+ */
+export const BootstrapVars = z
+  .record(
+    z.string().describe("The `.dev.vars` variable name — wrangler's namespace, so UPPER_SNAKE by convention."),
+    z.string().describe("The value the Worker's binding carries. Never logged, never printed, never in --json."),
+  )
+  .describe("Every value this machine has to hand a Worker through a .dev.vars binding, by variable name.");
+
+/** The bootstrap set. Same name as its schema, as every Zod object in this repo is. */
+export type BootstrapVars = z.output<typeof BootstrapVars>;
+
+/**
+ * The shape this module reads `dev.json` as: its own key, and every other tenant's, preserved.
+ *
+ * `catchall` rather than a closed object, because a write here must not delete the dev-login preferences
+ * sitting beside it. Two tenants in one file is the whole reason the key exists.
+ *
+ * **Exported so a caller planning a write into this file reads it through one schema (#222).** A
+ * planning read goes through `readMergeBase` against this schema, so what it computes is a `dev.json`
+ * that was actually read rather than a `{}` a lenient read invented. One schema, because two would be
+ * two answers to "what is in that file", and a plan is what somebody deletes a line on the strength of.
+ */
+export const DevJson = z
+  .object({
+    [BOOTSTRAP_VARS_KEY]: BootstrapVars.optional().describe("The bootstrap `.dev.vars` set — this module's tenant."),
+  })
+  .catchall(z.unknown().describe("Another tenant's key, read and written back untouched."))
+  .describe("This machine's per-project dev file, of which the bootstrap vars are one tenant.");
+
+/** The whole file, every tenant included. Same name as its schema, as every Zod object in this repo is. */
+export type DevJson = z.output<typeof DevJson>;
+
+/** `<config>/<project>/dev.json` for a project root, or `null` when the project has no name to key on. */
+export async function bootstrapVarsPath(projectDir: string, options: StatePathOptions = {}): Promise<string | null> {
+  try {
+    return devPreferencesPath(requireProjectName(await loadProject(projectDir)), options);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * This project's bootstrap set, or an empty one. **The reporting read of the two in this file.**
+ *
+ * **Every failure is an empty set, and that is deliberate here where it is a defect elsewhere.** The
+ * sibling readers refuse an unreadable credential file because they are about to *rewrite* it, and
+ * "absent" would license replacing what they could not read. Nothing is rewritten from this call — the
+ * result is merged into a file that is regenerated wholesale — so a `dev.json` that will not parse costs
+ * a set of bindings and says so through the Worker's own missing-binding error, rather than stopping
+ * `pithy dev` over a hand-edited preferences file. This is the read `pithy dev` starts through.
+ *
+ * **What that argument is not about (#219).** It is an argument about *this call*, and it was read for a
+ * while as if it were about the file: the two writers below reached the same `{}` through
+ * {@link readDevJson} and renamed a document built from it over a file with another tenant in it. They
+ * refuse now, in every state but "there is no file", and this one still answers `{}` — the split is the
+ * fix, not a tightening. It is a type rather than a convention: they take a {@link MergeBase}, which only
+ * `readMergeBase` mints, so nothing that reads leniently can be handed to them by accident.
+ *
+ * So this read deliberately does *not* go through the primitive, and it is written down as such in that
+ * module's gate (`../project/readOptionalFile.test.ts`) rather than left to be rediscovered.
+ */
+export async function readBootstrapVars(projectDir: string, options: StatePathOptions = {}): Promise<BootstrapVars> {
+  const path = await bootstrapVarsPath(projectDir, options);
+  if (path === null) return {};
+  const source = await readFile(path, "utf8").catch(() => null);
+  if (source === null) return {};
+  const parsed = DevJson.safeParse(safeJson(source));
+  if (!parsed.success) return {};
+  return parsed.data[BOOTSTRAP_VARS_KEY] ?? {};
+}
+
+/**
+ * Merge `values` into this project's bootstrap set and write `dev.json` back. Returns the merged set,
+ * so a caller regenerating from it never re-reads what it has just written.
+ *
+ * **Read-modify-write over a file with other tenants**, so every state but "there is no file" refuses:
+ * writing this set over a `dev.json` that could not be read, or is not JSON, or parsed to something that
+ * is not a document, or is a record of something else, would silently delete a developer's dev-login
+ * preference along with every value this module had. Only `ENOENT` licenses starting from `{}`.
+ *
+ * A value is never removed here. A name that leaves the registry leaves a line nothing reads; `pithy
+ * doctor` is where a value nobody declares gets named, in this file exactly as in its neighbor.
+ *
+ * **An empty `values` returns before the read, and that is a decision (#222).** The refusal above exists
+ * because a merge into an invented `{}` gets renamed over another tenant's keys; a call that writes
+ * nothing performs no merge and no rename, so there is nothing for it to protect. It was reached —
+ * `writeDevVars({ values: {} })` is the turnstile teardown's regeneration — where refusing turns a
+ * regeneration into a failure over a file the run was never going to touch. The split in this module is
+ * by *power*, not by file, and a write of nothing has a reader's power: the set it answers is
+ * {@link readBootstrapVars}'s, which is the read whose whole argument is that it rewrites nothing.
+ */
+export async function writeBootstrapVars(
+  projectDir: string,
+  values: Record<string, string>,
+  options: StatePathOptions = {},
+): Promise<BootstrapVars> {
+  const path = await bootstrapVarsPath(projectDir, options);
+  if (path === null) return {};
+  if (Object.keys(values).length === 0) return readBootstrapVars(projectDir, options);
+  const base = await readDevJson(path);
+  const merged: BootstrapVars = { ...(base.document[BOOTSTRAP_VARS_KEY] ?? {}), ...values };
+  await ensureDevSecretsDir(base.path);
+  await writeFileAtomic(base.path, `${JSON.stringify(withBootstrapVars(base, merged), null, 2)}\n`, {
+    mode: 0o600,
+  });
+  // Unconditionally and after the write, the same as the secrets file's: a `dev.json` an older pithy or an
+  // editor created at the umask kept 0644 while holding the dev master key. Narrowing only.
+  await tightenMode(base.path);
+  return merged;
+}
+
+/**
+ * The document to write: every tenant's key as it was read, with this module's set replaced.
+ *
+ * **It takes a {@link MergeBase} and that is the whole point (#219).** Only `readMergeBase` mints one, so
+ * {@link readBootstrapVars} — which answers `{}` for a file it cannot make sense of, correctly, because
+ * it rewrites nothing — cannot be handed to it. The accident that produced five instances of this defect
+ * is a type error here rather than another tenant's key gone at the next rename.
+ */
+function withBootstrapVars(base: MergeBase<DevJson>, vars: BootstrapVars): DevJson {
+  return { ...base.document, [BOOTSTRAP_VARS_KEY]: vars };
+}
+
+/**
+ * Take names out of this project's bootstrap set — the teardown half, for a value whose resource no
+ * longer exists. Returns the set that remains, so a caller regenerating from it never re-reads.
+ *
+ * A name that is not there is a no-op, and a project with no `dev.json` is not created one. Removing a
+ * value here is what makes the next generation drop its line: the generated file is built from the
+ * sources rather than edited, so there is no line to delete anywhere else.
+ *
+ * **That no-op still reads strictly, and its sibling does not — same rule, different answer (#222).** The
+ * early return belongs before the read exactly when the *caller's arguments* settle whether anything is
+ * written. {@link writeBootstrapVars} knows that from an empty `values`. This one only learns it from the
+ * file, and a file nothing could read supports no claim about what is in it — least of all "that name is
+ * not there". So the one case its arguments do settle, an empty `names`, returns before the read, and
+ * every other case earns its no-op by reading the document properly or refusing.
+ */
+export async function removeBootstrapVars(
+  projectDir: string,
+  names: readonly string[],
+  options: StatePathOptions = {},
+): Promise<BootstrapVars> {
+  const path = await bootstrapVarsPath(projectDir, options);
+  if (path === null) return {};
+  if (names.length === 0) return readBootstrapVars(projectDir, options);
+  const base = await readDevJson(path);
+  const current: BootstrapVars = base.document[BOOTSTRAP_VARS_KEY] ?? {};
+  const remaining = Object.fromEntries(Object.entries(current).filter(([name]) => !names.includes(name)));
+  if (Object.keys(remaining).length === Object.keys(current).length) return current;
+  await ensureDevSecretsDir(base.path);
+  await writeFileAtomic(base.path, `${JSON.stringify(withBootstrapVars(base, remaining), null, 2)}\n`, {
+    mode: 0o600,
+  });
+  await tightenMode(base.path);
+  return remaining;
+}
+
+/**
+ * The merge base for a write over `dev.json`: every tenant's key intact, known-good, or a refusal.
+ *
+ * **The writers' read, and the strict half of this file's split.** `{}` for an absent file and for
+ * nothing else. Unopenable, not JSON, parsed to something that is not a document, or a document of
+ * something else: four refusals, because the two writers below merge into this answer and rename the
+ * result over a file with another tenant in it. Answering `{}` for any of the four is a dev-login
+ * preference and this module's own set deleted, with the run reporting a clean write.
+ *
+ * It used to answer `{}` for a non-object (#209), and then for a file that would not parse and for one
+ * that failed its schema (#219) — each corrected once someone noticed that the argument for leniency was
+ * {@link readBootstrapVars}'s and had been read as if it belonged to the file. The two are different
+ * calls with different powers, and now different types: this one hands back a {@link MergeBase}, which
+ * nothing else in this repository can produce.
+ *
+ * The `ENOENT`-only rule and the other three are `readMergeBase`'s (`../project/readOptionalFile.ts`);
+ * the words below are this file's, because "cannot update" is what a read-modify-write over somebody
+ * else's tenants has to say.
+ */
+async function readDevJson(path: string): Promise<MergeBase<DevJson>> {
+  return readMergeBase(path, DevJson, {
+    unreadable: ({ code, cause }) =>
+      new ConflictError(
+        {
+          message: `Cannot update ${path}: Pithy could not read what is already in it.`,
+          action: "Fix the file's permissions, or move it aside, and run the command again.",
+          detail: `${code ?? "unknown error"} while reading ${path}`,
+        },
+        { cause },
+      ),
+    unparseable: () =>
+      new ConflictError({
+        message: `Cannot update ${path}: it is there and is not JSON.`,
+        action: "Fix the JSON, or move it aside, and run the command again.",
+        // Never the parser's own message: it quotes the line it choked on, and the dev master key is one.
+        detail: `dev.json at ${path} did not parse, and every tenant's keys would be replaced by a write from it`,
+      }),
+    notARecord: ({ found }) =>
+      new ConflictError({
+        message: `Cannot update ${path}: it holds ${found}, not a document.`,
+        action: "Restore it to a JSON object, or move it aside, and run the command again.",
+        detail: `dev.json at ${path} parsed to ${found}, and other tenants' keys would be replaced by a write from it`,
+      }),
+    invalid: ({ at }) =>
+      new ConflictError({
+        message: `Cannot update ${path}: it is not the document Pithy keeps there.`,
+        action: "Fix it, or move it aside, and run the command again.",
+        // The key path, so the line can be found. Never the value on it, which may be the dev master key.
+        detail: `dev.json at ${path} failed its schema at ${at}`,
+      }),
+  });
+}
+
+/** `JSON.parse` that answers `undefined` rather than throwing — this file is hand-edited. */
+function safeJson(source: string): unknown {
+  try {
+    return JSON.parse(source);
+  } catch {
+    return undefined;
+  }
+}

package/src/devSecrets/devVars.ts

@@ -0,0 +1,240 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { parseDevVars } from "@pithy-sh/cloudflare/src/env/devVars";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { StatePathOptions } from "../notifier/state";
+import { readOptionalFile } from "../project/readOptionalFile";
+import { writeBootstrapVars } from "./bootstrapVars";
+import { generateDevVars } from "./generate";
+import type { DevSecretsTarget } from "./targets";
+
+/**
+ * The one place a value becomes a `.dev.vars` line — and the one place that makes sure the line reaches
+ * the Worker that has to read it.
+ *
+ * Two defects lived here, and both were silent, which is why this is a funnel rather than a fix at each
+ * of the four call sites that had them.
+ *
+ * **Values were written raw.** wrangler parses `.dev.vars` with `dotenv`, whose unquoted value grammar
+ * is `[^#\r\n]+` — so `KEY=s3cr3t#tail` hands the Worker `s3cr3t`, with no warning anywhere. A generated
+ * key is base64 and never contains a `#`; an OAuth client secret is whatever the provider issued, and
+ * this file is where those land. The failure arrives at the first sign-in, as a signature that does not
+ * verify, against a value that looks present in every file you would think to check.
+ *
+ * **And the line went somewhere the Worker does not read.** `pithy dev` spawns wrangler with
+ * `cwd: apps/<worker>`, and wrangler loads the `.dev.vars` beside the Worker's own config — so a value
+ * written to the project root alone landed in a file nothing reads. That was solved with a symlink into
+ * each `apps/<worker>/`, and the symlink produced five defects of its own. It is solved by generation
+ * now: see {@link ./generate}, which owns the whole destination side.
+ *
+ * **The encoding is verified, not reasoned about.** {@link encodeDevVarsValue} tries the three forms
+ * dotenv accepts and keeps the first one that survives a round trip through *both* readers — wrangler's
+ * and ours. A value no form survives is refused by name. That is deliberately stricter than a rule
+ * about which characters are dangerous: the rule would need updating for the shape nobody thought of,
+ * and the round trip already covers it.
+ *
+ * **A refusal is fail-closed, and now structurally.** The binding is the only place a `cf-secrets-store`
+ * secret is read from, so a refused value that left the superseded line in place handed the Worker the
+ * *previous* secret while every report said the value was replaced. The generated file is built from the
+ * sources every run rather than upserted into, so a refused value has no line to leave behind.
+ *
+ * **What this function still owns is persistence.** A generated file cannot be its own source of truth,
+ * so a value written here goes to the machine-local bootstrap store (`./bootstrapVars`) and the Workers'
+ * files are regenerated from it. That is what makes a master key minted by `pithy add secrets` survive to
+ * the next `pithy dev` without `.dev.vars` accumulating state nobody can regenerate.
+ */
+
+/** What one value's encoding produced: the bytes to write, or the sentence saying why nothing was. */
+export interface DevVarsEncoding {
+  /** The text that goes after `KEY=`, ready to write. `null` when no faithful encoding exists. */
+  encoded: string | null;
+  /** Why the value cannot be written, naming the secret and never its value. `null` when it can. */
+  refused: string | null;
+}
+
+/**
+ * `dotenv@16.3.1`'s line grammar, copied verbatim from the parser wrangler ships
+ * (`node_modules/wrangler/wrangler-dist/cli.js`, `var LINE = …`).
+ *
+ * It is exported so a test can assert it still appears in that bundle byte for byte. A copy that drifts
+ * from wrangler's is worse than no copy at all: {@link encodeDevVarsValue} verifies every value against
+ * it, so a drift would silently bless an encoding the Worker reads differently.
+ */
+export const DOTENV_LINE =
+  /(?:^|^)\s*(?:export\s+)?([\w.-]+)(?:\s*=\s*?|:\s+?)(\s*'(?:\\'|[^'])*'|\s*"(?:\\"|[^"])*"|\s*`(?:\\`|[^`])*`|[^#\r\n]+)?\s*(?:#.*)?(?:$|$)/gm;
+
+/**
+ * Parse a `.dev.vars` body the way **wrangler** does — quoted spans, inline `#` comments, and the
+ * `\n`/`\r` expansion a double-quoted value gets. This is the reader whose answer the Worker actually
+ * receives, so it is the one an encoding has to satisfy.
+ *
+ * Not a replacement for `parseDevVars`. That one is what pithy's own commands read the file with, and
+ * the two disagree — on `#`, on backticks, on escapes. Both are checked, because a value that reads one
+ * way in the Worker and another in `pithy doctor` is its own bug.
+ */
+export function parseDotenv(source: string): Record<string, string> {
+  const vars: Record<string, string> = {};
+  const line = new RegExp(DOTENV_LINE.source, DOTENV_LINE.flags);
+  const body = source.toString().replace(/\r\n?/gm, "\n");
+  let match: RegExpExecArray | null = line.exec(body);
+  while (match !== null) {
+    const key = match[1];
+    let value = (match[2] ?? "").trim();
+    const quote = value[0];
+    value = value.replace(/^(['"`])([\s\S]*)\1$/gm, "$2");
+    if (quote === '"') value = value.replace(/\\n/g, "\n").replace(/\\r/g, "\r");
+    if (key !== undefined) vars[key] = value;
+    match = line.exec(body);
+  }
+  return vars;
+}
+
+/** The three forms dotenv accepts, in the order they are tried: as-is, single-quoted, double-quoted. */
+function candidates(value: string): string[] {
+  const forms = [value];
+  if (!value.includes("'")) forms.push(`'${value}'`);
+  if (!value.includes('"')) forms.push(`"${value}"`);
+  return forms;
+}
+
+/**
+ * Encode one value for `.dev.vars`, or refuse.
+ *
+ * A candidate is accepted only when writing `NAME=<candidate>` and reading it back gives the value
+ * again — through wrangler's parser *and* through pithy's. The plain form is tried first, so the
+ * overwhelming majority of values (base64 keys, JSON envelopes) are written exactly as they always
+ * were and no existing file churns.
+ *
+ * The name is checked by the same round trip rather than by a separate rule: dotenv's key grammar is
+ * `[\w.-]+`, so a secret named with a `:` produces a line the Worker never sees at all. Silence is the
+ * worst answer available for a secret, so that is a refusal too.
+ */
+export function encodeDevVarsValue(name: string, value: string): DevVarsEncoding {
+  for (const candidate of candidates(value)) {
+    const line = `${name}=${candidate}\n`;
+    if (parseDotenv(line)[name] === value && parseDevVars(line)[name] === value) {
+      return { encoded: candidate, refused: null };
+    }
+  }
+  return {
+    encoded: null,
+    refused: `${name} cannot be written to .dev.vars — no quoting survives its value. It belongs in the dev secrets file; see #153.`,
+  };
+}
+
+/** What {@link writeDevVars} needs. Every seam defaults to the real project. */
+export interface WriteDevVarsOptions {
+  /** The project root — owner of `apps/`, of the `.dev.vars.local` files, and of the project's name. */
+  projectDir: string;
+  /**
+   * The values to record in `dev.json`, by variable name. **Only what no registry declares** — a
+   * Turnstile sitekey, a machine-local endpoint. A registry secret's value belongs in `secrets.jsonc`,
+   * which the generator reads directly (#179). Empty records nothing and regenerates anyway.
+   */
+  values: Record<string, string>;
+  /** The Worker directories to generate into. Defaults to every discovered Worker with a `wrangler.jsonc`. */
+  workerDirs?: string[];
+  /** The Workers whose registries decide which secrets are materialised. Defaults to every one composing `secrets`. */
+  targets?: DevSecretsTarget[];
+  /** Where the Pithy config directory is. Defaults to the real one; a seam so a test writes its own. */
+  paths?: StatePathOptions;
+}
+
+/** What one write did. Every list is sorted, so two runs of the same state read the same. */
+export interface WriteDevVarsResult {
+  /** The variable names actually recorded — the ones an encoding survives. */
+  written: string[];
+  /**
+   * One sentence per value or Worker directory that did not get one: a value no quoting survives, a
+   * `.dev.vars` pithy did not generate, a directory this project may not write into. Never a value.
+   */
+  refused: string[];
+  /** Worker directories whose `.dev.vars` this run wrote. */
+  generated: string[];
+  /** Worker directories whose `.dev.vars` already held exactly these bytes. No bytes written, mtime intact. */
+  unchanged: string[];
+  /** Worker directories whose `.dev.vars` was a symlink from the old shared-file design, now a real file. */
+  relinked: string[];
+  /** Every variable name the generated files carry, sorted. Names only — never a value, anywhere. */
+  names: string[];
+}
+
+/**
+ * Record values in the machine-local bootstrap store, then regenerate every Worker's `.dev.vars` from it.
+ *
+ * Mode `0600` on every file written, the same as the dev secrets file: this one holds the dev master key
+ * and every `cf-secrets-store` value, and the umask default is world-readable.
+ */
+export async function writeDevVars(options: WriteDevVarsOptions): Promise<WriteDevVarsResult> {
+  const written: string[] = [];
+  const refused: string[] = [];
+  const encoded: Record<string, string> = {};
+  for (const name of Object.keys(options.values).sort()) {
+    const value = options.values[name];
+    if (value === undefined) continue;
+    // Encoded here only to decide whether the value can be delivered at all. The bootstrap store keeps
+    // the plain value — quoting is `.dev.vars` grammar, and a quoted value round-tripped through a JSON
+    // file would acquire a second layer of it on the next generation.
+    const result = encodeDevVarsValue(name, value);
+    if (result.encoded === null) {
+      if (result.refused !== null) refused.push(result.refused);
+      continue;
+    }
+    encoded[name] = value;
+    written.push(name);
+  }
+
+  await writeBootstrapVars(options.projectDir, encoded, options.paths ?? {});
+  // Regenerated from the **sources**, never from what was just recorded. A generator handed a value set
+  // by its caller is a generator that can disagree with the files it claims to read — which is exactly
+  // how a `cf-secrets-store` secret came to reach a Worker one `pithy seed` after it was rotated (#179).
+  const generated = await generateDevVars({
+    projectDir: options.projectDir,
+    ...(options.workerDirs !== undefined ? { workerDirs: options.workerDirs } : {}),
+    ...(options.targets !== undefined ? { targets: options.targets } : {}),
+    ...(options.paths !== undefined ? { paths: options.paths } : {}),
+  });
+
+  return {
+    written,
+    refused: [...refused, ...generated.refused].sort(),
+    generated: generated.generated,
+    unchanged: generated.unchanged,
+    relinked: generated.relinked,
+    names: generated.names,
+  };
+}
+
+/**
+ * The file's bytes, or `null` when there is no file — and **only** when there is no file.
+ *
+ * The rule and its three producers now live in {@link readOptionalFile} (`../project/`). What stays here
+ * is what is `.dev.vars`-shaped: the sentence an adopter reads, the mode it names, and *why* absence had
+ * to stop meaning "unreadable" for this file in particular. Reading `EACCES` or `EIO` as "empty" meant
+ * the next content was built from an empty base and renamed over a file full of values this process never
+ * saw — the adopter's `CLOUDFLARE_API_TOKEN` and every other line, gone, with the run reporting a clean
+ * write. The same defect `readSource` was written to end for the dev secrets file, in the file beside it,
+ * twice over.
+ *
+ * The wrapped error carries the node error as `cause`. Its message is a path and an errno, never a line
+ * of the file.
+ *
+ * **Exported because reading this file honestly is not only the writer's problem.** `pithy add` asks the
+ * same question — is this secret already here? — and its own `.catch(() => "")` answered "no" for an
+ * unreadable file, so `add` minted a second value and the project held two under one name, one in each
+ * file. Three readers of one file is how one of them keeps getting it wrong.
+ */
+export async function readDevVarsSource(path: string): Promise<string | null> {
+  return readOptionalFile(path, {
+    unreadable: ({ code, cause }) =>
+      new InternalError(
+        {
+          message: ".dev.vars is there and could not be read.",
+          action: `Check ${path} and its permissions. It should be a file, mode 600.`,
+          detail: `.dev.vars '${path}' failed to read: ${code ?? "unknown error"}`,
+        },
+        { cause },
+      ),
+  });
+}