@pithy-sh/cli 0.1.0

package/src/doctor/secretBindings.ts

@@ -0,0 +1,166 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { resolveDevSecretsTargets } from "../devSecrets/targets";
+import { projectEnvironments } from "../project/config";
+import { readOptionalWranglerConfig } from "../project/wrangler";
+import { boundSecretNames } from "../provision/secretBindings";
+
+/**
+ * **Does every deployed environment bind the `cf-secrets-store` secrets its Workers read?** (#238)
+ *
+ * The safety net for a project that predates the stanza existing at all — which is every project
+ * scaffolded before it, including the adopter who found this by reading their own `wrangler.jsonc` and
+ * asking where the binding was. `pithy add` deliberately cannot write a `secret` binding (the entry needs
+ * a `store_id` and a `secret_name` that do not exist until an account has been reached) and
+ * `pithy secrets provision` is the step that comes back and writes it. Nothing said so. A Worker deployed
+ * without `SECRETS_ENCRYPTION_KEYS` boots and answers its first request with
+ * `Missing required bindings: secret:SECRETS_ENCRYPTION_KEYS`, and until this line the only thing that
+ * reported it was that response.
+ *
+ * **Files only, and it never asks the store.** Whether an *entry* exists is a question for the account,
+ * and provisioning is what asks it — a declared secret whose entry has not been written is reported
+ * rather than bound, because wrangler refuses a config naming an absent entry and binding one would turn
+ * a single missing value into a failed deploy of the whole Worker. So this reports the stanza against the
+ * registry and names the command that reconciles both.
+ *
+ * **`dev` never appears, and not by being filtered.** The environments walked are the ones the project
+ * declares, and `dev` is not among them. Local dev materialises every `cf-secrets-store` secret into the
+ * generated `.dev.vars` (#179), so a stanza there would name store entries a local run never reads.
+ *
+ * **Which secrets need a binding is not decided here.** {@link boundSecretNames} is the one predicate,
+ * shared with the writer in `provision/secretBindings.ts` — so a check that reported a binding the writer
+ * would never write, or missed one it would, is not a state these two can reach.
+ */
+
+/** One `cf-secrets-store` secret a deployed environment declares and does not bind. */
+export interface MissingSecretBinding {
+  /** The Worker's name, as `pithy worker list` shows it. */
+  worker: string;
+  /** The declared environment whose stanza lacks it. */
+  env: string;
+  /** The binding name — the registry key, which is also the name every read site uses. */
+  binding: string;
+}
+
+/** What this check established. Listed positively, so an inconclusive read says so. */
+export type SecretBindingsState =
+  /** Every declared environment binds every `cf-secrets-store` secret its Worker reads. */
+  | "ok"
+  /** A `wrangler.jsonc` would not parse, or the declared set would not load. */
+  | "could-not-check"
+  /** A deployed environment declares a secret it does not bind. */
+  | "unbound";
+
+/** What `doctor` learned about this project's Secrets Store bindings. */
+export interface SecretBindingsCheck {
+  state: SecretBindingsState;
+  missing: MissingSecretBinding[];
+}
+
+/** The `wrangler.jsonc` slice this reads: each environment stanza's `secrets_store_secrets` array. */
+interface RawWrangler {
+  env?: Record<string, { secrets_store_secrets?: { binding?: string }[] } | undefined>;
+}
+
+/** What {@link checkSecretBindings} needs. Both seams default to the real project's. */
+export interface CheckSecretBindingsOptions {
+  /** The project root. */
+  projectDir: string;
+  /** The Workers whose registries declare the secrets. Defaults to every one composing `secrets`. */
+  targets?: { name: string; dir: string; registry: Record<string, unknown> }[];
+  /**
+   * The Workers whose `pithy.config.ts` would not import. Read only when {@link targets} is supplied —
+   * both halves of one resolution, so a seam cannot state one and let the other default to a lie.
+   */
+  unresolvable?: readonly unknown[];
+  /** The environments to check. Defaults to the set the root `pithy.config.ts` declares. */
+  environments?: readonly string[];
+}
+
+/**
+ * Compare each Worker's declared secrets against each declared environment's stanza. Never throws — a
+ * diagnostic has to work in the broken environment it exists to diagnose.
+ *
+ * `null` means no Worker composes `secrets`, so there is no registry and no question — the same
+ * discipline `checkDevSecrets` holds.
+ *
+ * **The unresolvable half is carried, not dropped (#199).** "This stanza binds no `X`" is a negative
+ * claim about a registry, and a Worker whose `pithy.config.ts` would not import is exactly the one that
+ * might have declared `X` — so one unreadable config makes the whole check `could-not-check` rather than
+ * a confident `ok`. `pithy doctor`'s `Dev secrets:` block is what names the Worker and the reason; this
+ * one only has to stop claiming something it could not establish.
+ */
+export async function checkSecretBindings(options: CheckSecretBindingsOptions): Promise<SecretBindingsCheck | null> {
+  const resolved =
+    options.targets === undefined
+      ? await resolveDevSecretsTargets(options.projectDir).catch(() => ({ targets: [], unresolvable: [] }))
+      : { targets: options.targets, unresolvable: options.unresolvable ?? [] };
+  const targets = resolved.targets;
+  if (targets.length === 0 && resolved.unresolvable.length === 0) return null;
+  if (resolved.unresolvable.length > 0) return { state: "could-not-check", missing: [] };
+
+  let environments: readonly string[];
+  if (options.environments) {
+    environments = options.environments;
+  } else {
+    try {
+      environments = await projectEnvironments(options.projectDir);
+    } catch {
+      return { state: "could-not-check", missing: [] };
+    }
+  }
+
+  const missing: MissingSecretBinding[] = [];
+  let unreadable = false;
+  for (const target of targets) {
+    const config = (await readOptionalWranglerConfig(target.dir).catch(() => undefined)) as
+      | RawWrangler
+      | null
+      | undefined;
+    if (config === undefined) {
+      // A `wrangler.jsonc` that will not parse states nothing about what it binds, and "this stanza is
+      // missing a binding" is a negative claim. The `Project health` block already says the file is
+      // broken, and saying it again in other words is how a report starts contradicting itself.
+      unreadable = true;
+      continue;
+    }
+    // No file at all is not a Worker with a broken config — a process in the dev set with no
+    // `wrangler.jsonc` declares no environments and binds nothing.
+    if (config === null) continue;
+    const declared = boundSecretNames(target.registry as Parameters<typeof boundSecretNames>[0]).sort();
+    for (const env of environments) {
+      const bound = new Set(
+        (config.env?.[env]?.secrets_store_secrets ?? []).map((entry) => entry.binding).filter(Boolean),
+      );
+      for (const binding of declared) {
+        if (!bound.has(binding)) missing.push({ worker: target.name, env, binding });
+      }
+    }
+  }
+
+  if (missing.length > 0) return { state: "unbound", missing };
+  return { state: unreadable ? "could-not-check" : "ok", missing: [] };
+}
+
+/**
+ * The lines the report prints, or none at all when there is nothing to say.
+ *
+ * One line per Worker-and-environment rather than per binding: the remedy is the same command for all of
+ * them, and a project composing four `cf-secrets-store` secrets would otherwise print eight sentences
+ * that differ only in a name. An adopter counts lines.
+ */
+export function describeSecretBindings(check: SecretBindingsCheck): string[] {
+  const grouped = new Map<string, MissingSecretBinding[]>();
+  for (const entry of check.missing) {
+    // `\0` written as the escape, never raw: a raw NUL makes the whole file binary to git, so it
+    // has no line diff and nothing in review can see what changed around it.
+    const key = `${entry.worker}\0${entry.env}`;
+    grouped.set(key, [...(grouped.get(key) ?? []), entry]);
+  }
+  return [...grouped.values()].map((entries) => {
+    const first = entries[0] as MissingSecretBinding;
+    const names = entries.map((entry) => entry.binding).join(", ");
+    return `${first.worker} env.${first.env} binds no ${names}. Run pithy secrets provision — it creates the store entries and writes the stanza.`;
+  });
+}

