@pithy-sh/cli 0.1.0

package/src/doctor/environments.ts

@@ -0,0 +1,155 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { basename } from "node:path";
+import { loadProject, loadProjectEnvironments } from "../project/config";
+import { discoverWorkers, type WorkerTarget } from "../project/workers";
+import { readWranglerConfig } from "../project/wrangler";
+
+/**
+ * **Does every Worker still declare the environments this project says it has?** (#241)
+ *
+ * The root `pithy.config.ts` declares the set; each Worker's `wrangler.jsonc` records which of them it has
+ * a stanza for. Before the declaration existed there was nothing to compare a stanza to — two Workers in
+ * one project could declare different environments and nothing reconciled them, and a project could
+ * acquire `env.live` that `pithy secrets provision` would never give a master key.
+ *
+ * Two different faults live here, and they are worth telling apart because the remedies are opposite:
+ *
+ * - **A disagreement.** A Worker declares an environment the project does not, or is missing one it does.
+ *   Nothing has been provisioned under it; the fix is an edit to one file or the other.
+ * - **An orphan.** The same undeclared stanza, but carrying **resource ids** — so resources were created
+ *   under a name this project no longer claims. That is a declaration changed *after* provisioning, and
+ *   the answer is never "apply it": `<project>-<env>-<thing>` is recomputed, never stored, so renaming an
+ *   environment does not rename a database. It orphans it, exactly as renaming `name` does. This reports
+ *   it and stops.
+ *
+ * **Files only.** No account call, so it answers offline, in the project that is not working — and its
+ * verdict is established by this repo contradicting itself, which is the standard `doctorExitCode` holds
+ * a gating check to.
+ */
+
+/** What this check established. Listed positively, so an inconclusive read never gates CI. */
+export type EnvironmentsState =
+  /** Every Worker's stanzas are exactly the declared set. */
+  | "ok"
+  /** A `wrangler.jsonc` would not parse, the root config would not load, or the worker set would not enumerate. */
+  | "could-not-check"
+  /** A Worker's stanzas and the declaration contradict each other. Established from local files alone. */
+  | "drifted";
+
+/** One Worker-and-environment disagreement. */
+export interface EnvironmentDrift {
+  /** The Worker's `apps/<name>` directory. */
+  worker: string;
+  /** The environment the stanza names, or the declared one that has no stanza. */
+  env: string;
+  /** Which of the three faults this is. */
+  kind: "undeclared" | "orphaned" | "missing";
+  /** The resource ids found under an orphaned environment — the evidence, never a secret. */
+  resources: string[];
+}
+
+/** What `doctor` learned about this project's environments. */
+export interface EnvironmentsCheck {
+  state: EnvironmentsState;
+  /** The declared set, in declaration order — so the report says what it compared against. */
+  declared: string[];
+  drift: EnvironmentDrift[];
+}
+
+/** The `wrangler.jsonc` keys this reads: the environment stanzas and the binding ids inside them. */
+interface StanzaBindings {
+  d1_databases?: { binding?: string; database_id?: string }[];
+  kv_namespaces?: { binding?: string; id?: string }[];
+  r2_buckets?: { binding?: string; bucket_name?: string }[];
+  vectorize?: { binding?: string; index_name?: string }[];
+  env?: Record<string, StanzaBindings | undefined>;
+}
+
+/**
+ * The provisioned resources one stanza names — the evidence that separates "a stanza nobody deleted" from
+ * "resources nobody can find any more".
+ *
+ * An id, never a value: these are Cloudflare identifiers an adopter's `wrangler.jsonc` already commits, so
+ * naming them in a report costs nothing and is the only way the line is actionable. A binding with no id is
+ * deliberately not counted — that is the not-yet-provisioned shape #241 asks `doctor` to read as *not
+ * provisioned* rather than as broken.
+ */
+function provisionedResources(stanza: StanzaBindings): string[] {
+  const found: string[] = [];
+  for (const entry of stanza.d1_databases ?? []) if (entry.database_id) found.push(`d1 ${entry.database_id}`);
+  for (const entry of stanza.kv_namespaces ?? []) if (entry.id) found.push(`kv ${entry.id}`);
+  for (const entry of stanza.r2_buckets ?? []) if (entry.bucket_name) found.push(`r2 ${entry.bucket_name}`);
+  for (const entry of stanza.vectorize ?? []) if (entry.index_name) found.push(`vectorize ${entry.index_name}`);
+  return found;
+}
+
+/** The declared environment set, or `null` when the root config would not read or would not validate. */
+async function declaredEnvironments(projectDir: string): Promise<string[] | null> {
+  try {
+    return [...loadProjectEnvironments(await loadProject(projectDir))];
+  } catch {
+    // `checkProjectName` and the `Project:` block already own "the config would not load". A second block
+    // reporting it is how a report starts contradicting itself.
+    return null;
+  }
+}
+
+/** Compare every Worker's `env.<name>` stanzas against the project's declaration. */
+export async function checkEnvironments(projectDir: string): Promise<EnvironmentsCheck> {
+  const declared = await declaredEnvironments(projectDir);
+  if (declared === null) return { state: "could-not-check", declared: [], drift: [] };
+
+  let workers: WorkerTarget[];
+  try {
+    workers = await discoverWorkers(projectDir);
+  } catch {
+    return { state: "could-not-check", declared, drift: [] };
+  }
+
+  const drift: EnvironmentDrift[] = [];
+  let unreadable = false;
+  for (const target of workers) {
+    // A process in the dev set with no `wrangler.jsonc` — a Vite frontend — declares no environments at
+    // all, which is not a disagreement with anything.
+    if (!target.hasWrangler) continue;
+    let config: StanzaBindings;
+    try {
+      config = (await readWranglerConfig(target.dir)) as StanzaBindings;
+    } catch {
+      unreadable = true;
+      continue;
+    }
+    const worker = basename(target.dir);
+    const stanzas = Object.entries(config.env ?? {});
+    for (const [env, stanza] of stanzas) {
+      if (declared.includes(env)) continue;
+      const resources = stanza ? provisionedResources(stanza) : [];
+      drift.push({ worker, env, kind: resources.length > 0 ? "orphaned" : "undeclared", resources });
+    }
+    for (const env of declared) {
+      if (stanzas.some(([name]) => name === env)) continue;
+      drift.push({ worker, env, kind: "missing", resources: [] });
+    }
+  }
+
+  if (drift.length > 0) return { state: "drifted", declared, drift };
+  return { state: unreadable ? "could-not-check" : "ok", declared, drift: [] };
+}
+
+/**
+ * One drift, as the sentence that fits it. Three faults, three remedies — and the orphan's remedy is
+ * deliberately not "change it back and carry on": the resources are still there under the old name, and
+ * only the adopter can say whether to adopt them or delete them.
+ */
+export function describeEnvironmentDrift(drift: EnvironmentDrift, declared: string[]): string {
+  const set = declared.join(", ");
+  if (drift.kind === "missing") {
+    return `pithy.config.ts declares ${drift.env}, and this Worker has no env.${drift.env} stanza. Add one, or drop ${drift.env} from environments.`;
+  }
+  if (drift.kind === "undeclared") {
+    return `env.${drift.env} is a stanza pithy.config.ts does not declare (${set}). Add ${drift.env} to environments, or remove the stanza.`;
+  }
+  return `env.${drift.env} holds provisioned resources and pithy.config.ts no longer declares it (${set}). Renaming an environment does not rename what it provisioned — those resources are orphaned. Restore ${drift.env} to environments, or delete them in Cloudflare and remove the stanza.`;
+}

