@pithy-sh/cli 0.1.0

package/src/project/dashboard.ts

@@ -0,0 +1,118 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+/**
+ * Cloudflare dashboard deep-link builders, keyed by resource kind. `pithy env` renders a
+ * provisioned resource's id as a link to the exact dashboard page for that resource, so an
+ * operator jumps straight from the inventory to the console.
+ *
+ * **Every path here was checked against a live dashboard.** A kind with no confirmed path gets no
+ * link — {@link dashboardUrl} returns `null` for it — because an unconfirmed deep link is worse
+ * than a bare id: it looks authoritative and lands on a 404. All links share the base
+ * `https://dash.cloudflare.com/<account_id>/…`.
+ *
+ * Two shapes of link live here. **Resource links** address one provisioned resource by its id.
+ * **Account links** address a product page that has no per-resource route at all (Workers AI usage,
+ * Images, Stream, Email Service); they ignore the id, so a caller may pass an empty one.
+ *
+ * Two kinds deliberately have no builder:
+ * - **`ratelimit`** — Workers Rate Limiting has no dashboard page at all.
+ * - **`service`** — a service binding is not a resource; it is direct RPC to *another Worker*. Its
+ *   page is that Worker's, so a caller resolves the target script name and asks for the `worker`
+ *   kind instead.
+ */
+
+/** Kinds whose dashboard page addresses one resource by id. */
+type ResourceKind =
+  | "worker"
+  | "d1"
+  | "kv"
+  | "r2"
+  | "vectorize"
+  | "workflow"
+  | "durable_object"
+  | "queue"
+  | "secret"
+  | "turnstile";
+
+/** Kinds with no per-resource page — the link is the product's account-level page. */
+type AccountKind = "ai" | "images" | "stream" | "email";
+
+/** The base every dashboard link is built on. */
+const DASHBOARD_BASE = "https://dash.cloudflare.com";
+
+/**
+ * One builder per id-addressed kind. `id` is that kind's **dashboard** identifier, which is not
+ * always the identifier `wrangler.jsonc` carries — see the notes below before wiring a caller.
+ *
+ * D1 and KV land on the resource's metrics tab, which is the dashboard's own default page for those
+ * two, so the link lands exactly where clicking through the console would.
+ */
+const RESOURCE_BUILDERS: Record<ResourceKind, (accountId: string, id: string) => string> = {
+  worker: (accountId, id) => `${DASHBOARD_BASE}/${accountId}/workers/services/view/${id}/production`,
+  d1: (accountId, id) => `${DASHBOARD_BASE}/${accountId}/workers/d1/databases/${id}/metrics`,
+  kv: (accountId, id) => `${DASHBOARD_BASE}/${accountId}/workers/kv/namespaces/${id}/metrics`,
+  r2: (accountId, id) => `${DASHBOARD_BASE}/${accountId}/r2/default/buckets/${id}`,
+  vectorize: (accountId, id) => `${DASHBOARD_BASE}/${accountId}/ai/vectorize/${id}`,
+  workflow: (accountId, id) => `${DASHBOARD_BASE}/${accountId}/workers/workflows/${id}/instances`,
+  // `id` is the Durable Object **namespace id** Cloudflare assigns (32-char hex), not the class
+  // name. `wrangler.jsonc` carries only the class name, so a caller holding just that must not build
+  // this link — see `envInventory`, which renders DO bindings unlinked for exactly this reason.
+  durable_object: (accountId, id) => `${DASHBOARD_BASE}/${accountId}/workers/durable-objects/view/${id}/overview`,
+  // `id` is the **queue id** (32-char hex), not the queue name a producer binding declares. Same
+  // caveat as `durable_object`: a caller holding only the name must not build this link.
+  queue: (accountId, id) => `${DASHBOARD_BASE}/${accountId}/workers/queues/${id}/metrics`,
+  // `id` is the Secrets Store id, not a secret's name — the page is the store, not one entry.
+  secret: (accountId, id) => `${DASHBOARD_BASE}/${accountId}/secrets-store/${id}`,
+  // `id` is the widget's sitekey (e.g. `0x4AAA…`), which `pithy turnstile` writes into wrangler vars.
+  turnstile: (accountId, id) => `${DASHBOARD_BASE}/${accountId}/turnstile/widget/${id}`,
+};
+
+/**
+ * The product **list** page for a kind whose per-resource id a project cannot know from config alone.
+ *
+ * A Durable Object binding names a *class* and a queue binding names a *queue*, but the dashboard addresses
+ * both by an id Cloudflare assigns — a DO namespace id when a Worker exporting the class deploys, a queue id
+ * when the queue is created. Neither is written back into `wrangler.jsonc`, and resolving one would take an
+ * API call this read-only, credential-optional command deliberately does not make. So the link goes to the
+ * product's list, which is one click from the resource and always correct, rather than nowhere.
+ *
+ * Both routes below were checked against a live dashboard, like every other path in this file.
+ */
+const LIST_BUILDERS: Record<string, (accountId: string) => string> = {
+  durable_object: (accountId) => `${DASHBOARD_BASE}/${accountId}/workers/durable-objects`,
+  queue: (accountId) => `${DASHBOARD_BASE}/${accountId}/workers/queues`,
+};
+
+/**
+ * The list page for a kind, or `null` when it has none. Used as the fallback when a resource is real and
+ * provisioned but its dashboard id is not knowable from the project's own config.
+ */
+export function dashboardListUrl(kind: string, accountId: string): string | null {
+  const build = LIST_BUILDERS[kind];
+  return build ? build(accountId) : null;
+}
+
+/** One builder per account-level kind. The resource id is not part of the route. */
+const ACCOUNT_BUILDERS: Record<AccountKind, (accountId: string) => string> = {
+  ai: (accountId) => `${DASHBOARD_BASE}/${accountId}/ai/workers-ai/usage`,
+  images: (accountId) => `${DASHBOARD_BASE}/${accountId}/images/hosted`,
+  stream: (accountId) => `${DASHBOARD_BASE}/${accountId}/stream/videos`,
+  email: (accountId) => `${DASHBOARD_BASE}/${accountId}/email-service/sending`,
+};
+
+/**
+ * Build the Cloudflare dashboard URL for a resource, or `null` when the kind has no confirmed
+ * dashboard path. `kind` is a plain string so callers can pass any binding kind (`ratelimit`,
+ * `service`, …) without narrowing; an unsupported kind returns `null` rather than a guessed link.
+ * An account-level kind ignores `id`, so `""` is fine for those.
+ */
+export function dashboardUrl(kind: string, accountId: string, id: string): string | null {
+  const account = (ACCOUNT_BUILDERS as Record<string, ((accountId: string) => string) | undefined>)[kind];
+  if (account) return account(accountId);
+
+  const resource = (RESOURCE_BUILDERS as Record<string, ((accountId: string, id: string) => string) | undefined>)[kind];
+  // An id-addressed kind with no id has nothing to point at — a bare product page would be a lie.
+  if (!resource || !id) return null;
+  return resource(accountId, id);
+}