package/src/doctor/settings.ts

@@ -0,0 +1,274 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
+import type {
+  SettingsAccountReader,
+  SettingsEnvironment,
+  SettingsFinding,
+} from "@pithy-sh/core/src/capability/settings";
+
+/**
+ * Whether each composed capability's **settings work**, as opposed to being merely present (#411).
+ *
+ * Every other check in this directory asks a presence question — is the option key written, is the binding
+ * declared, is the ledger level. All of them can pass while `fromAddress` names a domain nobody onboarded,
+ * the signing key was never created, `BASE_URL` is staging's URL in production's config, and no mail
+ * arrives. Only the capability knows what its own values have to be, so the capability declares the check
+ * (`@pithy-sh/core/src/capability/settings.ts`) and this runs it.
+ *
+ * ## What this module is, and is not
+ *
+ * It is the **runner**: it walks the composed instances, hands each declared check its context, collects
+ * findings, and keeps a check that could not run apart from one that passed. Every source it needs is a
+ * seam — the environments, the account — so the whole of it is testable without a project or a network,
+ * which is the same reason `checkProjectName` takes its account probe as a parameter.
+ *
+ * It is not a check of its own. Nothing here knows what an email setting is, and nothing here reads a
+ * `pithy.manifest.json`: discovery keys on the capability instance, because a manifest is a file a
+ * capability package can be shipped without — `@pithy-sh/matchmaking` and `@pithy-sh/rating` both were,
+ * from the day they landed until #415 — and a manifest-keyed rule skips such a package in silence.
+ *
+ * ## The three rules it exists to keep
+ *
+ * - **`null` means the question does not arise.** No composed capability declares a check, so there is
+ *   nothing to report — the same fact `checkDevSecrets` reports as `null` for a project with no registry.
+ *   A capability declaring nothing is ordinary, and it is silent.
+ * - **A check that did not run is never rendered as a pass.** A local check that throws, and an account
+ *   check the account never answered, land in {@link SettingsCheck.unchecked} — not in `findings`, and not
+ *   in `checked`.
+ * - **Skipped is a third answer.** When the account cannot be reached — offline, no credentials, no answer
+ *   — the account tier is `skipped` with the reason, no account check runs, and nothing gates the exit.
+ *   A local finding gates. An account finding gates too, because by then the account *was* reached.
+ *
+ * Nothing here writes. `pithy upgrade`, `pithy <capability> provision`, and the command each finding names
+ * are what change anything.
+ */
+
+/** One Worker's name and the capabilities its own `pithy.config.ts` composes. */
+export interface SettingsScope {
+  /** The Worker, as `apps/<name>` and the health block name it. */
+  name: string;
+  /** Its composed capability instances, app capability included. */
+  capabilities: readonly Capability[];
+}
+
+/** Which half of a check something came from. The two cost different things and gate on different terms. */
+export type SettingsTier = "local" | "account";
+
+/** One finding, plus where it was found. */
+export interface SettingsFindingEntry extends SettingsFinding {
+  /** The Worker whose composition produced it. */
+  worker: string;
+  /** The capability that reported it. */
+  capability: string;
+  /** Which tier reported it. */
+  tier: SettingsTier;
+}
+
+/** One capability-and-tier nobody could answer for. Never a pass, and never a fault. */
+export interface SettingsUnchecked {
+  worker: string;
+  capability: string;
+  tier: SettingsTier;
+}
+
+/**
+ * The check's verdict, listed positively.
+ *
+ * - `ok` — every check that ran passed, and nothing was left unanswered.
+ * - `faults` — at least one setting does not work. This is what fails the exit.
+ * - `could-not-check` — nothing is wrong that anybody established, and something could not be asked.
+ */
+export type SettingsState = "ok" | "faults" | "could-not-check";
+
+/**
+ * Why the account tier did not run.
+ *
+ * Four reasons, and they are not interchangeable in a report: `offline` is a decision somebody made,
+ * `no-credentials` is a project that has not been set up, `unreachable` is a network or an account that
+ * did not answer, and `not-declared` is nobody having asked the account anything. A single boolean would
+ * have said "not checked" to all four, which is the conflation `CloudflareAccessState` grew `not_checked`
+ * and `probe_failed` to avoid.
+ */
+export type SettingsAccountSkip = "offline" | "no-credentials" | "unreachable" | "not-declared";
+
+/** Whether the account tier ran, and why not when it did not. */
+export interface SettingsAccountTier {
+  state: "checked" | "skipped";
+  /** The reason, set exactly when `state` is `skipped`. */
+  reason: SettingsAccountSkip | null;
+}
+
+/** What the whole check found, across every Worker. */
+export interface SettingsCheck {
+  state: SettingsState;
+  /** Whether the account half ran at all. Reported whether or not it found anything. */
+  account: SettingsAccountTier;
+  /** Every capability whose check ran to completion, in Worker then composition order. */
+  checked: { worker: string; capability: string }[];
+  /** Every setting that does not work, in the order the checks reported them. */
+  findings: SettingsFindingEntry[];
+  /** Every capability-and-tier that could not be asked. */
+  unchecked: SettingsUnchecked[];
+}
+
+/**
+ * The account, or the reason there is none to ask.
+ *
+ * Resolved once per run and shared by every capability: the credentials are account-scoped, so asking a
+ * second time could only produce a second answer to one question.
+ */
+export type SettingsAccountConnection =
+  | { state: "reachable"; reader: SettingsAccountReader }
+  | { state: "skipped"; reason: SettingsAccountSkip };
+
+/** Everything the runner needs, all of it injectable. */
+export interface CapabilitySettingsOptions {
+  /** The root config's `name` — the leading segment of every name this project provisions. */
+  project: string;
+  /** The Workers in scope. `--worker <name>` has already narrowed this; the runner never re-enumerates. */
+  workers: readonly SettingsScope[];
+  /**
+   * The environments a Worker declares, and the origin it answers on in each.
+   *
+   * Per Worker, because an origin is a Worker's own declaration — two Workers in one project answer on
+   * two hostnames, and a check told otherwise would report the wrong one as drift.
+   */
+  environments: (worker: string) => Promise<readonly SettingsEnvironment[]>;
+  /**
+   * Reach the account. Called **at most once**, and only when some composed capability declares an account
+   * tier — a project whose capabilities ask the account nothing pays for no call, the same rule
+   * `probeAccountEvidence` follows.
+   */
+  connect: () => Promise<SettingsAccountConnection>;
+}
+
+/** Every composed capability that declares a check, flattened with the Worker it came from. */
+function declared(workers: readonly SettingsScope[]): { worker: string; capability: Capability }[] {
+  const found: { worker: string; capability: Capability }[] = [];
+  for (const worker of workers) {
+    for (const capability of worker.capabilities) {
+      if (capability.settings) found.push({ worker: worker.name, capability });
+    }
+  }
+  return found;
+}
+
+/**
+ * Run every composed capability's settings check.
+ *
+ * Never throws — a diagnostic has to keep working in exactly the broken environment it exists to
+ * diagnose, and the checks here are adopter-supplied code reached through a live `import()`. Every throw
+ * becomes an `unchecked` entry naming the capability and the tier, which is the one actionable fact in it;
+ * nothing derived from what was thrown is kept, because a capability's own failure names config paths and
+ * sometimes values.
+ */
+export async function checkCapabilitySettings(options: CapabilitySettingsOptions): Promise<SettingsCheck | null> {
+  const entries = declared(options.workers);
+  // The question does not arise: no capability composed here has anything to say about its own settings.
+  if (entries.length === 0) return null;
+
+  const findings: SettingsFindingEntry[] = [];
+  const unchecked: SettingsUnchecked[] = [];
+  const checked: { worker: string; capability: string }[] = [];
+
+  // Resolved once, ahead of the loop, and only when something will ask it. A second call could answer
+  // differently, and a report whose two halves disagree about whether the account was reached is worse
+  // than one that never asked.
+  const wantsAccount = entries.some((entry) => entry.capability.settings?.account);
+  const connection: SettingsAccountConnection = wantsAccount
+    ? await connectQuietly(options.connect)
+    : { state: "skipped", reason: "not-declared" };
+
+  for (const { worker, capability } of entries) {
+    const settings = capability.settings;
+    if (!settings) continue;
+    let context: { project: string; worker: string; environments: readonly SettingsEnvironment[] };
+    try {
+      context = { project: options.project, worker, environments: await options.environments(worker) };
+    } catch {
+      // Nothing was checked against nothing: without the declared set there is no environment to judge a
+      // per-environment value in, and a check run against an empty list would report a clean pass.
+      unchecked.push({ worker, capability: capability.name, tier: "local" });
+      continue;
+    }
+
+    let ranLocal = false;
+    try {
+      for (const finding of await settings.local(context)) {
+        findings.push({ ...finding, worker, capability: capability.name, tier: "local" });
+      }
+      ranLocal = true;
+    } catch {
+      unchecked.push({ worker, capability: capability.name, tier: "local" });
+    }
+
+    if (settings.account && connection.state === "reachable") {
+      try {
+        for (const finding of await settings.account({ ...context, account: connection.reader })) {
+          findings.push({ ...finding, worker, capability: capability.name, tier: "account" });
+        }
+      } catch {
+        unchecked.push({ worker, capability: capability.name, tier: "account" });
+      }
+    }
+
+    if (ranLocal) checked.push({ worker, capability: capability.name });
+  }
+
+  return {
+    // Listed positively, and a fault outranks an unanswered question: a project with one of each has
+    // something to fix, and the line that says so must not be softened into "could not check".
+    state: findings.length > 0 ? "faults" : unchecked.length > 0 ? "could-not-check" : "ok",
+    account:
+      connection.state === "reachable"
+        ? { state: "checked", reason: null }
+        : { state: "skipped", reason: connection.reason },
+    checked,
+    findings,
+    unchecked,
+  };
+}
+
+/**
+ * Reach the account, and treat a throw as unreachable rather than as a lost report.
+ *
+ * `try`/`catch` rather than `.catch()` for the reason `commands/doctor.ts` states about its own guards: a
+ * seam that throws before returning a promise is not a rejected promise, and `.catch()` never sees it.
+ */
+async function connectQuietly(connect: () => Promise<SettingsAccountConnection>): Promise<SettingsAccountConnection> {
+  try {
+    return await connect();
+  } catch {
+    return { state: "skipped", reason: "unreachable" };
+  }
+}
+
+/**
+ * One finding as one sentence — the capability, the setting, the environment it is about, then the problem
+ * and the action.
+ *
+ * The `--json` `detail` and the source of the text block's two lines, so a consumer never has to
+ * reassemble the wording from the fields. The environment is in parentheses and absent when the finding is
+ * about every environment at once, which is the difference between one edit and three.
+ */
+export function describeSettingsFinding(entry: SettingsFindingEntry): string {
+  const where = entry.environment === null ? "" : ` (${entry.environment})`;
+  return `${entry.capability}: ${entry.setting}${where} — ${entry.problem} ${entry.action}`;
+}
+
+/** The account tier's own sentence — which of the four things happened, in the run's own words. */
+export function describeSettingsAccount(tier: SettingsAccountTier): string {
+  if (tier.state === "checked") return "account checks ran";
+  if (tier.reason === "not-declared") return "no capability asks the account anything";
+  const why =
+    tier.reason === "offline"
+      ? "offline"
+      : tier.reason === "no-credentials"
+        ? "no Cloudflare credentials"
+        : "the account did not answer";
+  // Said out loud, every time: a tier nobody ran is not a tier that passed, and the one thing a reader
+  // must not take from a quiet report is that the account was checked.
+  return `account checks skipped (${why}) — nothing here was established about the account`;
+}

