@pithy-sh/cli 0.1.0

package/src/feature/worktree.ts

@@ -0,0 +1,282 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { execFile } from "node:child_process";
+import { existsSync, readdirSync, rmSync } from "node:fs";
+import { realpath } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { ConflictError, InternalError } from "@pithy-sh/core/src/error/pithyError";
+
+const run = promisify(execFile);
+
+/**
+ * The git worktree/branch core behind `pithy feature create`/`destroy`. It is the same proven shape as
+ * the repo's `scripts/worktree.ts` — compose `feature/<issue>-<slug>` + `.worktrees/<issue>-<slug>` from
+ * the issue and slug, attach-or-cut the branch, and tear down the Linux-safe way (`rm .git` +
+ * `git worktree prune`, never `rm -rf`/`git worktree remove`, which trigger inotify storms on Linux) —
+ * ported into the CLI: async (no `execFileSync`), runtime- and package-manager-agnostic, and free of the
+ * `.dev.vars` symlinking, which the richer consolidated composition (`devVars.ts`) supersedes.
+ */
+
+/** Runs git and returns trimmed stdout; throws on a non-zero exit. Injectable so tests fake git. */
+export type GitRunner = (args: string[], cwd?: string) => Promise<string>;
+
+/** The default git runner — shells out to the system `git`. */
+export const defaultGit: GitRunner = async (args, cwd) => {
+  const { stdout } = await run("git", args, cwd ? { cwd } : {});
+  return stdout.trim();
+};
+
+/** Run git, swallow the error, and report whether it succeeded — for best-effort steps. */
+async function gitTry(git: GitRunner, args: string[], cwd?: string): Promise<boolean> {
+  try {
+    await git(args, cwd);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** The composed names for a feature: the branch, the worktree dir name, and its absolute path. */
+export interface FeatureNames {
+  /** The feature branch, `feature/<issue>-<slug>`. */
+  branch: string;
+  /** The worktree directory name, `<issue>-<slug>`. */
+  dir: string;
+  /** The absolute worktree path, `<root>/.worktrees/<issue>-<slug>`. */
+  wtPath: string;
+}
+
+/** Compose the branch, dir, and worktree path for an issue + slug under a main-checkout root. */
+export function featureNames(issue: string, slug: string, root: string): FeatureNames {
+  const dir = `${issue}-${slug}`;
+  return { branch: `feature/${issue}-${slug}`, dir, wtPath: join(root, ".worktrees", dir) };
+}
+
+/**
+ * One spelling of a repository path, whoever asked and however they got there.
+ *
+ * **Two things derive the main checkout's root and they must agree, because it is a registry key now**
+ * (#435): {@link mainRepoRoot} below, off `git worktree list`, and `resolveMainRepoRoot` in `ports.ts`,
+ * off `git rev-parse --git-common-dir`. Under the old design both were a *place to put a file* and any
+ * two spellings of one directory addressed the same file, so a difference could not be observed. As keys
+ * they are two entries for one repository — `pithy feature create` reserving under one while `destroy`
+ * frees under the other, `freePortBlock` no-opping, and `portsFreed: true` reported over a block that
+ * leaks forever.
+ *
+ * They diverge two ways, one per platform, and neither shows up in CI (every job is `ubuntu-24.04`).
+ * On POSIX, `--git-common-dir` answers `.git` and resolving that against the working directory keeps
+ * whatever symlinks were walked to get there, while `worktree list` always reports the real path. On
+ * **Windows** git emits forward slashes — `C:/code/app` — while `dirname`/`realpath` give `C:\code\app`.
+ * `realpath` settles both: it resolves the links and returns the platform's own separators.
+ *
+ * A failure is not worth refusing a command over — the path came from git, so it exists — and the
+ * uncanonicalised answer stands in.
+ */
+export function canonicalRepoPath(path: string): Promise<string> {
+  return realpath(path).catch(() => path);
+}
+
+/**
+ * The main checkout's root. The first `git worktree list` entry is always the primary worktree, so this
+ * resolves the same path whether invoked from the root or from inside another worktree.
+ *
+ * Canonicalised through {@link canonicalRepoPath}, which is what makes it the *same string* as the other
+ * derivation rather than merely the same directory.
+ */
+export async function mainRepoRoot(git: GitRunner = defaultGit): Promise<string> {
+  const first = (await git(["worktree", "list", "--porcelain"])).split("\n")[0] ?? "";
+  const path = first.startsWith("worktree ") ? first.slice("worktree ".length) : "";
+  if (!path) {
+    throw new InternalError({
+      message: "Could not resolve the main repository root.",
+      action: "Run pithy feature from inside a git repository.",
+    });
+  }
+  return canonicalRepoPath(path);
+}
+
+/** Whether a worktree is registered at this absolute path. */
+async function isRegistered(git: GitRunner, wtPath: string): Promise<boolean> {
+  return (await git(["worktree", "list", "--porcelain"])).split("\n").some((line) => line === `worktree ${wtPath}`);
+}
+
+/**
+ * Whether a non-empty, unregistered directory already sits at `wtPath` — the leftover files a prior
+ * {@link teardownWorktree} deliberately left behind. `git worktree add` refuses to write into such a
+ * directory, so this is checked first to fail with an actionable error instead of a raw git one.
+ */
+function hasLeftoverFiles(wtPath: string): boolean {
+  if (!existsSync(wtPath)) return false;
+  return readdirSync(wtPath).length > 0;
+}
+
+/** Run git for its output, or `null` when it fails. The `gitTry` of answers rather than of exit codes. */
+async function gitOut(git: GitRunner, args: string[], cwd?: string): Promise<string | null> {
+  try {
+    const out = (await git(args, cwd)).trim();
+    return out === "" ? null : out;
+  } catch {
+    return null;
+  }
+}
+
+/** Whether a ref exists locally or on origin. */
+async function branchExists(git: GitRunner, branch: string, cwd?: string): Promise<boolean> {
+  return (
+    (await gitTry(git, ["rev-parse", "--verify", "--quiet", `refs/heads/${branch}`], cwd)) ||
+    (await gitTry(git, ["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${branch}`], cwd))
+  );
+}
+
+/**
+ * The name of this repository's trunk — `main` unless the remote says otherwise.
+ *
+ * **Read from `origin/HEAD`, which is the remote's answer to "what is the default branch".** Only the
+ * *name* comes from the remote; the ref cut from is always the local branch of that name. A repository
+ * whose trunk is `master` and which also carries a stale local `main` — a rename left behind, a fork —
+ * would otherwise have every feature cut from the stale one, silently, which is `#454` again in a
+ * different shape.
+ *
+ * `main` when there is no remote to ask. That is this project family's convention and what
+ * `scripts/worktree.ts` has always assumed; a repository with no remote and a non-`main` trunk is the
+ * one case still open, and it resolves through {@link baseRef}'s fallback rather than guessing.
+ */
+async function trunkName(git: GitRunner): Promise<string> {
+  const named = await gitOut(git, ["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"]);
+  return named === null ? "main" : named.replace(/^origin\//, "");
+}
+
+/**
+ * The trunk to cut a fresh feature branch from: the local trunk branch when it exists, else `HEAD`.
+ *
+ * **Local, never `origin/<trunk>` — `#454`.** It preferred the remote whenever the ref existed, which meant
+ * a feature cut on a repository holding unpushed work started before that work. On `pithy-sh/dashboard`
+ * that was 159 commits, and the symptom was a config error naming a field the branch was too old to have —
+ * a sentence that says nothing about the base it was cut from. Where the old config still parses there is
+ * no symptom at all: the branch is simply rooted in the past, and the operator learns at merge.
+ *
+ * A remote that is *ahead* is the ordinary case and not this function's business: cutting from a trunk that
+ * is a few commits behind is usually fine and sometimes deliberate. {@link behindRemote} is how the operator
+ * gets told, because being told is what stops it becoming a surprise at merge time.
+ */
+async function baseRef(git: GitRunner): Promise<string> {
+  const trunk = await trunkName(git);
+  return (await gitTry(git, ["rev-parse", "--verify", "--quiet", `refs/heads/${trunk}`])) ? trunk : "HEAD";
+}
+
+/**
+ * How many commits the local trunk is behind its remote, or `null` when the question does not arise —
+ * no remote ref, no local trunk, or nothing behind.
+ *
+ * Reported rather than refused, and the caller decides how to say it. A repository with no `origin` is the
+ * ordinary case for a fresh `pithy init`, and a count of zero is the ordinary case for everybody else.
+ */
+export async function behindRemote(git: GitRunner = defaultGit): Promise<number | null> {
+  const trunk = await trunkName(git);
+  if (!(await gitTry(git, ["rev-parse", "--verify", "--quiet", `refs/remotes/origin/${trunk}`]))) return null;
+  if (!(await gitTry(git, ["rev-parse", "--verify", "--quiet", `refs/heads/${trunk}`]))) return null;
+  const behind = Number.parseInt(await git(["rev-list", "--count", `${trunk}..origin/${trunk}`]), 10);
+  return Number.isFinite(behind) && behind > 0 ? behind : null;
+}
+
+/** The outcome of {@link createWorktree}: the composed names and whether a new worktree was created. */
+export interface CreateWorktreeResult extends FeatureNames {
+  /** The main checkout root the worktree lives under. */
+  root: string;
+  /** True when a new worktree was created; false when one already existed (idempotent re-run). */
+  created: boolean;
+  /**
+   * The ref a fresh branch was cut from — the trunk's name, or `"HEAD"`. **Null when nothing was cut**:
+   * an already-registered worktree, or a branch that already existed and was attached to.
+   *
+   * A caller reporting a base has to know that difference. `feature create` prints how far the trunk is
+   * behind its remote, and on the attach path that sentence would be about a branch somebody else cut
+   * months ago — a false sentence about a base, which is the thing `#454` is about.
+   */
+  base: string | null;
+}
+
+/**
+ * Create the feature's branch and worktree, or no-op if the worktree is already registered. Attaches to
+ * the branch when it already exists (a re-run after teardown left the branch behind); otherwise cuts a
+ * fresh one from the trunk. Idempotent **only** while the worktree stays registered — a re-run after
+ * {@link teardownWorktree} (which deliberately leaves the files on disk) fails with an actionable
+ * `ConflictError` instead of a raw git error, because those leftover files must not be recursively
+ * deleted on Linux (CLAUDE.md).
+ */
+export async function createWorktree(options: {
+  issue: string;
+  slug: string;
+  git?: GitRunner;
+}): Promise<CreateWorktreeResult> {
+  const git = options.git ?? defaultGit;
+  const root = await mainRepoRoot(git);
+  const names = featureNames(options.issue, options.slug, root);
+
+  if (await isRegistered(git, names.wtPath)) {
+    return { ...names, root, created: false, base: null };
+  }
+
+  if (hasLeftoverFiles(names.wtPath)) {
+    throw new ConflictError({
+      message: `${names.wtPath} already exists and is not empty.`,
+      action:
+        "A previous 'pithy feature destroy' left these files on disk by design. Once no file watcher or editor " +
+        `has it open, remove the directory yourself (rm -r ${names.wtPath}) and re-run 'pithy feature create'.`,
+      detail: `git worktree add would fail: ${names.wtPath} is an unregistered, non-empty directory.`,
+    });
+  }
+
+  if (await branchExists(git, names.branch)) {
+    // Attached, not cut. The branch already exists — pushed by a colleague, or left behind by a teardown —
+    // so its base is whatever it was cut from, months ago and by somebody else. Nothing about this trunk.
+    await git(["worktree", "add", names.wtPath, names.branch]);
+    return { ...names, root, created: true, base: null };
+  }
+  const base = await baseRef(git);
+  await git(["worktree", "add", names.wtPath, "-b", names.branch, base]);
+  return { ...names, root, created: true, base };
+}
+
+/** The outcome of {@link teardownWorktree}: what was actually removed. */
+export interface TeardownWorktreeResult extends FeatureNames {
+  /** True when a registered worktree was pruned. */
+  pruned: boolean;
+  /** True when the local branch was deleted (a merged branch); false when kept (unmerged) or absent. */
+  branchDeleted: boolean;
+}
+
+/**
+ * Tear down the feature's worktree the Linux-safe way and drop its branch. Drops the gitlink then prunes
+ * the registration — never `rm -rf` or `git worktree remove`, whose recursive delete over a node_modules
+ * tree triggers inotify storms that crash the box (CLAUDE.md). Files remain on disk by design (the dir is
+ * git-ignored). The lowercase `-d` refuses an unmerged branch, so an open feature keeps its branch.
+ * Idempotent for repeated teardowns: nothing registered / no branch is a clean no-op. Recreating the same
+ * feature afterwards is **not** automatically idempotent — the leftover files on disk make
+ * {@link createWorktree} fail loudly until an operator clears them; see its docstring.
+ */
+export async function teardownWorktree(options: {
+  issue: string;
+  slug: string;
+  git?: GitRunner;
+}): Promise<TeardownWorktreeResult> {
+  const git = options.git ?? defaultGit;
+  const root = await mainRepoRoot(git);
+  const names = featureNames(options.issue, options.slug, root);
+
+  let pruned = false;
+  if (await isRegistered(git, names.wtPath)) {
+    const gitlink = join(names.wtPath, ".git");
+    if (existsSync(gitlink)) rmSync(gitlink);
+    await git(["worktree", "prune"], root);
+    pruned = true;
+  }
+
+  let branchDeleted = false;
+  if (await gitTry(git, ["rev-parse", "--verify", "--quiet", `refs/heads/${names.branch}`], root)) {
+    branchDeleted = await gitTry(git, ["branch", "-d", names.branch], root);
+  }
+  return { ...names, pruned, branchDeleted };
+}

package/src/help/groups.ts

@@ -0,0 +1,47 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { SubCommandsDef } from "citty";
+
+/**
+ * The groups the root help screen prints, in the order it prints them (#407).
+ *
+ * **A presentation grouping, and only that.** Nothing dispatches through it, no invocation carries a
+ * group segment, and `pithy email provision` is still `pithy email provision`. Putting the group in the
+ * command path would rename nine commands, add a segment to every doc page and every agent's call, and
+ * buy a screen what a blank line already buys it. It is also not the same concept as `dispatch.test.ts`'s
+ * groups — commands that declare subcommands and cannot act — and neither is derived from the other.
+ *
+ * **The group is declared on the command, not in a list beside it.** A second list of the command set is
+ * a list that drifts, and the drift has a direction that matters: a command added to the tree and
+ * forgotten here would not break, it would *disappear* — from the one screen whose whole job is to say
+ * what the CLI can do. So `main.ts` carries `group` as a **required** field on every entry, this type is
+ * what that field must be, and a command with no group or a misspelled one is a compile error rather
+ * than something a test has to notice. There is no catch-all group, because there is nothing to catch.
+ */
+export const HELP_GROUP_ORDER = ["Project", "Develop", "Operate", "Capabilities", "Toolchain"] as const;
+
+/** One of {@link HELP_GROUP_ORDER}. The type `main.ts`'s `group` field takes. */
+export type HelpGroup = (typeof HELP_GROUP_ORDER)[number];
+
+/**
+ * How a command module is loaded — a thunk, so the tree stays as lazy as it was.
+ *
+ * Typed through citty's own `SubCommandsDef` rather than `CommandDef`. A command declares its own `args`,
+ * so its type is `CommandDef<ThoseArgs>`, and `run` puts that parameter in contravariant position — which
+ * makes `CommandDef<SpecificArgs>` unassignable to `CommandDef<ArgsDef>`. citty resolves this in the one
+ * place it has to, on the element type of `subCommands`; this borrows that resolution instead of writing
+ * a second one — `CittyCommand` lifts that element type out without this file naming `any` itself.
+ * Keeping the `() => Promise<…>` wrapper is what still requires a thunk.
+ */
+type CittyCommand = Awaited<Extract<SubCommandsDef[string], Promise<unknown>>>;
+
+export type CommandLoader = () => Promise<CittyCommand>;
+
+/** One command in the root's registry: which group it prints under, and how to load it. */
+export interface CommandEntry {
+  /** The heading this command prints under. Required: that is the whole mechanism. */
+  group: HelpGroup;
+  /** The command module, imported on demand. */
+  load: CommandLoader;
+}

package/src/help/rootUsage.ts

@@ -0,0 +1,135 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import type { ArgsDef, CommandDef } from "citty";
+import { COMMAND_REGISTRY } from "../main";
+import { bold, cyan, dim, heading } from "../terminal/style";
+import { HELP_GROUP_ORDER } from "./groups";
+
+/**
+ * The root help screen — the one screen of help Pithy renders rather than hosts (#407).
+ *
+ * citty listed twenty-six commands in declaration order under one heading, behind a `USAGE` line that
+ * alternated every name before a single description appeared. Nothing on it said `email`, `media` and
+ * `turnstile` are the same kind of thing and `deploy` is not, and the list only grows: every capability
+ * that lands adds a row. So the root screen groups them, and every screen below it stays citty's.
+ *
+ * **Only the root.** `pithy add --help`, `pithy secrets`, and the screen after an unknown name one level
+ * down are citty's `renderUsage`, byte for byte — §4.2's transcript is pinned against it. The seam is
+ * `parent === undefined`, which `dispatch.ts` establishes is true of the root and nothing else.
+ *
+ * **The grouping is read off the command registry, not off a table beside it.** `main.ts` declares every
+ * command with a required `group`, so there is no ungrouped state to render and no second list to drift
+ * from the first — see `groups.ts`. A group with no members prints no heading rather than an empty one.
+ *
+ * **The shapes are citty's on purpose.** Same right-aligned name column, same four-space gutter, same
+ * closing pointer. The two screens sit one keystroke apart, and a root screen that repainted itself
+ * would read as a different program. What changes is the grouping and the `USAGE` line.
+ *
+ * **Nothing here reads the terminal.** No `process.stdout.columns`, no `COLUMNS`: the layout is a pure
+ * function of the command tree, which is what lets `binDocs.test.ts` pin the whole screen byte for byte
+ * against `docs/CLI.md` §4.1 and get the same answer on every machine.
+ *
+ * **Color goes through `terminal/style.ts` and nowhere else** (docs/CLI.md §3.4). That is also the whole
+ * mechanism behind §4.3's claim that piped root help is plain: `bin.test.ts` asserts no escape byte with
+ * every color signal scrubbed, and an escape byte under `FORCE_COLOR`, and only the seam satisfies both.
+ */
+
+/** Two spaces of indent, then the name column, then the gutter — citty's `formatLineColumns` shape. */
+const INDENT = "  ";
+const GUTTER = "    ";
+
+/** A resolved subcommand: the label its row prints, and every name the `USAGE` line must list. */
+interface Entry {
+  /** The row's left column — the name, plus any aliases, comma-joined. citty's rule. */
+  label: string;
+  /** The command's own name, for grouping. */
+  name: string;
+  /** `meta.description`, or empty when it declares none. */
+  description: string;
+}
+
+/** citty allows `meta` to be a value, a promise, or a thunk. Resolve all three the way it does. */
+async function resolve<T>(value: T | Promise<T> | (() => T | Promise<T>)): Promise<T> {
+  return typeof value === "function" ? await (value as () => T | Promise<T>)() : await value;
+}
+
+/** Everything citty would put in the `COMMANDS` block, resolved from the lazy tree, in declaration order. */
+async function entries<T extends ArgsDef>(cmd: CommandDef<T>): Promise<Entry[]> {
+  const subCommands = await resolve(cmd.subCommands);
+  if (subCommands === undefined) return [];
+  const resolved = await Promise.all(
+    Object.entries(subCommands).map(async ([name, value]) => {
+      const sub = await resolve(value as CommandDef | (() => Promise<CommandDef>));
+      const meta = (await resolve(sub.meta)) ?? {};
+      // `hidden` is skipped from the rows *and* from the USAGE line — citty's `continue` precedes its
+      // own `commandNames.push`. Nothing declares it today; the rule is preserved rather than dropped.
+      if (meta.hidden === true) return null;
+      const alias = meta.alias === undefined ? [] : Array.isArray(meta.alias) ? meta.alias : [meta.alias];
+      return { label: [name, ...alias].join(", "), name, description: meta.description ?? "" };
+    }),
+  );
+  return resolved.filter((entry): entry is Entry => entry !== null);
+}
+
+/**
+ * The whole screen, as one string with no trailing newline.
+ *
+ * A pure function of the tree so a test can call it without spawning anything, and so the byte-for-byte
+ * pin has one thing to compare. Exported for `rootUsage.test.ts`; `bin.ts` goes through {@link showRootUsage}.
+ */
+export async function renderRootUsage<T extends ArgsDef = ArgsDef>(cmd: CommandDef<T>): Promise<string> {
+  const meta = (await resolve(cmd.meta)) ?? {};
+  const name = meta.name ?? "pithy";
+  const found = await entries(cmd);
+
+  // Width is the widest label across every command, not per group: the columns line up down the whole
+  // screen, which is what makes it read as one table with headings rather than five small ones.
+  const width = found.reduce((max, entry) => Math.max(max, entry.label.length), 0);
+
+  const lines: string[] = [
+    dim(`${meta.description ?? ""} (${name}${meta.version === undefined ? "" : ` v${meta.version}`})`),
+    "",
+    // No alternation. Twenty-six names before the first description was never information, and the line
+    // was already wider than a terminal.
+    `${bold("USAGE")} ${cyan(`${name} <command> [OPTIONS]`)}`,
+    "",
+    bold("COMMANDS"),
+  ];
+
+  const row = (entry: Entry): string =>
+    // Pad the plain label and colorize after. citty pads the already-colored string; the visible result
+    // is identical and the plain bytes — the only ones pinned — are identical too.
+    `${INDENT}${" ".repeat(width - entry.label.length)}${cyan(entry.label)}${GUTTER}${entry.description}`;
+
+  for (const group of HELP_GROUP_ORDER) {
+    // Registry order inside a group, which is `main.ts`'s declaration order — the file is written in the
+    // order this prints, so the screen and the registry read the same way down the page.
+    const members = found.filter((entry) => COMMAND_REGISTRY[entry.name]?.group === group);
+    if (members.length === 0) continue;
+    lines.push("", `${INDENT}${heading(group)}`);
+    for (const entry of members) lines.push(row(entry));
+  }
+
+  lines.push("", `Use ${cyan(`${name} <command> --help`)} for more information about a command.`);
+  return lines.join("\n");
+}
+
+/**
+ * Print the root screen. `showUsage`-shaped so `bin.ts` can hand one function to both of citty's paths.
+ *
+ * `process.stdout.write` rather than `console.log`: `plugins/no-console.grit` covers `packages/*​/src/**`
+ * and citty's own `showUsage` is a `console.log`, so copying it would fail the Lint job.
+ */
+export async function showRootUsage<T extends ArgsDef = ArgsDef>(cmd: CommandDef<T>): Promise<void> {
+  // Caught for the same reason citty catches in its own `showUsage`, and it matters more here: this is
+  // installed as `runMain`'s `showUsage`, so it runs *inside* citty's `CLIError` handler. Rendering
+  // resolves all twenty-six command modules, and a module that rejects at import would throw out of that
+  // handler — turning `pithy` and `pithy nonsense` into an unhandled-rejection stack instead of a help
+  // screen, which is the crash-banner failure #329 removed. stderr, and the run still ends.
+  try {
+    process.stdout.write(`${await renderRootUsage(cmd)}\n`);
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  }
+}

package/src/main.ts

@@ -0,0 +1,73 @@
+// SPDX-FileCopyrightText: 2026 Pithy
+// SPDX-License-Identifier: MIT
+
+import { readFileSync } from "node:fs";
+import { defineCommand } from "citty";
+import type { CommandEntry } from "./help/groups";
+
+const { version } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as {
+  version: string;
+};
+
+/**
+ * Every command the CLI has, the group it prints under, and how to load it. One list, not two.
+ *
+ * **The group is a required field, so a command cannot be added without deciding where it belongs.**
+ * The root help screen groups its commands (§4.3), and the obvious way to spell that — a table of names
+ * per group beside this one — is a second list of the same set. Two lists drift, and this drift is the
+ * bad kind: a command added here and forgotten there would not fail, it would *vanish* from the one
+ * screen whose whole job is to say what the CLI can do. `satisfies` makes the omission a compile error
+ * and `HelpGroup` makes a typo one, which is why there is no gate for it and no catch-all group.
+ *
+ * **Written in the order the help screen prints**, so this file reads top-to-bottom like the output.
+ * Dispatch is keyed by name and does not care; the order is here for whoever is reading.
+ *
+ * Subcommands load lazily — cold start stays fast as the set grows, and `load` stays a thunk so nothing
+ * is imported until a name is walked into or the help screen resolves every description.
+ */
+const COMMANDS = {
+  // Project — what the project is, and what it composes.
+  init: { group: "Project", load: () => import("./commands/init").then((m) => m.default) },
+  add: { group: "Project", load: () => import("./commands/add").then((m) => m.default) },
+  remove: { group: "Project", load: () => import("./commands/remove").then((m) => m.default) },
+  worker: { group: "Project", load: () => import("./commands/worker").then((m) => m.default) },
+  ui: { group: "Project", load: () => import("./commands/ui").then((m) => m.default) },
+  upgrade: { group: "Project", load: () => import("./commands/upgrade").then((m) => m.default) },
+
+  // Develop — the local loop.
+  dev: { group: "Develop", load: () => import("./commands/dev").then((m) => m.default) },
+  migrate: { group: "Develop", load: () => import("./commands/migrate").then((m) => m.default) },
+  seed: { group: "Develop", load: () => import("./commands/seed").then((m) => m.default) },
+  feature: { group: "Develop", load: () => import("./commands/feature").then((m) => m.default) },
+
+  // Operate — the deployed thing: its resources, its credentials, and who may manage it.
+  provision: { group: "Operate", load: () => import("./commands/provision").then((m) => m.default) },
+  deploy: { group: "Operate", load: () => import("./commands/deploy").then((m) => m.default) },
+  env: { group: "Operate", load: () => import("./commands/env").then((m) => m.default) },
+  token: { group: "Operate", load: () => import("./commands/token").then((m) => m.default) },
+  dashboard: { group: "Operate", load: () => import("./commands/dashboard").then((m) => m.default) },
+
+  // Capabilities — one command per capability that provisions infrastructure of its own.
+  secrets: { group: "Capabilities", load: () => import("./commands/secrets").then((m) => m.default) },
+  email: { group: "Capabilities", load: () => import("./commands/email").then((m) => m.default) },
+  media: { group: "Capabilities", load: () => import("./commands/media").then((m) => m.default) },
+  payments: { group: "Capabilities", load: () => import("./commands/payments").then((m) => m.default) },
+  storage: { group: "Capabilities", load: () => import("./commands/storage").then((m) => m.default) },
+  support: { group: "Capabilities", load: () => import("./commands/support").then((m) => m.default) },
+  testers: { group: "Capabilities", load: () => import("./commands/testers").then((m) => m.default) },
+  turnstile: { group: "Capabilities", load: () => import("./commands/turnstile").then((m) => m.default) },
+  vector: { group: "Capabilities", load: () => import("./commands/vector").then((m) => m.default) },
+
+  // Toolchain — the tool rather than the project.
+  doctor: { group: "Toolchain", load: () => import("./commands/doctor").then((m) => m.default) },
+  alias: { group: "Toolchain", load: () => import("./commands/alias").then((m) => m.default) },
+} as const satisfies Record<string, CommandEntry>;
+
+/** The registry, for the help screen. Every name, its group, and its loader. */
+export const COMMAND_REGISTRY: Readonly<Record<string, CommandEntry>> = COMMANDS;
+
+/** The root command. `subCommands` is projected from {@link COMMANDS} — citty sees the thunks it always did. */
+export const main = defineCommand({
+  meta: { name: "pithy", version, description: "A backend kit for Cloudflare Workers." },
+  subCommands: Object.fromEntries(Object.entries(COMMANDS).map(([name, entry]) => [name, entry.load])),
+});