package/src/project/deploy.ts

@@ -0,0 +1,364 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { InternalError, messageOf, NotFoundError, PithyError } from "@pithy-sh/core/src/error/pithyError";
+import type { WorkerDomains } from "@pithy-sh/core/src/naming/domains";
+import type { CliAuditEmit } from "../audit/cliAudit";
+import { type CloudflareAccountSelection, cloudflareEnv } from "../cloudflare/config";
+import { isSourceEnvironment, wranglerConfigPath } from "../provision/featureConfig";
+import { red } from "../terminal/style";
+import { loadWorkerConfig, loadWorkerDomains } from "./config";
+import { detectPackageManager, execArgs, type PackageManager } from "./packageManager";
+import type { DeployVerification, VerifyDeployResult } from "./verifyDeploy";
+import { isDeployFailure, verifyDeployedVersion } from "./verifyDeploy";
+import { type AddressStanza, resolveWorkerAddress } from "./workerAddress";
+import { parseWorkerManifest } from "./workerManifest";
+import { discoverWorkers, type WorkerTarget } from "./workers";
+import { readWranglerConfig, runWrangler } from "./wrangler";
+
+/** The `wrangler deploy` runner for one worker — injectable so tests exercise orchestration without wrangler. */
+export type RunDeploy = (target: WorkerTarget, args: string[]) => Promise<string>;
+
+/**
+ * The UI build runner for one worker — injectable so tests exercise orchestration without a real build.
+ *
+ * `environment` is not optional decoration. `@pithy-sh/vite` resolves each capability's client-safe
+ * projection *for a named environment* at build time — a Turnstile sitekey differs per environment, and
+ * the plugin falls back to `dev` when nothing says otherwise. A build that does not carry the deploy's
+ * `--env` therefore inlines dev values into a production bundle, which for Turnstile means shipping
+ * Cloudflare's always-passes test sitekey. It is silent, and it defeats the gate entirely.
+ */
+export type RunBuild = (
+  target: WorkerTarget,
+  command: string,
+  args: string[],
+  environment: string | undefined,
+) => Promise<void>;
+
+export interface DeployProjectOptions {
+  /** The project root — the parent of `apps/`, where every Worker lives. */
+  projectDir: string;
+  /**
+   * The Cloudflare account this project belongs to, from `projectCloudflareAccount(projectDir)` — or
+   * `null` for a project that names none.
+   *
+   * **Required, and stated by the caller rather than defaulted.** An omitted account would resolve
+   * whatever the last-loaded project happened to select, and the failure that produces is a successful
+   * deploy to the wrong tenant. There is no safe default, so there is no default (#206).
+   */
+  account: CloudflareAccountSelection | null;
+  /** Target environment; omitted deploys each worker's top-level config (no `--env`). */
+  env?: string;
+  /** Test seam: run one worker's deploy and return its captured stdout. Defaults to real wrangler. */
+  runDeploy?: RunDeploy;
+  /** Test seam: run one worker's UI build. Defaults to the real package-manager invocation. */
+  runBuild?: RunBuild;
+  /** Audit emitter. Defaults to recording nothing, so a caller without audit wiring still works. */
+  audit?: CliAuditEmit;
+  /**
+   * Test seam: probe a declared domain for the version just shipped. Defaults to the real HTTP probe.
+   *
+   * Injected rather than reached for, so the deploy tests never touch the network and the retry/backoff
+   * behavior is exercised without waiting for it.
+   */
+  verifyDeploy?: VerifyDeploy;
+}
+
+/** Probe one address for one expected version. The seam `verifyDeployedVersion` fills by default. */
+export type VerifyDeploy = (options: { url: string; expectedVersion: string }) => Promise<VerifyDeployResult>;
+
+/**
+ * Shipping code is production-affecting the moment `prod` is the named target — everything else
+ * (`staging`, a bare deploy with no `--env`) is routine. Exported so the command layer and tests agree on
+ * the same rule.
+ */
+export function deploySeverity(env: string | undefined): "info" | "warning" {
+  return env === "prod" ? "warning" : "info";
+}
+
+/** One worker's deploy outcome — the `--json` row and the human summary line both read from this. */
+export interface WorkerDeploy {
+  /** The worker's name. */
+  name: string;
+  /** Whether `wrangler deploy` succeeded for this worker. */
+  ok: boolean;
+  /** The deployed version id, when wrangler's output carried one. */
+  versionId?: string;
+  /** The worker's public URL, when wrangler's output carried one. */
+  url?: string;
+  /**
+   * Whether this worker's UI build ran and succeeded. Absent when the worker declares no `ui` block —
+   * so `false` means the build is what failed, and the deploy never ran.
+   */
+  built?: boolean;
+  /** The failure reason, present only when `ok` is false. */
+  error?: string;
+  /**
+   * What probing the **declared** domain concluded about the version just shipped.
+   *
+   * Absent when there was nothing to check: a bare `pithy deploy` with no `--env` has no environment to
+   * resolve a domain for, and a Worker that declares no address has no domain to probe. `mismatch` and
+   * `unreachable` are the two that fail the command — see `isDeployFailure`.
+   */
+  verification?: DeployVerification;
+  /** The one-line explanation behind `verification`, for the summary and the `--json` row. */
+  verificationDetail?: string;
+}
+
+/** Scrape the version id and public url from `wrangler deploy` output — best-effort, both optional. */
+function parseDeployOutput(stdout: string): { versionId?: string; url?: string } {
+  const summary: { versionId?: string; url?: string } = {};
+  const version = stdout.match(/Version ID:\s*(\S+)/);
+  if (version) summary.versionId = version[1];
+  // The deployed URL is the last one wrangler prints (after upload), not an earlier docs/dashboard link.
+  const urls = stdout.match(/https?:\/\/\S+/g);
+  if (urls) summary.url = urls[urls.length - 1];
+  return summary;
+}
+
+/**
+ * The failure reason for a thrown deploy. For a `PithyError` (how `runWrangler` reports a non-zero
+ * exit) that means the `detail` — wrangler's captured exit code and stderr, the part a CI operator
+ * needs — not just the generic public `message`. Anything else falls back to the shared `messageOf`.
+ */
+function reasonOf(error: unknown): string {
+  if (error instanceof PithyError) return error.payload.detail ?? error.payload.message;
+  return messageOf(error);
+}
+
+/**
+ * The default deploy step: `wrangler deploy [--env <env>]` in the worker's directory, quiet on
+ * success (its output is captured and summarized, not streamed — the brand voice). Wrangler reads
+ * `CLOUDFLARE_API_TOKEN`/`CLOUDFLARE_ACCOUNT_ID`, so CI needs no interactive login; we also pass them
+ * from the project's own credentials file so a local deploy authenticates the same way.
+ *
+ * **The account is an argument, and that is load-bearing here more than anywhere.** This is the exact
+ * pair handed to `wrangler deploy`: resolving it against the wrong account does not fail, it ships to
+ * another company's tenant and exits 0. A pinned `accountId` that disagrees refuses before wrangler is
+ * ever spawned (#206).
+ */
+function defaultRunDeploy(account: CloudflareAccountSelection | null): RunDeploy {
+  const vars = cloudflareEnv({ account });
+  const env: Record<string, string> = {};
+  if (vars.CLOUDFLARE_API_TOKEN) env.CLOUDFLARE_API_TOKEN = vars.CLOUDFLARE_API_TOKEN;
+  if (vars.CLOUDFLARE_ACCOUNT_ID) env.CLOUDFLARE_ACCOUNT_ID = vars.CLOUDFLARE_ACCOUNT_ID;
+  return async (target, args) => {
+    const { stdout } = await runWrangler(args, { cwd: target.dir, env });
+    return stdout;
+  };
+}
+
+const runProcess = promisify(execFile);
+
+/**
+ * The default UI build step: the worker's `ui.build` argv, through the project's package manager, in the
+ * worker's own directory. Quiet on success like the deploy step — the output is captured and surfaced only
+ * as the failure `detail`. A build's chunk table can be long, so the buffer is generous; truncation would
+ * turn a real failure into a confusing one.
+ */
+const defaultRunBuild: RunBuild = async (target, command, args, environment) => {
+  try {
+    await runProcess(command, args, {
+      cwd: target.dir,
+      maxBuffer: 16 * 1024 * 1024,
+      // `ENVIRONMENT` is the same signal the deployed Worker reads (wrangler.jsonc `vars`), and it is
+      // what the Vite plugin resolves each capability's projection against. Absent, it builds `dev`.
+      ...(environment ? { env: { ...process.env, ENVIRONMENT: environment } } : {}),
+    });
+  } catch (cause) {
+    throw new InternalError({
+      message: `${command} ${args.join(" ")} failed.`,
+      action: `Build ${target.name} by hand: ${command} ${args.join(" ")}.`,
+      detail: cause instanceof Error ? cause.message : String(cause),
+    });
+  }
+};
+
+/**
+ * The build command for one worker, or `undefined` when it serves no front end. The SPA lives in the Worker
+ * that serves it, so its assets have to exist before `wrangler deploy` uploads them. `vite build` also writes
+ * `.wrangler/deploy/config.json` in the worker's directory, which redirects the following plain
+ * `wrangler deploy` to the built config — so the deploy argv needs no `-c` and does not change.
+ */
+async function uiBuild(
+  worker: WorkerTarget,
+  packageManager: PackageManager,
+): Promise<{ command: string; args: string[] } | undefined> {
+  const manifest = await parseWorkerManifest(worker.dir);
+  const build = manifest?.ui?.build;
+  if (!build || build.length === 0) return undefined;
+  return execArgs(packageManager, build[0] as string, build.slice(1));
+}
+
+/**
+ * Deploy the project's Workers — the logic behind `pithy deploy`. It enumerates the worker registry
+ * (`apps/*` — there is no root Worker) and runs `wrangler deploy` in each worker's own directory, against
+ * that worker's own `wrangler.jsonc`, letting wrangler own bundling, upload, bindings, and routes. One
+ * worker's failure does not abort the batch: every worker is attempted and reported, so the caller can
+ * exit non-zero if any `ok` is false.
+ *
+ * A worker that serves a front end (a `ui` block in its `pithy.worker.jsonc`) is **built first**, in its own
+ * directory, through the adopter's package manager. A failed build fails that worker and skips its deploy —
+ * shipping a Worker whose assets are stale, or missing, is worse than not shipping it.
+ */
+/**
+ * Probe one Worker's declared domain for the version just shipped, or return null when there is nothing
+ * to check.
+ *
+ * Three ways to have nothing to check, and all three are ordinary rather than failures. **No `--env`**:
+ * a bare `pithy deploy` ships each Worker's top-level stanza, which is the `dev` environment, and `dev`
+ * has no public address by design. **No version id**: wrangler printed none, so there is nothing to
+ * correlate against. **No declared address**: the Worker has no domain, no route, and no `BASE_URL`, so
+ * there is nowhere to probe — and inventing `workers.dev` here would be exactly the assumption #89 rules
+ * out, since the subdomain can be disabled per account and commonly is in production.
+ */
+async function verifyWorkerDeploy(
+  worker: WorkerTarget,
+  env: string | undefined,
+  versionId: string | undefined,
+  probe: VerifyDeploy,
+): Promise<VerifyDeployResult | null> {
+  if (!env || env === "dev" || !versionId) return null;
+
+  let domains: WorkerDomains | undefined;
+  try {
+    domains = loadWorkerDomains(await loadWorkerConfig(worker.dir));
+  } catch {
+    domains = undefined;
+  }
+
+  let stanza: AddressStanza | undefined;
+  try {
+    stanza = ((await readWranglerConfig(worker.dir)) as { env?: Record<string, AddressStanza | undefined> }).env?.[env];
+  } catch {
+    stanza = undefined;
+  }
+
+  const address = resolveWorkerAddress({ environment: env, domains, stanza });
+  if (!address) return null;
+
+  return probe({ url: address.url, expectedVersion: versionId });
+}
+
+export async function deployProject(options: DeployProjectOptions): Promise<WorkerDeploy[]> {
+  // Only real Workers deploy. A non-Worker process in the dev set (a Vite frontend with a
+  // `pithy.worker.jsonc` but no `wrangler.jsonc`) has nothing for `wrangler deploy` to ship.
+  const workers = (await discoverWorkers(options.projectDir)).filter((worker) => worker.hasWrangler !== false);
+  if (workers.length === 0) {
+    throw new NotFoundError({
+      message: "No deployable workers here.",
+      action: "Every worker lives in apps/<name> with its own wrangler.jsonc. Run pithy worker add <name>.",
+    });
+  }
+
+  const run = options.runDeploy ?? defaultRunDeploy(options.account);
+  const build = options.runBuild ?? defaultRunBuild;
+  const packageManager = await detectPackageManager(options.projectDir);
+  // `--config` for a feature environment, and only there. Provisioning writes a feature's ids into a
+  // generated config under `.wrangler/` rather than into the tracked `wrangler.jsonc` (#242), so wrangler
+  // has to be told where they are. A declared environment's ids are in the file wrangler already reads.
+  const configFor = (worker: WorkerTarget): string[] =>
+    options.env && !isSourceEnvironment(options.env) ? ["--config", wranglerConfigPath(worker.dir, options.env)] : [];
+  const args = options.env ? ["deploy", "--env", options.env] : ["deploy"];
+  const audit = options.audit ?? (async () => {});
+  const probe = options.verifyDeploy ?? ((probeOptions) => verifyDeployedVersion(probeOptions));
+  const severity = deploySeverity(options.env);
+
+  const deploys: WorkerDeploy[] = [];
+  for (const worker of workers) {
+    // Stays undefined for an API-only worker, turns false while a UI worker's build is in flight: a
+    // `built: false` row is how a `--json` consumer reads "the build failed, the deploy never ran".
+    let built: boolean | undefined;
+    try {
+      const ui = await uiBuild(worker, packageManager);
+      if (ui) {
+        built = false;
+        await build(worker, ui.command, ui.args, options.env);
+        built = true;
+      }
+      const stdout = await run(worker, [...args, ...configFor(worker)]);
+      const deploy: WorkerDeploy = {
+        name: worker.name,
+        ok: true,
+        ...parseDeployOutput(stdout),
+        ...(built === undefined ? {} : { built }),
+      };
+      // Prove the Worker just shipped is the one answering at the address this project claims. Not a
+      // liveness probe — the old version answering happily is exactly the failure worth catching — and
+      // not a comparison against the URL wrangler printed, which under versions may be a version-scoped
+      // preview rather than the stable route.
+      const verified = await verifyWorkerDeploy(worker, options.env, deploy.versionId, probe);
+      if (verified) {
+        deploy.verification = verified.status;
+        deploy.verificationDetail = verified.detail;
+      }
+      deploys.push(deploy);
+      await audit({
+        action: "deploy/worker_deployed",
+        outcome: "success",
+        severity,
+        resourceType: "cf_worker",
+        resourceId: worker.name,
+        // Neither `worker` nor `env` belongs here any more. The environment is the `environment`
+        // column the recorder stamps, and the Worker deployed is already `resourceId` — which is
+        // also the truer home for it, since that Worker is what this action *targeted*, not where
+        // the action came from (a CLI deploy comes from no Worker at all).
+        metadata: { versionId: deploy.versionId ?? null, verification: deploy.verification ?? null },
+      });
+    } catch (error) {
+      const reason = reasonOf(error);
+      deploys.push({ name: worker.name, ok: false, ...(built === undefined ? {} : { built }), error: reason });
+      // A failed deploy is exactly what an audit trail is for — record it too, not just successes.
+      await audit({
+        action: "deploy/worker_deployed",
+        outcome: "failure",
+        severity,
+        resourceType: "cf_worker",
+        resourceId: worker.name,
+        // Same as the success path: `worker` is `resourceId` and `env` is the `environment` column.
+        // What stays is what is genuinely per-event — which stage failed, and why.
+        metadata: {
+          stage: built === false ? "build" : "deploy",
+          error: reason,
+        },
+      });
+    }
+  }
+  return deploys;
+}
+
+/** One worker's human summary line — brand voice; red on failure, url + version id on success. */
+export function summarizeDeploy(deploy: WorkerDeploy): string {
+  // A build failure and a deploy failure are different problems with different fixes, so they read differently.
+  if (!deploy.ok) {
+    const problem = deploy.built === false ? "build failed." : "failed.";
+    return red(`${deploy.name}: ${problem}`) + (deploy.error ? ` ${deploy.error}` : "");
+  }
+  const detail = [deploy.url, deploy.versionId].filter(Boolean).join(" ");
+  const line = detail ? `${deploy.name}: deployed. ${detail}` : `${deploy.name}: deployed.`;
+  // Wrangler's own URL keeps appearing above, as it always did — it tells a human where their deploy
+  // went. The verification line below is the separate question of whether the *declared* address is now
+  // serving what was just shipped, and it is the only one that can fail the command.
+  if (!deploy.verification || deploy.verification === "verified") return line;
+  const note = deploy.verificationDetail ?? "";
+  // Red for the two that fail the command, plain for the two that do not — one rule, `isDeployFailure`,
+  // so the color and the exit code can never disagree about which is which.
+  return isDeployFailure(deploy.verification) ? `${line}\n  ${red(note)}` : `${line}\n  ${note}`;
+}
+
+/** Whether any Worker's declared address is consistently serving something other than what just shipped. */
+export function deployVerificationFailed(deploys: readonly WorkerDeploy[]): boolean {
+  return deploys.some((deploy) => deploy.verification !== undefined && isDeployFailure(deploy.verification));
+}
+
+/**
+ * The warn line when the target env's schema is behind — deploy never migrates, so it only surfaces
+ * the drift and points at `pithy migrate`. `undefined` when nothing is pending or the count is unknown.
+ */
+export function pendingWarning(pending: number | undefined, env: string): string | undefined {
+  if (!pending || pending <= 0) return undefined;
+  const plural = pending === 1 ? "" : "s";
+  return `${pending} migration${plural} unapplied for ${env}. Deploy does not migrate — run pithy migrate --env ${env}.`;
+}