package/src/doctor/settingsSources.ts

@@ -0,0 +1,202 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { CloudflareClients } from "@pithy-sh/cloudflare/src/client/clients";
+import type { Capability } from "@pithy-sh/core/src/capability/capability";
+import type { SettingsAccountReader, SettingsEnvironment } from "@pithy-sh/core/src/capability/settings";
+import { InternalError } from "@pithy-sh/core/src/error/pithyError";
+import type { SecretProbe } from "@pithy-sh/secrets/src/cli/dispatch";
+import { buildSecretDispatcher } from "../capabilities/secretsDispatcher";
+import { type CloudflareAccountSelection, cloudflareEnv } from "../cloudflare/config";
+import {
+  loadProject,
+  loadWorkerConfig,
+  loadWorkerDomains,
+  projectEnvironments,
+  requireProjectName,
+} from "../project/config";
+import { type AddressStanza, resolveWorkerAddress } from "../project/workerAddress";
+import { readOptionalWranglerConfig } from "../project/wrangler";
+import { checkCapabilitySettings, type SettingsAccountConnection, type SettingsCheck } from "./settings";
+
+/**
+ * Where `pithy doctor`'s settings check gets the two things it cannot invent: the environments a capability
+ * is judged against, and the account it may ask (#411).
+ *
+ * Split from `settings.ts` on purpose. That module is the runner — pure, seam-driven, and testable with no
+ * project and no network. This one is the wiring: it reads the adopter's config off disk and opens a
+ * Cloudflare client. Keeping them apart is what lets the three account outcomes (reached and clean, reached
+ * and failing, never reached) be stated as three tests rather than as three mocks of a network.
+ */
+
+/**
+ * The environments this project declares, and the origin the given Worker answers on in each.
+ *
+ * Both halves come from the readers that already own them — `loadProjectEnvironments` for the declared set,
+ * `resolveWorkerAddress` for the address — so a capability's idea of "the origin for prod" is the same one
+ * `pithy deploy` refuses on and the `Origins:` block reports. `dev` never resolves to a public address, and
+ * an environment nothing serves carries `null` rather than being dropped: a check judging `BASE_URL` needs
+ * to know the environment exists even when nothing declares where it answers.
+ *
+ * A `wrangler.jsonc` or a `pithy.config.ts` that will not read costs the origins and nothing else. The
+ * declared set is the root config's, and without it there is no answer at all — which the runner turns
+ * into an unchecked capability rather than into a clean pass.
+ */
+export async function settingsEnvironments(projectDir: string, workerDir: string): Promise<SettingsEnvironment[]> {
+  const declared = await projectEnvironments(projectDir);
+  const config = (await readOptionalWranglerConfig(workerDir).catch(() => null)) as {
+    env?: Record<string, AddressStanza | undefined>;
+  } | null;
+  // A negative claim about a Worker's domains needs a config that was actually read: the `pithy.config.ts`
+  // nobody could import is exactly the one that might have declared one.
+  const domains = await loadWorkerConfig(workerDir)
+    .then((worker) => loadWorkerDomains(worker))
+    .catch(() => undefined);
+  return declared.map((name) => {
+    const address = resolveWorkerAddress({ environment: name, domains, stanza: config?.env?.[name] });
+    return { name, origin: address?.url ?? null };
+  });
+}
+
+/** What it takes to reach the account, all of it injectable so a unit test never calls out. */
+export interface SettingsAccountOptions {
+  /** The account this project belongs to, from its own root `pithy.config.ts`. */
+  account: CloudflareAccountSelection | null;
+  /** The root config's `name` — the leading segment of the manager Workflow a secret question is asked of. */
+  project: string;
+  /** Whether this run refuses ambient credentials and every network call. */
+  offline: boolean;
+  /** Environment overlay seam, so a test resolves credentials without a `.dev.vars`. */
+  env?: NodeJS.ProcessEnv;
+  /** Home directory seam — the credentials file is resolved under it, exactly as every other doctor path is. */
+  homedir?: string;
+  /** Cloudflare client seam. */
+  connect?: (credentials: { accountId: string; apiToken: string }) => CloudflareClients;
+  /** Secret-probe seam — the manager Workflow that answers whether a `d1` secret has a value. */
+  probe?: (credentials: { accountId: string; apiToken: string }, project: string) => SecretProbe;
+}
+
+/**
+ * Resolve the account the account tier asks, or the reason there is none to ask.
+ *
+ * **Four skips, and they are not one boolean.** `offline` is a decision somebody made and is settled first,
+ * before any file is read. A pin the credentials contradict ends it as `unreachable` — the `Cloudflare:`
+ * block of the same report already names that fault, and one fact belongs in one line. Credentials that
+ * simply are not there are `no-credentials`, because a project that has not been provisioned yet is a
+ * legitimate state and calling it unreachable would blame a network nobody touched.
+ *
+ * The reader memoizes: every composed capability asks the same account, and a doctor run must cost one
+ * listing rather than one per capability.
+ */
+export async function settingsAccountConnection(options: SettingsAccountOptions): Promise<SettingsAccountConnection> {
+  if (options.offline) return { state: "skipped", reason: "offline" };
+
+  let vars: Record<string, string>;
+  try {
+    vars = cloudflareEnv({
+      account: options.account,
+      ...(options.env ? { env: options.env } : {}),
+      ...(options.homedir ? { homedir: options.homedir } : {}),
+    });
+  } catch {
+    return { state: "skipped", reason: "unreachable" };
+  }
+  const accountId = vars.CLOUDFLARE_ACCOUNT_ID ?? "";
+  const apiToken = vars.CLOUDFLARE_API_TOKEN ?? "";
+  if (!accountId || !apiToken) return { state: "skipped", reason: "no-credentials" };
+
+  const credentials = { accountId, apiToken };
+  const clients = (options.connect ?? ((creds) => new CloudflareClients(creds)))(credentials);
+  const probe = (
+    options.probe ?? ((creds, project) => buildSecretDispatcher(creds.accountId, creds.apiToken, project))
+  )(credentials, options.project);
+
+  let databases: Promise<readonly string[]> | undefined;
+  const zones = new Map<string, Promise<boolean>>();
+
+  const reader: SettingsAccountReader = {
+    d1Databases: () => {
+      databases ??= clients
+        .d1Provisioner()
+        .listDatabases()
+        .then((list) => list.map((entry) => entry.name));
+      return databases;
+    },
+    zone: (hostname) => {
+      const existing = zones.get(hostname);
+      if (existing) return existing;
+      const answer = clients
+        .zones()
+        .findZoneForHostname(hostname)
+        .then((zone) => zone !== null);
+      zones.set(hostname, answer);
+      return answer;
+    },
+    // `async` so a refusal is a rejected promise rather than a synchronous throw: the runner guards both,
+    // but a seam that throws before returning a promise is the shape `commands/doctor.ts` documents as the
+    // one `.catch()` never sees, and no caller of this should have to know which it is.
+    secret: async ({ name, environment }) => {
+      // **`dev` is refused rather than answered.** A `d1` secret's value is sealed under a master key that
+      // never leaves that environment's manager Worker, and `dev` has no manager — it is local Miniflare.
+      // Answering `false` would report a signing key as missing on every developer's machine, which is a
+      // fault nobody has and a report nobody would read twice.
+      if (environment === "dev") {
+        throw new InternalError({
+          message: "A dev secret cannot be asked of the account.",
+          action: "Ask about a deployed environment, or read the local value through pithy secrets edit.",
+          detail: `secret ${name} in dev has no manager Worker to answer`,
+        });
+      }
+      return probe.probe({ env: environment as "staging" | "prod", name });
+    },
+  };
+  return { state: "reachable", reader };
+}
+
+/** One Worker as `pithy doctor` already holds it: its name, its directory, and what it composes. */
+export interface SettingsWorkerScope {
+  name: string;
+  dir: string;
+  capabilities: readonly Capability[];
+}
+
+/** What the default settings probe needs, all of it already resolved once by `buildDoctorReport`. */
+export interface DoctorSettingsOptions {
+  projectDir: string;
+  /** The Workers in scope — already narrowed by `--worker`, so nothing here re-enumerates `apps/`. */
+  workers: readonly SettingsWorkerScope[];
+  /** The account this project belongs to, as the `Cloudflare:` block of the same report reads it. */
+  account: CloudflareAccountSelection | null;
+  /** Whether this run refuses ambient credentials and every network call. */
+  offline: boolean;
+  homedir?: string;
+  env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * `pithy doctor`'s settings probe, wired to a real project.
+ *
+ * **The declaration test comes before the project name**, and that order is the point: a project whose
+ * capabilities declare no check has no settings question, and resolving a name it may not have would turn
+ * that silence into a `could-not-check`. `requireProjectName` and not `resolveProjectName`, because the
+ * name reaches an account resource name — `<project>-global-email-suppressions` — and a fallback-derived
+ * one would have the check reporting a database missing that is sitting there under the real name.
+ */
+export async function doctorSettingsCheck(options: DoctorSettingsOptions): Promise<SettingsCheck | null> {
+  if (!options.workers.some((worker) => worker.capabilities.some((capability) => capability.settings))) return null;
+  const project = requireProjectName(await loadProject(options.projectDir));
+  const dirs = new Map(options.workers.map((worker) => [worker.name, worker.dir]));
+  return checkCapabilitySettings({
+    project,
+    workers: options.workers.map((worker) => ({ name: worker.name, capabilities: worker.capabilities })),
+    environments: (worker) => settingsEnvironments(options.projectDir, dirs.get(worker) ?? options.projectDir),
+    connect: () =>
+      settingsAccountConnection({
+        account: options.account,
+        project,
+        offline: options.offline,
+        ...(options.homedir ? { homedir: options.homedir } : {}),
+        ...(options.env ? { env: options.env } : {}),
+      }),
+  });
+}