package/src/doctor/health.ts

@@ -0,0 +1,354 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
+import { type AvailableManifests, availableManifests, type ManifestFault } from "../capabilities/manifests";
+import type { MissingPrerequisite } from "../capabilities/prerequisites";
+import {
+  type BindingDeclines,
+  type BuildReconcilePlanOptions,
+  buildReconcilePlan,
+  type EntitlementGap,
+  type ReadLedger,
+  type ReconcilePlan,
+} from "../capabilities/reconcile";
+import type { CloudflareAccountSelection } from "../cloudflare/config";
+import type { ProjectLedger, readProjectLedger } from "../migrations/run";
+import type { WorkerConfig } from "../project/config";
+
+/**
+ * The read-only project-health engine behind `pithy doctor`'s `Project health` block — the *same*
+ * {@link buildReconcilePlan} `pithy upgrade` runs, rendered without writing (one engine, two commands).
+ * `upgrade` fixes the drift this reports; `doctor` only surfaces it and drives a non-zero exit so CI can
+ * gate on a project whose wiring has fallen out of sync with its installed capabilities.
+ *
+ * Health is **per Worker**, because the wiring is: each Worker under `apps/` has its own `pithy.config.ts`
+ * and `wrangler.jsonc`, so each drifts independently. One unhealthy Worker makes the project unhealthy.
+ */
+
+/** The `config` check: capabilities whose `pithy.config.ts` registration is missing manifest options. */
+export interface ConfigHealth {
+  ok: boolean;
+  /** Per drifting capability: the option keys not yet written into its registration. */
+  drift: { capability: string; keys: string[] }[];
+}
+
+/**
+ * The `bindings` check: required bindings absent from `wrangler.jsonc`, each with the envs that lack it —
+ * **and the Durable Object classes the Worker's entry does not export.**
+ *
+ * One check, because a Durable Object is one binding written in two files. The `durable_objects.bindings`
+ * entry names a `class_name` and wrangler resolves that name against the module `main` names; a Worker
+ * carrying the first and not the second is refused at deploy. Reporting only the half that lives in
+ * `wrangler.jsonc` is what let `doctor` call a project healthy that `wrangler deploy` would not take
+ * (#428).
+ */
+export interface BindingHealth {
+  ok: boolean;
+  missing: { name: string; type: string; envs: string[] }[];
+  /** Durable Object classes bound in `wrangler.jsonc` that this Worker's entry does not export. */
+  missingExports: string[];
+  /**
+   * Optional bindings this Worker's `pithy.config.ts` declines, resolved against what it composes.
+   *
+   * Taken from the plan **by reference**, never re-projected: `groupMissingBindings` below constructs a
+   * fresh object per binding, and a field that had to survive that construction is a field the two
+   * commands would eventually disagree about — which is #440 itself, one level up.
+   *
+   * An honored decline does not fail `ok`. A decline that cannot be honored does, because it means
+   * the adopter believes a binding is being left out that is not.
+   */
+  declinedBindings: BindingDeclines;
+}
+
+/**
+ * The `migrations` check: the target environment's ledger against what this Worker declares — **both
+ * directions**.
+ *
+ * `pending` alone passed a database `pithy migrate` refused to touch. An extra applied migration is
+ * invisible to declared-minus-applied: nothing is missing, so nothing is pending, so the check was
+ * green while the migrator read the same ledger as a corrupted chain and applied nothing (#282). Each
+ * half fails the check on its own, because either one means the schema is not where the project says.
+ */
+export interface MigrationHealth {
+  ok: boolean;
+  /**
+   * The environment's ledger, exactly as {@link readProjectLedger} answered it — the counts behind their
+   * discriminant rather than flattened onto this object (#371).
+   *
+   * Flattening was the fault. A database that could not be read contributed nothing to `pending`, so a
+   * project whose D1 was unreachable read as `0 pending` — the same two fields a healthy project has, and
+   * a green line about a schema nobody had compared.
+   */
+  ledger: ProjectLedger;
+  env: string;
+}
+
+/**
+ * The `entitlements` check: routes gated on an entitlement with no capability composed to resolve one.
+ * The seam fails closed, so this Worker would deny every gated route in production and look, to the
+ * runtime, exactly like a project full of unentitled users. Unlike the other three checks, `pithy upgrade`
+ * cannot fix it — which capability to compose is the adopter's decision, so this only ever reports.
+ */
+export interface EntitlementHealth {
+  ok: boolean;
+  /**
+   * The scan's answer, exactly as the plan carried it (#371) — the file list behind its discriminant.
+   *
+   * A flat `gates: []` said "no gap" and "no scan" in the same two characters, and only one of those is
+   * good news.
+   */
+  gap: EntitlementGap;
+}
+
+/**
+ * The `prerequisites` check: a composed capability whose manifest declares a peer this Worker does not
+ * compose.
+ *
+ * **The only check here that is a boot failure rather than drift.** `createBackend` refuses to assemble
+ * on exactly this pair, so the Worker does not start at all — which is what `pithy add auth` used to
+ * leave behind, on a project this command called healthy (#273). It reports and does not fix, like the
+ * entitlement gap: `pithy upgrade` writes bindings and config keys, and composing a capability is a
+ * different kind of decision. The line names the command that makes it.
+ */
+export interface PrerequisiteHealth {
+  ok: boolean;
+  /** Each composed capability paired with the peer it declares and this Worker lacks. */
+  missing: MissingPrerequisite[];
+}
+
+/** One Worker's five checks, when the plan behind them was built. `ok` is their AND. */
+export interface WorkerChecks {
+  config: ConfigHealth;
+  bindings: BindingHealth;
+  migrations: MigrationHealth;
+  entitlements: EntitlementHealth;
+  prerequisites: PrerequisiteHealth;
+}
+
+/**
+ * One Worker's health — **or that this Worker could not be checked at all (#371)**.
+ *
+ * The plan behind a Worker's five checks reads that Worker's own `pithy.config.ts` and `wrangler.jsonc`
+ * and, through the ledger, its databases. Any of that can fail for reasons that belong to one Worker: a
+ * config that will not import, a stanza that will not parse. It used to throw out of the loop, and one
+ * Worker in that state erased every *other* Worker's config, bindings, migrations, entitlement and
+ * prerequisite lines — from the command whose whole job is to say which part of a project is broken.
+ *
+ * **The state rides on the value**, so an unchecked Worker cannot be rendered as a checked one. The five
+ * checks live behind `checked`, and `unavailable` carries nothing but the Worker's name: a Worker with no
+ * `ok`, no empty drift lists and no `0 pending` to mistake for a clean bill.
+ *
+ * This is the same treatment the *manifest* half of {@link buildProjectHealth} got under #184. It was
+ * applied to one loop in this file and not the other.
+ */
+export type WorkerHealth =
+  | ({
+      /** The plan was built and every check ran. */
+      state: "checked";
+      /** The Worker's name, as `pithy worker list` shows it. */
+      worker: string;
+      /** The AND of the five checks below. */
+      ok: boolean;
+    } & WorkerChecks)
+  | {
+      /** The plan could not be built, so nothing is known about this Worker. */
+      state: "unavailable";
+      /** The Worker's name, as `pithy worker list` shows it. */
+      worker: string;
+    };
+
+/**
+ * The `manifests` check: installed packages whose `pithy.manifest.json` is present and unusable.
+ *
+ * Project-wide rather than per Worker, because manifests resolve once from the project root. It fails the
+ * doctor exit for the same reason the others do: a capability nobody can read is a capability every check
+ * below silently leaves out, and `doctor` reporting a healthy project around that hole is what #184 was
+ * reported about. `pithy upgrade` cannot fix it — the manifest belongs to someone else's package.
+ */
+export interface ManifestHealth {
+  ok: boolean;
+  faults: ManifestFault[];
+}
+
+/** The whole project's health: one entry per Worker, plus the project-wide manifest read. `ok` is the AND. */
+export interface ProjectHealth {
+  ok: boolean;
+  workers: WorkerHealth[];
+  manifests: ManifestHealth;
+}
+
+/** The manifest-scan seam: defaults to {@link availableManifests}, the scan every capability command reads. */
+export type ReadManifests = (projectDir: string) => Promise<AvailableManifests>;
+
+/** The plan-builder seam: defaults to {@link buildReconcilePlan}, the engine `upgrade` shares. */
+export type BuildPlan = (options: BuildReconcilePlanOptions) => Promise<ReconcilePlan>;
+
+/** The shared engine, exported so a test can assert doctor and upgrade use one implementation. */
+export const defaultBuildPlan: BuildPlan = buildReconcilePlan;
+
+/** The minimum a health check needs to know about a Worker — what `resolveWorkers` already returns. */
+export interface HealthWorker {
+  /** The Worker's name. */
+  name: string;
+  /** The Worker's directory (`apps/<name>/`) — the config and wrangler stanzas the plan reads. */
+  dir: string;
+  /** That Worker's composed capabilities, forwarded to the plan for its migration count. */
+  capabilities?: Capability[];
+  /**
+   * That Worker's own `pithy.config.ts`, as `resolveWorkers` already returns it. The plan reads
+   * `declinedBindings` off it — the whole object, because the reader also refuses a key that is nearly
+   * that one and can only see one if it is handed what the adopter wrote. Optional because the
+   * resolver is a test seam: a double with no config is a Worker that declines nothing.
+   */
+  config?: WorkerConfig;
+}
+
+/** Options for {@link buildProjectHealth}. */
+export interface ProjectHealthOptions {
+  /** The project root — where the capability manifests resolve from. */
+  projectDir: string;
+  /** The environment the migration check is computed for. */
+  env: string;
+  /**
+   * The Cloudflare account this project belongs to, or `null` when it names none. `doctor` already
+   * resolves it for the `Cloudflare:` block; the pending-migration count inside each plan is the read
+   * that needs it, and it was reading whichever credentials file the machine defaulted to (#234).
+   */
+  account: CloudflareAccountSelection | null;
+  /** The Workers to check, in report order. Doctor resolves them once and passes them in. */
+  workers: HealthWorker[];
+  /** Test seam: read the migration ledger without a real Miniflare/D1 run. */
+  readLedger?: ReadLedger;
+  /** Test seam: substitute the plan builder. Defaults to the shared reconcile engine. */
+  buildPlan?: BuildPlan;
+  /** Test seam: substitute the manifest scan. Defaults to the real `node_modules/@pithy-sh` read. */
+  readManifests?: ReadManifests;
+}
+
+/** Group a plan's per-capability missing bindings into one entry per binding, listing the envs that lack it. */
+function groupMissingBindings(plan: ReconcilePlan): BindingHealth["missing"] {
+  const byKey = new Map<string, { name: string; type: string; envs: string[] }>();
+  for (const cap of plan.perCapability) {
+    for (const binding of cap.missingBindings) {
+      const key = `${binding.name} ${binding.type}`;
+      const entry = byKey.get(key) ?? { name: binding.name, type: binding.type, envs: [] };
+      if (!entry.envs.includes(binding.env)) entry.envs.push(binding.env);
+      byKey.set(key, entry);
+    }
+  }
+  return [...byKey.values()];
+}
+
+/** Project one Worker's reconcile plan into its three health checks. */
+function healthFromPlan(worker: string, plan: ReconcilePlan): WorkerHealth {
+  const drift = plan.perCapability
+    .filter((cap) => cap.missingConfigKeys.length > 0)
+    .map((cap) => ({ capability: cap.name, keys: cap.missingConfigKeys.map((key) => key.key) }));
+  const config: ConfigHealth = { ok: drift.length === 0, drift };
+
+  const missing = groupMissingBindings(plan);
+  // Deduplicated across capabilities: two capabilities binding one class is one missing export.
+  const missingExports = [...new Set(plan.perCapability.flatMap((cap) => cap.missingEntryExports))];
+  // A decline that cannot be honored is a defect in the declaration and fails the check. `unrecognized`
+  // does not: `pithy remove <capability>` produces it, and a red no command can clear is worse than the
+  // line that reports it.
+  const declinedBindings = plan.declinedBindings;
+  const badDeclines =
+    declinedBindings.state === "invalid" ||
+    declinedBindings.declines.some((decline) => decline.state === "required" || decline.state === "undeclinable");
+  const bindings: BindingHealth = {
+    ok: missing.length === 0 && missingExports.length === 0 && !badDeclines,
+    missing,
+    missingExports,
+    declinedBindings,
+  };
+
+  // `ok` only on a whole read with nothing on either side of it. A `partial` ledger is a database this
+  // check did not compare, and a check that did not run is not a check that passed — the same standard
+  // `pithy doctor` already applies to a manifest it could not parse (#184). It is also what today's
+  // behavior was: an unreadable ledger threw, and the exit was non-zero.
+  const ledger = plan.ledger;
+  const migrations: MigrationHealth = {
+    ok: ledger.state === "read" && ledger.pending === 0 && ledger.undeclared.length === 0,
+    ledger,
+    env: plan.env,
+  };
+
+  // `ok` only on a scan that ran and found nothing, on the same standard the migrations check applies: a
+  // check that did not run is not a check that passed.
+  const gap = plan.entitlements;
+  const entitlements: EntitlementHealth = { ok: gap.state === "read" && gap.gates.length === 0, gap };
+
+  const prerequisites: PrerequisiteHealth = {
+    ok: plan.missingPrerequisites.length === 0,
+    missing: plan.missingPrerequisites,
+  };
+
+  return {
+    state: "checked",
+    worker,
+    ok: config.ok && bindings.ok && migrations.ok && entitlements.ok && prerequisites.ok,
+    config,
+    bindings,
+    migrations,
+    entitlements,
+    prerequisites,
+  };
+}
+
+/**
+ * Build the project's health from one read-only reconcile plan per Worker. For each Worker, `config` fails
+ * when a capability's `pithy.config.ts` registration is missing manifest options; `bindings` fails when a
+ * required binding is absent from an environment; `migrations` fails when the target env has unapplied migrations **or** has applied one
+ * this Worker no longer declares; `entitlements` fails when a route gates on an entitlement no composed capability resolves;
+ * `prerequisites` fails when a composed capability declares a peer the Worker does not compose, which is
+ * the one that means the Worker will not start at all. The project is healthy only when every Worker is.
+ * Writes nothing — safe to run on every `pithy doctor` invocation.
+ */
+export async function buildProjectHealth(options: ProjectHealthOptions): Promise<ProjectHealth> {
+  const build = options.buildPlan ?? defaultBuildPlan;
+  const scan = options.readManifests ?? availableManifests;
+
+  // Read once, at the project, because that is where manifests live: one install under the root's
+  // `node_modules/@pithy-sh`, shared by every Worker. Every plan below is built from the same scan, so a
+  // capability whose manifest will not read is missing from every Worker's checks at once — which is the
+  // hole this reports, and the reason it is not a per-Worker line.
+  const { faults } = await scan(options.projectDir);
+
+  // **One Worker at a time (#371).** The wiring is per Worker, so a failure to read it is per Worker too —
+  // and this is a diagnostic, so one Worker nobody could check must never cost the report on the others.
+  // The manifest scan above is not a contributor to this loop: it is read once, at the project, and every
+  // plan is built from it, which is why it is a project-wide line and why it still throws.
+  //
+  // The guard takes no binding. A plan reaches a customer's D1 and imports their config, so what it throws
+  // is throw-site context; the Worker's name is the actionable fact and `doctor` already prints it.
+  const workers: WorkerHealth[] = [];
+  for (const worker of options.workers) {
+    let plan: ReconcilePlan;
+    try {
+      plan = await build({
+        projectDir: options.projectDir,
+        workerDir: worker.dir,
+        worker: worker.name,
+        env: options.env,
+        account: options.account,
+        capabilities: worker.capabilities,
+        ...(worker.config ? { workerConfig: worker.config } : {}),
+        readLedger: options.readLedger,
+      });
+    } catch {
+      workers.push({ state: "unavailable", worker: worker.name });
+      continue;
+    }
+    workers.push(healthFromPlan(worker.name, plan));
+  }
+
+  const manifests: ManifestHealth = { ok: faults.length === 0, faults };
+  // An unchecked Worker fails the project, on the same standard #184 set for an unreadable manifest: a
+  // check that did not run established nothing, and a report calling a project healthy around a hole is
+  // the under-report this whole family exists to prevent. It is also what the behavior already was —
+  // the throw reached `pithy doctor`'s catch and drove a non-zero exit — so the gate does not weaken.
+  const checked = workers.every((worker) => worker.state === "checked" && worker.ok);
+  return { ok: manifests.ok && checked, workers, manifests };
+}

