@pithy-sh/cli 0.1.0

package/src/devSecrets/store.ts

@@ -0,0 +1,262 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { D1Database } from "@cloudflare/workers-types";
+import { parseDevVars } from "@pithy-sh/cloudflare/src/env/devVars";
+import { sentenceOf } from "@pithy-sh/core/src/error/pithyError";
+import { masterKeyRegistryEntry } from "@pithy-sh/secrets/src/capability";
+import { type DevSecretsStore, devVarsForRegistry } from "@pithy-sh/secrets/src/dev/seedDevSecrets";
+import { MASTER_KEY_BINDING } from "@pithy-sh/secrets/src/env/bindings";
+import { SystemSecretsStore } from "@pithy-sh/secrets/src/store/systemSecretsStore";
+import { Miniflare } from "miniflare";
+import type { StatePathOptions } from "../notifier/state";
+import { resolveStoreIds } from "../seed/drivers";
+import { readBootstrapVars } from "./bootstrapVars";
+import { readDevSecrets } from "./file";
+import { resolveDevSecretsFile } from "./location";
+
+/**
+ * The local `SECRETS` D1, opened the way `wrangler dev` opens it — the same Miniflare store under the
+ * project root's `.wrangler/state`, so a row seeded here is a row the running Worker reads.
+ *
+ * **Three things have to be true before a secret can be seeded**, and each is a different fix, so each
+ * comes back named rather than as one "seeding failed": the Worker must declare the `SECRETS` binding
+ * (`pithy add secrets`), the project must have a dev master key (the same command mints it), and the
+ * database must be migrated (`pithy migrate`). None of them is an error — a project that never composed
+ * `secrets` is a perfectly good project — so this answers with a reason, and the caller decides whether
+ * to print it. `pithy add` and `pithy dev` must not fail over a capability the project does not have.
+ */
+
+/**
+ * The D1 binding name the secrets store reads through, fixed across environments. It is `SecretsStoreEnv`'s
+ * `SECRETS` field and the secrets manifest's required `d1` binding — stated here because this file opens
+ * that store from outside a Worker, where neither of those types is in play.
+ */
+export const SECRETS_D1_BINDING = "SECRETS";
+
+/**
+ * Where a project's local dev D1 databases are persisted — the directory `wrangler dev` writes into, and
+ * the one thing that makes a store provably *this project's local dev store* rather than something a
+ * caller called `dev`.
+ *
+ * Exported because the seeder asserts against it (#159). It is a destination, not a claim: a handle over
+ * a remote D1 cannot name this path and mean it.
+ */
+export function localDevStorePath(projectDir: string): string {
+  return join(localDevStateRoot(projectDir), "v3", "d1");
+}
+
+/**
+ * The one local state root a project has, and the only statement of where it is.
+ *
+ * **One store for the whole project, at its root.** Each Worker runs in its own `apps/<name>/`, where
+ * wrangler would otherwise create a private `.wrangler/` — so two Workers sharing a binding would not
+ * share the data. Every worktree gets its own, which is the point: state follows the checkout.
+ *
+ * Exported because `dev`'s orchestrator hands it to wrangler as `--persist-to`, and the scaffolded
+ * `vite.config.ts` names the same directory as a **relative** path from `apps/<worker>/`. Those two must
+ * agree, and only one of them can be checked by reading it: a wrong depth in the relative one resolves
+ * silently to `apps/.wrangler/state`, and the failure is a Worker reading an empty database rather than
+ * an error. `packages/cli/src/project/scaffoldGates.test.ts` holds the template against this function —
+ * see `pithy-sh/pithy#404`.
+ */
+export function localDevStateRoot(projectDir: string): string {
+  return join(projectDir, ".wrangler", "state");
+}
+
+/** An open local store, or the reason there is none. `dispose` is safe to call either way. */
+export type DevSecretsStoreHandle =
+  | {
+      readonly ready: true;
+      /** The store `seedDevSecrets` writes through — the real `SystemSecretsStore` over the local D1. */
+      readonly store: DevSecretsStore;
+      /**
+       * Where rows written through {@link store} actually land. The seeder refuses anything that is not
+       * {@link localDevStorePath} for the project it was asked about — see `assertLocalDevStore`.
+       *
+       * Required, and that is the point: a handle assembled without it does not compile, so a future
+       * store seam cannot quietly become a path dev secrets reach a managed environment through.
+       */
+      readonly persistPath: string;
+      readonly dispose: () => Promise<void>;
+    }
+  | {
+      readonly ready: false;
+      /** One sentence naming what is missing and the command that supplies it. Never a value. */
+      readonly reason: string;
+      readonly dispose: () => Promise<void>;
+    };
+
+/** What {@link openDevSecretsStore} needs to find the store a Worker would read. */
+export interface OpenDevSecretsStoreOptions {
+  /**
+   * The project root — owner of the `.wrangler/state` Miniflare stores every Worker shares, and of the
+   * one `.dev.vars` the dev master key lives in. Never a Worker directory: persistence is project-scoped
+   * (see the seed driver), and a per-Worker root would seed a database no Worker opens.
+   */
+  projectDir: string;
+  /** The Worker's directory — its `wrangler.jsonc` declares the `SECRETS` binding and its database id. */
+  workerDir: string;
+  /** The Worker's name, for the reason text. Defaults to naming no Worker. */
+  worker?: string;
+  /**
+   * **Unsayable on purpose (#159).** There is no environment here, and there must not be one: this opens
+   * the project's own Miniflare-backed store and nothing else. `never` means a caller that tries to pass
+   * `prod` fails to compile, which is stronger than any check it could fail at runtime.
+   */
+  env?: never;
+  /** Where the Pithy config directory is. Defaults to the real one; a seam so a test reads its own. */
+  paths?: StatePathOptions;
+}
+
+/** Open the local secrets store for one Worker, or say why there is none to open. */
+export async function openDevSecretsStore(options: OpenDevSecretsStoreOptions): Promise<DevSecretsStoreHandle> {
+  const noop = { dispose: async () => {} };
+  const scope = options.worker ? ` --worker ${options.worker}` : "";
+
+  const ids = await resolveStoreIds({ workerDir: options.workerDir, env: "dev" });
+  const databaseId = ids.d1.get(SECRETS_D1_BINDING);
+  if (!databaseId) {
+    return { ready: false, reason: `No ${SECRETS_D1_BINDING} D1 binding. Run pithy add secrets${scope}.`, ...noop };
+  }
+
+  // The dev secrets file, which is what the Worker's generated `.dev.vars` is built from (#179) —
+  // materialised through the same function the generator uses, so the key this store opens with and the
+  // key the running Worker receives cannot be two different strings.
+  //
+  // **Both older homes are still read, in the order they were used.** `dev.json` is where #154 put it and
+  // where an upgrading project still has it; the project root's `.dev.vars` is where it lived before that
+  // and still does until `pithy add secrets` adopts it. Reading only the current one would make every
+  // project that has not upgraded unopenable — and this is the master key, so an "absent" answer is not a
+  // fresh start: it is every secret already encrypted under it becoming unreadable.
+  const stated = await statedMasterKey(options.projectDir, options.paths ?? {});
+  // **A file that states a key which will not read ends it here, whatever an older home holds (#325).**
+  // The fallbacks below are for a file that says nothing, and this file has said something. Reading past
+  // it opened the store under the *older* key without a word about the newer claim — and this file is
+  // what every Worker's `.dev.vars` is generated from, so the next seed encrypted rows under a key the
+  // running Worker is never handed. The only symptom is a decrypt failure, three commands later.
+  //
+  // Deliberately a refusal rather than a fallback with a warning: nothing in this function prints, and a
+  // handle carries one sentence. Refusing is the only answer here that a caller cannot miss.
+  if (stated.unreadable) return { ready: false, reason: stated.unreadable, ...noop };
+
+  const masterKey =
+    stated.value ||
+    (await readBootstrapVars(options.projectDir, options.paths ?? {}))[MASTER_KEY_BINDING] ||
+    parseDevVars(await readFile(join(options.projectDir, ".dev.vars"), "utf8").catch(() => ""))[MASTER_KEY_BINDING];
+  if (!masterKey) {
+    // The sentence for a project with no file to state anything, and only then the absent one. "Not
+    // recorded" is a claim about the file, and it may only be made when the file makes no claim (#323) —
+    // which includes there being no file to make one.
+    const reason = stated.unlocatable ?? `No ${MASTER_KEY_BINDING} recorded. Run pithy add secrets${scope}.`;
+    return { ready: false, reason, ...noop };
+  }
+
+  const persistPath = localDevStorePath(options.projectDir);
+  const miniflare = new Miniflare({
+    modules: true,
+    script: "export default {};",
+    d1Databases: { [SECRETS_D1_BINDING]: databaseId },
+    d1Persist: persistPath,
+  });
+  const dispose = () => miniflare.dispose();
+
+  let store: SystemSecretsStore;
+  try {
+    // Neither call touches the database — `fromEnv` resolves the master key and wraps the binding — so
+    // a failure here is the key, and only the key. Kept apart from the probe below so the two cannot
+    // answer for each other: "not migrated" over an unreadable master key sends the adopter to the
+    // wrong command, and they run it, and nothing changes.
+    store = await SystemSecretsStore.fromEnv({
+      SECRETS: (await miniflare.getD1Database(SECRETS_D1_BINDING)) as unknown as D1Database,
+      SECRETS_ENCRYPTION_KEYS: masterKey,
+    });
+  } catch {
+    await dispose();
+    return { ready: false, reason: `${MASTER_KEY_BINDING} is not a valid master key.`, ...noop };
+  }
+
+  try {
+    // The probe reads the same table the seeder writes, so "migrated" means migrated for this purpose
+    // and not for some adjacent one. An unmigrated database is the ordinary state right after `pithy add
+    // secrets`, and `no such table: pithy_secrets_system_secrets` is not an answer anybody can act on.
+    await store.listNames();
+  } catch {
+    await dispose();
+    return { ready: false, reason: "The local SECRETS database is not migrated. Run pithy migrate.", ...noop };
+  }
+  return { ready: true, store, persistPath, dispose };
+}
+
+/**
+ * What the dev secrets file says about the master key. At most one of the three is set; none of them
+ * means a readable file that simply carries no key.
+ *
+ * **The type is the fix (#323).** A `string | undefined` had one slot for two answers — "the file states
+ * nothing" and "the file states something that will not read" — so a bare `catch {}` collapsed them, and
+ * a present-but-malformed key printed `No SECRETS_ENCRYPTION_KEYS recorded. Run pithy add secrets.` That
+ * sentence is false about a key that is there, and the command it names then does nothing, because
+ * `ensureDevMasterKey` finds a key already present and returns. Two investigations died in that gap.
+ *
+ * **And the fix is one slot short, which is #325.** "The file will not answer" and "there is no file to
+ * ask" were still one field, and the caller has to treat them oppositely: the first overrides every older
+ * home, because the file is authoritative about a claim it makes; the second overrides nothing, because a
+ * project with no name has no file and has made no claim.
+ */
+interface StatedMasterKey {
+  /** The key, materialised exactly as a Worker's binding receives it. Absent when the file has none. */
+  readonly value?: string;
+  /**
+   * Why the file — which is there — could not answer: the thrown error's own sentence.
+   *
+   * **Authoritative.** The file states a master key and it will not read, so no older home may stand in
+   * for it: opening under one encrypts rows under a key this file does not name.
+   */
+  readonly unreadable?: string;
+  /**
+   * Why there is no file to ask at all — no project, or a project with no `name`, since the path is
+   * resolved from the name.
+   *
+   * **Not authoritative.** Nothing was stated, so the older homes are still read, and this is only the
+   * sentence the caller falls back to when none of them holds a key either.
+   */
+  readonly unlocatable?: string;
+}
+
+/**
+ * The master key as the dev secrets file states it, or the sentence saying why it could not be read.
+ *
+ * Through {@link devVarsForRegistry} and {@link masterKeyRegistryEntry} rather than by reaching into the
+ * envelope here: the entry is what says the value is an `EncryptionConfig` and that its binding carries
+ * the value rather than the envelope, and a second reading of that in this file is how the seeder and the
+ * store come to disagree about what the key is.
+ *
+ * **Nothing new is written here.** Every reader below already throws a `PithyError` naming the secret,
+ * the file, and the fix — `requireProjectName`, `readDevSecretsSource`, `loadDevSecrets`,
+ * `storedSecretValue`. The defect was never a missing message; it was a `catch` that threw four of them
+ * away. So this carries each one out verbatim, and a fifth reader gets its sentence for free.
+ */
+async function statedMasterKey(projectDir: string, paths: StatePathOptions): Promise<StatedMasterKey> {
+  // Resolved separately from the read, because a path that does not resolve is a different claim: the
+  // project has no name, so it has no secrets file, so nothing was ever recorded in one.
+  let path: string;
+  try {
+    path = await resolveDevSecretsFile(projectDir, paths);
+  } catch (error) {
+    // `unlocatable`, never `unreadable` (#325). There is no file here, so nothing has been stated, and
+    // an older home is still the honest place to look for the key.
+    return { unlocatable: `No ${MASTER_KEY_BINDING} recorded: ${sentenceOf(error)}` };
+  }
+
+  try {
+    const file = await readDevSecrets(path);
+    const value = devVarsForRegistry(file, { [MASTER_KEY_BINDING]: masterKeyRegistryEntry }, path)[MASTER_KEY_BINDING];
+    // An absent key in a readable file is the one state `No … recorded` is true of, so it is the one
+    // state that says nothing here and lets the caller's own sentence stand.
+    return value === undefined ? {} : { value };
+  } catch (error) {
+    return { unreadable: sentenceOf(error) };
+  }
+}

