@devdogsuga/devtools 0.1.0

package/dist/cli.js

@@ -0,0 +1,1077 @@
+/**
+ * `pnpm devtools [--tier <development:local|development:remote|staging|production>] [command]`
+ *
+ * Run it with no arguments and it opens a menu. That is the point: a
+ * contributor should be able to set up a database and check their moderation
+ * integration without knowing a single command name, and without reading this
+ * file first.
+ *
+ * The subcommands still exist for anyone who does know them, and for CI, which
+ * cannot answer a prompt.
+ *
+ * ## Three files, one tree
+ *
+ * `commands.ts` holds the command tree as data. `help.ts` renders one level of
+ * it at a time, and `menu.ts` walks it into an argv that comes back through
+ * `dispatch()` below, the same entry a typed command line takes. That is why
+ * the menu covers everything the CLI does: there is no second list of commands
+ * anywhere, so there is nothing to fall out of step.
+ */
+import { confirm, intro, log, note, outro, select, spinner, } from "@clack/prompts";
+import { assertMigrated, detectLocalInstance, PERSONAS, } from "./instance.js";
+import { conformance, listApps, quarantineRoundTrip } from "./doctor.js";
+import { currentRootHolder, grantRoot, listCandidates, transferRoot, } from "./grantRoot.js";
+import { connectRemoteProject, runStackCommand, } from "./stack.js";
+import { runConfigPush } from "./db/config-push.js";
+import { describeDbTarget, isLocalConnection, resolveDbConnection, } from "./db/connection.js";
+import { runDbExec } from "./db/exec.js";
+import { runGenerateMigration } from "./db/generate-migration.js";
+import { runGenerateTypes } from "./db/generate-types.js";
+import { runIntrospect } from "./db/introspect.js";
+import { runNewMigration } from "./db/new-migration.js";
+import { runSeedBuckets } from "./db/seed-buckets.js";
+import { runSeedProduction } from "./db/seed-production.js";
+import { runSeedRoles } from "./db/seed-roles.js";
+import { runOAuthSetup } from "./oauth/wizard.js";
+import { beginInvocation, recordEnteredTier, recordResolved, reproducibleCommand, } from "./invocation.js";
+import { runSetup } from "./setup.js";
+import { readCatalog, renderCatalog } from "./catalog.js";
+import { runEnvAudit, runEnvPull, runEnvPush, runEnvReset, } from "./env/commands.js";
+import { runEnvExample, runEnvInit } from "./env/example.js";
+import { runPlannerCreate, runPlannerDrop, runPlannerResetPassword, runPlannerStatus, } from "./planner/commands.js";
+import { loadRegistry } from "./env/discovery.js";
+import { loadEnv } from "./repo/peers.js";
+import { setExplicitAccessToken } from "./bws/client.js";
+import { positionals } from "./args.js";
+import { resolveVaultTarget } from "./pick.js";
+import { bail, errorMessage, explain, renderChecks, unwrap } from "./ui.js";
+import { helpPath, renderHelp } from "./help.js";
+import { subcommandList, subcommandNames } from "./commands.js";
+import { bareGroupStartPath, runMenu } from "./menu.js";
+import { runDocsIndex } from "./docs/index-pages.js";
+import { runTask } from "./run/pick.js";
+import { runCompletions } from "./completions.js";
+import { runBw } from "./bws/bw.js";
+import { runImages } from "./images/commands.js";
+import { runEmails } from "./emails/commands.js";
+import { runGen } from "./gen/commands.js";
+import { runCronList, runCronRun } from "./cron/commands.js";
+import { runGithubRulesets } from "./gh/rulesets/commands.js";
+import { runGithubSettings } from "./gh/settings/commands.js";
+import { runWorkflows } from "./workflows/commands.js";
+import { runCf } from "./cf/commands.js";
+import { captureDevtoolsError, initDevtoolsTelemetry } from "./telemetry.js";
+import { ownVersion } from "./repo/preflight.js";
+const DOCTOR_COMMANDS = [
+    "doctor",
+    "roundtrip",
+    "catalog",
+    "grant-root",
+];
+function isDoctorCommand(value) {
+    return DOCTOR_COMMANDS.includes(value);
+}
+function flagValue(rest, flag) {
+    const index = rest.indexOf(flag);
+    if (index === -1)
+        return undefined;
+    const value = rest[index + 1];
+    return value && !value.startsWith("--") ? value : undefined;
+}
+/**
+ * The retired flags a `db` invocation can still carry from muscle memory or
+ * an old script. Refused loudly, never ignored: a flag that looks like it
+ * selects the database while actually deciding nothing is exactly the
+ * silent lie the session vocabulary replaced. The session (`--tier
+ * development:local|development:remote|staging|production`, settled by the
+ * launcher before dispatch) is the ONE selector now.
+ */
+function refuseRetiredDbFlags(rest) {
+    for (const flag of ["--target", "--team"]) {
+        if (rest.includes(flag)) {
+            process.stderr.write(`devtools db: ${flag} is retired. The session already names the ` +
+                "database — relaunch with --tier development:local, " +
+                "development:remote, staging, or production.\n");
+            process.exitCode = 1;
+            return true;
+        }
+    }
+    return false;
+}
+// ── Connecting ───────────────────────────────────────────────────────────────
+/**
+ * Finds the local stack and checks it has been migrated.
+ *
+ * These commands only ever run against a local stack, and that is structural
+ * rather than a rule they follow: `detectLocalInstance` reads `supabase
+ * status`, which describes the Docker stack on this machine and nothing else.
+ * There is no remote project for it to return, so the tier check that used to
+ * sit here, reading a `production` flag out of the database, bought nothing and
+ * has been removed along with the table it read.
+ */
+async function connect() {
+    const s = spinner();
+    s.start("Looking for your database");
+    let instance;
+    try {
+        instance = detectLocalInstance();
+    }
+    catch (err) {
+        s.stop("Could not find a running database");
+        explain("The local Supabase stack is not reachable.", errorMessage(err), [
+            "1. Make sure Docker is running",
+            "2. Run `pnpm devtools db start` (or choose Database → start in the menu)",
+            "3. Confirm with `supabase status`",
+        ]);
+        return null;
+    }
+    try {
+        await assertMigrated(instance);
+        s.stop(`Connected to your database at ${instance.apiUrl}`);
+    }
+    catch (err) {
+        s.stop("Connected, but the schema is not there");
+        explain("That instance cannot be used here.", errorMessage(err), [
+            "Run `pnpm devtools db reset` to rebuild your own database from migrations and seeds.",
+        ]);
+        return null;
+    }
+    return instance;
+}
+// ── Commands ─────────────────────────────────────────────────────────────────
+async function runStack(command, rest) {
+    // The data commands need the session's connection before anything else —
+    // including before the reset confirmation below, which has to name what it
+    // is about to erase. The lifecycle commands (`start`/`stop`/`restart`)
+    // skip resolution outright: they act on this machine's containers, and
+    // `db start` is the FIX for the very state resolution would refuse on.
+    // `status` resolves quietly and treats "nothing resolvable" as an answer.
+    let connection = null;
+    if (command === "migrate" || command === "reset") {
+        connection = await resolveDbConnection({ label: `devtools db ${command}` });
+        if (!connection) {
+            process.exitCode = 1;
+            return;
+        }
+    }
+    else if (command === "status") {
+        connection = await resolveDbConnection({ quiet: true });
+    }
+    // `reset` drops everything, and a non-local `migrate` pushes straight to a
+    // shared database — both worth a question before they run. The local stack
+    // gets the harmless-sounding question, every hosted database a harder one
+    // naming exactly which, and production the hardest of all.
+    const local = connection !== null && isLocalConnection(connection);
+    if (connection !== null &&
+        (command === "reset" || (command === "migrate" && !local))) {
+        if (!local) {
+            // Named up front, and ONLY the tier/host and project — never the
+            // DB_URL, which carries the password — so whoever is about to answer
+            // "yes" knows exactly what they are agreeing to.
+            log.message(`This will ${command === "reset" ? "reset" : "push migrations to"} ${describeDbTarget(connection)}` +
+                (connection.projectRef
+                    ? ` (project ${connection.projectRef}).`
+                    : "."));
+        }
+        // ⚠️ SAFETY: gates every branch below, including production — `--yes` is
+        // the ONE way past any of them, checked before anything TTY-dependent
+        // runs. clack's `confirm()` never resolves without a TTY (reproduced
+        // against @clack/core@1.4.3), so a non-interactive caller without --yes
+        // must be refused outright rather than left to hang forever on a prompt
+        // nobody is there to answer.
+        if (!rest.includes("--yes")) {
+            if (!process.stdin.isTTY) {
+                process.stderr.write(`devtools db ${command}: --yes is required to run non-interactively.\n`);
+                process.exitCode = 1;
+                return;
+            }
+            if (connection.tier === "production") {
+                // Production gets the sternest wording of the three: this is the one
+                // database in this whole CLI that must never be touched by a
+                // reflexive keystroke.
+                const confirmed = unwrap(await confirm({
+                    message: (command === "reset"
+                        ? "This PERMANENTLY ERASES the PRODUCTION database "
+                        : "This pushes new migrations to the PRODUCTION database ") +
+                        `(project ${connection.projectRef ?? "unknown"}). Continue?`,
+                    initialValue: false,
+                }));
+                if (!confirmed)
+                    bail("Left the database alone.");
+            }
+            else {
+                const confirmed = unwrap(await confirm({
+                    message: command === "reset"
+                        ? local
+                            ? "This erases your local database and rebuilds it. Continue?"
+                            : `This erases ${describeDbTarget(connection)} and rebuilds it. Continue?`
+                        : `This pushes new migrations to ${describeDbTarget(connection)}. Continue?`,
+                    initialValue: local,
+                }));
+                if (!confirmed)
+                    bail("Left the database alone.");
+            }
+        }
+    }
+    try {
+        const { code, lines } = await runStackCommand(command, connection);
+        for (const line of lines)
+            log.message(line);
+        if (code !== 0) {
+            // Lines on a failure ARE the explanation, which is the contract with
+            // `runStackCommand`. "Scroll up for the Supabase CLI's output" is only
+            // true when a delegated script ran, and pointing a reader at output that
+            // does not exist is worse than adding nothing. A failure with scrollback
+            // worth reading says so in its own line.
+            if (lines.length === 0) {
+                explain(`\`${command}\` did not finish cleanly.`, "", [
+                    "Scroll up for the output from the Supabase CLI.",
+                ]);
+            }
+            process.exitCode = code;
+        }
+    }
+    catch (err) {
+        explain(`\`${command}\` failed.`, errorMessage(err));
+        process.exitCode = 1;
+    }
+}
+async function runCatalog(instance) {
+    const catalog = await readCatalog(instance);
+    note(renderCatalog(catalog), "Moderation catalog");
+}
+async function runDoctor(instance, appSlug) {
+    let slug = appSlug;
+    if (!slug) {
+        const apps = await listApps(instance);
+        slug = unwrap(await select({
+            message: "Which app should I check?",
+            options: apps.map((value) => ({
+                value,
+                label: value,
+                hint: value === "platform" ? "the worked example" : undefined,
+            })),
+        }));
+    }
+    const s = spinner();
+    s.start(`Checking ${slug}`);
+    let types;
+    try {
+        types = await conformance(instance, slug);
+        s.stop(`Checked ${slug}`);
+    }
+    catch (err) {
+        s.stop("The check could not run");
+        explain("conformance_check() failed.", errorMessage(err), [
+            `Signing in as ${PERSONAS.moderator} needs the seeds — try \`pnpm devtools db reset\`.`,
+        ]);
+        return;
+    }
+    if (types.length === 0) {
+        note(`${slug} has no moderatable content types.\n\n` +
+            "A table becomes one by carrying a foreign key to\n" +
+            'platform."reportResolutions" -- adding that column is the whole\n' +
+            "registration. See docs/platform/reporting-and-feedback.md.", "Nothing to check");
+        return;
+    }
+    let failures = 0;
+    for (const type of types) {
+        const failed = type.checks.filter((c) => !c.ok).length;
+        failures += failed;
+        note(renderChecks(type.checks), `${type.tableName} → "${type.contentType}"`);
+    }
+    if (failures === 0) {
+        log.success(`${slug} looks correctly integrated.`);
+    }
+    else {
+        log.warn(`${failures} check${failures === 1 ? "" : "s"} failed. The last two are ` +
+            "heuristics over policy text, so a failure there is worth reading rather " +
+            "than trusting outright.");
+    }
+}
+async function runRoundTrip(instance) {
+    const s = spinner();
+    s.start("Filing a report, quarantining it, and looking again");
+    try {
+        const steps = await quarantineRoundTrip(instance);
+        s.stop("Round-trip finished");
+        note(renderChecks(steps), "What happened");
+        const failed = steps.filter((step) => !step.ok);
+        if (failed.length === 0) {
+            log.success("Quarantine freezes a reported profile and resets the display name, and the fixtures were cleaned up.");
+        }
+        else {
+            log.warn(`${failed.length} step${failed.length === 1 ? "" : "s"} did not hold. ` +
+                "The fixtures were still cleaned up.");
+        }
+    }
+    catch (err) {
+        s.stop("The round-trip could not run");
+        explain("Something went wrong before the checks could finish.", errorMessage(err), [
+            "`pnpm devtools db reset` rebuilds the database with the seeded personas and the open report they act on.",
+        ]);
+    }
+}
+/**
+ * Grants Root, asking who to if it was not told.
+ *
+ * Transferring is a separate confirmation from granting, because they are
+ * different actions wearing the same name: one gives you a console you did not
+ * have, the other takes somebody else's away. `userRoles_root_singleton` means
+ * there is no state where both hold it, so the release cannot be skipped.
+ */
+async function runGrantRoot(instance, userEmail) {
+    let holder;
+    let candidates;
+    try {
+        [holder, candidates] = await Promise.all([
+            currentRootHolder(instance),
+            listCandidates(instance),
+        ]);
+    }
+    catch (err) {
+        explain("Could not read the current roles.", errorMessage(err));
+        process.exitCode = 1;
+        return;
+    }
+    if (candidates.length === 0) {
+        explain("There are no accounts on this database yet.", "", [
+            "Sign in once through the app, then run this again.",
+            `Or use a seeded persona: ${PERSONAS.member}, password \`password\`.`,
+        ]);
+        return;
+    }
+    const chosen = userEmail ??
+        unwrap(await select({
+            message: "Which account should hold Root?",
+            options: candidates.map((c) => ({
+                value: c.email,
+                label: c.email,
+                hint: c.userId === holder?.userId ? "holds it now" : undefined,
+            })),
+        }));
+    const target = candidates.find((c) => c.email === chosen);
+    if (!target) {
+        explain(`No account on this database has the address ${chosen}.`, "", [
+            "Run without --user to pick from a list.",
+        ]);
+        process.exitCode = 1;
+        return;
+    }
+    if (holder?.userId === target.userId) {
+        log.info(`${target.email} already holds Root.`);
+        return;
+    }
+    try {
+        if (holder) {
+            const confirmed = unwrap(await confirm({
+                message: `Root is held by ${holder.email}. Take it away and give it to ${target.email}?`,
+                initialValue: false,
+            }));
+            if (!confirmed)
+                bail("Left Root where it was.");
+            await transferRoot(instance, holder.userId, target.userId);
+        }
+        else {
+            await grantRoot(instance, target.userId);
+        }
+        log.success(`${target.email} now holds Root, which confers every permission. ` +
+            "Sign out and back in if the console was already open.");
+    }
+    catch (err) {
+        explain("Could not grant Root.", errorMessage(err), [
+            "Seeds create the Root role definition — try `pnpm devtools db reset` first.",
+        ]);
+        process.exitCode = 1;
+    }
+}
+/**
+ * `env <pull|push|audit> --target <preflight|staging|production>`, plus the
+ * three local-only subcommands: `reset`, `example [--check]`, and
+ * `init [--target <target>]`.
+ *
+ * The target has no default for pull/push/audit, and is asked for when
+ * `--target` is absent. Every other command here defaults to the local stack
+ * because guessing wrong is free; guessing wrong about whose credentials to
+ * overwrite is not. (`init` does default, to development: it refuses to touch
+ * an existing file, so the worst a wrong guess can do is create a blank one.)
+ *
+ * One flag, one vocabulary. `--target` names a row in the target table, and
+ * the file, the Bitwarden project and whether `DEPLOY_ENV` may say it all come
+ * from that row. Its predecessor `--env` named one of two different enums
+ * depending on which subcommand read it, which is why `init --env staging`
+ * wrote `.env.staging` while `push --env staging` uploaded `.env`.
+ */
+async function runEnvCommand(rest) {
+    const { ENV_TARGETS, isEnvTarget } = await loadEnv();
+    // `positionals` rather than `rest[0]`, so a flag before the subcommand does
+    // not become the subcommand -- and, more to the point, so the VALUE of a flag
+    // never does: in `env --file production pull`, `production` is a filename and
+    // must not be read as anything else.
+    const [sub] = positionals(rest);
+    // Validated against the command tree rather than a list kept here. One
+    // declaration means a subcommand cannot exist in the CLI and be missing
+    // from the menu, or the reverse.
+    if (!sub || !subcommandNames(["env"]).includes(sub)) {
+        log.error(`Unknown env subcommand: ${sub ?? "(none)"}`);
+        log.message(`Try ${subcommandList(["env"])}.`);
+        process.exitCode = 1;
+        return;
+    }
+    // Refused by name rather than ignored. `--env` used to be this flag, and the
+    // words it took (`staging`, `production`) are still valid `--target` values,
+    // so a stale invocation would otherwise run with NO target: prompting, or
+    // failing as "nobody here to ask", neither of which says what changed.
+    if (rest.includes("--env")) {
+        explain("`--env` is now `--target`.", "", [
+            "It named two different things depending on the subcommand: which file",
+            "(init) and which Bitwarden project (pull/push/audit). --target names",
+            `one row: ${ENV_TARGETS.join(", ")}.`,
+            "wrangler, supabase and gh still have their own --env; this is ours.",
+        ]);
+        process.exitCode = 1;
+        return;
+    }
+    // `reset` only edits a local file. Asking which target to clear it against
+    // would imply it reaches one, which is the opposite of what it does.
+    if (sub === "reset") {
+        try {
+            await runEnvReset({
+                file: flagValue(rest, "--file"),
+                yes: rest.includes("--yes"),
+            });
+        }
+        catch (err) {
+            explain("The reset failed.", errorMessage(err));
+            process.exitCode = 1;
+        }
+        return;
+    }
+    // Every remaining subcommand reads the registry, which fills only when the
+    // env manifests are imported. Loaded HERE, lazily, rather than at CLI
+    // start: the import pass touches a manifest in nearly every workspace
+    // package, and `pnpm devtools db reset` (or any stack command) should not pay
+    // for declarations it never reads. `env reset` returned above for the
+    // same reason: it edits the local file and consults no key set.
+    await loadRegistry();
+    // `example` and `init` are pure registry → text. They return BEFORE the
+    // Bitwarden token lookup and the pull/push target prompt, and must
+    // keep doing so: CI's credential-free validate job runs `example --check`,
+    // and a generator that needed a secret to describe the secrets could not
+    // live there.
+    if (sub === "example") {
+        try {
+            await runEnvExample({ check: rest.includes("--check") });
+        }
+        catch (err) {
+            explain("Generating .env.example failed.", errorMessage(err));
+            process.exitCode = 1;
+        }
+        return;
+    }
+    if (sub === "init") {
+        // Every target, including `development` and `preflight`: init maps target
+        // → file and nothing else, and every target has a file. It is the one
+        // subcommand here that needs no Bitwarden project, though WHAT it writes
+        // now depends on the target. See `example.ts`'s header for why a vault
+        // target's file is not the development one under a different name.
+        const given = flagValue(rest, "--target") ?? "development";
+        if (!isEnvTarget(given)) {
+            explain(`"${given}" is not a target init can create a file for.`, "", [
+                `Pass --target ${ENV_TARGETS.join(" | ")} (default: development).`,
+            ]);
+            process.exitCode = 1;
+            return;
+        }
+        try {
+            // `--apps` (development only): which projects' sections to render, as
+            // comma-separated app names, plus `devtools` for the operator role.
+            // Absent at a terminal, init asks; absent in a pipe, it renders
+            // everything, which is what every pre-picker caller got.
+            await runEnvInit(given, flagValue(rest, "--apps") ?? undefined);
+        }
+        catch (err) {
+            explain("env init failed.", errorMessage(err));
+            process.exitCode = 1;
+        }
+        return;
+    }
+    // The question names the direction, because the answer means something
+    // different each way: pull overwrites your file, push overwrites theirs.
+    const target = await resolveVaultTarget(flagValue(rest, "--target"), sub === "pull"
+        ? "Which target should I pull into its env file?"
+        : sub === "push"
+            ? "Which target should I push its env file to?"
+            : "Which target should I audit?");
+    if (!target) {
+        process.exitCode = 1;
+        return;
+    }
+    // A target chosen at the prompt (not passed as a flag) is what the rerun
+    // line needs to skip that prompt next time.
+    if (flagValue(rest, "--target") === undefined) {
+        recordResolved("--target", target);
+    }
+    // Before any command runs, so every `bws` call in it sees the same token.
+    setExplicitAccessToken(flagValue(rest, "--access-token"));
+    const options = {
+        target,
+        file: flagValue(rest, "--file"),
+        yes: rest.includes("--yes"),
+    };
+    try {
+        if (sub === "pull")
+            await runEnvPull(options);
+        else if (sub === "push")
+            await runEnvPush(options);
+        else
+            await runEnvAudit(options);
+    }
+    catch (err) {
+        explain("The env command failed.", errorMessage(err), [
+            "The access token is read from --access-token, then BWS_ACCESS_TOKEN,",
+            "then your Bitwarden vault, and finally by asking.",
+            "`gh auth status` shows whether the GitHub CLI is signed in.",
+        ]);
+        process.exitCode = 1;
+    }
+}
+/**
+ * `db planner <status|create|reset-password|drop> [--db-url <url>]`
+ *
+ * Operator-side lifecycle of the `migration_planner` role. See
+ * `planner/commands.ts` for the commands themselves and for why there is no
+ * `retrieve`. Interactive by design (create and reset confirm before writing
+ * to production), so unlike the `deploy` group it talks through clack and is
+ * fine to run as plain `pnpm devtools db planner …`.
+ */
+async function runPlannerCommand(rest) {
+    const [sub] = positionals(rest);
+    const options = { dbUrl: flagValue(rest, "--db-url") ?? undefined };
+    if (sub === "status") {
+        await runPlannerStatus(options);
+        return;
+    }
+    if (sub === "create") {
+        await runPlannerCreate(options);
+        return;
+    }
+    if (sub === "reset-password") {
+        await runPlannerResetPassword(options);
+        return;
+    }
+    if (sub === "drop") {
+        await runPlannerDrop(options);
+        return;
+    }
+    log.error(sub
+        ? `devtools db planner: unknown subcommand "${sub}". Try ${subcommandList(["db", "planner"])}.`
+        : `devtools db planner: which of ${subcommandList(["db", "planner"])}?`);
+    process.exitCode = 1;
+}
+// ── Database ─────────────────────────────────────────────────────────────────
+/**
+ * `db <subcommand> …` — the merged Supabase/Database group.
+ *
+ * One dispatcher, replacing the flat `isStackCommand`/`isDbCommand` checks
+ * that used to sit in `dispatch` directly: every verb below (`start`,
+ * `migrate`, `types`, `seed roles`, `planner status`, …) used to be its own
+ * top-level command, so a bare `push` told the reader nothing about what it
+ * touched. Nesting them under `db` is what lets `--help db` and the wizard
+ * group them by `scope` (see `commands.ts`) instead of listing all of them
+ * flat. `planner` keeps its own dispatcher unchanged; this just routes to it
+ * one level deeper.
+ */
+async function runDbCommand(rest) {
+    const { fileFor } = await loadEnv();
+    if (refuseRetiredDbFlags(rest))
+        return;
+    const [sub, ...subRest] = rest;
+    if (sub === "connect") {
+        const ref = subRest.find((arg) => !arg.startsWith("-"));
+        const code = await connectRemoteProject(ref);
+        process.exitCode = code === 0 ? 0 : 1;
+        return;
+    }
+    if (sub === "start" ||
+        sub === "stop" ||
+        sub === "restart" ||
+        sub === "status" ||
+        sub === "migrate" ||
+        sub === "reset") {
+        await runStack(sub, subRest);
+        return;
+    }
+    if (sub === "migration") {
+        const [msub, ...mrest] = subRest;
+        if (msub === "new") {
+            const code = await runNewMigration(mrest.find((arg) => !arg.startsWith("-")));
+            process.exitCode = code === 0 ? 0 : 1;
+            return;
+        }
+        if (msub === "generate") {
+            const code = await runGenerateMigration(flagValue(mrest, "--app"));
+            process.exitCode = code === 0 ? 0 : 1;
+            return;
+        }
+        log.error(msub
+            ? `devtools db migration: unknown subcommand "${msub}". Try ${subcommandList(["db", "migration"])}.`
+            : `devtools db migration: which of ${subcommandList(["db", "migration"])}?`);
+        process.exitCode = 1;
+        return;
+    }
+    if (sub === "types") {
+        const connection = await resolveDbConnection({ label: "devtools db types" });
+        if (!connection) {
+            process.exitCode = 1;
+            return;
+        }
+        const code = await runGenerateTypes(connection.dbUrl);
+        process.exitCode = code === 0 ? 0 : 1;
+        return;
+    }
+    if (sub === "seed") {
+        const [ssub] = subRest;
+        if (ssub === "buckets") {
+            const connection = await resolveDbConnection({
+                label: "devtools db seed buckets",
+            });
+            if (!connection) {
+                process.exitCode = 1;
+                return;
+            }
+            // `seed buckets` drives the Storage API, which has no `--db-url` mode
+            // (see `db/run.ts`), so this is the one data command still keyed on
+            // local-vs-hosted rather than handed the session's URL.
+            const code = await runSeedBuckets(isLocalConnection(connection)
+                ? { kind: "local" }
+                : { kind: "remote", projectRef: connection.projectRef });
+            process.exitCode = code === 0 ? 0 : 1;
+            return;
+        }
+        if (ssub === "roles") {
+            const connection = await resolveDbConnection({
+                label: "devtools db seed roles",
+            });
+            if (!connection) {
+                process.exitCode = 1;
+                return;
+            }
+            const code = await runSeedRoles(connection.dbUrl);
+            process.exitCode = code === 0 ? 0 : 1;
+            return;
+        }
+        if (ssub === "production") {
+            const connection = await resolveDbConnection({
+                label: "devtools db seed production",
+            });
+            if (!connection) {
+                process.exitCode = 1;
+                return;
+            }
+            // Same non-local gate `runStack` uses for `reset`/`migrate`: named up
+            // front (tier/host only, never the DB_URL) and, absent --yes, refused
+            // outright for a non-interactive caller rather than left to hang on a
+            // prompt nobody is there to answer. `seed production` writes real rows
+            // to whatever it targets, so a staging or production session gets the
+            // same confirmation those destructive commands do; a local session
+            // (the common case — verifying the seed split, or repairing a local
+            // stack after `reset --no-seed`) does not, matching `seed
+            // buckets`/`seed roles` today.
+            if (!isLocalConnection(connection)) {
+                log.message(`This will write supabase/seed/production/*.sql to ${describeDbTarget(connection)}` +
+                    (connection.projectRef
+                        ? ` (project ${connection.projectRef}).`
+                        : "."));
+                if (!subRest.includes("--yes")) {
+                    if (!process.stdin.isTTY) {
+                        process.stderr.write("devtools db seed production: --yes is required to run non-interactively.\n");
+                        process.exitCode = 1;
+                        return;
+                    }
+                    const confirmed = unwrap(await confirm({
+                        message: connection.tier === "production"
+                            ? "This writes the production seed set to the PRODUCTION database " +
+                                `(project ${connection.projectRef ?? "unknown"}). Continue?`
+                            : `This writes the production seed set to ${describeDbTarget(connection)}. Continue?`,
+                        initialValue: false,
+                    }));
+                    if (!confirmed)
+                        bail("Left the database alone.");
+                }
+            }
+            const code = await runSeedProduction(connection.dbUrl);
+            process.exitCode = code === 0 ? 0 : 1;
+            return;
+        }
+        log.error(ssub
+            ? `devtools db seed: unknown subcommand "${ssub}". Try ${subcommandList(["db", "seed"])}.`
+            : `devtools db seed: which of ${subcommandList(["db", "seed"])}?`);
+        process.exitCode = 1;
+        return;
+    }
+    if (sub === "introspect") {
+        const code = await runIntrospect(flagValue(subRest, "--app"));
+        process.exitCode = code === 0 ? 0 : 1;
+        return;
+    }
+    if (sub === "config") {
+        const [csub] = subRest;
+        if (csub === "push") {
+            // Hosted-only — `config.toml` is pushed to a project ref, and the
+            // Docker stack has none (it reads the file directly at `db start`).
+            const connection = await resolveDbConnection({
+                label: "devtools db config push",
+            });
+            if (!connection) {
+                process.exitCode = 1;
+                return;
+            }
+            if (isLocalConnection(connection)) {
+                process.stderr.write("devtools db config push: the local stack reads config.toml " +
+                    "directly (`db restart` applies changes). Relaunch with --tier " +
+                    "development:remote, staging, or production to push it to a " +
+                    "hosted project.\n");
+                process.exitCode = 1;
+                return;
+            }
+            if (!connection.projectRef) {
+                process.stderr.write(`devtools db config push: ${fileFor(connection.tier)} has no PROJECT_REF.\n`);
+                process.exitCode = 1;
+                return;
+            }
+            const code = await runConfigPush(connection.projectRef);
+            process.exitCode = code === 0 ? 0 : 1;
+            return;
+        }
+        log.error(csub
+            ? `devtools db config: unknown subcommand "${csub}". Try ${subcommandList(["db", "config"])}.`
+            : `devtools db config: which of ${subcommandList(["db", "config"])}?`);
+        process.exitCode = 1;
+        return;
+    }
+    if (sub === "planner") {
+        await runPlannerCommand(subRest);
+        return;
+    }
+    if (sub === "exec") {
+        const execArgs = subRest[0] === "--" ? subRest.slice(1) : subRest;
+        const code = await runDbExec(execArgs);
+        process.exitCode = code === 0 ? 0 : 1;
+        return;
+    }
+    log.error(sub
+        ? `devtools db: unknown subcommand "${sub}". Try ${subcommandList(["db"])}.`
+        : `devtools db: which of ${subcommandList(["db"])}?`);
+    process.exitCode = 1;
+}
+// ── Docs ─────────────────────────────────────────────────────────────────────
+/**
+ * `docs index [--target <local|remote>]`, the documentation search index.
+ *
+ * One subcommand today, and a group rather than a top-level `docs-index`
+ * because the artifact it reads has more than one thing worth doing to it
+ * (a `--check` that reports drift is the obvious next one).
+ */
+async function runDocsCommand(rest) {
+    const [sub] = positionals(rest);
+    if (!sub || !subcommandNames(["docs"]).includes(sub)) {
+        log.error(sub
+            ? `devtools docs: unknown subcommand "${sub}". Try ${subcommandList(["docs"])}.`
+            : `devtools docs: which subcommand? Try ${subcommandList(["docs"])}.`);
+        process.exitCode = 1;
+        return;
+    }
+    // `docs index`'s `--target remote` is NOT the retired db selector: it is
+    // the explicit acknowledgment its destructive delete requires when DB_URL
+    // is not local (see `docs/index-pages.ts`). The database itself still
+    // comes from the session's DB_URL like everything else.
+    const target = flagValue(rest, "--target") === "remote" ? "remote" : "local";
+    await runDocsIndex({ target });
+}
+// ── Dispatch ─────────────────────────────────────────────────────────────────
+/** The outro line for a command that finished; `null` means one that failed. */
+const DONE = "Done.";
+/**
+ * Routes an argv to a command, and reports what to print when it returns.
+ *
+ * The wizard calls THIS rather than the command functions, so a menu walk and
+ * a typed command line take the identical path. `deploy` is not routed here.
+ * It is dispatched before `intro()` in `main()`, for the reason
+ * `runDeployCommand`'s header gives.
+ *
+ * Returns the `outro()` line, or `null` where the failure has already been
+ * explained and a cheerful "Done." would contradict it.
+ */
+async function dispatch(argv) {
+    const [first, ...rest] = argv;
+    if (!first)
+        return DONE;
+    if (first === "setup") {
+        await runSetup();
+        return DONE;
+    }
+    if (first === "completions") {
+        const code = runCompletions(rest);
+        process.exitCode = code;
+        return code === 0 ? DONE : null;
+    }
+    // Reached only from the wizard. A typed `run` or `bw` is handled in
+    // `main()` before `intro()`. Both exit with their child's status, so
+    // neither returns and `outro()` is never reached. That is right: by the
+    // time a menu walk gets here the banner is already on screen, above the
+    // menu it introduced, rather than wedged between this CLI and pnpm's
+    // output.
+    if (first === "run")
+        return runTask(rest);
+    if (first === "bw")
+        return runBw(rest);
+    if (first === "oauth") {
+        const forceDevice = rest.includes("--device");
+        const forceLoopback = rest.includes("--loopback");
+        if (forceDevice && forceLoopback) {
+            process.stderr.write("devtools oauth: --device and --loopback are mutually exclusive — pass at most one.\n");
+            process.exitCode = 1;
+            return null;
+        }
+        await runOAuthSetup(flagValue(rest, "--base-url"), flagValue(rest, "--platform-url"), forceDevice ? "device" : forceLoopback ? "loopback" : undefined);
+        return 'All done! You\'re ready to "Sign in with DevDogs".';
+    }
+    if (first === "docs") {
+        await runDocsCommand(rest);
+        return DONE;
+    }
+    if (first === "images") {
+        // `connect` is passed rather than called: only event graphics need a
+        // database, and `images page/*` must not demand a running stack to draw
+        // pictures that come entirely out of this repo.
+        await runImages(rest, { connect });
+        return DONE;
+    }
+    if (first === "emails") {
+        await runEmails(rest);
+        return DONE;
+    }
+    if (first === "cf") {
+        const code = await runCf(rest);
+        process.exitCode = code;
+        return DONE;
+    }
+    if (first === "gen") {
+        const code = await runGen(rest);
+        process.exitCode = code;
+        return DONE;
+    }
+    if (first === "cron") {
+        const sub = rest[0];
+        const cronArgs = rest.slice(1);
+        let code;
+        if (sub === "list") {
+            code = await runCronList(cronArgs);
+        }
+        else if (sub === "run") {
+            code = await runCronRun(cronArgs);
+        }
+        else {
+            process.stderr.write(`devtools cron: unknown subcommand "${sub ?? "(none)"}". Expected: list or run.\n`);
+            code = 1;
+        }
+        process.exitCode = code;
+        return DONE;
+    }
+    if (first === "github") {
+        const sub = rest[0];
+        const githubArgs = rest.slice(1);
+        let code;
+        if (sub === "rulesets") {
+            code = await runGithubRulesets(githubArgs);
+        }
+        else if (sub === "settings") {
+            code = await runGithubSettings(githubArgs);
+        }
+        else {
+            process.stderr.write(`devtools github: unknown subcommand "${sub ?? "(none)"}". Expected: rulesets or settings.\n`);
+            code = 1;
+        }
+        process.exitCode = code;
+        return DONE;
+    }
+    if (first === "workflows") {
+        const code = await runWorkflows(rest);
+        process.exitCode = code;
+        return code === 0 ? DONE : null;
+    }
+    if (first === "env") {
+        await runEnvCommand(rest);
+        return DONE;
+    }
+    if (first === "db") {
+        await runDbCommand(rest);
+        return DONE;
+    }
+    // The old name, refused with the new one rather than falling into "Unknown
+    // command". It is in this repo's own docs, scripts and shell histories, and
+    // the rename came with a flag rename, so a bare "unknown" would leave both
+    // halves to be rediscovered.
+    if (first === "secrets") {
+        explain("`secrets` is now `env`.", "", [
+            "pnpm devtools env <pull|push|audit|reset|example|init>",
+            "`--env` is now `--target`, for the same reason: one name, one meaning.",
+        ]);
+        process.exitCode = 1;
+        return null;
+    }
+    if (!isDoctorCommand(first)) {
+        log.error(`Unknown command: ${first}`);
+        // The top level only. The command is unknown, so there is no level below
+        // it to describe, and reprinting the whole tree here is what made the old
+        // help unreadable in the first place.
+        log.message(renderHelp());
+        process.exitCode = 1;
+        return null;
+    }
+    const instance = await connect();
+    if (!instance) {
+        process.exitCode = 1;
+        return null;
+    }
+    if (first === "catalog") {
+        await runCatalog(instance);
+    }
+    else if (first === "doctor") {
+        await runDoctor(instance, flagValue(rest, "--app"));
+    }
+    else if (first === "grant-root") {
+        await runGrantRoot(instance, flagValue(rest, "--user"));
+    }
+    else {
+        await runRoundTrip(instance);
+    }
+    return DONE;
+}
+// ── Entry ────────────────────────────────────────────────────────────────────
+/**
+ * Runs the CLI against an already-resolved argv.
+ *
+ * Exported rather than run at import, so `src/launch.ts` can resolve the
+ * deploy tier and enter its environment BEFORE this module's imports (and the
+ * commands they pull in) ever see `process.env` — see that file's header. The
+ * shebang above stays harmless: importing this module runs nothing, only
+ * `main()` does, and nothing calls it but `launch.ts` and the `import.meta.url`
+ * guard at the bottom of this file, for a direct `tsx src/cli.ts` run.
+ */
+export async function main(argv) {
+    // Bootstrapped here — after `argv` is parsed off `process.argv`, before any
+    // dispatch below (including `bw`'s passthrough) touches it — so the
+    // `command` tag on whatever this run reports is the same argv every branch
+    // below is about to act on. See `telemetry.ts`'s header for the no-op
+    // contract when no DSN is configured.
+    initDevtoolsTelemetry(argv[0] ?? "menu");
+    // ⚠️ BEFORE the `--help` check, unlike everything else here. `bw` is a
+    // passthrough, so `pnpm devtools bw --help` is a request for Bitwarden's
+    // help, not for ours. Answering it with our own would be this CLI talking
+    // over a tool it promised to get out of the way of.
+    if (argv[0] === "bw") {
+        await runBw(argv.slice(1));
+        return;
+    }
+    // `helpPath` so that `env pull --help` answers about `env pull` rather than
+    // reprinting the top level, which is the whole point of the split.
+    if (argv.includes("--help") || argv.includes("-h")) {
+        console.log(renderHelp(helpPath(argv)));
+        return;
+    }
+    // `completions --shell bash|zsh` is meant for `eval "$(pnpm devtools
+    // completions --shell bash)"`, which executes every line of stdout as a
+    // shell command. Dispatched before `intro()` so the banner — and the
+    // `outro()` below — never land on that stdout; a typed completions
+    // invocation is never part of an interactive wizard walk, so there is no
+    // banner worth keeping here the way there is for the menu.
+    if (argv[0] === "completions") {
+        const code = runCompletions(argv.slice(1));
+        process.exitCode = code;
+        return;
+    }
+    // Clean stdout, same reasoning as `completions` above: mostly useful for
+    // confirming which build actually ran, since a dlx self-refresh (see
+    // `repo/preflight.ts`) is otherwise invisible short of reading stderr's
+    // one-line nudge/refresh notice.
+    if (argv[0] === "version") {
+        process.stdout.write(`${ownVersion()}\n`);
+        return;
+    }
+    // Deploy has moved to the devtools-ci bin. Point any stray invocations at it
+    // before `intro()`, because `devtools deploy secrets-file` could otherwise
+    // fall through to the wizard banner on a stdout that is a credential channel.
+    if (argv[0] === "deploy") {
+        process.stderr.write("deploy has moved to devtools-ci.\n" +
+            "  Use: pnpm devtools-ci deploy <step|app> [flags]\n");
+        process.exitCode = 1;
+        return;
+    }
+    // A bare command group at a terminal resumes the wizard at that node, so
+    // `devtools db` opens db's subcommand screen instead of printing "which of …?"
+    // and exiting 1. Placed here — before `run`'s passthrough and before intro() —
+    // so every group routes the same way (bare `run` resumes too, while
+    // `run <task>` resolves to a leaf and falls through). Non-interactive callers
+    // get startPath === null and keep the dispatcher's error + exit 1.
+    const startPath = process.stdin.isTTY ? bareGroupStartPath(argv) : null;
+    // Also before `intro()`, for the neighbouring reason: this one hands stdout
+    // to pnpm, and through it to a Next dev server or a Flutter run that owns
+    // the terminal until Ctrl-C. A banner above that output would be this CLI
+    // announcing itself over somebody else's, and the `outro()` below would
+    // print "Done." after a dev server was interrupted. `runTask` exits with
+    // the child's own status and never comes back. `!startPath` excludes the one
+    // case that is not this: a bare `run` at a terminal, which the block above
+    // already resolved to its own subcommand screen rather than a task to run.
+    if (!startPath && argv[0] === "run") {
+        await runTask(argv.slice(1));
+        return;
+    }
+    intro("DevDogs devtools");
+    // The wizard builds an argv and hands it back to `dispatch`. See `menu.ts`.
+    // `runMenu` begins its own recording from the built argv; a typed command
+    // begins here, non-interactive until a runner resolves a flag from a prompt.
+    let closing;
+    if (argv.length === 0) {
+        closing = await runMenu(dispatch);
+    }
+    else if (startPath) {
+        // Same wizard entry as the no-argument path, at the resumed node instead
+        // of the first screen. `env` left `undefined` so `runMenu` probes once,
+        // identically to the bare-invocation branch above.
+        closing = await runMenu(dispatch, undefined, { startPath });
+    }
+    else {
+        beginInvocation(argv, false);
+        // `launch.ts` already resolved and entered the session's deploy tier —
+        // see its header — so `process.env.DEPLOY_ENV` names it here for every
+        // path, typed or menu-built, rather than this module resolving a second
+        // opinion.
+        recordEnteredTier(process.env.DEPLOY_ENV ?? "development");
+        closing = await dispatch(argv);
+    }
+    if (closing) {
+        // Only prints when a prompt actually decided something — see
+        // `reproducibleCommand`. Above the outro, so the takeaway is the last
+        // thing on screen.
+        const rerun = reproducibleCommand();
+        if (rerun)
+            note(rerun, "Run it directly next time");
+        outro(closing);
+    }
+}
+// Only for a direct `tsx src/cli.ts` run, bypassing `launch.ts` entirely —
+// no deploy tier resolved, no env entered. Not a path anything in this repo
+// takes any more (`launch.ts` always runs first, see its header), kept as a
+// fallback for the same reason `ci.ts`'s guard is.
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main(process.argv.slice(2)).catch(async (err) => {
+        log.error(errorMessage(err));
+        // Report BEFORE exiting — `process.exit` kills the event loop, taking any
+        // in-flight request to Sentry's ingest endpoint with it. See
+        // `captureDevtoolsError`'s header.
+        await captureDevtoolsError(err);
+        process.exit(1);
+    });
+}