package/src/doctor/localDelivery.ts

@@ -0,0 +1,91 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
+import { HOST_WORKERS } from "../capabilities/hostRegistry";
+import { hasCloudflareLogin as defaultHasCloudflareLogin, deliveryPreflight } from "../dev/delivery";
+
+/**
+ * Whether local email delivery is **live** — the question `pithy doctor` answers about a machine, and
+ * the one nothing else in the report asks (pithy-sh/pithy#410).
+ *
+ * `Settings:` says whether the values work. Every other block says whether something is there. Neither
+ * says the thing a developer actually wants to know before they sit waiting on an inbox: does a magic
+ * link triggered from localhost leave this machine, or is it written to disk. That depends on a
+ * Cloudflare login and on the delivery mode the config selected, and both are readable here for free.
+ *
+ * **It is the same function `pithy dev` decides with.** {@link deliveryPreflight} returns the verdict
+ * and its wording, and this hands back exactly what it said — so doctor and the dev command cannot come
+ * to two answers about one project, and a rule that changes changes in one file. Which capability
+ * answers for delivery is the host registry's, not this module's: a tenth capability that puts
+ * something on the wire implements `delivery` and is reported here with no change.
+ *
+ * It is not a fault. The simulator is a legitimate choice — `email({ devDelivery: "simulator" })` picks
+ * it deliberately, and an offline machine has no other option — so this never fails the exit. It prints
+ * because silence would be read as "of course it sends".
+ */
+
+/** What this machine would do with a message, and the words the run said it in. */
+export interface LocalDeliveryCheck {
+  /** Whether a message sent from localhost actually leaves the machine. */
+  live: boolean;
+  /** The capability that answers for delivery — `email` today, the only one holding a send binding. */
+  capability: string;
+  /** The verdict verbatim: the same lines `pithy dev` prints in its ready banner, action included. */
+  lines: string[];
+}
+
+/** Everything the check reads, all of it injectable so a unit test never touches a credential file. */
+export interface LocalDeliveryOptions {
+  projectDir: string;
+  /** The Workers in scope, with the capability instances doctor already resolved. */
+  workers: readonly { capabilities: readonly Capability[] }[];
+  /** Seam: whether Cloudflare credentials resolve at all. Defaults to the dev command's own reader. */
+  hasCloudflareLogin?: (projectDir: string, env: NodeJS.ProcessEnv) => Promise<boolean>;
+  env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * The delivery verdict for this project, or `null` when nothing composed puts a message on the wire.
+ *
+ * `null` is the ordinary case and is silent: a project with no sending capability has no local delivery
+ * to be right or wrong about. A capability whose package will not load answers nothing rather than
+ * failing the report — the `Settings:` block reaches the same package on the same run and names it.
+ */
+export async function checkLocalDelivery(options: LocalDeliveryOptions): Promise<LocalDeliveryCheck | null> {
+  const composed = new Map<string, Capability>();
+  for (const worker of options.workers) {
+    for (const capability of worker.capabilities) {
+      if (!composed.has(capability.name)) composed.set(capability.name, capability);
+    }
+  }
+
+  for (const spec of HOST_WORKERS) {
+    const capability = composed.get(spec.capability);
+    if (!capability || !spec.delivery) continue;
+    let identity: Awaited<ReturnType<NonNullable<typeof spec.delivery>>>;
+    try {
+      identity = await spec.delivery(capability);
+    } catch {
+      continue;
+    }
+    if (!identity) continue;
+    const preflight = deliveryPreflight({
+      composed: true,
+      requested: identity.requested,
+      ...(identity.fromAddress !== undefined ? { fromAddress: identity.fromAddress } : {}),
+      hasCloudflareLogin: await (options.hasCloudflareLogin ?? defaultHasCloudflareLogin)(
+        options.projectDir,
+        options.env ?? process.env,
+      ),
+    });
+    return { live: preflight.live, capability: spec.capability, lines: preflight.lines };
+  }
+
+  return null;
+}
+
+/** The check as one sentence — the `--json` `detail`, and never a second wording of the lines. */
+export function describeLocalDelivery(check: LocalDeliveryCheck): string {
+  return check.lines.join(" ").replace(/\s+/g, " ").trim();
+}