package/src/devSecrets/targets.ts

@@ -0,0 +1,204 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { join } from "node:path";
+import { PithyError } from "@pithy-sh/core/src/error/pithyError";
+import { isSecretsCapability } from "@pithy-sh/secrets/src/capability";
+import type { SecretRegistry } from "@pithy-sh/secrets/src/registry";
+import { aggregateSecretRegistries } from "@pithy-sh/secrets/src/sharedSecretsStore";
+import { loadWorkerConfig, type WorkerConfig } from "../project/config";
+import { resolveWorkers } from "../project/workerScope";
+import { discoverWorkers } from "../project/workers";
+import { ownProperties } from "./records";
+
+/**
+ * Which Workers a dev-secrets run acts on, and the registry each one resolves secrets through.
+ *
+ * **Its own module, because both ends of the run need it and one of them is upstream of the other.**
+ * `pithy seed` needs the targets to know where a `d1` value goes; the generator needs them to know which
+ * `cf-secrets-store` secrets to materialise into each Worker's `.dev.vars` (#179). With this in the
+ * seeder, the generator importing it closed a cycle — generator → seeder → writer → generator — and the
+ * answer to "which Workers, with which registry" is neither of their business to own privately.
+ */
+
+/** One Worker's contribution: its name, its directory, and the registry that decides its destinations. */
+export interface DevSecretsTarget {
+  /** The Worker's name — what a skipped reason names, so the adopter knows which one to fix. */
+  name: string;
+  /** The Worker's directory; its `wrangler.jsonc` declares the `SECRETS` binding. */
+  dir: string;
+  /** That Worker's secret registry. */
+  registry: SecretRegistry;
+}
+
+/** A Worker that has a `pithy.config.ts` and could not be asked what it declares. Never a value. */
+export interface UnresolvableWorker {
+  /** The Worker's name — what the report names, so the adopter knows which config to fix. */
+  name: string;
+  /** The Worker's directory. Its `.dev.vars` is the file that went without. */
+  dir: string;
+  /** Why the config did not import, already actionable. Reaches a terminal, so never `detail`. */
+  reason: string;
+}
+
+/**
+ * Which Workers declare secrets, **and which ones could not be asked** — the two answers that must not
+ * arrive as one (#199).
+ *
+ * **An array cannot say "and this one is broken", which is the whole defect.** `resolveWorkers` throws
+ * for a config that is present and will not import, deliberately: swallowing it prints "No workers here"
+ * for a project that plainly has workers. A lossy wrapper here caught that throw into `[]` — and
+ * `[]` is also what a project that never composed `secrets` returns. So every consumer read a config
+ * that would not load as a Worker that declares nothing. Since #179 that is not a cosmetic conflation:
+ * a `cf-secrets-store` secret is materialised only from the registry, so an empty registry means the
+ * generated `.dev.vars` is written down to its header and the Worker starts with **no bindings at all**.
+ * `pithy dev` did exactly that and printed `Starting replay-board.` and nothing else.
+ *
+ * Behavior is unchanged and correct — a registry nobody can read has no honest answer, and the old
+ * answer came from the `dev.json` copy #179 exists to delete. What changes is that the failure is now a
+ * field rather than an absence, so a caller has to drop it on purpose instead of by taking the only
+ * thing there was to take.
+ *
+ * **Resolved one Worker at a time, so a failure costs exactly one.** `resolveWorkers`' fan-out throws on
+ * the first bad config, which took every healthy sibling's registry with it: a project with two Workers
+ * lost both because one of them had a typo. Discovery happens once and the single-Worker path — the same
+ * `pick`-then-load `resolveWorkers` already owns, seams included — is driven per target.
+ *
+ * **A missing `pithy.config.ts` is skipped, not reported.** A Vite frontend joining the dev set through
+ * `pithy.worker.jsonc` alone has no config and declares nothing; that is the ordinary state, not a
+ * failure, and reporting it would put a permanent warning in front of every project with a frontend.
+ * Exactly `core/not_found`, which is the code {@link loadWorkerConfig} raises for the absent file and
+ * nothing else — the same rule, and the same test, `resolveWorkers`' own loop applies.
+ *
+ * **The registry is the aggregate, not the secrets capability's own slice.** `aggregateSecretRegistries`
+ * is the exact call the Worker makes at composition: every capability contributes the secrets it owns,
+ * and `auth-session-secret` is auth's declaration, not something an adopter re-types into
+ * `secrets({ registry })`. Reading only the secrets capability's slice seeded nothing in a real project
+ * and threw outright in a scaffolded one, where `pithy add secrets` writes `secrets({ rotationIntervalDays })`
+ * and leaves `registry` for the adopter — so the slice is `undefined` on a config the CLI itself wrote.
+ */
+export async function resolveDevSecretsTargets(
+  projectDir: string,
+  options: DevSecretsTargetsOptions = {},
+): Promise<DevSecretsResolution> {
+  // Never throws. A directory that is not a project has no workers, no secrets, and nothing to report —
+  // `pithy add` runs this wherever the adopter is standing, and refusing there would fail a command that
+  // has nothing to do. That is the one absence this module is still allowed to answer with silence.
+  const discovered = await discoverWorkers(projectDir).catch(() => []);
+  const scoped =
+    options.worker === undefined
+      ? discovered
+      : discovered.filter((target) => target.name === options.worker || target.dir.endsWith(`/${options.worker}`));
+
+  const targets: DevSecretsTarget[] = [];
+  const unresolvable: UnresolvableWorker[] = [];
+  for (const target of scoped) {
+    const [resolved] = await resolveWorkers({
+      projectDir,
+      worker: target.name,
+      // Discovery is already done; this hands `resolveWorkers` the one target so its single-Worker path
+      // loads exactly this config and its failure belongs to exactly this Worker.
+      discoverWorkers: async () => [target],
+      ...(options.reload ? { loadConfig: reloadWorkerConfig } : {}),
+    }).catch((error: unknown) => {
+      if (error instanceof PithyError && error.payload.code === "core/not_found") return [];
+      unresolvable.push({ name: target.name, dir: target.dir, reason: messageOf(error) });
+      return [];
+    });
+    if (!resolved) continue;
+    if (!resolved.capabilities.some(isSecretsCapability)) continue;
+    targets.push({
+      name: resolved.name,
+      dir: resolved.dir,
+      // Prototype-free, so `registry[name]` here and in every consumer — `pithy doctor` included — is an
+      // own-property lookup for a secret a capability chose to call `constructor`. See {@link ownProperties}.
+      registry: ownProperties(aggregateSecretRegistries(resolved.capabilities)),
+    });
+  }
+  return { targets, unresolvable };
+}
+
+/** Both halves of one resolution: what declared secrets, and what could not be asked. */
+export interface DevSecretsResolution {
+  /** Every Worker that composes `secrets`, with the registry it resolves them through. */
+  targets: DevSecretsTarget[];
+  /** Every Worker with a `pithy.config.ts` that would not import, and why. Empty on an ordinary run. */
+  unresolvable: UnresolvableWorker[];
+}
+
+/**
+ * One actionable sentence from a thrown failure.
+ *
+ * `message` and `action` together, never `detail`: `detail` is throw-site context — for
+ * {@link loadWorkerConfig} it is the raw module-resolution error — and these lines reach a terminal and
+ * `logs/dev.log`.
+ */
+function messageOf(error: unknown): string {
+  if (error instanceof PithyError) return `${error.payload.message} ${error.payload.action ?? ""}`.trim();
+  return error instanceof Error ? error.message : String(error);
+}
+
+/** How {@link resolveDevSecretsTargets} narrows and how it loads. Both default to the whole project, cached. */
+export interface DevSecretsTargetsOptions {
+  /** Narrow to one Worker, by the name `pithy worker list` shows or its `apps/<dir>` basename. */
+  worker?: string;
+  /**
+   * Re-import each `pithy.config.ts` rather than taking the module this process already holds.
+   *
+   * For **`pithy add`, and only for it.** That command rewrites the Worker's config and then seeds, in
+   * one process that imported the config before the write — so the aggregate registry it seeds against
+   * is the composition from *before* the add, and the secret the same run has just minted never
+   * reaches the store. The next unrelated command picked it up, which made it look like a store
+   * problem rather than a stale module.
+   *
+   * Off by default because it is not free: every reload adds a module instance to the ESM registry for
+   * the life of the process, and re-runs the config's top-level code. `pithy dev` and `pithy seed` load
+   * the config once and never rewrite it, so they have nothing stale to correct.
+   */
+  reload?: boolean;
+  /** **Unsayable on purpose (#159).** Targets are the project's own Workers; there is no environment. */
+  env?: never;
+}
+
+/** Distinguishes one reload from the next, so two in a process both get a module and not the first one twice. */
+let reloadCount = 0;
+
+/**
+ * Every target's registry, merged by secret name — the same join `pithy secrets` does.
+ *
+ * One function rather than one per command, because a secret's registry entry is what says how its value
+ * is shaped, and two merges is two answers to that (#323). Later targets win on a repeated name, which is
+ * the state `pithy doctor` reports rather than one this has an opinion about.
+ */
+export function mergedSecretRegistry(targets: readonly DevSecretsTarget[]): SecretRegistry {
+  const merged: SecretRegistry = {};
+  for (const target of targets) for (const [name, entry] of Object.entries(target.registry)) merged[name] = entry;
+  return merged;
+}
+
+/**
+ * One Worker's `pithy.config.ts`, imported past the ESM module cache with a query the resolver ignores
+ * and the cache key does not.
+ *
+ * **The specifier is the absolute path, not `pathToFileURL`, and that is load-bearing under Bun.** Bun
+ * honors the query as part of the cache key for a path specifier and ignores it for a `file://` URL:
+ * `import("/abs/pithy.config.ts?v=2")` re-evaluates, `import("file:///abs/pithy.config.ts?v=2")` hands
+ * back the first instance. The URL form is what {@link loadWorkerConfig} uses and is right there — it
+ * *wants* the cache. Written the same way here, `pithy add auth` seeded nothing and said nothing about
+ * it, because the fallback below silently returned the stale module. Vitest's module runner busts on
+ * either form, so no unit test can tell the two apart; the CLI itself was what caught it.
+ *
+ * Every failure falls back to {@link loadWorkerConfig}, which owns the two actionable errors — a config
+ * that is absent, and one that will not import — so nothing here has to restate them, and a config that
+ * loads clean but exports the wrong shape is answered by the same message it always was.
+ */
+async function reloadWorkerConfig(workerDir: string): Promise<WorkerConfig> {
+  const path = join(workerDir, "pithy.config.ts");
+  reloadCount += 1;
+  const module = await import(`${path}?pithy-reload=${reloadCount}`).catch(() => null);
+  const config: unknown = module?.default;
+  if (config === null || typeof config !== "object" || !Array.isArray((config as WorkerConfig).capabilities)) {
+    return loadWorkerConfig(workerDir);
+  }
+  return config as WorkerConfig;
+}

