@devdogsuga/devtools 0.1.0

package/dist/launch.js

@@ -0,0 +1,371 @@
+/**
+ * `pnpm devtools`'s actual entry point, run by the `bin/devtools.mjs`
+ * bootstrap BEFORE `cli.ts` — and therefore every command it dispatches — is
+ * even imported.
+ *
+ * ## Why this has to run first
+ *
+ * A deploy tier used to be resolved deep inside `menu.ts`, after the wizard
+ * had already opened, and a typed command's tier lived wherever that command
+ * happened to resolve one — `cf preview`, `cron run` and `db --target remote`
+ * each asking their own question. That meant `--tier` only worked for the
+ * commands that had been taught to parse it, and a contributor who wanted
+ * `pnpm devtools db status --target remote --tier staging` piped through a
+ * wizard question first anyway.
+ *
+ * This module settles the tier ONCE, before any command's imports — let alone
+ * its code — run, using the shared policy in `@devdogsuga/env/session`. By
+ * the time `cli.ts` is imported, `process.env.DEPLOY_ENV` already names the
+ * tier and its env files are already loaded, so `cli.ts`, `menu.ts` and every
+ * runner underneath them just read `process.env` like any other command would
+ * under `with-env` — this module IS the replacement for `with-env`'s job.
+ *
+ * ## `--tier`, a global flag
+ *
+ * `--tier <t>` is accepted at ANY position in argv and stripped here before
+ * `cli.ts` ever sees the rest, precisely so it cannot collide with a
+ * command's own flag of the same name (`db --target remote --tier staging`,
+ * `cron run --tier production`) — those still parse their OWN `--tier` out of
+ * the argv `cli.ts` receives, but by then the session's tier decision has
+ * already been made, and `resolveTier` (see `tier.ts`) falls back to reading
+ * it off `process.env.DEPLOY_ENV` rather than asking again.
+ */
+import { confirm, select } from "@clack/prompts";
+import { findCommand } from "./commands.js";
+import { discoverRepoRoot, findRepoRoot, RepoNotFoundError } from "./repo/root.js";
+import { loadEnvLoad, loadEnvSession } from "./repo/peers.js";
+import { isDevMode, ownVersion, runPreflight } from "./repo/preflight.js";
+import { errorMessage, unwrap } from "./ui.js";
+/**
+ * Pulls the two preflight-only boolean flags out of `argv`, wherever they
+ * sit, the same way `stripTierFlag` does for `--tier` below. Neither takes
+ * a value. `DEVTOOLS_SKIP_PREFLIGHT=1` is the env-var spelling of
+ * `--skip-preflight`, for shells/CI wrappers that would rather set an env
+ * var once than remember a flag on every invocation.
+ */
+export function stripPreflightFlags(argv) {
+    const rest = [];
+    let skipPreflight = process.env.DEVTOOLS_SKIP_PREFLIGHT === "1";
+    let refresh = false;
+    for (const arg of argv) {
+        if (arg === "--skip-preflight") {
+            skipPreflight = true;
+        }
+        else if (arg === "--refresh") {
+            refresh = true;
+        }
+        else {
+            rest.push(arg);
+        }
+    }
+    return { skipPreflight, refresh, rest };
+}
+/**
+ * Pulls a global `--tier <t>` out of `argv`, wherever it sits, leaving every
+ * other argument untouched and in its original order. Exported for its own
+ * unit tests; `launch()` below is the only real caller.
+ */
+export function stripTierFlag(argv) {
+    const rest = [...argv];
+    const index = rest.indexOf("--tier");
+    if (index === -1)
+        return { explicit: undefined, rest };
+    const value = rest[index + 1];
+    // A trailing `--tier` with nothing after it removes just the flag; the
+    // missing value then reaches `resolveSessionTier` as `explicit: undefined`,
+    // which falls through to `DEPLOY_ENV`/the sole tier/the prompt exactly as
+    // if `--tier` had never been typed, rather than this function guessing.
+    //
+    // A following token that is itself a flag is treated the same way, NOT
+    // consumed as the value — the guard every other flag-value reader in this
+    // CLI keeps (`cli.ts`'s `flagValue`). Without it,
+    // `--tier --help` or `--tier -h` would swallow the flag as a bogus tier and
+    // refuse with "unknown tier" instead of reaching the help bypass below.
+    const missing = value === undefined || value.startsWith("-");
+    rest.splice(index, missing ? 1 : 2);
+    return { explicit: missing ? undefined : value, rest };
+}
+/**
+ * Whether the command `rest` dispatches to is declared `envFree` in
+ * `commands.ts`'s catalog — the leading run of non-flag tokens is the
+ * command path (`["github", "rulesets"]` out of `["github", "rulesets",
+ * "--apply"]`), the same convention `stripTierFlag`/`stripPreflightFlags`
+ * already use for pulling a flag out of argv wherever it sits.
+ *
+ * Catalog-driven rather than a second hardcoded name list: `setup` and
+ * `completions` below stay their own explicit branch (each skips tier
+ * resolution for a DIFFERENT reason worth spelling out at the call site —
+ * see the comment above), but a plain "this command touches no env at all"
+ * exemption reads once, from the same tree `--help` and the wizard already
+ * render, rather than as a name a future GitHub-only command has to
+ * remember to add here too.
+ */
+function isEnvFreeCommand(rest) {
+    const path = [];
+    for (const arg of rest) {
+        if (arg.startsWith("-"))
+            break;
+        path.push(arg);
+    }
+    return findCommand(path)?.envFree === true;
+}
+/** The real interactive picker: a clack `select`, unwrapped so Ctrl-C exits
+ * cleanly instead of leaking a cancel symbol into `resolveSessionTier`.
+ * Values are session selector words (`"development:local"`, `"staging"`…). */
+async function promptTier(message, choices) {
+    return unwrap(await select({ message, options: choices }));
+}
+/**
+ * Imports `cli.ts` and runs it, reporting a thrown rejection the same way
+ * `cli.ts`'s own top level used to before `main` became an export instead of
+ * an auto-running IIFE (see `main`'s own header). Shared by both places
+ * `launch()` hands off to it: the `--help`/`-h` bypass below, and the normal
+ * post-tier-resolution path.
+ */
+async function dispatch(argv) {
+    const { main } = await import("./cli.js");
+    try {
+        await main(argv);
+    }
+    catch (err) {
+        process.stderr.write(`devtools: ${errorMessage(err)}\n`);
+        process.exit(1);
+    }
+}
+/**
+ * Resolves the session's deploy tier, enters it, and hands off to `cli.ts`.
+ *
+ * Exits the process directly on a refusal from `resolveSessionTier` — there
+ * is no command dispatched yet for a caller to fall back to, so there is
+ * nothing this function could return that would mean anything.
+ */
+export async function launch(argv) {
+    // Preflight runs on EVERY command of this bin, including `--help` — see
+    // `repo/preflight.ts`'s header. It never requires a repo (the manifest
+    // fetch/cache/self-refresh logic is entirely repo-independent), so it
+    // runs before `findRepoRoot()` is anywhere near the picture, unlike tier
+    // resolution below. `devtools-ci` (`launch-ci.ts`) deliberately does not
+    // call this at all — CI pins an exact version on purpose.
+    const { skipPreflight, refresh, rest: afterPreflight } = stripPreflightFlags(argv);
+    await runPreflight({
+        currentVersion: ownVersion(),
+        argv: afterPreflight,
+        skipPreflight,
+        refresh,
+        devMode: isDevMode(),
+        // Set only for testing against a local Verdaccio (see the end-to-end
+        // self-refresh validation in CUTOVER.md); unset in production, where a
+        // bare `pnpm dlx @devdogsuga/devtools@<version>` resolves against the
+        // default npm registry with no flag needed at all.
+        registry: process.env.DEVTOOLS_REGISTRY,
+    });
+    const { explicit, rest } = stripTierFlag(afterPreflight);
+    // `--help`/`-h` bypasses tier resolution entirely, BEFORE it can refuse.
+    // `cli.ts`'s own `main()` already answers these with no env in play (see
+    // its header comment); resolving a tier first anyway meant `pnpm devtools
+    // --help` refused outright on a machine with two-or-more tier files
+    // present — the ordinary state for anyone who has ever run `env pull` for
+    // staging or production — even though the command that would have run
+    // needs no database, credential, or `DEPLOY_ENV` at all. `bw --help` is
+    // NOT special-cased here the way `cli.ts` special-cases it ahead of its own
+    // `--help` check: `main()` still sees `bw` first and hands off to Bitwarden
+    // before ever reaching its `--help` branch, so routing straight to `main()`
+    // below reproduces that passthrough correctly either way.
+    if (rest.includes("--help") || rest.includes("-h")) {
+        await dispatch(rest);
+        return;
+    }
+    const envLoad = await loadEnvLoad();
+    const envSession = await loadEnvSession();
+    let tier;
+    let devDatabase;
+    if (rest[0] === "setup" || rest[0] === "completions" || isEnvFreeCommand(rest)) {
+        // Two commands run BEFORE there is a tier to resolve, and forcing the
+        // mandate on them breaks each in its own way:
+        //
+        //   * `setup` exists to CREATE a missing env file. A stale
+        //     `DEPLOY_ENV=staging` in the shell with no `.env.staging` on disk
+        //     would resolve that tier, fail `enterEnvironment` fatally below, and
+        //     lock a new contributor out of the one command that fixes their
+        //     state — a bootstrap deadlock. It is development-only by nature
+        //     (it writes `.env`), so the session tier question has one answer.
+        //   * `completions` runs from shell rc files (`eval "$(pnpm devtools
+        //     completions bash)"`), always non-TTY, and reads no env at all; the
+        //     multi-tier refusal would exit 1 in every new shell on exactly the
+        //     machines of the people working on the deploy workflow.
+        //
+        // A third, open-ended case joins them here via `isEnvFreeCommand`:
+        // `github rulesets` and `github settings` (TASK-322, TASK-342) touch no
+        // DevDogsUGA env file or database at all — every write either one makes
+        // is a `gh api` call resolved from its own `--org`/`--repo` flags — so
+        // demanding a `--tier` before either could run was never a real
+        // requirement, only every command sharing one dispatch gate. See
+        // `isEnvFreeCommand`'s own doc for why this is catalog-driven rather
+        // than a third name joining the `rest[0] ===` checks above.
+        //
+        // Development is still ENTERED below (missing-file tolerated), not
+        // skipped: `setup` under the old `with-env` wrapper saw whatever `.env`
+        // already existed, and keeping that means it can read current values
+        // when offering to rewrite them.
+        tier = "development";
+    }
+    else if (discoverRepoRoot() === null) {
+        // Every command past this point needs a real repo to resolve a tier
+        // against (`findRepoRoot()` below would throw `RepoNotFoundError`
+        // anyway) — surfaced here as the same clean, expected refusal every
+        // other repo-dependent command gives, rather than an uncaught throw
+        // with a stack trace pointing at internal module paths.
+        process.stderr.write(`devtools: ${new RepoNotFoundError().message}\n`);
+        process.exit(1);
+    }
+    else {
+        // The `.env`-names-a-remote-database lookup (and the port probe that
+        // phrases the local hint) are only paid when the resolution could
+        // actually land on BARE development — an explicit staging/production or
+        // qualified selector, an already-deployed DEPLOY_ENV, or a DEV_DB answer
+        // all settle the question without them, and the lookup imports dotenvx.
+        const deployEnv = process.env.DEPLOY_ENV ?? "";
+        const couldBeBareDevelopment = (process.env.DEV_DB ?? "") === "" &&
+            (explicit === "development" ||
+                (explicit === undefined &&
+                    (deployEnv === "" || deployEnv === "development")));
+        const remoteCandidate = couldBeBareDevelopment
+            ? await envSession.developmentRemoteCandidate(findRepoRoot())
+            : undefined;
+        const localStackOnline = typeof remoteCandidate === "string" ? await envLoad.probeLocalStack() : undefined;
+        const resolution = await envSession.resolveSessionTier({
+            explicit,
+            deployEnv: process.env.DEPLOY_ENV,
+            devDb: process.env.DEV_DB,
+            available: await envSession.availableTiers(findRepoRoot()),
+            isTTY: process.stdin.isTTY === true,
+            prompt: promptTier,
+            promptMessage: "Which environment should this session use?",
+            remoteCandidate,
+            localStackOnline,
+        });
+        if (!resolution.ok) {
+            process.stderr.write(`devtools: ${resolution.reason}\n`);
+            process.exit(1);
+        }
+        tier = resolution.tier;
+        devDatabase = resolution.devDatabase;
+    }
+    // Mandatory, not chattiness: which database a command is about to touch
+    // must never be a guess. Names the QUALIFIED session (`development:local`)
+    // when one was resolved. See `session.ts`'s and `load.ts`'s own headers.
+    const reportEntered = (files, label) => {
+        process.stderr.write(`devtools: loaded ${files.length > 0 ? files.join(", ") : "no env files"} (${label})\n`);
+    };
+    const sessionLabel = devDatabase === undefined ? tier : `${tier}:${devDatabase}`;
+    try {
+        // `override: false` — a fresh process, so an already-exported shell
+        // variable beats the file the same way `with-env` always let it, rather
+        // than a stale `.env.<tier>` value silently winning over what the caller
+        // just set for this one invocation.
+        const entered = await envSession.enterEnvironment(tier, {
+            override: false,
+            devDatabase,
+        });
+        for (const warning of entered.warnings) {
+            process.stderr.write(`devtools: ${warning}\n`);
+        }
+        reportEntered(entered.files, sessionLabel);
+    }
+    catch (err) {
+        if (err instanceof envLoad.LocalStackOfflineError) {
+            // The session explicitly means the local database and the stack is not
+            // reachable.
+            process.stderr.write(`devtools: ${err.message}\n`);
+            // Rather than making the contributor stop, run `db start`, and re-run
+            // whatever they meant, offer to bring the stack up right here and then
+            // carry on with their original command. Only on a TTY (there is no one
+            // to answer otherwise), and not when the command is ITSELF a stack
+            // lifecycle command — `db start`/`stop`/`restart` do this on their own,
+            // and `db stop` against an already-down stack must not be interrupted by
+            // an offer to start it. The bare top menu is likewise left to its own
+            // Database → start entry.
+            const lifecycle = rest[0] === "db" &&
+                (rest[1] === "start" || rest[1] === "stop" || rest[1] === "restart");
+            if (process.stdin.isTTY === true && rest.length !== 0 && !lifecycle) {
+                const start = unwrap(await confirm({
+                    message: "Start the local Supabase stack now?",
+                }));
+                if (start) {
+                    // Keep the session's local qualifier set so the env refresh that
+                    // `runStackCommand("start")` performs on success re-applies the
+                    // overlay under it, and the command we dispatch next resolves the
+                    // freshly-started local database.
+                    if (devDatabase !== undefined)
+                        process.env.DEV_DB = devDatabase;
+                    const { runStackCommand } = await import("./stack.js");
+                    const { code, lines } = await runStackCommand("start", null);
+                    for (const line of lines) {
+                        process.stderr.write(`devtools: ${line}\n`);
+                    }
+                    if (code === 0) {
+                        await dispatch(rest);
+                        return;
+                    }
+                    process.stderr.write("devtools: the stack did not start — see the Supabase CLI output " +
+                        "above.\n");
+                    process.exit(1);
+                }
+            }
+            // Declined, or nobody to ask. `db` (whose `start` is the fix, and whose
+            // data commands re-check the connection themselves) and the bare menu
+            // (the road to `db start`) may continue in a degraded, unqualified
+            // entry; anything else stops here, with the error's own troubleshooting,
+            // instead of failing later against whatever `.env` happens to name.
+            if (rest.length !== 0 && rest[0] !== "db")
+                process.exit(1);
+            process.stderr.write("devtools: continuing without the overlay so `db start` can fix this.\n");
+            const inherited = process.env.DEV_DB;
+            delete process.env.DEV_DB;
+            const entered = await envSession.enterEnvironment(tier, { override: false });
+            if (devDatabase !== undefined) {
+                // Children spawned AFTER `db start` succeeds should still inherit
+                // the session's answer; the refresh that follows a successful start
+                // re-applies the overlay under this same variable.
+                process.env.DEV_DB = devDatabase;
+            }
+            else if (inherited !== undefined) {
+                process.env.DEV_DB = inherited;
+            }
+            for (const warning of entered.warnings) {
+                process.stderr.write(`devtools: ${warning}\n`);
+            }
+            reportEntered(entered.files, tier);
+            await dispatch(rest);
+            return;
+        }
+        if (!(err instanceof envLoad.MissingEnvFileError))
+            throw err;
+        if (tier === "development") {
+            // The clean-clone path: a fresh checkout has no `.env` at all, and
+            // `pnpm devtools setup` is how one gets created — `MissingEnvFileError`
+            // names it. Reporting and continuing here, rather than refusing, is
+            // what lets `setup` itself run through this same entry point. See
+            // `load.ts`'s `MissingEnvFileError` for the message this prints.
+            process.stderr.write(`devtools: ${err.message}\n`);
+        }
+        else {
+            // An EXPLICITLY selected staging/production tier with no env file is
+            // not a first run — it is a real problem, and `env pull` is the fix
+            // `MissingEnvFileError`'s own message already names. Fatal.
+            process.stderr.write(`devtools: ${err.message}\n`);
+            process.exit(1);
+        }
+    }
+    // Caught here rather than left to `bin/devtools.mjs`'s `child.on("error",
+    // …)`, which only ever sees a spawn failure, never a rejection thrown
+    // inside this process.
+    await dispatch(rest);
+}
+// `bin/devtools.mjs` runs this file directly through tsx — `tsx
+// --conditions=devdogs-source src/launch.ts <argv…>` — so `process.argv`
+// carries this file's own path where a bare `node` invocation would, and the
+// real argv starts one slot later.
+if (import.meta.url === `file://${process.argv[1]}`) {
+    await launch(process.argv.slice(2));
+}

