@pithy-sh/cli 0.1.0

package/src/dev/delivery.ts

@@ -0,0 +1,174 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import { renderTerminal } from "@pithy-sh/core/src/error/terminal";
+import { resolveCloudflare } from "../cloudflare/config";
+import { projectCloudflareAccount } from "../project/config";
+
+/**
+ * **Real mail from a laptop, and what happens when it cannot be.**
+ *
+ * `pithy dev` runs each composed capability's host Worker, and email's host carries the one binding in
+ * the kit that puts a message on the wire. `remote: true` on that binding runs the Worker locally and
+ * delivers through Cloudflare Email Service for real — the same pipeline, the same DKIM, the same
+ * delivery logs as production — which is what makes a magic link triggered from localhost actually
+ * arrive (pithy-sh/pithy#410).
+ *
+ * That depends on two things the kit does not own: a Cloudflare login `wrangler dev` can use, and a
+ * sending domain already onboarded onto Email Service. The requirement is not that both always hold.
+ * It is that **no path from here ends in silence** — because silence is the defect this whole issue is
+ * about, and a developer waiting on an inbox is the worst possible place to discover a missing login.
+ *
+ * So there are two checks, and they are deliberately different in kind:
+ *
+ * - {@link deliveryPreflight} runs **before anything spawns**, costs nothing, and *decides*. A check
+ *   that runs first is worth more than a message that arrives second: where it can already see that
+ *   real delivery is impossible, the host is resolved with the simulator instead and the banner says
+ *   so once. The session is correct either way.
+ * - {@link deliveryFailureNote} runs over the host's own output and *reports*. The preflight is cheap,
+ *   which is another way of saying it is not the guarantee: a remote binding is established when the
+ *   Worker starts, and a domain that is not onboarded most likely fails there — or at the first send.
+ *   Either shape is caught where it appears and rendered as a `PithyError` with the action that fixes
+ *   it, rather than scrolling past as somebody else's stack trace.
+ *
+ * Neither path kills the session. `pithy dev` supervises Workers; a message that did not send is a
+ * reason for a sentence, not for tearing down every process a developer is working in.
+ */
+
+/**
+ * Whether Cloudflare credentials resolve at all — the cheap half of the delivery preflight.
+ *
+ * No network call and no account probe: it reads the file this project's own account selection points
+ * at, overlaid with the environment, exactly as every other command does. That is enough to catch the
+ * state a developer most often starts in, at none of the cost of asking Cloudflare.
+ *
+ * Here rather than in the dev command because `pithy dev` and `pithy doctor` both ask it, and they must
+ * not come to two answers about one machine.
+ */
+export async function hasCloudflareLogin(projectDir: string, env: NodeJS.ProcessEnv): Promise<boolean> {
+  try {
+    const vars = resolveCloudflare({ account: await projectCloudflareAccount(projectDir), env }).vars;
+    return Boolean(vars.CLOUDFLARE_ACCOUNT_ID && vars.CLOUDFLARE_API_TOKEN);
+  } catch {
+    return false;
+  }
+}
+
+/** What the preflight was asked to check, and what it had to check with. */
+export interface DeliveryPreflightOptions {
+  /** Whether the project composes email at all. Nothing to check when it does not. */
+  composed: boolean;
+  /** The delivery mode the adopter's config selected — `simulator` is a deliberate choice, not a failure. */
+  requested: "remote" | "simulator";
+  /** The from address the capability sends as; its domain is what must be onboarded. */
+  fromAddress?: string;
+  /** Whether Cloudflare credentials resolved at all. `false` means `wrangler dev` has no login to use. */
+  hasCloudflareLogin: boolean;
+}
+
+/** The preflight's answer: what this session will do about delivery, and the lines that say so. */
+export interface DeliveryPreflight {
+  /** Whether the email host is resolved for real delivery. `false` selects the local simulator. */
+  live: boolean;
+  /** Terminal lines — a problem and its action, or the one line that states a deliberate choice. */
+  lines: string[];
+}
+
+/** Domains that cannot be onboarded onto Email Service, so a from address on one can never deliver. */
+const UNDELIVERABLE_DOMAINS = new Set(["example.com", "example.org", "example.net", "localhost", "test", "invalid"]);
+
+/** The domain half of an address, lowercased, or `undefined` when the address has no usable one. */
+function domainOf(address: string | undefined): string | undefined {
+  const at = address?.lastIndexOf("@") ?? -1;
+  if (at < 0 || address === undefined) return undefined;
+  const domain = address
+    .slice(at + 1)
+    .trim()
+    .toLowerCase();
+  return domain === "" ? undefined : domain;
+}
+
+/**
+ * Decide, before anything spawns, whether this session sends real mail — and say why when it does not.
+ *
+ * Cheap by construction: no network call, no account lookup. It reads the credentials that already
+ * resolved and the address the capability is configured to send as. That catches the two states a
+ * developer most often starts a session in — no Cloudflare login at all, and a placeholder from
+ * address nobody has replaced — which is most of the value, at none of the cost of asking Cloudflare.
+ */
+export function deliveryPreflight(options: DeliveryPreflightOptions): DeliveryPreflight {
+  if (!options.composed) return { live: false, lines: [] };
+
+  if (options.requested === "simulator") {
+    return {
+      live: false,
+      lines: ["Email: the simulator, by config. Messages are logged and written to disk, never sent."],
+    };
+  }
+
+  if (!options.hasCloudflareLogin) {
+    return {
+      live: false,
+      lines: [
+        "Email: no Cloudflare credentials, so real delivery is not possible here — using the simulator.",
+        "  run: pithy init, or set CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_API_TOKEN",
+      ],
+    };
+  }
+
+  const domain = domainOf(options.fromAddress);
+  if (domain === undefined || UNDELIVERABLE_DOMAINS.has(domain)) {
+    return {
+      live: false,
+      lines: [
+        `Email: ${options.fromAddress ?? "no from address"} cannot be onboarded onto Email Service — using the simulator.`,
+        "  set email({ fromAddress }) to an address on a domain you have onboarded.",
+      ],
+    };
+  }
+
+  return { live: true, lines: [`Email: sending for real from ${options.fromAddress}.`] };
+}
+
+/**
+ * What the host says when a remote `send_email` binding will not stand up, or a send is rejected.
+ *
+ * Matched narrowly and on purpose. These are wrangler's and Cloudflare's words, not ours, so this is
+ * pattern matching over somebody else's output and the failure mode of being too clever is a false
+ * accusation on an unrelated line. Two shapes only — a binding that could not be established, and a
+ * send refused for an address or domain that is not onboarded — and anything else falls through to
+ * the ordinary tee'd output, where it is at least visible.
+ */
+const DELIVERY_FAILURES: readonly { pattern: RegExp; message: string; action: string }[] = [
+  {
+    pattern: /remote binding.*(send_email|EMAIL)|(send_email|EMAIL).*remote binding/i,
+    message: "The email host's send binding could not be established, so nothing will be delivered.",
+    action: 'Check the Cloudflare login wrangler dev uses, or set email({ devDelivery: "simulator" }).',
+  },
+  {
+    pattern:
+      /(sender|from address|domain).*(not (a )?verified|unverified|not onboarded)|(not (a )?verified|unverified|not onboarded).*(sender|address|domain)/i,
+    message: "Cloudflare Email Service refused the sending address — its domain is not onboarded.",
+    action: 'Onboard the domain onto Email Service, or set email({ devDelivery: "simulator" }).',
+  },
+];
+
+/**
+ * A rendered problem + action block for a host output line that reports a delivery failure, or
+ * `undefined` for every other line. Rendered through `renderTerminal` so it reads exactly like every
+ * other operator-facing failure, rather than being a second error format nobody recognizes.
+ */
+export function deliveryFailureNote(line: string): string | undefined {
+  const match = DELIVERY_FAILURES.find((failure) => failure.pattern.test(line));
+  if (!match) return undefined;
+  return renderTerminal(
+    new PithyError({
+      code: "core/upstream_failed",
+      status: 502,
+      message: match.message,
+      action: match.action,
+      detail: line,
+    }).payload,
+  );
+}