package/src/dispatch.ts

@@ -0,0 +1,147 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { CommandDef } from "citty";
+
+/**
+ * **A command that names no action is asking what it can do. Answering it is a success.**
+ *
+ * That is the rule, stated once, for every level of the tree. `pithy` is somebody's first day; `pithy
+ * secrets` is the same question one level down. Both are answered by a command list, and a command list
+ * is the right answer, so neither is an error.
+ *
+ * citty disagrees, structurally. `runCommand` throws `E_NO_COMMAND` whenever a command declares
+ * `subCommands`, receives no subcommand name, has no `default`, and has no `run` of its own — and
+ * `runMain` catches every `CLIError` the same way: print the usage, echo the message, `process.exit(1)`.
+ * So the bare invocation printed a complete command list and then said `No command specified.` under it,
+ * arguing with a user it had just served, and exited non-zero — which fails `pithy && next`, fails a CI
+ * step, and under `bun run` adds `error: script "pithy" exited with code 1` as the loudest and least
+ * informative line on screen (#319).
+ *
+ * **One rule, one place.** Fifteen commands take that path — the root and fourteen groups — and giving
+ * each of them a `run` would be fifteen producers of one rule, plus a subtlety that guarantees drift:
+ * citty runs a parent's `run` *after* dispatching to a subcommand, so each would need to know whether it
+ * had been dispatched through. This module answers the question before citty is asked, so a group added
+ * next year inherits the rule with nothing to remember.
+ *
+ * What is **not** covered, deliberately: a name that is not a command. `pithy nonsense` is a mistake, not
+ * a question, and citty's own `E_UNKNOWN_COMMAND` already names it, shows the help, and exits non-zero.
+ * The walk stops at the first token it cannot resolve and hands the whole invocation back untouched.
+ *
+ * **Reaching that path requires the tree to answer only to the names it declares**, which an object
+ * literal does not — see {@link ownNamesOnly}.
+ */
+
+/** A command and the parent it was reached through — what citty's `showUsage` takes. */
+export interface UsageTarget {
+  /** The command whose usage to render. */
+  cmd: CommandDef;
+  /** Its parent, so the rendered line reads `pithy secrets` rather than `secrets`. Absent at the root. */
+  parent?: CommandDef;
+}
+
+/** citty's lazy subcommand value: a definition, a promise of one, or a thunk returning either. */
+type SubCommand = CommandDef | Promise<CommandDef> | (() => CommandDef | Promise<CommandDef>);
+
+/** Resolve one of citty's three subcommand spellings to a definition. */
+async function resolve(value: SubCommand): Promise<CommandDef> {
+  return typeof value === "function" ? await value() : await value;
+}
+
+/**
+ * The same command tree, answering only to the names it declares.
+ *
+ * A `subCommands` is an object literal, so `Object.prototype` is a member of every lookup at every level
+ * — and citty resolves a subcommand with `name in subCommands`, then calls the value when it is a
+ * function. `pithy valueOf` therefore called `Object.prototype.valueOf` with no receiver and died on a
+ * raw `TypeError` under a crash banner, and `pithy constructor` called `Object`, took the `{}` it
+ * returned for a command definition, ran nothing at all, and exited **0**. Neither name is a command.
+ * Both belong on the path `pithy nonsense` takes.
+ *
+ * Copying each record onto a null prototype is the whole fix: an inherited name resolves to nothing, and
+ * citty's `E_UNKNOWN_COMMAND` names it and exits non-zero exactly as it does for a typo. Done here, once,
+ * rather than at the twenty-six `defineCommand` calls — the same reason the usage rule is: a group
+ * added next year inherits it with nothing to remember. **Laziness survives**: a thunk is wrapped, never
+ * called, so the imports this tree defers stay deferred until a name is actually walked into.
+ */
+export function ownNamesOnly(cmd: CommandDef): CommandDef {
+  const declared = cmd.subCommands;
+  if (declared === undefined) return cmd;
+  return {
+    ...cmd,
+    subCommands: async () => {
+      const subCommands = (typeof declared === "function" ? await declared() : await declared) as Record<
+        string,
+        SubCommand
+      >;
+      const own: Record<string, SubCommand> = Object.create(null);
+      for (const [name, value] of Object.entries(subCommands))
+        own[name] = async () => ownNamesOnly(await resolve(value));
+      return own;
+    },
+  } as CommandDef;
+}
+
+/**
+ * Find a subcommand by the name the user typed, matching citty's own lookup: the key first, then any
+ * command whose `meta.alias` claims the name.
+ *
+ * **The key is an own name or it is not a name.** `subCommands[name]` alone answers `valueOf` and
+ * `constructor` with `Object.prototype`'s members, which is the hole {@link ownNamesOnly} closes for
+ * citty; this walk states the same rule for itself, because it is exported and takes any `CommandDef` —
+ * including one nobody hardened.
+ *
+ * Resolving every sibling to read its alias costs the lazy imports this tree exists to avoid, so the key
+ * is tried first and the alias scan only runs when it misses — which is the miss path already, and the
+ * path that ends in "unknown command" either way.
+ */
+async function findSubCommand(subCommands: Record<string, SubCommand>, name: string): Promise<CommandDef | undefined> {
+  const direct = Object.hasOwn(subCommands, name) ? subCommands[name] : undefined;
+  if (direct !== undefined) return resolve(direct);
+  for (const value of Object.values(subCommands)) {
+    const candidate = await resolve(value);
+    const meta = typeof candidate.meta === "function" ? await candidate.meta() : await candidate.meta;
+    const alias = meta?.alias;
+    if (alias === name || (Array.isArray(alias) && alias.includes(name))) return candidate;
+  }
+  return undefined;
+}
+
+/** Whether a command can act on its own — through its own `run`, or by defaulting to a subcommand. */
+function actsOnItsOwn(cmd: CommandDef): boolean {
+  return typeof cmd.run === "function" || cmd.default !== undefined;
+}
+
+/**
+ * The command whose usage answers this invocation, or `null` when the invocation names an action and
+ * belongs to citty.
+ *
+ * Flags are skipped rather than resolved: only commands that dispatch are walked into, and a dispatching
+ * command in this tree declares no `args` of its own, so a leading `-` is a builtin (`--help`,
+ * `--version`) or a flag for a group that has none. The walk stops the moment a token resolves to
+ * nothing, so an unknown command reaches citty exactly as before.
+ */
+export async function usageTarget(root: CommandDef, argv: readonly string[]): Promise<UsageTarget | null> {
+  let cmd = root;
+  let parent: CommandDef | undefined;
+
+  for (const token of argv) {
+    if (token.startsWith("-")) continue;
+    const subCommands = (typeof cmd.subCommands === "function" ? await cmd.subCommands() : await cmd.subCommands) as
+      | Record<string, SubCommand>
+      | undefined;
+    if (!subCommands) return null;
+    const next = await findSubCommand(subCommands, token);
+    // An unknown name is a mistake, not a question. Hand it back — citty names it and exits non-zero.
+    if (!next) return null;
+    parent = cmd;
+    cmd = next;
+  }
+
+  const subCommands = (typeof cmd.subCommands === "function" ? await cmd.subCommands() : await cmd.subCommands) as
+    | Record<string, SubCommand>
+    | undefined;
+  if (!subCommands || Object.keys(subCommands).length === 0) return null;
+  if (actsOnItsOwn(cmd)) return null;
+  return parent === undefined ? { cmd } : { cmd, parent };
+}