@pithy-sh/cli 0.1.0

package/src/project/appBindings.ts

@@ -0,0 +1,184 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { resourceNames } from "@pithy-sh/core/src/naming/resourceNames";
+import { hostWorkflowsFor } from "@pithy-sh/core/src/workflow/host";
+import type { WorkflowHostNameParts } from "@pithy-sh/core/src/workflow/naming";
+import type { WorkflowRegistry } from "@pithy-sh/core/src/workflow/spec";
+import { readWranglerConfig, writeWranglerConfig } from "./wrangler";
+
+/**
+ * The bindings a capability's **provisioner** writes into the app's `wrangler.jsonc` — the ones
+ * `pithy add` deliberately cannot write.
+ *
+ * Wrangler validates its config before it does anything else, and two binding kinds carry required
+ * fields whose values only exist after provisioning: a `vectorize` entry must name an `index_name`,
+ * and a `workflows` entry must carry a `name` and a `class_name`. `pithy add` is offline — it knows
+ * neither the provisioned index name nor the per-environment Workflow script name — so an `add` that
+ * emitted a partial entry would leave the adopter with a `wrangler.jsonc` that fails to load. It
+ * emits nothing instead, and this module completes the entry once `pithy <capability> provision` has
+ * stood the resources up. `capabilities/add.ts` states the same contract from the other side.
+ *
+ * `dev` writes the top-level stanza and every other environment writes its own `env.<name>` — the same
+ * rule `commands/vector.ts` reads the app database id by and writes `VECTOR_PROVISIONED` by. Wrangler
+ * does not inherit bindings into a named environment, and every name written here is
+ * environment-scoped anyway. Upsert by binding name, comment-preserving, idempotent: re-provisioning
+ * rewrites the same entries in place.
+ */
+
+/**
+ * One `workflows` entry, complete. `binding` and `class_name` are code references; `name` is the
+ * deployed Workflow and `script_name` the host Worker that runs it — both environment-scoped, which
+ * is exactly why they arrive here rather than at add time.
+ */
+export interface AppWorkflowBinding {
+  /** The binding name the Worker env exposes, e.g. `STORAGE_SWEEP`. */
+  binding: string;
+  /** The deployed Workflow name, `<project>-<env>-<capability>-<job>`. */
+  name: string;
+  /** The exported `WorkflowEntrypoint` subclass that runs the job. */
+  class_name: string;
+  /** The host Worker the class lives in, `<project>-<env>-<capability>` — this is a cross-script binding. */
+  script_name: string;
+}
+
+/** One `vectorize` entry, complete. `index_name` is the provisioned index, `<project>-<env>-vector-<index>`. */
+export interface AppVectorizeBinding {
+  /** The binding name the Worker env exposes, e.g. `VECTORIZE`. */
+  binding: string;
+  /** The provisioned Vectorize index this binding addresses. */
+  index_name: string;
+  /** Reach the real index in local dev. Vectorize has no local emulation, so this is always true. */
+  remote?: boolean;
+}
+
+/** The provisioner-owned slice of one `env.<env>` stanza. */
+interface AppBindingStanza {
+  workflows?: AppWorkflowBinding[];
+  vectorize?: AppVectorizeBinding[];
+}
+
+/** The bindings one provisioning run wrote for one environment. Either list may be omitted. */
+export interface AppBindings {
+  /** Complete `workflows` entries, one per hosted job. */
+  workflows?: readonly AppWorkflowBinding[];
+  /** Complete `vectorize` entries, one per configured index. */
+  vectorize?: readonly AppVectorizeBinding[];
+}
+
+/**
+ * Upsert entries into a binding array **in place**. comment-json stores an array's comments as
+ * symbol-keyed properties on the array object itself, so replacing the array with a fresh one would
+ * silently delete the adopter's notes — the rule `capabilities/remove.ts` and
+ * `feature/wranglerEnv.ts` both document.
+ */
+function upsertByBinding<Entry extends { binding: string }>(entries: Entry[], incoming: readonly Entry[]): void {
+  for (const entry of incoming) {
+    const index = entries.findIndex((candidate) => candidate.binding === entry.binding);
+    if (index === -1) entries.push(entry);
+    else entries[index] = entry;
+  }
+}
+
+/**
+ * The fields wrangler's config validator **requires**, per binding kind. An entry missing one of these
+ * does not degrade — it fails validation, and `wrangler dev` and `wrangler deploy` both refuse to run.
+ * Stated here once, so the writer and its tests check the same list.
+ */
+const REQUIRED_FIELDS: Record<"workflows" | "vectorize", readonly string[]> = {
+  workflows: ["binding", "name", "class_name"],
+  vectorize: ["binding", "index_name"],
+};
+
+/**
+ * Every `workflows`/`vectorize` entry in one stanza that wrangler would reject, described. Empty means
+ * the stanza loads. Exported because "does this config still load" is the property the writer promises,
+ * and a promise worth making is worth asserting.
+ */
+export function incompleteBindings(stanza: unknown): string[] {
+  if (typeof stanza !== "object" || stanza === null) return [];
+  const problems: string[] = [];
+  for (const [key, required] of Object.entries(REQUIRED_FIELDS)) {
+    const entries = (stanza as Record<string, unknown>)[key];
+    if (!Array.isArray(entries)) continue;
+    entries.forEach((entry: unknown, index: number) => {
+      const record = typeof entry === "object" && entry !== null ? (entry as Record<string, unknown>) : {};
+      const missing = required.filter((field) => typeof record[field] !== "string" || record[field] === "");
+      if (missing.length > 0) {
+        const named = typeof record.binding === "string" ? record.binding : `#${index}`;
+        problems.push(`${key}[${named}] is missing ${missing.join(", ")}`);
+      }
+    });
+  }
+  return problems;
+}
+
+/**
+ * Write a capability's provisioned bindings into the project's `wrangler.jsonc`, for one environment.
+ *
+ * Every entry written here is complete by construction — the types demand each field wrangler
+ * requires — and the stanza is checked before the file is written, so a `wrangler.jsonc` this function
+ * touched always loads. Idempotent and comment-preserving.
+ */
+export async function applyAppBindings(projectDir: string, env: string, bindings: AppBindings): Promise<void> {
+  if (!bindings.workflows?.length && !bindings.vectorize?.length) return;
+
+  const config = (await readWranglerConfig(projectDir)) as AppBindingStanza & {
+    env?: Record<string, AppBindingStanza | undefined>;
+  };
+
+  let stanza: AppBindingStanza = config;
+  if (env !== "dev") {
+    config.env ??= {};
+    stanza = config.env[env] ?? {};
+    config.env[env] = stanza;
+  }
+
+  if (bindings.workflows?.length) {
+    stanza.workflows ??= [];
+    upsertByBinding(stanza.workflows, bindings.workflows);
+  }
+  if (bindings.vectorize?.length) {
+    stanza.vectorize ??= [];
+    upsertByBinding(stanza.vectorize, bindings.vectorize);
+  }
+
+  // Never write a config wrangler will not load. A hand-edited entry that lost a field lands here too,
+  // which is the right place to hear about it — before the next deploy.
+  const problems = incompleteBindings(stanza);
+  if (problems.length > 0) {
+    throw new InternalError({
+      message: "wrangler.jsonc would not load with these bindings.",
+      action: `Fix the ${env} bindings in wrangler.jsonc by hand, then re-run provision.`,
+      detail: problems.join("; "),
+    });
+  }
+
+  await writeWranglerConfig(projectDir, config);
+}
+
+/**
+ * The complete `workflows` entries for one capability in one environment, derived from its own
+ * registry. Thin over core's {@link hostWorkflowsFor}, which already computes the deployed Workflow
+ * name from the spec — the app's entry is the host's plus `script_name`, because the class lives in
+ * the host Worker rather than the app's own script.
+ *
+ * Every job the capability owns, which is right when the app dispatches all of them (storage, vector).
+ * A capability whose host self-fires a job the app must never bind — `@pithy-sh/email`'s scheduler —
+ * filters the result against its manifest's `requiredBindings` before writing.
+ *
+ * Takes the same `{ project, capability, env }` object the naming seam does. `project` comes from
+ * `requireProjectName`, never `resolveProjectName`: these two names must match the ones the capability's
+ * provisioner deployed under byte for byte, and a guessed project would write a `script_name` pointing
+ * at a Worker that does not exist — a config that loads and a dispatch that fails at runtime.
+ */
+export function appWorkflowBindings(registry: WorkflowRegistry, parts: WorkflowHostNameParts): AppWorkflowBinding[] {
+  // Through the facade, so the host script is held to a Worker's 63 rather than a Workflow's 64 — the
+  // one-character gap is real, and it is the one that survives an adopter enabling workers.dev.
+  const scriptName = resourceNames(parts.project).env(parts.env).worker(parts.capability);
+  return hostWorkflowsFor(registry, parts).workflows.map((entry) => ({
+    ...entry,
+    script_name: scriptName,
+  }));
+}