package/dist/menu.d.ts

@@ -0,0 +1,31 @@
+import { type Environment } from "./environment.js";
+/**
+ * The command path when argv names a group with subcommands but no subcommand
+ * token — what `devtools db` and `devtools db seed` are. Returns null for a
+ * leaf command, an unknown token, or a bare invocation (which the no-argument
+ * wizard already covers). The caller resumes the wizard at this node when
+ * stdin is a TTY; a non-TTY caller keeps the dispatcher's "which of …?" exit.
+ */
+export declare function bareGroupStartPath(argv: readonly string[]): string[] | null;
+/**
+ * Runs the wizard, returning the `outro()` line its command earned.
+ *
+ * `dispatch` is the CLI's own argv handler, injected rather than imported so
+ * that `cli.ts` keeps a single definition of what each command does and the
+ * tests can watch what a walk produces without running it. Its return value
+ * passes straight through, the closing line or `null` for a failure already
+ * explained, so a command reached from the menu signs off exactly as it does
+ * from the command line.
+ *
+ * `options.startPath`, from `bareGroupStartPath`, skips straight to that
+ * node's subcommand screen — see `walk`'s `startPath` branch.
+ *
+ * The deploy tier is NOT asked here any more. `src/launch.ts` resolves and
+ * enters it before `cli.ts` — and therefore this module — is even imported,
+ * so by the time the wizard opens the whole session is already running under
+ * it, exactly as if `--tier` had been typed. Recording it for the "run it
+ * directly next time" line only needs to read `process.env.DEPLOY_ENV` back.
+ */
+export declare function runMenu(dispatch: (argv: string[]) => Promise<string | null>, env?: Environment, options?: {
+    startPath?: string[];
+}): Promise<string | null>;

