@devdogsuga/devtools 0.1.0

package/dist/commands.js

@@ -0,0 +1,1279 @@
+/**
+ * The command tree, as data.
+ *
+ * One declaration, three readers:
+ *
+ *   * `help.ts` renders it, one level at a time.
+ *   * `menu.ts` walks its interactive commands and options without a second
+ *     list to keep in step.
+ *   * contributor documentation uses the same group and command vocabulary.
+ *
+ * It is deliberately inert: names, summaries and option shapes, no imports of
+ * anything that runs. `cli.ts` owns dispatch; the wizard turns a walk of this
+ * tree into an argv and hands it to that same dispatcher, which keeps menu and
+ * CLI behavior aligned by construction rather than by review.
+ *
+ * One exception: `WORKER_APP_CHOICES` imports the shared `WORKER_APPS` list
+ * (root `workers.json`) so `cf preview`/`typegen`/`build`'s `--app` choices
+ * cannot drift from the six-site source of truth. It is data — a string
+ * array read from a JSON file — not a function this file calls.
+ *
+ * ## What a summary is for
+ *
+ * Every `summary` is one line and is the ONLY thing `--help` prints for a
+ * command at the level above it. Rationale, target tables, credential lookup
+ * order and deploy internals live in `docs/`, not here: `--help` is a map, and
+ * a map that reprints the territory is the thing this replaced.
+ */
+import { workerApps } from "./workers.js";
+/**
+ * The `--app <slug>` choices shared by `cf preview`/`typegen`/`build`.
+ *
+ * `workerApps()` reads `workers.json` via `findRepoRoot()`, which throws
+ * outside a DevDogsUGA checkout — and this module (via `help.ts`/`menu.ts`)
+ * is imported for `devtools --help`, which must work from anywhere,
+ * `/tmp` included (see `workers.ts`'s header). The tree below is built once
+ * at import time regardless, so this falls back to an empty choice list
+ * rather than propagating the throw: `--help` still renders the command
+ * shape with no `--app` values listed, and any actual `cf preview --app …`
+ * invocation outside a repo fails with the same clear `RepoNotFoundError`
+ * it always would have, just a little further downstream.
+ */
+const WORKER_APP_CHOICES = (() => {
+    try {
+        return workerApps().map((app) => ({ value: app, label: app }));
+    }
+    catch {
+        return [];
+    }
+})();
+/**
+ * How each scope reads, in the two places that draw it.
+ *
+ * `menu` sits inline in a hint, so it is one word. `help` heads a block of
+ * commands, so it can be a phrase. Both live here rather than in the renderers
+ * because they are labels, the same kind of data as a group title.
+ */
+export const SCOPES = {
+    machine: { menu: "This machine", help: "Supabase on this machine" },
+    repo: { menu: "Repo", help: "files in the repo" },
+    endpoint: { menu: "Database", help: "the session's database (--tier)" },
+    infra: {
+        menu: "Hosted",
+        help: "hosted infrastructure, each naming its own connection",
+    },
+};
+// ── Exit codes ───────────────────────────────────────────────────────────────
+/** Standard success. */
+export const EXIT_OK = 0;
+/** Command failed. */
+export const EXIT_FAIL = 1;
+/** `--check` found drift. Distinct from failure so scripts can tell them apart. */
+export const EXIT_DRIFT = 2;
+// ── Shared option shapes ─────────────────────────────────────────────────────
+/**
+ * `docs index`'s delete acknowledgment — NOT a database selector.
+ *
+ * The db namespace's old `--target local|remote` flag is retired outright
+ * (the SESSION names the database now — see `db/connection.ts`), but `docs
+ * index` keeps this spelling for a different job: its prune deletes rows,
+ * and running that against a non-local `DB_URL` requires saying so out
+ * loud. The database itself still comes from the session's env.
+ */
+export const DOCS_TARGET = {
+    flag: "--target",
+    value: "<local|remote>",
+    summary: "Acknowledge indexing a non-local DB_URL. Defaults to local-only.",
+    prompt: {
+        kind: "select",
+        message: "May this prune a non-local database?",
+        choices: [
+            { value: "local", label: "Local only", hint: "the default" },
+            { value: "remote", label: "Yes — the session's remote DB_URL" },
+        ],
+    },
+};
+/**
+ * The deployment-tier selector, for the commands that resolve a tier of
+ * their OWN (cron/workflows run against a chosen tier's env). The session's
+ * global `--tier` — `development:local|development:remote|staging|production`,
+ * stripped by the launcher before dispatch — is a superset of this
+ * vocabulary; this per-command flag still reads plain tiers.
+ */
+export const TIER = {
+    flag: "--tier",
+    value: "<t>",
+    summary: "Which deployment tier. Asked for when absent.",
+};
+/** Print what would change; write nothing; exit 0. On every command that writes. */
+export const DRY_RUN = {
+    flag: "--dry-run",
+    summary: "Print what would change, write nothing, exit 0.",
+};
+/** Verify correctness; write nothing; exit 2 on drift. */
+export const CHECK = {
+    flag: "--check",
+    summary: "Verify, write nothing, exit 2 on drift.",
+};
+/**
+ * Machine-readable output to stdout.
+ *
+ * Promptless by design: the wizard is already interactive; a flag that switches
+ * its output format has no meaning there. `commands.test.ts` pins the promptless
+ * set with a "scripting-only" category for exactly this kind of flag.
+ */
+export const JSON_FLAG = {
+    flag: "--json",
+    summary: "Print machine-readable JSON to stdout.",
+};
+const VAULT_TARGET = {
+    flag: "--target",
+    value: "<t>",
+    summary: "preflight, staging or production. Asked for when absent.",
+    // No prompt: `pick.ts` already owns this question, and it orders the list
+    // least- to most-dangerous so a reflexive Enter cannot select production.
+    // Duplicating it here would put production one keystroke closer.
+};
+/**
+ * The three flags every `run` task takes.
+ *
+ * None carries a `prompt`, and that is the point rather than an omission.
+ * `run` opens a multiselect of the apps defining the task, so a wizard that
+ * asked "every package?", "which filter?" and "which tier?" up front would
+ * ask the same question three times and let the answers disagree. `--tier`
+ * is promptless for a different reason than `--filter`/`--all`, though: it is
+ * not a question `run` asks itself elsewhere (unlike `cron run`'s own
+ * `--tier`, which opens a live picker) — it is a scripting input with no
+ * wizard equivalent, the same category `--json` sits in. `--help` still
+ * documents all three, which is where someone scripting this will look.
+ *
+ * Same reasoning as `VAULT_TARGET` above: the command owns the question, so the
+ * tree declares the flag and stays quiet.
+ */
+const RUN_OPTIONS = [
+    {
+        flag: "--filter",
+        value: "<pkg>",
+        summary: "Limit to a package. pnpm's own flag; skips the question.",
+    },
+    {
+        flag: "--all",
+        summary: "Every package, unfiltered, with nothing asked.",
+    },
+    {
+        flag: "--tier",
+        value: "<t>",
+        summary: "Load a tier's env into the run. CLI-only; never prompted.",
+    },
+];
+const ENV_FILE = {
+    flag: "--file",
+    value: "<path>",
+    summary: "Read and write this file instead of the target's own.",
+};
+/** Skip every interactive confirmation prompt. On every destructive command. */
+export const YES = {
+    flag: "--yes",
+    summary: "Skip the confirmations.",
+};
+const ACCESS_TOKEN = {
+    flag: "--access-token",
+    value: "<token>",
+    summary: "Bitwarden Secrets Manager token. Prefer the vault or the env var.",
+};
+const DB_URL = {
+    flag: "--db-url",
+    value: "<url>",
+    summary: "Privileged connection. Defaults to .env.production's DB_URL.",
+    prompt: {
+        kind: "text",
+        message: "Connection URL? (blank uses .env.production's DB_URL)",
+        optional: true,
+    },
+};
+// ── The tree ─────────────────────────────────────────────────────────────────
+const DECLARED_GROUPS = [
+    {
+        title: "Start here",
+        commands: [
+            {
+                name: "setup",
+                summary: "Check prerequisites and seed .env.",
+                hint: "run this first",
+            },
+            {
+                name: "completions",
+                summary: "Output a shell completion script for devtools.",
+                hint: "pipe to source or write to a file",
+                surface: "cli-only",
+                options: [
+                    {
+                        flag: "--shell",
+                        value: "<bash|zsh>",
+                        summary: "Target shell. Asked for when absent.",
+                        prompt: {
+                            kind: "select",
+                            message: "Which shell?",
+                            choices: [{ value: "bash" }, { value: "zsh" }],
+                        },
+                    },
+                ],
+            },
+        ],
+    },
+    {
+        title: "Workspace",
+        commands: [
+            {
+                name: "run",
+                summary: "Run a pnpm workspace task, asking which apps first.",
+                hint: "build, dev, lint…",
+                // The six with a root alias, which are the six a contributor types.
+                // NOT an exhaustive list of every package script: `run` forwards
+                // whatever name it is given, so `test:coverage` works without being
+                // listed here, and this CLI's own unrelated `deploy` command group
+                // stays out of a menu where a same-named package script would sit
+                // one line away from it.
+                subcommands: [
+                    {
+                        name: "build",
+                        summary: "Compile every package an app needs.",
+                        options: RUN_OPTIONS,
+                    },
+                    {
+                        name: "dev",
+                        summary: "Start the development servers.",
+                        options: RUN_OPTIONS,
+                    },
+                    {
+                        name: "typecheck",
+                        summary: "Run tsc across the workspace.",
+                        options: RUN_OPTIONS,
+                    },
+                    {
+                        name: "lint",
+                        summary: "Run ESLint across the workspace.",
+                        options: RUN_OPTIONS,
+                    },
+                    {
+                        name: "lint:fix",
+                        summary: "Run ESLint and write what it can fix.",
+                        options: RUN_OPTIONS,
+                    },
+                    {
+                        name: "test",
+                        summary: "Run the unit tests.",
+                        options: RUN_OPTIONS,
+                    },
+                ],
+            },
+        ],
+    },
+    {
+        title: "Brand",
+        commands: [
+            {
+                name: "emails",
+                summary: "Render populated transactional email previews.",
+                hint: "HTML or plain text, one template or all",
+                // Like `images`, this command owns its dependent questions: formats
+                // and output only make sense after the templates have been selected.
+                options: [
+                    {
+                        flag: "--format",
+                        value: "<html,text>",
+                        summary: "Outputs to write. Defaults to html.",
+                    },
+                    {
+                        flag: "--out",
+                        value: "<dir>",
+                        summary: "Output directory. Defaults to ./email-previews.",
+                    },
+                    {
+                        flag: "--dry-run",
+                        summary: "List subjects and destination files without writing.",
+                    },
+                ],
+            },
+            {
+                name: "images",
+                summary: "Render a club image at one or more sizes.",
+                hint: "brand/*, page/*, app/*, event/*, or * for all",
+                // No subcommands: graphics are positional, and several can be named at
+                // once. The command owns its interactive path because it can ask in CLI
+                // order — graphic, format, output — and derive each question from the
+                // previous answer. The outer wizard therefore dispatches bare `images`;
+                // these options remain here for help and scripted invocations.
+                options: [
+                    {
+                        flag: "--format",
+                        value: "<a,b,…>",
+                        summary: "Sizes to render: og, gdgc-wide, gdgc-square, savvycal, email-*, icon-*.",
+                        // Not prompted here: the command asks itself, from the formats the
+                        // chosen graphics actually support, which a static list cannot know.
+                    },
+                    {
+                        flag: "--all-formats",
+                        summary: "Every size the named graphics support.",
+                    },
+                    {
+                        flag: "--out",
+                        value: "<dir>",
+                        summary: "Write everything into one directory, flat.",
+                    },
+                    {
+                        flag: "--default-out",
+                        summary: "Write each image where it belongs in the repo.",
+                    },
+                    {
+                        flag: "--dry-run",
+                        summary: "List what would be written, and what each size is for.",
+                    },
+                ],
+            },
+        ],
+    },
+    {
+        title: "Moderation",
+        commands: [
+            {
+                name: "catalog",
+                summary: "List the report reasons and content types in the database.",
+                hint: "what can be reported here",
+                needs: "instance-running",
+                options: [JSON_FLAG],
+            },
+            {
+                name: "doctor",
+                summary: "Check an app's moderation integration.",
+                hint: "and whether the catalog holds up",
+                needs: "instance-running",
+                options: [
+                    {
+                        flag: "--app",
+                        value: "<slug>",
+                        summary: "App to check. Asked for when absent.",
+                    },
+                    JSON_FLAG,
+                ],
+            },
+            {
+                name: "roundtrip",
+                summary: "File a report, quarantine it, and check the freeze.",
+                hint: "end to end, then cleans up",
+                needs: "instance-running",
+            },
+            {
+                name: "grant-root",
+                summary: "Give an account every permission on your own database.",
+                needs: "instance-running",
+                options: [
+                    {
+                        flag: "--user",
+                        value: "<email>",
+                        summary: "Account to grant Root to. Asked for when absent.",
+                    },
+                ],
+            },
+        ],
+    },
+    {
+        title: "Generate",
+        commands: [
+            {
+                name: "gen",
+                summary: "Regenerate committed, generated source.",
+                hint: "refresh a tracked artifact",
+                subcommands: [
+                    {
+                        name: "campus-map",
+                        summary: "Rebuild the FindUs campus map from OpenStreetMap.",
+                        hint: "occasional — rerun when OSM improves the area",
+                    },
+                    {
+                        name: "hypno",
+                        summary: "Bake the hero spiral into a pre-blurred raster.",
+                        hint: "needs Playwright",
+                    },
+                    {
+                        name: "og-assets",
+                        summary: "Re-embed OG fonts, icons and brand art.",
+                        hint: "after a brand, font or Phosphor bump",
+                    },
+                    {
+                        name: "email-templates",
+                        summary: "Recompile the transactional email chunks.",
+                        hint: "render → tokenize → emit",
+                    },
+                ],
+            },
+        ],
+    },
+    {
+        title: "Cron",
+        commands: [
+            {
+                name: "cron",
+                summary: "Cloudflare cron triggers: list schedules or fire one now.",
+                hint: "list schedules, run a job",
+                subcommands: [
+                    {
+                        name: "list",
+                        summary: "Every registered cron: schedule, English description, routes.",
+                        hint: "the audit view",
+                        options: [
+                            {
+                                flag: "--app",
+                                value: "<slug>",
+                                summary: "Limit to one app. All apps if omitted.",
+                            },
+                            {
+                                flag: "--tier",
+                                value: "<t>",
+                                summary: "Whose wrangler schedules to read. All tiers if omitted.",
+                                prompt: {
+                                    kind: "select",
+                                    message: "Which tier's wrangler schedules?",
+                                    choices: [
+                                        { value: "development", hint: "the default" },
+                                        { value: "staging" },
+                                        { value: "production" },
+                                    ],
+                                },
+                            },
+                            JSON_FLAG,
+                        ],
+                    },
+                    {
+                        name: "run",
+                        summary: "Choose and fire a configured cron schedule now.",
+                        hint: "pick a job from the Worker configuration",
+                        options: [
+                            {
+                                flag: "--app",
+                                value: "<slug>",
+                                summary: "Limit the discovered jobs to one app.",
+                            },
+                            {
+                                flag: "--tier",
+                                value: "<t>",
+                                summary: "development, staging or production. Asked when absent.",
+                            },
+                            {
+                                flag: "--cron",
+                                value: "<expr>",
+                                summary: "Fire this schedule without opening the picker.",
+                            },
+                            YES,
+                        ],
+                    },
+                ],
+            },
+            {
+                name: "workflows",
+                summary: "Cloudflare Workflows: list configured bindings or trigger one.",
+                hint: "pick a workflow from wrangler.jsonc",
+                subcommands: [
+                    {
+                        name: "list",
+                        summary: "List every Workflow binding declared by each Wrangler tier.",
+                        options: [
+                            {
+                                flag: "--app",
+                                value: "<slug>",
+                                summary: "Limit to one app.",
+                            },
+                            {
+                                flag: "--tier",
+                                value: "<t>",
+                                summary: "Limit to development, staging or production.",
+                            },
+                            JSON_FLAG,
+                        ],
+                    },
+                    {
+                        name: "run",
+                        summary: "Choose and trigger a Workflow through Wrangler.",
+                        hint: "local session or a deployed tier",
+                        options: [
+                            {
+                                flag: "--app",
+                                value: "<slug>",
+                                summary: "Limit the discovered Workflows to one app.",
+                            },
+                            {
+                                flag: "--tier",
+                                value: "<t>",
+                                summary: "development, staging or production. Asked when absent.",
+                            },
+                            {
+                                flag: "--workflow",
+                                value: "<name>",
+                                summary: "Trigger this configured name without opening the picker.",
+                            },
+                            {
+                                flag: "--params",
+                                value: "<json>",
+                                summary: "JSON parameters passed to the Workflow instance.",
+                            },
+                            {
+                                flag: "--port",
+                                value: "<n>",
+                                summary: "Local Wrangler session port. Defaults to 8787.",
+                            },
+                            YES,
+                        ],
+                    },
+                    {
+                        name: "serve",
+                        summary: "Start an app-scoped local Wrangler runtime until Ctrl+C.",
+                        hint: "secure alternative to bare wrangler dev",
+                        options: [
+                            {
+                                flag: "--app",
+                                value: "<slug>",
+                                summary: "Serve the development Workflow for this app.",
+                            },
+                            {
+                                flag: "--port",
+                                value: "<n>",
+                                summary: "Local Wrangler session port. Defaults to 8787.",
+                            },
+                        ],
+                    },
+                ],
+            },
+        ],
+    },
+    {
+        title: "GitHub",
+        commands: [
+            {
+                name: "github",
+                summary: "Reconcile the repository's rulesets and settings.",
+                hint: "rulesets: main, production, ~ALL, team/**, tags; settings: security, Actions, environments",
+                subcommands: [
+                    {
+                        name: "rulesets",
+                        summary: "Diff the fixed rulesets against live GitHub; --apply to write.",
+                        hint: "dry-run plan by default",
+                        envFree: true,
+                        options: [
+                            {
+                                flag: "--org",
+                                value: "<org>",
+                                summary: "GitHub org. Defaults to DevDogsUGA.",
+                            },
+                            {
+                                flag: "--repo",
+                                value: "<repo>",
+                                summary: "Repository name. Defaults to DevDogsUGA.",
+                            },
+                            {
+                                flag: "--app-slug",
+                                value: "<slug>",
+                                summary: "The GitHub App whose id bypasses team/** creation. Defaults to devdogs-platform.",
+                            },
+                            {
+                                flag: "--apply",
+                                summary: "Write the plan instead of only printing it.",
+                            },
+                            YES,
+                            JSON_FLAG,
+                        ],
+                    },
+                    {
+                        name: "settings",
+                        summary: "Diff security/Actions/environment settings vs live GitHub.",
+                        hint: "dry-run plan by default",
+                        envFree: true,
+                        options: [
+                            {
+                                flag: "--org",
+                                value: "<org>",
+                                summary: "GitHub org. Defaults to DevDogsUGA.",
+                            },
+                            {
+                                flag: "--repo",
+                                value: "<repo>",
+                                summary: "Repository name. Defaults to DevDogsUGA.",
+                            },
+                            {
+                                flag: "--apply",
+                                summary: "Write fixable drift instead of only printing it.",
+                            },
+                            YES,
+                            JSON_FLAG,
+                        ],
+                    },
+                ],
+            },
+        ],
+    },
+    {
+        title: "Project setup",
+        commands: [
+            {
+                name: "oauth",
+                summary: 'Configure "Sign in with DevDogs" for this directory.',
+                hint: "works outside a DevDogsUGA checkout too",
+                // Talks only to whatever local Supabase project is running in `cwd`
+                // (see `oauth/db.ts`'s `detectLocalSupabase`) and, for a hosted
+                // target, to the platform's own OAuth endpoints — never a
+                // DevDogsUGA env file, database, or `DEPLOY_ENV`. TASK-345: a
+                // workshop repo with no DevDogsUGA checkout at all must still be
+                // able to run `pnpm dlx @devdogsuga/devtools oauth`, so this joins
+                // `github rulesets`/`github settings` in the catalog-driven bypass
+                // rather than the hardcoded `setup`/`completions` check — see
+                // `launch.ts`'s `isEnvFreeCommand`. Inside a checkout, the command's
+                // own hosted-target path still resolves a tier itself, lazily, only
+                // when a hosted target is actually chosen (see `oauth/wizard.ts`).
+                envFree: true,
+                options: [
+                    {
+                        flag: "--base-url",
+                        value: "<url>",
+                        summary: "DevDogs API URL. Only used by \"Paste credentials instead\".",
+                        prompt: {
+                            kind: "text",
+                            message: "DevDogs API URL? (blank asks inside the wizard)",
+                            optional: true,
+                        },
+                    },
+                    {
+                        flag: "--platform-url",
+                        value: "<url>",
+                        summary: "Platform URL for one-click connect. Defaults to https://devdogsuga.org.",
+                        prompt: {
+                            kind: "text",
+                            message: "Platform URL? (blank uses the default)",
+                            optional: true,
+                        },
+                    },
+                    {
+                        flag: "--device",
+                        summary: "Force the device-code flow instead of the local loopback listener.",
+                    },
+                    {
+                        flag: "--loopback",
+                        summary: "Force the local loopback listener even over SSH/Codespaces/a dev container.",
+                    },
+                ],
+            },
+            {
+                name: "docs",
+                summary: "The documentation search index.",
+                subcommands: [
+                    {
+                        name: "index",
+                        summary: "Push the built docs artifact into the search index.",
+                        hint: "prunes stale rows in the target database",
+                        scope: "endpoint",
+                        options: [DOCS_TARGET],
+                    },
+                ],
+            },
+        ],
+    },
+    {
+        title: "Env files",
+        commands: [
+            {
+                name: "env",
+                summary: "One env file per target, synced to Bitwarden and GitHub.",
+                subcommands: [
+                    {
+                        name: "pull",
+                        summary: "Bitwarden → the target's file, in place.",
+                        options: [VAULT_TARGET, ENV_FILE, YES, ACCESS_TOKEN],
+                    },
+                    {
+                        name: "push",
+                        summary: "The target's file → Bitwarden and GitHub.",
+                        options: [VAULT_TARGET, ENV_FILE, YES, ACCESS_TOKEN],
+                    },
+                    {
+                        name: "audit",
+                        summary: "Compare the file, Bitwarden, GitHub and Cloudflare.",
+                        hint: "reads only",
+                        options: [VAULT_TARGET, ENV_FILE, YES, ACCESS_TOKEN, JSON_FLAG],
+                    },
+                    {
+                        name: "init",
+                        summary: "Create a target file, or append newly declared keys.",
+                        hint: "existing lines are never changed",
+                        options: [
+                            {
+                                flag: "--target",
+                                value: "<t>",
+                                summary: "Which file to create. Defaults to development.",
+                                prompt: {
+                                    kind: "select",
+                                    message: "Create a file for which target?",
+                                    choices: [
+                                        { value: "development", hint: ".env — the default" },
+                                        { value: "preflight", hint: ".env.preflight" },
+                                        { value: "staging", hint: ".env.staging" },
+                                        { value: "production", hint: "⚠️  .env.production" },
+                                    ],
+                                },
+                            },
+                            {
+                                flag: "--apps",
+                                value: "<a,b,…>",
+                                summary: "Which sections to render. Development only; asks.",
+                            },
+                        ],
+                    },
+                    {
+                        name: "example",
+                        summary: "Regenerate .env.example from the manifests.",
+                        options: [
+                            {
+                                flag: "--check",
+                                summary: "Verify it is current, as CI does. Writes nothing.",
+                                prompt: {
+                                    kind: "confirm",
+                                    message: "Check only, without rewriting .env.example?",
+                                    initial: true,
+                                },
+                            },
+                        ],
+                    },
+                    {
+                        name: "reset",
+                        summary: "Blank every value in .env, keeping each commented out.",
+                        hint: "local only, no target",
+                        options: [ENV_FILE, YES],
+                    },
+                ],
+            },
+            {
+                // The Bitwarden CLI, not a command of this one: everything after `bw`
+                // is handed to it untouched. It is here because it is the login that
+                // `env pull` depends on, it ships as a devtools dependency, and the
+                // root `bw` alias it replaces was the last thing at the workspace root
+                // reaching into this package. Declaring no subcommands is deliberate:
+                // Bitwarden's commands are its own to document, and mirroring a slice
+                // of them here would go stale on their release schedule, not ours.
+                name: "bw",
+                summary: "Run the Bitwarden CLI. `bw login` is the one you want.",
+                hint: "passes everything through",
+            },
+        ],
+    },
+    {
+        title: "Database",
+        // One command, `db`. Its OWN subcommands carry the scopes — see the
+        // header comment on `Scope` and `db`'s `hint` below. Declared in scope
+        // order (machine, repo, endpoint, infra, then the unscoped escape hatch)
+        // so `--help` and the wizard render one contiguous block per scope
+        // instead of several.
+        commands: [
+            {
+                name: "db",
+                summary: "Supabase endpoints, and the databases inside them.",
+                hint: "start, migrate, reset, types…",
+                subcommands: [
+                    // ── machine — Supabase on this machine ─────────────────────────
+                    {
+                        name: "start",
+                        summary: "Start Supabase on this machine.",
+                        hint: "boots the Docker containers",
+                        scope: "machine",
+                        when: "instance-stopped",
+                    },
+                    {
+                        name: "connect",
+                        summary: "Run `supabase link` against a hosted project ref.",
+                        hint: "for driving the bare supabase CLI by hand",
+                        scope: "machine",
+                    },
+                    {
+                        name: "stop",
+                        summary: "Shut it down, freeing its containers.",
+                        hint: "your data survives",
+                        scope: "machine",
+                        // Not offered while nothing is running: "stop" against a stopped
+                        // stack is the one shape of question a menu should never ask.
+                        when: "instance-running",
+                    },
+                    {
+                        name: "restart",
+                        summary: "Stop it, then start it again.",
+                        // The reason this exists rather than being a footnote on `reset`:
+                        // `config.toml` is read at `supabase start`, so a reset replays
+                        // migrations into containers still holding the old settings.
+                        hint: "the only way to pick up config.toml — reset will not",
+                        scope: "machine",
+                        when: "instance-running",
+                    },
+                    // ── repo — files in the repo, no live connection ───────────────
+                    {
+                        name: "migration",
+                        summary: "Migration files, empty or drafted from schema drift.",
+                        scope: "repo",
+                        subcommands: [
+                            {
+                                name: "new",
+                                summary: "Create an empty timestamped migration file.",
+                            },
+                            {
+                                name: "generate",
+                                summary: "Generate a migration from an app's Drizzle schema drift.",
+                                options: [
+                                    {
+                                        flag: "--app",
+                                        value: "<slug>",
+                                        summary: "Whose schema. Asked for when absent.",
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                    // ── endpoint — the session's database ──────────────────────────
+                    {
+                        name: "status",
+                        summary: "Report the session database's health, URLs and keys.",
+                        hint: "reads only",
+                        scope: "endpoint",
+                        options: [JSON_FLAG],
+                    },
+                    {
+                        name: "migrate",
+                        summary: "Apply new migrations to the database.",
+                        hint: "without erasing anything",
+                        scope: "endpoint",
+                        options: [YES],
+                    },
+                    {
+                        name: "reset",
+                        summary: "Rebuild the database: migrations, seeds, types, buckets.",
+                        hint: "⚠️  erases the database first",
+                        scope: "endpoint",
+                        options: [YES],
+                    },
+                    {
+                        name: "types",
+                        summary: "Regenerate database.types.ts, format it, rebuild the package.",
+                        hint: "after any schema change",
+                        scope: "endpoint",
+                        options: [],
+                    },
+                    {
+                        name: "seed",
+                        summary: "Seed storage buckets or the platform's role catalogue.",
+                        scope: "endpoint",
+                        subcommands: [
+                            {
+                                name: "buckets",
+                                summary: "Create the storage buckets config.toml declares.",
+                                options: [],
+                            },
+                            {
+                                name: "roles",
+                                summary: "Reconcile the platform's role catalogue.",
+                                options: [],
+                            },
+                            {
+                                name: "production",
+                                summary: "Apply supabase/seed/production/*.sql — roles and officers.",
+                                hint: "confirms before writing to a hosted database",
+                                options: [YES],
+                            },
+                        ],
+                    },
+                    {
+                        name: "introspect",
+                        summary: "Pull an app's live schema into its generated Drizzle files.",
+                        scope: "endpoint",
+                        options: [
+                            {
+                                flag: "--app",
+                                value: "<slug>",
+                                summary: "App whose schema to pull. Asked for when absent.",
+                            },
+                        ],
+                    },
+                    {
+                        name: "config",
+                        summary: "The Supabase config.toml, pushed to the session's project.",
+                        scope: "endpoint",
+                        subcommands: [
+                            {
+                                name: "push",
+                                summary: "Push config.toml to the session's hosted project.",
+                                hint: "hosted sessions only",
+                                options: [],
+                            },
+                        ],
+                    },
+                    // ── infra — hosted infrastructure, each naming its own connection
+                    {
+                        name: "planner",
+                        summary: "The migration_planner role the preflight tier may hold.",
+                        scope: "infra",
+                        subcommands: [
+                            {
+                                name: "status",
+                                summary: "Does the role exist, hold its two grants, and no more.",
+                                hint: "reads only — start here",
+                                options: [DB_URL, JSON_FLAG],
+                            },
+                            {
+                                name: "create",
+                                summary: "Mint the role, verify it live, write .env.preflight.",
+                                options: [DB_URL],
+                            },
+                            {
+                                name: "reset-password",
+                                summary: "Rotate the password. There is no retrieve.",
+                                options: [DB_URL, YES],
+                            },
+                            {
+                                name: "drop",
+                                summary: "Remove the role and blank the dead URL.",
+                                hint: "the recovery path",
+                                options: [DB_URL, YES],
+                            },
+                        ],
+                    },
+                    // ── unscoped — the escape hatch ─────────────────────────────────
+                    {
+                        name: "exec",
+                        summary: "Run the Supabase CLI. Everything after -- passes through.",
+                        hint: "the escape hatch",
+                    },
+                ],
+            },
+        ],
+    },
+    {
+        title: "Cloudflare",
+        commands: [
+            {
+                name: "cf",
+                summary: "Develop and build an app on the Workers runtime.",
+                hint: "preview, typegen — deploys live in CI",
+                subcommands: [
+                    {
+                        name: "preview",
+                        summary: "Build and serve an app on the Workers runtime.",
+                        options: [
+                            {
+                                flag: "--app",
+                                value: "<slug>",
+                                summary: "App to preview. Asked for when absent.",
+                                prompt: {
+                                    kind: "select",
+                                    message: "Which app?",
+                                    choices: WORKER_APP_CHOICES,
+                                },
+                            },
+                            {
+                                flag: "--tier",
+                                value: "<t>",
+                                summary: "Preview against a tier's env. Defaults to development.",
+                                // No prompt: the runtime resolver (`tier.ts`) asks this
+                                // itself, conditionally, for both the wizard and a direct
+                                // CLI invocation — a `prompt` here would ask it twice, once
+                                // on this screen and once when the command actually runs.
+                            },
+                            YES,
+                        ],
+                    },
+                    {
+                        name: "typegen",
+                        summary: "Regenerate cloudflare-env.d.ts from the wrangler config.",
+                        options: [
+                            {
+                                flag: "--app",
+                                value: "<slug>",
+                                summary: "App to run typegen for. Asked for when absent.",
+                                prompt: {
+                                    kind: "select",
+                                    message: "Which app?",
+                                    choices: WORKER_APP_CHOICES,
+                                },
+                            },
+                            {
+                                flag: "--check",
+                                summary: "Check types only — do not write.",
+                                prompt: {
+                                    kind: "confirm",
+                                    message: "Check only (do not write)?",
+                                    initial: true,
+                                },
+                            },
+                        ],
+                    },
+                    {
+                        name: "build",
+                        summary: "Build an app's Worker bundle for a tier.",
+                        options: [
+                            {
+                                flag: "--app",
+                                value: "<slug>",
+                                summary: "App to build. Asked for when absent.",
+                                prompt: {
+                                    kind: "select",
+                                    message: "Which app?",
+                                    choices: WORKER_APP_CHOICES,
+                                },
+                            },
+                            {
+                                flag: "--tier",
+                                value: "<t>",
+                                summary: "Which deployment tier to build for.",
+                                prompt: {
+                                    kind: "select",
+                                    message: "Which tier?",
+                                    choices: [
+                                        { value: "staging" },
+                                        { value: "production", hint: "⚠️  live bundle" },
+                                    ],
+                                },
+                            },
+                        ],
+                    },
+                    {
+                        name: "exec",
+                        summary: "Run wrangler. Everything after -- passes through.",
+                        hint: "the escape hatch",
+                    },
+                ],
+            },
+        ],
+    },
+];
+/**
+ * The contributor-facing navigation, grouped by the job somebody is doing.
+ *
+ * Command declarations stay close to their domain-specific option data above;
+ * this projection is the one place that decides how the root help and menu
+ * read. Paths do not change when a command moves between groups.
+ */
+const declaredByName = new Map(DECLARED_GROUPS.flatMap((group) => group.commands).map((command) => [
+    command.name,
+    command,
+]));
+function commands(...names) {
+    return names.map((name) => {
+        const command = declaredByName.get(name);
+        if (!command)
+            throw new Error(`Command "${name}" is not declared.`);
+        return command;
+    });
+}
+export const GROUPS = [
+    {
+        title: "Workspace",
+        commands: commands("setup", "oauth", "run", "gen", "docs"),
+    },
+    {
+        title: "Runtime & infrastructure",
+        commands: commands("db", "cf", "cron", "workflows"),
+    },
+    {
+        title: "Content & communications",
+        commands: commands("images", "emails"),
+    },
+    {
+        title: "Configuration & integrations",
+        commands: commands("env", "bw"),
+    },
+    {
+        title: "Moderation",
+        commands: commands("catalog", "doctor", "roundtrip", "grant-root"),
+    },
+    {
+        title: "GitHub",
+        commands: commands("github"),
+    },
+    {
+        title: "CLI utilities",
+        commands: commands("completions"),
+    },
+];
+// ── CI command tree ───────────────────────────────────────────────────────────
+/**
+ * The commands the `devtools-ci` bin exposes.
+ *
+ * Kept separate from `GROUPS` because CI commands are never reached from the
+ * wizard and never rendered in `--help`. They live here so the docs build can
+ * render a CI reference page from the same declaration, and so the tests that
+ * guard the style guide can cover both trees without duplicating the pins.
+ */
+export const CI_GROUPS = [
+    {
+        title: "Deploy",
+        commands: [
+            {
+                name: "deploy",
+                summary: "Deploy an app: token gate, per-app steps, upload.",
+                options: [TIER, DRY_RUN],
+                subcommands: [
+                    // ── App orchestrators ────────────────────────────────────────────
+                    {
+                        name: "platform",
+                        summary: "Deploy the platform app.",
+                        options: [TIER, DRY_RUN],
+                    },
+                    {
+                        name: "schedule-builder",
+                        summary: "Deploy the schedule-builder app.",
+                        options: [TIER, DRY_RUN],
+                    },
+                    {
+                        name: "sandbox",
+                        summary: "Deploy the sandbox app.",
+                        options: [TIER, DRY_RUN],
+                    },
+                    // ── Step commands ────────────────────────────────────────────────
+                    {
+                        name: "write-env",
+                        summary: "Compose .env.<DEPLOY_ENV> from the GitHub environment.",
+                        options: [
+                            {
+                                flag: "--source",
+                                value: "<manifest>",
+                                summary: "Compose one manifest's slice instead of all.",
+                            },
+                        ],
+                    },
+                    {
+                        name: "secrets-file",
+                        summary: "Write the --secrets-file wrangler uploads with a Worker.",
+                        options: [
+                            {
+                                flag: "--app",
+                                value: "<app>",
+                                summary: "Whose manifest declares the Worker's secrets.",
+                            },
+                        ],
+                    },
+                    {
+                        name: "orphans",
+                        summary: "Report Worker secrets nothing declares.",
+                        options: [
+                            {
+                                flag: "--prune",
+                                summary: "Delete them. production-apply only.",
+                            },
+                        ],
+                    },
+                    {
+                        name: "preflight",
+                        summary: "Classify the project: paused (skip) vs broken (fail).",
+                    },
+                    {
+                        name: "require-token",
+                        summary: "Refuse to deploy without CLOUDFLARE_API_TOKEN.",
+                    },
+                    {
+                        name: "require-planner",
+                        summary: "Refuse to plan unless DB_URL is the planner role.",
+                    },
+                    {
+                        name: "plan",
+                        summary: "Dry-run the migrations into the job summary.",
+                        options: [
+                            {
+                                flag: "--label",
+                                value: "<title>",
+                                summary: "Heading for the summary section.",
+                            },
+                        ],
+                    },
+                    {
+                        name: "migrate",
+                        summary: "Apply the migrations to DB_URL.",
+                    },
+                ],
+            },
+        ],
+    },
+];
+// ── Lookup ───────────────────────────────────────────────────────────────────
+/** Every top-level command, in group order. */
+export const TOP_LEVEL = GROUPS.flatMap((group) => group.commands);
+/** Every top-level CI command, in group order. */
+export const CI_TOP_LEVEL = CI_GROUPS.flatMap((group) => group.commands);
+/**
+ * Walks a path in the CI tree, returning `null` at the first miss.
+ *
+ * Identical to `findCommand` but over `CI_TOP_LEVEL` rather than `TOP_LEVEL`.
+ */
+export function findCiCommand(path) {
+    let nodes = CI_TOP_LEVEL;
+    let found = null;
+    for (const name of path) {
+        const next = nodes.find((node) => node.name === name);
+        if (!next)
+            return null;
+        found = next;
+        nodes = next.subcommands ?? [];
+    }
+    return found;
+}
+/** The subcommand names under a CI path. */
+export function subcommandCiNames(path) {
+    return (findCiCommand(path)?.subcommands ?? []).map((node) => node.name);
+}
+/**
+ * Walks a path like `["env", "pull"]`, returning `null` at the first miss.
+ *
+ * Callers use `null` to mean "not a command", which is the same answer the
+ * dispatcher gives, so an unknown name reads the same whichever notices first.
+ */
+export function findCommand(path) {
+    let nodes = TOP_LEVEL;
+    let found = null;
+    for (const name of path) {
+        const next = nodes.find((node) => node.name === name);
+        if (!next)
+            return null;
+        found = next;
+        nodes = next.subcommands ?? [];
+    }
+    return found;
+}
+/** The group a top-level command sits in, for the wizard's first screen. */
+export function groupOf(name) {
+    return GROUPS.find((group) => group.commands.some((command) => command.name === name));
+}
+/**
+ * The subcommand names under a path, in the order they are declared.
+ *
+ * This is what the dispatchers in `cli.ts` validate against. A subcommand the
+ * tree does not declare is refused by the CLI, and an interactive one it does
+ * declare is in the menu. There is one list, and this reads it.
+ */
+export function subcommandNames(path) {
+    return (findCommand(path)?.subcommands ?? []).map((node) => node.name);
+}
+/** `pull, push, audit, init, example or reset`, for a refusal message. */
+export function subcommandList(path) {
+    const names = subcommandNames(path);
+    if (names.length <= 1)
+        return names.join("");
+    return `${names.slice(0, -1).join(", ")} or ${names[names.length - 1]}`;
+}
+/**
+ * Every command path in the tree, deepest names included.
+ *
+ * Used by the coverage test, and by anything that wants to enumerate the CLI
+ * (the docs build's reference page is the intended second caller).
+ */
+export function allPaths() {
+    const paths = [];
+    const visit = (nodes, prefix) => {
+        for (const node of nodes) {
+            const path = [...prefix, node.name];
+            paths.push(path);
+            visit(node.subcommands ?? [], path);
+        }
+    };
+    visit(TOP_LEVEL, []);
+    return paths;
+}