package/src/project/appWorkflows.ts

@@ -0,0 +1,266 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import { hostWorkflowsFor } from "@pithy-sh/core/src/workflow/host";
+import { composeWorkflows } from "@pithy-sh/core/src/workflow/register";
+import { stringify } from "comment-json";
+import { incompleteBindings } from "./appBindings";
+import { readWranglerConfig, writeWranglerConfig } from "./wrangler";
+
+/**
+ * Workflows the adopter's **own app capability** declares, reconciled into that Worker's `wrangler.jsonc`.
+ *
+ * A library capability's Workflows already have a path: `pithy <capability> provision` deploys the host
+ * Worker and `project/appBindings.ts` writes the cross-script binding. Nothing did it for the app's own,
+ * so the `workflows` array, `triggers.crons`, and the per-environment repetition of both were hand-written
+ * — each entry having to match the kit's `<project>-<env>-<capability>-<job>` rule and Cloudflare's segment
+ * rule, which `workflowKey` asserts at assembly. A mistake therefore failed at deploy, not at the point of
+ * writing.
+ *
+ * The names come from core's own `hostWorkflowsFor`, so an app-declared job is named by exactly the code
+ * that names a library one. Nothing here formats a name.
+ *
+ * **What still belongs to the adopter: the class.** Cloudflare resolves a `class_name` in the script named
+ * by the binding, so the `WorkflowEntrypoint` subclass has to be exported from the Worker's `main`. That is
+ * five lines written once. The per-environment binding table is not.
+ */
+
+/**
+ * One `workflows` entry for a job the app capability declares. It carries **no `script_name`**: the class
+ * lives in this Worker's own `main`, so the binding is same-script. A library capability's entry does carry
+ * one, and that difference is how {@link reconcileAppWorkflows} tells the two apart in a stanza it did not
+ * write alone.
+ */
+export interface AppOwnedWorkflow {
+  /** The binding name the Worker env exposes, e.g. `KEY_ROTATION`. */
+  binding: string;
+  /** The deployed Workflow name, `<project>-<env>-<capability>-<job>`. */
+  name: string;
+  /** The exported `WorkflowEntrypoint` subclass that runs the job. */
+  class_name: string;
+}
+
+/** What one environment's stanza should say: the app's own `workflows` entries, and the crons that fire them. */
+export interface AppWorkflowPlan {
+  /** Complete entries, one per job the app declares, in declaration order. */
+  workflows: AppOwnedWorkflow[];
+  /** The declared cron schedules, deduplicated. Empty when no job is scheduled. */
+  crons: string[];
+}
+
+/** The identity an app-declared Workflow's name is composed from. */
+export interface AppWorkflowNameParts {
+  /**
+   * The project name — the root `pithy.config.ts` `name`, from `requireProjectName` and never guessed.
+   * Workflow names are account-scoped, so a guessed project deploys under a name another project owns.
+   */
+  project: string;
+  /** The target environment. `dev` is a real environment here: it names the local Workflow too. */
+  env: string;
+}
+
+/**
+ * What one environment's stanza should say, derived from the app capability alone.
+ *
+ * Thin over core's {@link hostWorkflowsFor}, which already refuses a job with no `className` and already
+ * composes the name — the deliberate point being that an app-declared job and a library-declared one get
+ * their names from one function. The host's entries are the app's minus `script_name`, so the extra field
+ * is dropped rather than a second name-composer being written.
+ */
+export function planAppWorkflows(app: Capability, parts: AppWorkflowNameParts): AppWorkflowPlan {
+  const registry = composeWorkflows([app]);
+  const { workflows, crons } = hostWorkflowsFor(registry, {
+    project: parts.project,
+    capability: app.name,
+    env: parts.env,
+  });
+  return {
+    workflows: workflows.map(({ binding, name, class_name }) => ({ binding, name, class_name })),
+    // Two jobs on one schedule are one cron: the Worker has a single `scheduled` handler and it fires
+    // every scheduled job on any tick, so a repeated expression is a duplicated run, not a second job.
+    crons: [...new Set(crons)],
+  };
+}
+
+/** The wrangler slice this module reads and writes. Unknown keys survive untouched — comment-json holds them. */
+export interface WorkflowStanza {
+  workflows?: (AppOwnedWorkflow & { script_name?: string })[];
+  triggers?: { crons?: string[] };
+}
+
+/** The whole config: the top-level stanza (wrangler's default environment) plus each named one. */
+export interface WorkflowConfig extends WorkflowStanza {
+  env?: Record<string, WorkflowStanza | undefined>;
+}
+
+/**
+ * Is this `workflows` entry the app capability's own?
+ *
+ * **One predicate, because the writer and the reader have to mean the same thing by it.** An entry
+ * carrying a `script_name` is a library capability's, written by that capability's provisioner and
+ * pointing at its host Worker. Everything else is same-script, which in this Worker means app-declared —
+ * that is what lets {@link reconcileAppWorkflows} replace the whole set rather than upsert it, and it is
+ * what `project/workflows.ts` reads back to ask whether the stanza binds what the app declares. Two
+ * copies of this rule would be two answers to "whose entry is this?", and drift the check could not see.
+ */
+function isAppOwned(entry: { script_name?: string }): boolean {
+  return entry.script_name === undefined;
+}
+
+/**
+ * The app's own entries in one stanza's `workflows` table — the table {@link reconcileAppWorkflows}
+ * replaces, and the one the doctor and deploy readers compare against the declaration.
+ *
+ * The extra `script_name` field is not carried, because by definition these have none: the shape returned
+ * is exactly {@link planAppWorkflows}'s, so the comparison is between two values of one type.
+ */
+export function appOwnedWorkflows(stanza: WorkflowStanza | undefined): AppOwnedWorkflow[] {
+  return (stanza?.workflows ?? [])
+    .filter(isAppOwned)
+    .map(({ binding, name, class_name }) => ({ binding, name, class_name }));
+}
+
+/** Options for {@link reconcileAppWorkflows}. */
+export interface ReconcileAppWorkflowsOptions {
+  /** The Worker's directory — `apps/<name>`, where its `wrangler.jsonc` lives. */
+  workerDir: string;
+  /** The project name, from `requireProjectName`. */
+  project: string;
+  /** The Worker's own app capability — the one whose `workflows` map is the source of truth. */
+  app: Capability;
+  /** Narrow to one environment. Omitted reconciles the top-level stanza and every `env.<name>` already declared. */
+  env?: string;
+}
+
+/** What one environment's reconciliation did. */
+export interface AppWorkflowRun {
+  /** The environment reconciled — `dev` for the top-level stanza. */
+  env: string;
+  /** The entries its `workflows` table now declares for the app, verbatim as written. */
+  workflows: AppOwnedWorkflow[];
+  /** The cron schedules its `triggers` now carries. */
+  crons: string[];
+  /** Whether anything moved. False on a re-run with nothing to change. */
+  changed: boolean;
+}
+
+/**
+ * The environments a run visits: the one named, else the top-level stanza plus every `env.<name>` the
+ * Worker already declares.
+ *
+ * Deriving the set from the file is the point — the defect was writing the same table once per environment
+ * by hand, so an adopter who adds `prod` later must not have to remember this command's argument list. An
+ * explicit `--env` still creates a stanza that is not there yet, because naming one is asking for it.
+ */
+function environmentsOf(config: WorkflowConfig, env: string | undefined): string[] {
+  if (env !== undefined) return [env];
+  return ["dev", ...Object.keys(config.env ?? {})];
+}
+
+/** The stanza for an environment, created when absent. `dev` is the top-level one — wrangler has no `env.dev`. */
+function stanzaFor(config: WorkflowConfig, env: string): WorkflowStanza {
+  if (env === "dev") return config;
+  config.env ??= {};
+  const existing = config.env[env] ?? {};
+  config.env[env] = existing;
+  return existing;
+}
+
+/**
+ * Replace the app's own entries in one stanza, leaving every provisioned one in place.
+ *
+ * An entry carrying a `script_name` is a library capability's, written by that capability's provisioner and
+ * pointing at its host Worker — untouchable here. Everything else is same-script, which in this Worker means
+ * app-declared, so the whole set is replaced rather than upserted: a job the app renamed or dropped must
+ * leave, and an upsert by binding name would strand it. The provisioned entries keep their positions ahead
+ * of the app's, so a re-run produces a byte-identical file.
+ */
+function replaceOwnWorkflows(stanza: WorkflowStanza, plan: AppWorkflowPlan): void {
+  const provisioned = (stanza.workflows ?? []).filter((entry) => !isAppOwned(entry));
+  const next = [...provisioned, ...plan.workflows];
+  if (stanza.workflows) {
+    // In place: comment-json keeps an array's comments as symbol-keyed properties on the array object,
+    // so a fresh array would silently drop the adopter's notes.
+    stanza.workflows.length = 0;
+    stanza.workflows.push(...next);
+  } else if (next.length > 0) {
+    stanza.workflows = next;
+  }
+}
+
+/**
+ * Set the stanza's cron schedule to what the app declares.
+ *
+ * Set, not merge. `createEntrypoint` gives a Worker one `scheduled` handler that starts **every** job
+ * carrying a schedule, whatever cron fired — so an expression nothing declares is not an extra job, it is
+ * every job running again at a time nobody asked for. The declaration is therefore the whole truth, and a
+ * schedule the adopter changes takes its old value with it.
+ *
+ * **An emptied schedule is written as `[]`, never as a deleted key.** Wrangler reads an absent `crons` as
+ * "not declared" and leaves the deployed Worker's schedule exactly as it was, so deleting the key when the
+ * app drops its last schedule would leave the old cron firing every job that remains — a reconcile that
+ * reports `Done.` and changes nothing where it matters. A stanza that never carried crons is still left
+ * alone, because a `triggers` block a project never had is noise in every config whose jobs all dispatch.
+ */
+function setCrons(stanza: WorkflowStanza, crons: string[]): void {
+  if (crons.length === 0 && stanza.triggers?.crons === undefined) return;
+  stanza.triggers ??= {};
+  stanza.triggers.crons = crons;
+}
+
+/**
+ * Reconcile the app capability's declared Workflows and cron schedule into the Worker's `wrangler.jsonc` —
+ * the seam behind `pithy worker sync`.
+ *
+ * Idempotent, comment-preserving, and all-or-nothing: every environment is computed and checked before the
+ * file is written once, so a stanza wrangler would reject aborts the run rather than leaving half a config
+ * behind. An app that declares no Workflows writes nothing at all — including no empty `workflows` key,
+ * which wrangler reads as a declaration.
+ *
+ * **An app that declares none is still reconciled**, and that is not the same statement. It used to
+ * return before the file was opened, which made "the declaration is the truth" false in the one case
+ * where it matters most: drop the last job from `pithy.config.ts` and the binding and the cron stayed in
+ * `wrangler.jsonc` forever, with no command that would take them out and — since #267 — a doctor fault
+ * naming a command that could not answer it. The empty declaration is a declaration. What it writes is
+ * still nothing at all where there was nothing: `replaceOwnWorkflows` creates no `workflows` key and
+ * `setCrons` creates no `triggers` block, so a project that never had either is byte-identical after.
+ */
+export async function reconcileAppWorkflows(options: ReconcileAppWorkflowsOptions): Promise<AppWorkflowRun[]> {
+  const { workerDir, project, app, env } = options;
+
+  const config = (await readWranglerConfig(workerDir)) as WorkflowConfig;
+  const before = stringify(config);
+
+  const runs: AppWorkflowRun[] = [];
+  for (const target of environmentsOf(config, env)) {
+    const plan = planAppWorkflows(app, { project, env: target });
+    const stanza = stanzaFor(config, target);
+    const stanzaBefore = stringify(stanza);
+
+    replaceOwnWorkflows(stanza, plan);
+    setCrons(stanza, plan.crons);
+
+    // Never write a config wrangler will not load. A hand-edited entry that lost a field lands here too,
+    // which is the right place to hear about it — before the next deploy.
+    const problems = incompleteBindings(stanza);
+    if (problems.length > 0) {
+      throw new InternalError({
+        message: `wrangler.jsonc would not load with the ${target} bindings.`,
+        action: `Fix the ${target} bindings in ${workerDir}/wrangler.jsonc by hand, then run pithy worker sync again.`,
+        detail: problems.join("; "),
+      });
+    }
+
+    runs.push({
+      env: target,
+      workflows: plan.workflows,
+      crons: plan.crons,
+      changed: stringify(stanza) !== stanzaBefore,
+    });
+  }
+
+  if (stringify(config) !== before) await writeWranglerConfig(workerDir, config);
+  return runs;
+}