package/dist/menu.js

@@ -0,0 +1,277 @@
+/**
+ * The wizard: `pnpm devtools` with no arguments.
+ *
+ * ## The one property worth protecting
+ *
+ * **It builds an argv and hands it to the CLI's own dispatcher.** It does not
+ * call command functions directly. That is what makes "the menu covers every
+ * interactive command" structural instead of aspirational. The menu it replaced held a
+ * hand-written list of ten entries beside a CLI that had grown to sixteen
+ * top-level commands and thirty-one subcommands, so `env`, `planner` and
+ * `docs index` were reachable only by someone who already knew their names.
+ * A contributor who does not know a command name is the entire audience for
+ * this file.
+ *
+ * Walking `commands.ts` means an interactive command added there is in the
+ * menu the same day, with its options. Commands marked `cli-only` and deploy
+ * commands in the separate `devtools-ci` bin do not appear here.
+ */
+import { confirm, note, select, text } from "@clack/prompts";
+import { positionals } from "./args.js";
+import { findCommand, GROUPS, SCOPES, } from "./commands.js";
+import { blockedBecause, describeEnvironment, isOffered, probeEnvironment, } from "./environment.js";
+import { beginInvocation, recordEnteredTier } from "./invocation.js";
+import { unwrap } from "./ui.js";
+/** Chosen when a submenu should return to the screen above it. */
+const BACK = Symbol("back");
+const BACK_OPTION = { value: BACK, label: "← Back" };
+// ── What this machine is offered ─────────────────────────────────────────────
+/**
+ * The commands at one level that are worth showing right now.
+ *
+ * `when` is the only thing that removes an entry, and it removes very few;
+ * see `isOffered`. Everything else stays on screen and explains itself
+ * through `hintFor` below, because the menu's job is to help someone who does
+ * not know a command's name, and it cannot do that for a command it declined
+ * to draw.
+ */
+function offered(nodes, env) {
+    return nodes.filter((node) => node.surface !== "cli-only" && isOffered(node, env));
+}
+/**
+ * The line beside a name, with whatever is standing in this command's way.
+ *
+ * The reader learns that `roundtrip` needs a stack that is not up *before*
+ * choosing it, instead of after a spinner and a connection error. The command
+ * stays selectable: the check is a probe, the probe can be wrong, and the
+ * command's own failure message is the authority on whether it can run.
+ */
+function hintFor(node, env) {
+    const base = node.hint ?? node.summary;
+    const blocked = blockedBecause(node, env);
+    const said = blocked ? `${base} — ${blocked}` : base;
+    // The scope leads, because in the one group that has scopes it is the thing
+    // the reader is actually choosing between: `restart` and `reset` sit four
+    // lines apart and act on different layers.
+    return node.scope ? `${SCOPES[node.scope].menu} · ${said}` : said;
+}
+// ── Screens ──────────────────────────────────────────────────────────────────
+async function pickGroup(env) {
+    // A group whose every command is hidden has nothing behind its door, so the
+    // door is not drawn. No group in the tree can empty out today; this is here
+    // so that a later `when` cannot leave a dead entry on the first screen.
+    const groups = GROUPS.filter((group) => offered(group.commands, env).length > 0);
+    const choice = unwrap(await select({
+        message: "What would you like to do?",
+        options: [
+            ...groups.map((group) => ({
+                value: group,
+                label: group.title,
+                // The group's own commands, so the first screen says what is behind
+                // each door rather than making the reader open every one to find out.
+                hint: offered(group.commands, env)
+                    .map((command) => command.name)
+                    .join(", "),
+            })),
+            { value: null, label: "Quit" },
+        ],
+    }));
+    return choice;
+}
+async function pickCommand(group, env) {
+    const commands = offered(group.commands, env);
+    // A group with one command has nothing to choose; asking would be a screen
+    // whose only real option is the one already implied by the group's title.
+    if (commands.length === 1)
+        return commands[0];
+    return unwrap(await select({
+        message: `${group.title}:`,
+        options: [
+            ...commands.map((command) => ({
+                value: command,
+                label: command.name,
+                hint: hintFor(command, env),
+            })),
+            BACK_OPTION,
+        ],
+    }));
+}
+async function pickSubcommand(node, env) {
+    return unwrap(await select({
+        message: `${node.name}:`,
+        options: [
+            ...offered(node.subcommands ?? [], env).map((child) => ({
+                value: child,
+                label: child.name,
+                hint: hintFor(child, env),
+            })),
+            BACK_OPTION,
+        ],
+    }));
+}
+// ── Options ──────────────────────────────────────────────────────────────────
+/**
+ * Asks for one option, returning the argv fragment it contributes.
+ *
+ * An empty array is a real answer, not a failure: a declined confirm adds no
+ * flag, and a blank optional text means "let the command decide", which is
+ * how `--db-url` falls back to `.env.production` and `--base-url` falls
+ * through to the OAuth wizard's own prompt.
+ */
+async function askOption(option) {
+    const prompt = option.prompt;
+    if (!prompt)
+        return [];
+    if (prompt.kind === "confirm") {
+        // Yes adds the flag, always. `commands.ts` phrases every message so that
+        // this needs no per-option inversion.
+        const yes = unwrap(await confirm({ message: prompt.message, initialValue: prompt.initial }));
+        return yes ? [option.flag] : [];
+    }
+    if (prompt.kind === "text") {
+        const answer = unwrap(await text({
+            message: prompt.message,
+            placeholder: prompt.placeholder,
+            defaultValue: "",
+        })).trim();
+        return answer ? [option.flag, answer] : [];
+    }
+    const choice = unwrap(await select({
+        message: prompt.message,
+        options: prompt.choices.map((c) => ({
+            value: c.value,
+            label: c.label ?? c.value,
+            hint: c.hint,
+        })),
+    }));
+    return [option.flag, choice];
+}
+async function askOptions(node) {
+    const argv = [];
+    for (const option of node.options ?? []) {
+        argv.push(...(await askOption(option)));
+    }
+    return argv;
+}
+/**
+ * Descends from `start` through its subcommand screens to a leaf, then asks
+ * that leaf's options.
+ *
+ * Shared by both entries into a walk: the top-of-tree loop below, which calls
+ * this once a group and its first command are chosen, and a resumed walk
+ * (`walk`'s `startPath` branch), which calls it directly on a node the caller
+ * already picked by argv. `while` rather than a single step because the tree
+ * is two deep today and this does not care. The condition counts the OFFERED
+ * children rather than all of them, so a node whose every subcommand is
+ * hidden is treated as the leaf it has become instead of opening a screen
+ * holding only "Back".
+ */
+async function descendFrom(start, pathNames, env) {
+    let node = start;
+    const path = [...pathNames];
+    while (offered(node.subcommands ?? [], env).length > 0) {
+        const child = await pickSubcommand(node, env);
+        if (child === BACK)
+            return BACK;
+        node = child;
+        path.push(node.name);
+    }
+    return { node, argv: [...path, ...(await askOptions(node))] };
+}
+/**
+ * Walks the tree to a leaf and its options, either from the top or resumed at
+ * a known group.
+ *
+ * `startPath`, when given, is a path to a group node from `bareGroupStartPath`
+ * — `["db"]` for `devtools db` — and lands here instead of at `pickGroup`.
+ * There is no group screen above a resumed node (the caller already named it
+ * by typing `db`), so BACK on its first subcommand screen has nowhere to
+ * return to but out, unlike BACK from the top of the tree, which returns to
+ * `pickGroup`.
+ */
+async function walk(env, startPath) {
+    if (startPath) {
+        const start = findCommand(startPath);
+        if (!start)
+            return null; // defensive: the caller guarantees a group node
+        const chosen = await descendFrom(start, [...startPath], env);
+        return chosen === BACK ? null : chosen;
+    }
+    for (;;) {
+        const group = await pickGroup(env);
+        if (!group)
+            return null;
+        const first = await pickCommand(group, env);
+        if (first === BACK)
+            continue;
+        const chosen = await descendFrom(first, [first.name], env);
+        if (chosen === BACK)
+            continue;
+        return chosen;
+    }
+}
+// ── Resuming at a node ───────────────────────────────────────────────────────
+/**
+ * The command path when argv names a group with subcommands but no subcommand
+ * token — what `devtools db` and `devtools db seed` are. Returns null for a
+ * leaf command, an unknown token, or a bare invocation (which the no-argument
+ * wizard already covers). The caller resumes the wizard at this node when
+ * stdin is a TTY; a non-TTY caller keeps the dispatcher's "which of …?" exit.
+ */
+export function bareGroupStartPath(argv) {
+    const path = positionals(argv);
+    if (path.length === 0)
+        return null;
+    const node = findCommand(path);
+    if (!node || (node.subcommands ?? []).length === 0)
+        return null;
+    return path;
+}
+// ── Entry ────────────────────────────────────────────────────────────────────
+/**
+ * Runs the wizard, returning the `outro()` line its command earned.
+ *
+ * `dispatch` is the CLI's own argv handler, injected rather than imported so
+ * that `cli.ts` keeps a single definition of what each command does and the
+ * tests can watch what a walk produces without running it. Its return value
+ * passes straight through, the closing line or `null` for a failure already
+ * explained, so a command reached from the menu signs off exactly as it does
+ * from the command line.
+ *
+ * `options.startPath`, from `bareGroupStartPath`, skips straight to that
+ * node's subcommand screen — see `walk`'s `startPath` branch.
+ *
+ * The deploy tier is NOT asked here any more. `src/launch.ts` resolves and
+ * enters it before `cli.ts` — and therefore this module — is even imported,
+ * so by the time the wizard opens the whole session is already running under
+ * it, exactly as if `--tier` had been typed. Recording it for the "run it
+ * directly next time" line only needs to read `process.env.DEPLOY_ENV` back.
+ */
+export async function runMenu(dispatch, env = probeEnvironment(), options = {}) {
+    // Before the first question, not after a failure. Three lines saying what
+    // this machine currently is explain why the database commands below are
+    // flagged, and cost one glance on a healthy machine. Injected rather than
+    // probed inside `walk` so the tests can drive a machine they describe
+    // instead of the one they happen to run on.
+    note(describeEnvironment(env), "This machine");
+    const chosen = await walk(env, options.startPath);
+    // Quitting is not a failure, but it has nothing to announce either.
+    if (!chosen)
+        return null;
+    // Every step here was a prompt, so the built argv is the reproducible
+    // command — a runner that prompts further (a bare `workflows run`) appends
+    // the rest through `recordResolved`, and the entered tier rides along as the
+    // `--tier` flag `recordEnteredTier` adds.
+    beginInvocation(chosen.argv, true);
+    // A development session that answered the "which development database?"
+    // question records the QUALIFIED selector, so the "run it directly next
+    // time" line reproduces the whole session — a bare `development` would
+    // re-ask (or refuse, non-interactively) on a machine whose `.env` names a
+    // remote DB_URL.
+    const enteredTier = process.env.DEPLOY_ENV ?? "development";
+    const devDb = process.env.DEV_DB;
+    recordEnteredTier(enteredTier === "development" && (devDb === "local" || devDb === "remote")
+        ? `development:${devDb}`
+        : enteredTier);
+    return dispatch(chosen.argv);
+}