package/src/project/devVars.ts

@@ -0,0 +1,113 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { ConflictError } from "@pithy-sh/core/src/error/pithyError";
+import { writeFileAtomic } from "./atomic";
+import { readOptionalFile } from "./readOptionalFile";
+
+/**
+ * The mode a `.dev.vars` this module *creates* lands with. `pithy init` seeds the project's own at 0600;
+ * this is the same rule for every other one — a `.dev.vars.<env>`, or a shared file a checkout has not
+ * got yet — because the very next thing written into it is a Cloudflare API token or the master key. The
+ * umask is not a permission policy for a credential file. A file already there keeps its own mode.
+ */
+const DEV_VARS_MODE = 0o600;
+
+function detectEol(content: string): "\r\n" | "\n" {
+  return content.includes("\r\n") ? "\r\n" : "\n";
+}
+
+/**
+ * Upsert `KEY=value` lines into a `.dev.vars` file body, preserving every other line — comments, blanks,
+ * and unrelated keys — and updating a key in place where it already exists. New keys are appended. Pure;
+ * the caller owns the file IO. Existing line endings (CRLF or LF) are preserved; empty content defaults to LF.
+ */
+export function upsertDevVarsContent(content: string, vars: Record<string, string>): string {
+  const eol = detectEol(content);
+  const updates = new Map(Object.entries(vars));
+  const lines = content.length === 0 ? [] : content.replace(/\r?\n$/, "").split(/\r?\n/);
+  const written = new Set<string>();
+  const out: string[] = [];
+  for (const line of lines) {
+    const eq = line.indexOf("=");
+    if (eq === -1 || line.trimStart().startsWith("#")) {
+      out.push(line);
+      continue;
+    }
+    const key = line.slice(0, eq).trim();
+    if (!updates.has(key)) {
+      out.push(line);
+      continue;
+    }
+    // First occurrence of an upserted key: update in place. Any later duplicate of the same key is
+    // dropped, so a key never appears twice — otherwise `parseDevVars` (last-wins) would read a stale value.
+    if (!written.has(key)) {
+      out.push(`${key}=${updates.get(key)}`);
+      written.add(key);
+    }
+  }
+  for (const [key, value] of updates) {
+    if (!written.has(key)) out.push(`${key}=${value}`);
+  }
+  return out.length === 0 ? "" : `${out.join(eol)}${eol}`;
+}
+
+/** Remove the given `KEY=` lines from a `.dev.vars` file body, leaving everything else untouched. */
+export function removeDevVarsContent(content: string, keys: string[]): string {
+  const eol = detectEol(content);
+  const drop = new Set(keys);
+  const lines = content.length === 0 ? [] : content.replace(/\r?\n$/, "").split(/\r?\n/);
+  const out = lines.filter((line) => {
+    const eq = line.indexOf("=");
+    if (eq === -1 || line.trimStart().startsWith("#")) return true;
+    return !drop.has(line.slice(0, eq).trim());
+  });
+  return out.length === 0 ? "" : `${out.join(eol)}${eol}`;
+}
+
+/**
+ * Read a dev-vars file (empty if absent), upsert the keys, and write it back atomically — owner-only when
+ * it has to be created, and *through* a symlink at `path` rather than over it, when the link is one we
+ * could have made ourselves. See {@link writeFileAtomic}.
+ */
+export async function upsertDevVars(path: string, vars: Record<string, string>): Promise<void> {
+  const content = await readDevVarsFile(path);
+  await writeFileAtomic(path, upsertDevVarsContent(content ?? "", vars), { mode: DEV_VARS_MODE });
+}
+
+/** Read a dev-vars file (no-op if absent), remove the keys, and write it back atomically. */
+export async function removeDevVars(path: string, keys: string[]): Promise<void> {
+  const content = await readDevVarsFile(path);
+  if (content === null) return;
+  await writeFileAtomic(path, removeDevVarsContent(content, keys), { mode: DEV_VARS_MODE });
+}
+
+/**
+ * The file's current contents, or `null` — **and `null` means the file is not there, nothing else.**
+ *
+ * Both writers above are read-modify-write over a credential file, so "absent" is the one answer that
+ * licenses replacing it. A `catch(() => "")` licensed it for every failure: `EACCES` on a file that
+ * plainly exists, `EISDIR`, `ELOOP`, an I/O error — and the atomic write then landed a `.dev.vars`
+ * holding **only the keys being upserted**, every other secret in it gone. No attacker is involved, and
+ * the file is gitignored, so there is no copy of what it held. `removeDevVars` had the same shape with a
+ * quieter failure: it returned early and its caller printed success, telling the adopter a credential
+ * was removed while it sat in the file untouched.
+ *
+ * This is the third data loss on this branch from that one shape, so the errno decision belongs to
+ * {@link readOptionalFile} and is made once for every reader. What stays here is the sentence a
+ * credential file deserves. A file we cannot read is not a file we may overwrite.
+ */
+async function readDevVarsFile(path: string): Promise<string | null> {
+  return readOptionalFile(path, {
+    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. Pithy won't rewrite a credential file it could not read.",
+          detail: `${code ?? "unknown error"} while reading ${path}`,
+        },
+        { cause },
+      ),
+  });
+}