package/src/project/applyDomains.ts

@@ -0,0 +1,166 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { DOMAIN_ENVIRONMENTS, domainFor, originFor, type WorkerDomains } from "@pithy-sh/core/src/naming/domains";
+import { readWranglerConfig, writeWranglerConfig } from "./wrangler";
+
+/**
+ * Generate a Worker's `routes` and `vars.BASE_URL` from its `domains` declaration.
+ *
+ * One declaration in, two derived wrangler values out, per environment. Nothing is hand-maintained: the
+ * whole point of #89 Part 1 is that an adopter states the address once and everything downstream of it is
+ * computed, so a route and a `BASE_URL` can no longer disagree with each other or with the declaration.
+ *
+ * `BASE_URL` stays a wrangler var rather than moving into the declaration alone, because the **Worker
+ * reads it at runtime** — `@pithy-sh/email` builds tracking and unsubscribe links against it, and the
+ * email Workflow host has it stamped into its own config at provision time. What changed is that it is
+ * derived rather than hand-set.
+ *
+ * ## Per environment, always
+ *
+ * `env.<name>` stanzas **replace** the top level rather than merging with it, so a value written once at
+ * the top would be invisible to staging and prod. That is the same trap `scaffoldProject` handles with
+ * `replaceAll` for `PROJECT`/`WORKER`, and the reason nothing here writes to the top-level stanza: `dev`
+ * has no domain by design.
+ *
+ * ## In place, never replaced
+ *
+ * `comment-json` stores an adopter's comments as symbol-keyed properties on the very array or object they
+ * hang off, so replacing an array deletes their notes. Every mutation here reuses the existing container.
+ */
+
+/** One environment's derived values, for the caller to report. */
+export interface AppliedDomain {
+  /** The environment written. */
+  env: string;
+  /** The hostname the route now points at. */
+  pattern: string;
+  /** The base URL written to `vars.BASE_URL`. */
+  baseUrl: string;
+  /**
+   * Whether this environment's stanza actually changed.
+   *
+   * Carried so a command can say "already in sync" and mean it. The write was always idempotent in bytes;
+   * this makes the *report* idempotent too, which is the difference between a reconcile command an
+   * adopter runs freely and one that appears to do something every time they run it.
+   */
+  changed: boolean;
+}
+
+/** The wrangler shape this writes. Only the keys it owns. */
+interface DomainStanza {
+  routes?: unknown[];
+  route?: unknown;
+  vars?: Record<string, unknown>;
+  workers_dev?: unknown;
+}
+interface DomainWrangler extends DomainStanza {
+  env?: Record<string, DomainStanza | undefined>;
+}
+
+/** A route entry as this generator writes one — a custom domain attached to its zone. */
+interface CustomDomainRoute {
+  pattern?: string;
+  custom_domain?: boolean;
+  zone_name?: string;
+}
+
+/**
+ * Upsert the custom-domain route for one environment, in place.
+ *
+ * Matches on `custom_domain: true` rather than on the pattern, because the pattern is precisely what may
+ * have changed — matching on it would append a second entry for the same Worker every time an adopter
+ * moved their domain, and wrangler would then serve whichever it liked. Any other route entry the adopter
+ * wrote is left exactly where it is: this owns the custom domain, not the route list.
+ */
+function upsertRoute(stanza: DomainStanza, pattern: string, zone: string): void {
+  if (!Array.isArray(stanza.routes)) stanza.routes = [];
+  const routes = stanza.routes;
+  const existing = routes.find(
+    (entry): entry is CustomDomainRoute =>
+      typeof entry === "object" && entry !== null && (entry as CustomDomainRoute).custom_domain === true,
+  );
+  if (existing) {
+    existing.pattern = pattern;
+    existing.zone_name = zone;
+    return;
+  }
+  routes.push({ pattern, custom_domain: true, zone_name: zone });
+}
+
+/**
+ * Turn off `workers.dev` for an environment that now has a custom domain — unless the adopter has
+ * already said what they want.
+ *
+ * **A declared domain is the origin, and `workers.dev` is a second one nothing declared.** Wrangler's
+ * `workers_dev` defaults to `true` and declaring `routes` does not change it, so a Worker with a custom
+ * domain also answers on `<name>.<subdomain>.workers.dev` — and `preview_urls` defaults to whatever
+ * `workers_dev` is, so every deployed version is reachable there too. `vars.BASE_URL` beside it names
+ * only the custom domain, so on that second origin the OAuth callbacks and magic links point elsewhere
+ * and the CSRF same-origin gate refuses the very requests that establish who you are. Reachable, and
+ * broken in exactly that half. Anything bound to the hostname rather than the script — a WAF rule, an
+ * Access policy, a per-hostname rate limit — does not apply there at all.
+ *
+ * **Written only when the key is absent, unlike the route and `BASE_URL` beside it.** Those two are
+ * *derived* from the declaration and are overwritten every run, because a stale one contradicts it.
+ * This is not derived: the declaration makes `false` the right default and does not make it the only
+ * answer. A team that wants the `workers.dev` URL for staging until DNS is cut over writes
+ * `"workers_dev": true`, and that is a named origin rather than an unnamed one — which is the whole
+ * distinction `originDrift` is built on. Overwriting it would delete the sentence they wrote.
+ */
+function closeWorkersDev(stanza: DomainStanza): void {
+  if (typeof stanza.workers_dev === "boolean") return;
+  stanza.workers_dev = false;
+}
+
+/**
+ * Write the declaration into a Worker's `wrangler.jsonc`. Returns what it wrote, per environment.
+ *
+ * Idempotent: a second run changes nothing and writes nothing, and running it after an adopter moved their
+ * domain updates the one route entry rather than appending another. An environment with no declared domain
+ * is left completely alone — never cleared, because an adopter may have written a route by hand and this
+ * must not delete it just because they have not adopted the declaration for that environment.
+ *
+ * **This is the only thing that writes a route, and until #264 the only way to reach it was a prompt.**
+ * Its one caller was `writeDomains`, called only from an interactive `pithy init` or `pithy worker add` —
+ * and `askDomains` returns nothing at all when a session is not interactive. So a `--json` scaffold, a CI
+ * run, and every adopter who added `domains` to a `pithy.config.ts` by hand got a declaration with no route
+ * behind it, and nothing downstream ever noticed. `pithy worker sync` is the second caller, and the
+ * non-interactive one: the declaration goes in the config, the command writes what it implies.
+ */
+export async function applyDomains(workerDir: string, domains: WorkerDomains): Promise<AppliedDomain[]> {
+  const config = (await readWranglerConfig(workerDir)) as DomainWrangler;
+  const applied: AppliedDomain[] = [];
+
+  for (const env of DOMAIN_ENVIRONMENTS) {
+    const domain = domainFor(domains, env);
+    if (!domain) continue;
+
+    // `dev` is never in `DOMAIN_ENVIRONMENTS`, so this only ever reaches an `env.<name>` stanza — which is
+    // also the only place the values would be read from, since env stanzas replace the top level.
+    config.env ??= {};
+    // Structural, before anything is touched. `JSON.stringify` sees none of comment-json's symbol-keyed
+    // comment properties, which is exactly right here: a run that changes no value changed nothing, and
+    // an adopter's comments are not a diff.
+    const before = JSON.stringify(config.env[env] ?? null);
+    config.env[env] ??= {};
+    const stanza = config.env[env];
+
+    upsertRoute(stanza, domain.pattern, domain.zone);
+    stanza.vars ??= {};
+    // Through `originFor`, never `baseUrlFor` directly — the same call an adopter's `pithy.config.ts`
+    // makes to hand a capability its origin (#256). That is what makes "`vars.BASE_URL` and the
+    // capability configs cannot disagree" a property of the code rather than a thing to remember.
+    const baseUrl = originFor(env, domains);
+    stanza.vars.BASE_URL = baseUrl;
+    closeWorkersDev(stanza);
+
+    applied.push({ env, pattern: domain.pattern, baseUrl, changed: before !== JSON.stringify(stanza) });
+  }
+
+  // Nothing changed, nothing written. The bytes were already identical, so the only thing skipping the
+  // write removes is an mtime bump on a file the adopter has open — and the one thing a reconcile command
+  // must never do is look like it edited something it did not.
+  if (applied.some((entry) => entry.changed)) await writeWranglerConfig(workerDir, config);
+  return applied;
+}