package/src/dev/devLogin.ts

@@ -0,0 +1,155 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { DEV_LOGIN_PATH, DEV_LOGIN_ROUTE, DevLogin } from "@pithy-sh/core/src/seed/devLogin";
+
+/**
+ * The `pithy dev` end of the dev login: say that there is one, and how to use it — **without ever
+ * saying what it is**.
+ *
+ * The banner is still where this belongs, because it is the only place a developer reliably looks and a
+ * seeded session nobody discovers has removed no friction. What changed is what the banner is allowed to
+ * carry. It used to hand over the credential itself:
+ *
+ * ```
+ * document.cookie = "better-auth.session_token=…; path=/; max-age=31535918"
+ * ```
+ *
+ * A working session cookie, rendered as text, on every `pithy dev`. Terminals scroll back, output gets
+ * tee'd and piped, screenshots get pasted into issues — a value printed once is a value at rest in
+ * places nobody chose. `core/src/seed/seed.ts` already treats the login artifact as sensitive for
+ * exactly this reason, so printing it was the one place the rule was suspended by design.
+ *
+ * Now the credential travels over HTTP, from the Worker to the browser, and the terminal carries a
+ * keypress and a URL. Neither is a secret: {@link DEV_LOGIN_ROUTE} is registered only in a `dev`
+ * composition that is not CI, and it hands out only what `pithy seed` already minted on this machine.
+ *
+ * **A cookie value must never appear in a string this module returns.** That is asserted directly, over
+ * every line every function here can produce, rather than trusted to review.
+ */
+
+/** A started worker the dev-login route can be opened on — one that composes auth. */
+export interface DevLoginTarget {
+  /** The worker's name, as `pithy dev` labels it. */
+  name: string;
+  /** Its localhost origin, from the pinned port. */
+  origin: string;
+}
+
+/** What the banner needs to know about the session it is describing. */
+export interface DevLoginBanner {
+  /** Whether a keypress can be offered — a TTY that is not being piped, and not `--json`. */
+  interactive: boolean;
+  /** The started workers that carry the route. Empty is a real answer, and gets its own sentence. */
+  targets: readonly DevLoginTarget[];
+  /**
+   * Whether this run is under CI, where the capability refuses to register the route at all.
+   *
+   * The keypress follows the route. Offering `l` here would be offering a 404, and it is the *only*
+   * refusal `pithy dev` can see coming: every other one is about what is running.
+   */
+  ci: boolean;
+}
+
+/** The one sentence for a run under CI. Stated once, because the banner and the keypress both say it. */
+const CI_REFUSAL = "the dev-login route is not registered under CI.";
+
+/** What pressing `l` should do: open this URL, and say these lines. Either half may be empty. */
+export interface DevLoginKeyAction {
+  /** The URL to open, or `undefined` when there is nothing to open — never a URL that would 404. */
+  url?: string;
+  /** What to print. A refusal always says what to do about it; an open says what it is opening. */
+  lines: string[];
+}
+
+/** Read the seeded dev login, or `undefined` when there is none. Validated — an unreadable file is no login. */
+export async function readDevLogin(projectDir: string): Promise<DevLogin | undefined> {
+  try {
+    const parsed = DevLogin.safeParse(JSON.parse(await readFile(join(projectDir, DEV_LOGIN_PATH), "utf8")));
+    return parsed.success ? parsed.data : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Where a worker serves the dev login. The route is core's, so both ends spell it the same way once. */
+export function devLoginUrl(origin: string): string {
+  return `${origin}${DEV_LOGIN_ROUTE}`;
+}
+
+/**
+ * A usable login, or `undefined`.
+ *
+ * An expired cookie is worse than no cookie: it looks like a way in, fails silently in the browser, and
+ * sends someone hunting for a bug in auth. The banner therefore treats expiry as absence; the keypress
+ * does not, because someone who pressed `l` asked a question and deserves the reason.
+ */
+function usable(login: DevLogin | undefined, now: Date): DevLogin | undefined {
+  if (!login) return undefined;
+  return login.expiresAt.getTime() > now.getTime() ? login : undefined;
+}
+
+/** One indented `name: url` line per target — the shape both the banner and the keypress list choices in. */
+function choices(targets: readonly DevLoginTarget[]): string[] {
+  return targets.map((target) => `  ${target.name}: ${devLoginUrl(target.origin)}`);
+}
+
+/**
+ * The banner lines for a seeded dev login — empty when there is none, and empty when it has expired.
+ *
+ * Four shapes, because the honest sentence differs: a keypress where there is a keypress and one target,
+ * a URL where there is not, the choices where more than one worker composes auth, and a plain statement
+ * where nothing running carries the route at all. Nothing here guesses.
+ */
+export function devLoginLines(login: DevLogin | undefined, now: Date, banner: DevLoginBanner): string[] {
+  const live = usable(login, now);
+  if (!live) return [];
+  if (banner.ci) return [`Dev login: ${live.email} — ${CI_REFUSAL}`];
+  const targets = banner.targets;
+
+  if (targets.length === 0) {
+    return [`Dev login: ${live.email} — no running worker composes auth, so there is nothing to open.`];
+  }
+  if (banner.interactive) {
+    const verb = targets.length === 1 ? "open a signed-in browser" : "choose a worker and open a signed-in browser";
+    return [`Dev login: ${live.email} — press l to ${verb}.`];
+  }
+  const first = targets[0];
+  if (targets.length === 1 && first) {
+    return [`Dev login: ${live.email} — open ${devLoginUrl(first.origin)} to sign in.`];
+  }
+  return [`Dev login: ${live.email} — open one of these to sign in.`, ...choices(targets)];
+}
+
+/**
+ * What `l` does, decided without touching the terminal or the network so it can be tested as a value.
+ *
+ * Every refusal names the command that fixes it and opens nothing. A browser sent to a route that 404s
+ * is worse than a sentence: it looks like the feature is broken rather than like the session is missing.
+ */
+export function devLoginKeyAction(
+  login: DevLogin | undefined,
+  now: Date,
+  targets: readonly DevLoginTarget[],
+  ci = false,
+): DevLoginKeyAction {
+  if (!login) return { lines: ["No dev login is seeded. Run pithy seed, then press l again."] };
+  if (!usable(login, now)) {
+    return { lines: ["The seeded dev login has expired. Run pithy seed to mint a fresh one."] };
+  }
+  // Before the targets, because this refusal is about the route rather than about what is running: the
+  // workers below all compose auth and none of them mounted it.
+  if (ci) return { lines: [`Not opening — ${CI_REFUSAL}`] };
+  if (targets.length === 0) return { lines: ["No running worker composes auth, so there is nothing to open."] };
+
+  const first = targets[0];
+  if (targets.length === 1 && first) {
+    const url = devLoginUrl(first.origin);
+    return { url, lines: [`Opening ${url} as ${login.email}.`] };
+  }
+  // More than one worker carries the route, and they are separate origins — a cookie set on one signs
+  // nobody into the other. There is no defensible guess, so the choice is printed.
+  return { lines: ["More than one worker composes auth. Open the one you want:", ...choices(targets)] };
+}

package/src/dev/devLoginTargets.ts

@@ -0,0 +1,91 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { allCapabilities, loadWorkerConfig } from "../project/config";
+import { parseWorkerManifest } from "../project/workerManifest";
+import type { DevLoginTarget } from "./devLogin";
+
+/**
+ * Which running worker `l` opens, in a project that runs more than one.
+ *
+ * **The rule is "the worker that carries the route", not "the worker with the UI"** — and the reason is
+ * the cookie, not preference. `Set-Cookie` is scoped to the origin that sent it, and every worker in a
+ * dev session is a different `localhost:<port>`. Opening a worker that does not compose auth would 404
+ * on {@link DEV_LOGIN_ROUTE}; opening one that does, and then browsing to a *different* worker, leaves
+ * the browser signed out on the second origin. So the candidate set is exactly the workers that compose
+ * auth, which is a fact read off each worker's own `pithy.config.ts` rather than guessed.
+ *
+ * **The UI block breaks a tie, and only a tie.** `pithy ui add` records `ui` in `pithy.worker.jsonc`,
+ * and in the ordinary Pithy project that block sits on the same worker that serves the API — one origin,
+ * one cookie, one thing to look at. Where two workers both compose auth and one of them is the one with
+ * a front end, that is the one a developer meant. Where the signal does not decide — neither carries a
+ * UI, or both do — nothing is narrowed and the caller prints the choices. A silent guess between two
+ * origins is the failure this avoids: it looks like the feature worked, and the browser is signed in to
+ * the wrong one.
+ *
+ * Both probes are non-fatal. A worker whose `pithy.config.ts` will not import composes nothing as far as
+ * this is concerned; wrangler reports that file's failure, loudly, and inventing a second complaint here
+ * would only bury it.
+ */
+
+/** A started worker, as this module needs it: its label, its directory, and where it answers. */
+export interface StartedWorkerDir {
+  name: string;
+  /** The `apps/<name>/` directory holding its `pithy.config.ts` and `pithy.worker.jsonc`. */
+  dir: string;
+  origin: string;
+}
+
+/** Everything {@link devLoginTargets} needs. Both probes default to reading the worker's own files. */
+export interface DevLoginTargetOptions {
+  started: readonly StartedWorkerDir[];
+  /** Does this worker compose the auth capability, and therefore carry the route? */
+  composesAuth?: (dir: string) => Promise<boolean>;
+  /** Does this worker carry a front end (`ui` in its `pithy.worker.jsonc`)? Breaks a tie, nothing more. */
+  hasUi?: (dir: string) => Promise<boolean>;
+}
+
+/** Whether a worker's own config composes auth. A config that will not load composes nothing. */
+async function composesAuthDefault(dir: string): Promise<boolean> {
+  try {
+    return allCapabilities(await loadWorkerConfig(dir)).some((capability) => capability.name === "auth");
+  } catch {
+    return false;
+  }
+}
+
+/** Whether a worker carries a front end. The `ui` block's presence *is* the signal (see `ui/workerUi.ts`). */
+async function hasUiDefault(dir: string): Promise<boolean> {
+  try {
+    return (await parseWorkerManifest(dir))?.ui !== undefined;
+  } catch {
+    return false;
+  }
+}
+
+/** Run a predicate over every started worker, keeping the started order. */
+async function keep(
+  workers: readonly StartedWorkerDir[],
+  predicate: (dir: string) => Promise<boolean>,
+): Promise<StartedWorkerDir[]> {
+  const verdicts = await Promise.all(
+    workers.map(async (worker) => {
+      try {
+        return await predicate(worker.dir);
+      } catch {
+        return false;
+      }
+    }),
+  );
+  return workers.filter((_worker, index) => verdicts[index] === true);
+}
+
+/** The workers `l` may open, in started order — one to open, several to choose from, or none. */
+export async function devLoginTargets(options: DevLoginTargetOptions): Promise<DevLoginTarget[]> {
+  const carriers = await keep(options.started, options.composesAuth ?? composesAuthDefault);
+  if (carriers.length <= 1) return carriers.map(({ name, origin }) => ({ name, origin }));
+
+  const withUi = await keep(carriers, options.hasUi ?? hasUiDefault);
+  const chosen = withUi.length === 1 ? withUi : carriers;
+  return chosen.map(({ name, origin }) => ({ name, origin }));
+}

package/src/dev/env.ts

@@ -0,0 +1,206 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { CI_ENV, isContinuousIntegration } from "@pithy-sh/core/src/env/ci";
+import { envStem } from "@pithy-sh/core/src/env/stem";
+import { WORKER_ORIGIN_VAR } from "@pithy-sh/core/src/worker/identity";
+import type { DevConfig } from "../feature/devConfig";
+import { DEV_PORT_TOKEN } from "../project/workerManifest";
+import type { WorkerTarget } from "../project/workers";
+
+/**
+ * Build the environment every child inherits: the parent env plus, for **every** worker in the feature's
+ * dev config, `<STEM>_PORT` and `<STEM>_ORIGIN`. That is how workers reach each other — each sibling's
+ * localhost address is known ahead of time and injected, so a worker calls its peers directly instead of
+ * relying on wrangler's flaky cross-`wrangler dev` service registry.
+ */
+export function buildWorkerEnv(config: DevConfig, base: NodeJS.ProcessEnv = process.env): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const [key, value] of Object.entries(base)) {
+    if (value !== undefined) env[key] = value;
+  }
+  for (const [name, worker] of Object.entries(config.workers)) {
+    const stem = envStem(name);
+    env[`${stem}_PORT`] = String(worker.port);
+    env[`${stem}_ORIGIN`] = worker.origin;
+  }
+  return env;
+}
+
+/**
+ * The origin to hand one worker as its own, or `null` when somebody else owns it.
+ *
+ * `null` is a capability host: its `BASE_URL` is the *app's* origin, because it holds no public route
+ * and a verification link it mails has to arrive back at the app. `materializeHostConfigs` writes that
+ * into the host's generated config, so a value from here could only be a second producer of one
+ * setting — and the one it would produce is the wrong one.
+ *
+ * One function rather than a condition repeated at each carrier, so a host cannot be exempt from the
+ * argv path and not from the environment path.
+ */
+export function ownOriginFor(workerName: string, origin: string, hostNames: ReadonlySet<string>): string | null {
+  return hostNames.has(workerName) ? null : origin;
+}
+
+/**
+ * One child's environment: everything {@link buildWorkerEnv} publishes, plus that child's own origin.
+ *
+ * Per child, and that is the point. `buildWorkerEnv` is built once and shared, because `<STEM>_ORIGIN`
+ * is the same table of *other people's* addresses for everybody. "Where do I answer" is the one fact
+ * that differs per child, so it cannot live in the shared object.
+ */
+export function childEnvFor(shared: Record<string, string>, ownOrigin: string | null): Record<string, string> {
+  if (ownOrigin === null) return shared;
+  return { ...shared, [WORKER_ORIGIN_VAR]: ownOrigin };
+}
+
+/** Turn `["dev", "--port", "8787"]` into a spawnable `{ command, args }` via the project's package manager. */
+export type WranglerLauncher = (args: string[]) => { command: string; args: string[] };
+
+/** A resolved start command for one worker. */
+export interface StartCommand {
+  command: string;
+  args: string[];
+}
+
+/**
+ * The command that starts one worker at its pinned `port`.
+ *
+ * A worker with an explicit `dev.command` (e.g. a Vite frontend with no `wrangler.jsonc`) runs that verbatim
+ * — the port is **not** appended; it reaches the process through `<STEM>_PORT` in the env, or through the
+ * `{port}` token wherever the manifest placed it on the argv. That token is the one substitution, and it
+ * exists because the orchestrator spawns with no shell: `$WEB_PORT` in an argv array is a literal, never an
+ * expansion, and a dev server that takes its port as a flag (`vite dev --port {port}`) has nowhere else to
+ * read it. A command with no token runs byte-identically. A plain Worker runs `wrangler dev --port <port>
+ * --inspector-port 0` (inspector `0` auto-assigns, so multiple workers never collide on the inspector port),
+ * resolved through the project's package manager rather than a hardcoded global wrangler.
+ *
+ * **`--persist-to` is what makes local sharing real.** Every Worker lives in its own `apps/<name>/` and
+ * wrangler defaults its local state to the *cwd* it runs in, so each Worker would get its own `.wrangler/`
+ * store — and two Workers that deliberately declare the same binding (the way Workers share a database)
+ * would silently read and write two different local D1s, with the divergence showing up only as
+ * inexplicably missing rows. Pointing every Worker at one project-level store makes local behave the way
+ * the deployed environment does.
+ */
+export function startCommand(
+  worker: WorkerTarget,
+  port: number,
+  origin: string | null,
+  launchWrangler: WranglerLauncher,
+  persistTo: string,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+  hostPorts: Readonly<Record<string, number>> = {},
+): StartCommand {
+  const custom = worker.dev?.command;
+  if (custom && custom.length > 0) {
+    // A custom command is run verbatim: it is not necessarily wrangler, so no flag is appended. The only
+    // edit is `{port}` → the pinned port, in every element that carries it. It also gets no `--var`: the
+    // process already inherits the real environment through `buildWorkerEnv`, which is exactly what the
+    // forwarding below exists to work around for workerd.
+    const resolved = custom.map((part) => part.replaceAll(DEV_PORT_TOKEN, String(port)));
+    return { command: resolved[0] as string, args: resolved.slice(1) };
+  }
+  return launchWrangler([
+    "dev",
+    "--port",
+    String(port),
+    "--inspector-port",
+    "0",
+    "--persist-to",
+    persistTo,
+    ...ownOriginVarArgs(origin),
+    ...ciVarArgs(baseEnv),
+    ...hostVarArgs(worker.name, hostPorts),
+  ]);
+}
+
+/**
+ * Tell the Worker where it itself answers, as `BASE_URL`.
+ *
+ * **The one address a Worker cannot work out and cannot be made to write down.** It cannot derive it
+ * from a request: `Host` is caller-controlled, so a Worker that did would take its own identity from
+ * whoever called it. And it cannot state it in `wrangler.jsonc`, because a dev port is *allocated* —
+ * every checkout reserves its own block, so a literal there is right in the first checkout on a machine
+ * and wrong in every other one. `pithy dev` is the only party that knows, and this is where it says so.
+ *
+ * `--var` beats a `vars` entry in the config, so a project that already wrote a dev `BASE_URL` down is
+ * corrected rather than asked to edit anything. Deployed environments never reach here: `applyDomains`
+ * generates theirs from the `domains` declaration, and this runs only under `pithy dev`.
+ *
+ * **Note what this is not.** {@link hostVarArgs} deliberately withholds a host's own `<STEM>_ORIGIN`,
+ * because that var names a *dispatch target* and a Worker posting to itself is a request that answers
+ * itself forever. `BASE_URL` is the opposite kind of fact — it is an identity, the `iss` a
+ * control-plane token carries and the origin a callback link is built against — and withholding it is
+ * what made `pithy-sh/dashboard#95`: a second checkout signed tokens as the first one and its own seam
+ * denied every call. The two vars look alike and mean opposite things.
+ *
+ * The origin travels **verbatim** from `.dev.config.json` rather than being rebuilt as
+ * `http://localhost:${port}`. The config pins both, and recomposing one from the other is a second
+ * producer of a value that is already written down — the same rule `SeedPrepareContext.origin` states.
+ *
+ * **`null` means somebody else owns this Worker's `BASE_URL`, and today that is a capability host.**
+ * A host's is the *app's* origin, not its own: it holds no public route, and a callback link it mails
+ * has to arrive back at the app. `materializeHostConfigs` writes that value into the host's generated
+ * `wrangler.jsonc`, from the same allocation, so a `--var` here could only be a second producer of one
+ * value — and the one it would produce is the wrong one. Overriding it would point every verification
+ * link at the email host.
+ */
+function ownOriginVarArgs(origin: string | null): string[] {
+  if (origin === null) return [];
+  // wrangler splits a `--var` at its first colon, so the `http://` in the value survives intact.
+  return ["--var", `BASE_URL:${origin}`];
+}
+
+/**
+ * Forward each capability host's address into the Worker as vars.
+ *
+ * Same reason as {@link ciVarArgs}, and the same mechanism: `buildWorkerEnv` publishes
+ * `<STEM>_ORIGIN` and `<STEM>_PORT` into every child *process*, and the host environment does not
+ * cross into workerd. So an app Worker asking for `EMAIL_ORIGIN` — the address core's loopback
+ * dispatcher posts a Workflow dispatch to, in place of the cross-script binding a deployed
+ * environment has — would read nothing at all. One `--var` per host is what makes the read truthful.
+ *
+ * Only the hosts, not every sibling. An `apps/*` Worker reaches another over `<STEM>_ORIGIN` in the
+ * *process* env today, and widening this to all of them is a change to what every Worker sees rather
+ * than the one wire this issue is about (pithy-sh/pithy#410).
+ *
+ * A host is never handed its own address: it *is* the thing at that origin, and a self-dispatch
+ * loop is a request that answers itself forever.
+ *
+ * **That is a rule about dispatch targets, not about self-knowledge.** A Worker does learn where it
+ * itself answers — see {@link ownOriginVarArgs}, which hands it exactly that as `BASE_URL`. The two
+ * vars are adjacent, look alike, and mean opposite things: `<STEM>_ORIGIN` is somewhere to send a
+ * request, `BASE_URL` is who you are. Reading the paragraph above as "a Worker never learns its own
+ * origin" is what left every checkout but the first signing tokens as another one (#462).
+ */
+function hostVarArgs(workerName: string, hostPorts: Readonly<Record<string, number>>): string[] {
+  const args: string[] = [];
+  for (const [name, port] of Object.entries(hostPorts)) {
+    if (name === workerName) continue;
+    const stem = envStem(name);
+    // wrangler splits a `--var` at its first colon, so the `http://` in the value survives intact.
+    args.push("--var", `${stem}_ORIGIN:http://localhost:${port}`, "--var", `${stem}_PORT:${port}`);
+  }
+  return args;
+}
+
+/**
+ * Forward `CI` into the Worker as a var, when this process is running under one.
+ *
+ * **The host's environment does not cross into workerd.** With `nodejs_compat`, `process.env` inside a
+ * Worker is populated from that script's own `vars` and secrets and nothing else — verified against a
+ * real `wrangler dev`, where `Object.keys(process.env)` at module scope is exactly the declared vars. So
+ * a capability that refuses to register itself under CI (`@pithy-sh/auth`'s dev-login route is the first)
+ * cannot see the `CI=true` that GitHub Actions set in the shell that ran this command. One `--var` is
+ * what makes that read truthful for every Worker Pithy starts.
+ *
+ * Nothing is forwarded off CI, so an ordinary `pithy dev` writes no var and the Worker's `process.env` is
+ * byte-identical to what it was. And the forwarding is a convenience, never the security boundary: the
+ * capability's environment gate refuses in `staging` and `prod` with no cooperation from anything here.
+ */
+function ciVarArgs(env: NodeJS.ProcessEnv): string[] {
+  if (!isContinuousIntegration(env)) return [];
+  // The value travels verbatim rather than normalized to `true`: "any non-blank value" is the rule at
+  // both ends (#218), and rewriting it here would be this file inventing a second one.
+  return ["--var", `${CI_ENV}:${env[CI_ENV] ?? ""}`];
+}