@devdogsuga/devtools 0.1.25 → 0.1.27

package/dist/menu-CQBsQRgH.js

@@ -0,0 +1,1684 @@
+import { c as YES, i as suppressFailureLog, l as createCatalog, o as JSON_FLAG, s as SCOPES } from "./failure-log-BBPGejQv.js";
+import { a as listContainerNames, i as foreignStackProjectId, n as containerPrefix, o as readProjectId, p as supabaseCapture, r as foreignStackMessage, t as STACK_API_PORT } from "./supabase-project-0knM0mqd.js";
+import { r as findRepoRoot } from "./root-C2OmZDwD.js";
+import { n as loadEnv, r as loadEnvLoad } from "./peers-RBplwovA.js";
+import { c as reportDevtoolsError, f as isNonInteractive } from "./telemetry-C4foD8MD.js";
+import { cancel, confirm, isCancel, log, note, select, text } from "@clack/prompts";
+import { existsSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { execFileSync } from "node:child_process";
+//#region ../cli-core/src/help.ts
+/**
+* `--help`, one level at a time.
+*
+* ## Why this is small
+*
+* The help this replaced was ~200 lines and printed the whole tree: every
+* subcommand of every group, the Bitwarden target table, the four places an
+* access token is looked for, the grants `migration_planner` holds, and which
+* deploy steps must avoid the `with-env` wrapper. A contributor running
+* `pnpm devtools --help` to find out how to start a database read all of it.
+*
+* Two rules now:
+*
+*   1. **A level prints its own children and stops.** `--help` lists the
+*      top-level commands; `env --help` lists env's subcommands; `env pull
+*      --help` lists that command's options. Depth is reached by asking for
+*      it.
+*   2. **No more than the caller needs to choose.** Operator internals are
+*      `docs/`'s job: which project a target maps to, how a credential is
+*      resolved, what a deploy job's environment holds. Help says what a
+*      command does and what it takes.
+*
+* Both fall out of rendering the catalog rather than hand-writing prose, so
+* neither can rot back into a wall of text one paragraph at a time.
+*/
+const INDENT = "  ";
+/** `--target <t>`, or `--prune` for a boolean. */
+function optionLabel(option) {
+	return option.value ? `${option.flag} ${option.value}` : option.flag;
+}
+/**
+* Two columns, with the gutter sized to the widest label in THIS block.
+*
+* Per-block rather than one width for the whole file: `deploy`'s labels are
+* long and `setup`'s are not, and a shared width would indent the short list
+* halfway across the terminal to accommodate a group the reader is not
+* looking at.
+*/
+function columns(rows) {
+	const width = Math.max(...rows.map(([label]) => label.length));
+	return rows.map(([label, text]) => `${INDENT}${label.padEnd(width)}  ${text}`);
+}
+/**
+* A list of commands, split into scope blocks when any of them declares one.
+*
+* Used at two levels: a GROUP's own commands (no group has scoped commands
+* today — `db` folded the old "Supabase" group's scopes into itself), and a
+* command's own SUBCOMMANDS (`db`'s: `start`/`connect`/`stop`/`restart` on
+* this machine, `migration` in the repo, `status`/`migrate`/`reset`/… on an
+* endpoint, `planner`/`signing-key` naming their own connection). Either way,
+* a flat list leaves the reader to work out which of `restart` and `reset` is
+* which, the distinction that costs people an afternoon. A list with no
+* scopes renders as it always did: one block, one indent, no headings.
+*
+* The blocks follow declaration order rather than `SCOPES` order, so the tree
+* stays the one place that decides how the list reads. The gutter is sized
+* across the whole list, not per block, so every block lines up with the
+* others rather than each finding its own column.
+*/
+function scopedBody(commands) {
+	if (!commands.some((command) => command.scope)) return columns(childRows(commands));
+	const width = Math.max(...commands.map((command) => command.name.length));
+	const lines = [];
+	let open;
+	for (const command of commands) {
+		if (command.scope && command.scope !== open) {
+			open = command.scope;
+			lines.push(`${INDENT}${SCOPES[open].help}:`);
+		}
+		lines.push(`${INDENT.repeat(2)}${command.name.padEnd(width)}  ${command.summary}`);
+	}
+	return lines;
+}
+function optionRows(options) {
+	return options.map((option) => [optionLabel(option), option.summary]);
+}
+function childRows(children) {
+	return children.map((child) => [child.name, child.deprecated ? `${child.summary} (deprecated)` : child.summary]);
+}
+/** `pnpm devtools --help`: the groups, and nothing below them. */
+function renderRoot(catalog) {
+	const lines = [
+		`${catalog.usage} [command] [options]`,
+		"",
+		"Run with no command to choose from a menu.",
+		"",
+		"Common tasks:",
+		...columns(catalog.commonTasks.map(([command, what]) => [command, what]))
+	];
+	for (const group of catalog.groups) lines.push("", `${group.title}:`, ...scopedBody(group.commands));
+	lines.push("", "Options:", ...columns([
+		["--help, -h", "Show this message"],
+		["--tier <t>", "Deploy tier for this whole invocation (development, staging, production)"],
+		["--no-env", "Load no env files; the environment you pass is the environment"]
+	]), "", `\`${catalog.usage} <command> --help\` shows what that command takes.`);
+	return lines.join("\n");
+}
+/** `pnpm devtools <path…> --help`: one command's own children and options. */
+function renderCommand(catalog, path, node) {
+	const children = node.subcommands ?? [];
+	const options = node.options ?? [];
+	const trail = path.join(" ");
+	const lines = [
+		[
+			catalog.usage,
+			trail,
+			children.length > 0 ? "<subcommand>" : "",
+			options.length > 0 ? "[options]" : ""
+		].filter(Boolean).join(" "),
+		"",
+		node.summary
+	];
+	if (node.deprecated) lines.push("", `Deprecated. ${node.deprecated}`);
+	if (children.length > 0) lines.push("", "Subcommands:", ...scopedBody(children));
+	if (options.length > 0) lines.push("", "Options:", ...columns(optionRows(options)));
+	if (children.length > 0) lines.push("", `\`${catalog.usage} ${trail} <subcommand> --help\` shows what that one takes.`);
+	return lines.join("\n");
+}
+/**
+* Renders help for a path, falling back to the root.
+*
+* An unknown path renders the root rather than an error: this is only reached
+* when `--help` was asked for, and answering a mistyped command with the list
+* it was mistyped from is more use than a refusal.
+*/
+function renderHelp(catalog, path = []) {
+	if (path.length === 0) return renderRoot(catalog);
+	const node = catalog.findCommand(path);
+	if (!node) return renderRoot(catalog);
+	return renderCommand(catalog, path, node);
+}
+/**
+* The command names in `argv` that precede any flag.
+*
+* `env pull --help` asks about `["env", "pull"]`; `--help env` asks about
+* nothing, because a flag's value is not a command path. Kept separate from
+* `positionals()`: that one strips a known set of value-taking flags to find a
+* subcommand, and here anything after the first flag is not part of the path at
+* all.
+*/
+function helpPath(argv) {
+	const path = [];
+	for (const arg of argv) {
+		if (arg.startsWith("-")) break;
+		path.push(arg);
+	}
+	return path;
+}
+/**
+* Every command path the CLI accepts, for tools that need the supported list
+* (the docs build refuses a page that shows a command that no longer exists).
+*
+* A declared export rather than a scrape of `--help`: same tree, parsed once.
+* Only this CLI's own tree, so a doc cannot pass by showing a command that
+* belongs to the other CLI (`pnpm devtools deploy`).
+*/
+function commandList(catalog) {
+	const entries = [];
+	const visit = (nodes, prefix, inheritedCliOnly) => {
+		for (const node of nodes) {
+			const path = [...prefix, node.name];
+			const cliOnly = inheritedCliOnly || node.surface === "cli-only";
+			entries.push({
+				path: path.join(" "),
+				summary: node.summary,
+				surface: cliOnly ? "cli-only" : "interactive",
+				...node.deprecated ? { deprecated: node.deprecated } : {}
+			});
+			visit(node.subcommands ?? [], path, cliOnly);
+		}
+	};
+	visit(catalog.topLevel, [], false);
+	return entries;
+}
+/** `--help --json`'s document: the version and every command path. */
+function renderCommandList(catalog, version) {
+	return JSON.stringify({
+		version,
+		commands: commandList(catalog)
+	}, null, 2);
+}
+//#endregion
+//#region src/completions/catalog.ts
+const completionsCommand = {
+	name: "completions",
+	dryRun: "read-only",
+	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" }]
+		}
+	}]
+};
+//#endregion
+//#region src/check/catalog.ts
+const checkCommand = {
+	name: "check",
+	dryRun: "read-only",
+	summary: "Structural checks over the checkout, for CI.",
+	hint: "migrations, env, workers, scripts",
+	surface: "cli-only",
+	subcommands: [
+		{
+			name: "migrations",
+			summary: "New migrations are timestamped after the base branch's.",
+			surface: "cli-only",
+			envFree: true,
+			noEnv: true,
+			options: [{
+				flag: "--base",
+				value: "<ref>",
+				summary: "Git ref to compare against. Defaults to origin/main."
+			}]
+		},
+		{
+			name: "env",
+			summary: "Every env variable is declared, and the registry agrees.",
+			surface: "cli-only",
+			envFree: true,
+			noEnv: true
+		},
+		{
+			name: "workers",
+			summary: "workers.json matches wrangler.jsonc and deploy-app.yaml.",
+			surface: "cli-only",
+			envFree: true,
+			noEnv: true
+		},
+		{
+			name: "scripts",
+			summary: "Package scripts use the shared vocabulary.",
+			surface: "cli-only",
+			envFree: true,
+			noEnv: true
+		}
+	]
+};
+//#endregion
+//#region src/cron/catalog.ts
+/**
+* `cron`'s place in the command tree: declaration only, nothing here runs.
+* The handler lives in `commands.ts` beside it.
+*/
+const cronCommand = {
+	name: "cron",
+	summary: "Cloudflare cron triggers: list schedules or fire one now.",
+	hint: "list schedules, run a job",
+	subcommands: [{
+		name: "list",
+		dryRun: "read-only",
+		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
+		]
+	}]
+};
+//#endregion
+//#region src/doctor/catalog.ts
+const doctorCommand = {
+	name: "doctor",
+	dryRun: "read-only",
+	summary: "Check this machine's environment against what the repo needs.",
+	hint: "node, pnpm, Docker, .env, hosted Supabase, OAuth — read-only",
+	options: [{
+		flag: "--app",
+		value: "<slug>",
+		summary: "Scope checks to one app. Defaults to every app you have env for."
+	}, {
+		flag: "--report",
+		summary: "Print a redacted, paste-able block (versions, OS, results — no secrets)."
+	}]
+};
+const envCommand = {
+	name: "env",
+	summary: "Create, regenerate and clear the local env files.",
+	subcommands: [
+		{
+			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.",
+			envFree: true,
+			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: [{
+				flag: "--file",
+				value: "<path>",
+				summary: "Read and write this file instead of the target's own."
+			}, YES]
+		}
+	]
+};
+//#endregion
+//#region src/roles/catalog.ts
+/**
+* `roles`' place in the command tree: declaration only, nothing here runs.
+* The handlers live in `commands.ts` beside it.
+*
+* `grant` and `revoke` take `<email> <role>` as positionals and ask for
+* whichever is missing, so the wizard reaches them with no arguments and the
+* pickers do the rest. That is why neither declares an option of its own.
+*/
+const rolesCommand = {
+	name: "roles",
+	summary: "See who holds each role, and grant or revoke one.",
+	hint: "list, grant, revoke",
+	subcommands: [
+		{
+			name: "list",
+			dryRun: "read-only",
+			summary: "Every role and the accounts that hold it.",
+			options: [JSON_FLAG]
+		},
+		{
+			name: "grant",
+			summary: "Give an account a role: <email> <role>.",
+			hint: "President moves from its current holder",
+			options: [YES]
+		},
+		{
+			name: "revoke",
+			summary: "Take a role from an account: <email> <role>.",
+			options: [YES]
+		}
+	]
+};
+//#endregion
+//#region src/oauth/catalog.ts
+const oauthCommand = {
+	name: "oauth",
+	summary: "Configure \"Sign in with DevDogs\" for this directory.",
+	hint: "works outside a DevDogsUGA checkout too",
+	envFree: true,
+	options: [
+		{
+			flag: "--base-url",
+			value: "<url>",
+			summary: "DevDogs API URL for \"Paste credentials instead\". Defaults to https://api.devdogsuga.org."
+		},
+		{
+			flag: "--platform-url",
+			value: "<url>",
+			summary: "Platform URL for one-click connect. Defaults to https://devdogsuga.org."
+		},
+		{
+			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."
+		}
+	]
+};
+//#endregion
+//#region src/passthrough/catalog.ts
+const supabaseCommand = {
+	name: "supabase",
+	dryRun: "handled",
+	summary: "Run the Supabase CLI against the session's tier.",
+	hint: "fills in --db-url / --project-ref; the rest is yours",
+	surface: "cli-only"
+};
+const wranglerCommand = {
+	name: "wrangler",
+	dryRun: "handled",
+	summary: "Run Wrangler with the session's env.",
+	hint: "everything after the name goes to wrangler",
+	surface: "cli-only"
+};
+const drizzleKitCommand = {
+	name: "drizzle-kit",
+	dryRun: "handled",
+	summary: "Run drizzle-kit with the session's env.",
+	hint: "run it from the app that owns the config",
+	surface: "cli-only"
+};
+const psqlCommand = {
+	name: "psql",
+	dryRun: "handled",
+	summary: "Run psql against the session's database.",
+	hint: "connects with the tier's DB_URL unless you say otherwise",
+	surface: "cli-only"
+};
+//#endregion
+//#region src/preset/catalog.ts
+/**
+* The TUI presets' place in the command tree: declaration only, nothing here
+* runs. The handlers live in `commands.ts` beside it.
+*
+* A preset sequences several tool calls (or asks a question between them) and
+* prints the commands it ran. Each is also typed as `devtools preset <name>`.
+*/
+const presetCommand = {
+	name: "preset",
+	dryRun: "handled",
+	summary: "Common Supabase jobs, each a few tool calls in a row.",
+	hint: "restart the stack, new migration, apply migrations, push config",
+	subcommands: [
+		{
+			name: "restart-stack",
+			summary: "Restart the local Supabase stack.",
+			hint: "supabase stop, then start; picks up config.toml",
+			scope: "machine",
+			when: "instance-running"
+		},
+		{
+			name: "new-migration",
+			summary: "Create an empty migration for an app's schema.",
+			hint: "supabase migration new <schema>_<description>",
+			scope: "repo",
+			options: [{
+				flag: "--app",
+				value: "<slug>",
+				summary: "Whose schema. Asked for when absent."
+			}]
+		},
+		{
+			name: "apply-migrations",
+			summary: "Apply new migrations to the session's database.",
+			hint: "supabase db push, then offers types:db",
+			scope: "endpoint",
+			options: [YES]
+		},
+		{
+			name: "push-config",
+			summary: "Push config.toml to the session's hosted project.",
+			hint: "shows the diff first; the local stack reads it on restart",
+			scope: "endpoint",
+			options: [YES]
+		}
+	]
+};
+//#endregion
+//#region src/run/catalog.ts
+/**
+* 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 catalog = createCatalog({
+	usage: "pnpm devtools",
+	commonTasks: [
+		["setup", "Prepare a new checkout"],
+		["run dev", "Start development servers"],
+		["supabase start", "Start Supabase on this machine"],
+		["supabase <args>", "Run the Supabase CLI against this session's tier"],
+		["preset apply-migrations", "Push migrations, then offer types:db"],
+		["cron run", "Choose and run a scheduled job"]
+	],
+	groups: [
+		{
+			title: "Workspace",
+			commands: [
+				{
+					name: "setup",
+					summary: "Check prerequisites and seed .env.",
+					hint: "run this first"
+				},
+				oauthCommand,
+				{
+					name: "script",
+					dryRun: "handled",
+					summary: "Pick a package, then one of its scripts, and run it.",
+					hint: "pnpm -F <package> run <script>"
+				},
+				{
+					name: "run",
+					dryRun: "handled",
+					summary: "Run a pnpm workspace task, asking which apps first.",
+					hint: "deprecated: pnpm -r run <task>",
+					deprecated: "Use `pnpm -r run <task>` for every package or `pnpm -F <app> <task>` for one. It still runs, and each use is reported so it can be removed (TASK-404).",
+					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: "Runtime & infrastructure",
+			commands: [
+				presetCommand,
+				cronCommand,
+				{
+					name: "workflows",
+					summary: "Cloudflare Workflows: list configured bindings or trigger one.",
+					hint: "pick a workflow from wrangler.jsonc",
+					subcommands: [
+						{
+							name: "list",
+							dryRun: "read-only",
+							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: "The real tools",
+			commands: [
+				supabaseCommand,
+				wranglerCommand,
+				drizzleKitCommand,
+				psqlCommand
+			]
+		},
+		{
+			title: "Configuration & integrations",
+			commands: [envCommand, rolesCommand]
+		},
+		{
+			title: "Environment",
+			commands: [doctorCommand]
+		},
+		{
+			title: "CI & CLI utilities",
+			commands: [checkCommand, completionsCommand]
+		}
+	]
+});
+//#endregion
+//#region ../cli-core/src/db/generated-env.ts
+/**
+* Regenerating `.env.generated` from a Supabase stack that is ALREADY
+* running — started by `db start` in THIS checkout, sure, but just as
+* often by another workspace (a different clone or worktree of the
+* DevDogsUGA repo) that shares this repo's `project_id`. `supabase status`
+* finds containers by project id, not by which checkout ran `db start`, so
+* a stack a sibling workspace brought up answers for THIS checkout too —
+* except `.env.generated` (the connection block `startLocalStack`,
+* the CLI's `db/stack.ts`, writes) only ever lands in the workspace that actually ran
+* it. Left alone, this checkout sees port 54321 listening with the file
+* missing, and `@devdogsuga/env/load`'s `selectEnvFiles` either warns (an
+* unqualified session) or throws `LocalStackOfflineError` (an explicit
+* `development:local` one) — both of which used to mean the contributor
+* ran `supabase status -o env > .env.generated` by hand.
+*
+* `ensureGeneratedEnvFile` does that automatically, before a session's env
+* files ever load: `enterSessionEnvironment` (`../env-entry.ts`) calls it on
+* every command dispatch, and `db status` (the CLI's `db/stack.ts`) calls it to
+* report the file's state accurately instead of trusting a stale absence.
+* Both are read-only from THIS checkout's point of view — nothing here
+* starts, stops, or resets anything; it only reads a port, a file, and
+* (best-effort) the stack's own connection block.
+*
+* The other failure this covers: `supabase status -o env` itself fails
+* because what is listening on 54321 belongs to a DIFFERENT Supabase
+* project — a stack this repo's own `project_id` rename left orphaned, or
+* an unrelated project entirely. That is reported (`"foreign"`) rather than
+* silently falling through to the existing offline handling, which would
+* otherwise just repeat "nothing is listening" advice for a port that very
+* much has something listening on it.
+*/
+/** The file this module writes and checks — see `@devdogsuga/env/load`'s
+*  `GENERATED_FILE`, duplicated as a literal rather than imported so this
+*  module never has to load the `@devdogsuga/env` peer just for one
+*  constant. Keep in sync if that constant's value ever changes. */
+const GENERATED_FILE = ".env.generated";
+/**
+* Regenerates `.env.generated` from a running local stack when THIS
+* checkout's own copy is missing.
+*
+* A no-op (`"skipped"`) unless every one of these holds: `tier` is
+* `"development"`, `devDatabase` is not `"remote"` (an explicit `"local"`
+* or the probe-decides `undefined` both qualify), the file is genuinely
+* absent, and something answers the local stack's port. That last check
+* also covers "the file is missing because the stack is genuinely down" —
+* nothing here runs `supabase status` against a stack that is not there;
+* the existing `LocalStackOfflineError`/warning handling covers that case
+* exactly as before.
+*
+* `"foreign"` and `"unreachable"` both mean `supabase status -o env`
+* itself failed — the port answered, but the CLI could not produce a
+* connection block. `"foreign"` is the case a running Docker container's
+* name resolves to: another project's stack holds the port.
+* `"unreachable"` is everything else (an unreadable `config.toml`, an
+* unreadable `docker ps`, a container name that matches nobody) — the
+* caller falls through to its existing offline handling either way, since
+* `.env.generated` is still missing on disk.
+*/
+async function ensureGeneratedEnvFile(tier, devDatabase, deps) {
+	if (tier !== "development" || devDatabase === "remote") return { outcome: "skipped" };
+	if (deps.exists(GENERATED_FILE)) return { outcome: "skipped" };
+	if (!await deps.probeLocalStack()) return { outcome: "skipped" };
+	try {
+		const env = await deps.captureStatus();
+		await deps.write(join(deps.repoRoot, GENERATED_FILE), env);
+		return {
+			outcome: "wrote",
+			line: "devtools: wrote .env.generated from the running local stack"
+		};
+	} catch {
+		const names = deps.listContainerNames();
+		const foreign = names === null ? null : foreignStackProjectId(names, deps.projectId());
+		if (foreign !== null) return {
+			outcome: "foreign",
+			projectId: foreign,
+			line: `devtools: ${foreignStackMessage(foreign)}`
+		};
+		return { outcome: "unreachable" };
+	}
+}
+/**
+* The production wiring for `EnsureGeneratedEnvDeps`, shared by
+* `../env-entry.ts` (via `realEnvEntryDeps`) and `../stack.ts`'s `db
+* status`. `probeLocalStack` is passed in rather than resolved here because
+* both callers already hold the loaded `@devdogsuga/env/load` peer their
+* own dispatch needs anyway — resolving it again here would mean two
+* different copies of the same optional peer in play.
+*/
+function realEnsureGeneratedEnvDeps(probeLocalStack) {
+	const repoRoot = findRepoRoot();
+	return {
+		probeLocalStack,
+		exists: (file) => existsSync(join(repoRoot, file)),
+		captureStatus: () => supabaseCapture("status", "-o", "env"),
+		write: (path, contents) => writeFile(path, contents),
+		listContainerNames: () => listContainerNames(STACK_API_PORT),
+		projectId: () => readProjectId(repoRoot),
+		repoRoot
+	};
+}
+//#endregion
+//#region ../cli-core/src/ui.ts
+/**
+* Shared prompt plumbing.
+*
+* The audience here is a contributor who may not be comfortable in a terminal
+* at all, so two rules apply throughout:
+*
+*   * Nothing requires knowing a command. Running `pnpm devtools` with no
+*     arguments opens a menu, and every prompt has a sensible default.
+*   * A failure says what to do next. `explain()` exists so no error path
+*     ends at a stack trace.
+*/
+function bail(message = "Cancelled.") {
+	if (message === "Cancelled.") suppressFailureLog();
+	if (isNonInteractive()) process.stderr.write(`${message}\n`);
+	else cancel(message);
+	process.exit(1);
+}
+/** Exits cleanly on Ctrl-C rather than letting a cancel symbol leak onward. */
+function unwrap(value) {
+	if (isCancel(value)) bail();
+	return value;
+}
+/**
+* Reports a failure with the next thing to try.
+*
+* `hints` is not decoration: for most of these failures the fix is one command,
+* and printing it is the difference between a contributor continuing and a
+* contributor asking in Discord.
+*/
+function explain(summary, detail, hints = []) {
+	if (isNonInteractive()) {
+		process.stderr.write(`${summary}\n`);
+		if (detail) process.stderr.write(`${detail}\n`);
+		for (const hint of hints) process.stderr.write(`  try: ${hint}\n`);
+		return;
+	}
+	log.error(summary);
+	if (detail) log.message(detail);
+	if (hints.length > 0) note(hints.join("\n"), "Try this");
+}
+/**
+* A refusal the reader can fix themselves — a name that matches nothing, a
+* flag missing where there is no terminal to ask. Thrown from deep enough
+* that the command's catch can't tell it from a real failure any other way;
+* `explainError` prints it like any other error but keeps it out of Sentry.
+*/
+var UsageError = class extends Error {
+	name = "UsageError";
+};
+/**
+* `explain()` for a caught error rather than a refusal: prints the same way,
+* with `err`'s message as the detail, and reports `err` to Sentry unless it
+* is a {@link UsageError}. Only failures nobody anticipated belong there.
+*/
+function explainError(summary, err, hints = []) {
+	if (!(err instanceof UsageError)) reportDevtoolsError(err);
+	explain(summary, errorMessage(err), hints);
+}
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+//#endregion
+//#region ../cli-core/src/env-entry.ts
+/**
+* Entering a resolved deploy tier's environment — the part of `launch.ts`
+* that actually loads `.env.<tier>` (and its `DEV_DB` overlay) onto
+* `process.env`, with the two recoverable failures `enterEnvironment` can
+* throw handled the same way everywhere it is called from.
+*
+* ## Why this is its own module
+*
+* A typed command line enters its tier at launch, before `cli.ts` is even
+* imported — see `launch.ts`'s header. A menu invocation cannot: the whole
+* point of the wizard is to show a contributor what is possible before they
+* have chosen anything, and loading env files (and possibly offering to
+* start the local stack) before that first question is answered means
+* whatever changed in another terminal while they were deciding — the stack
+* coming up, `.env.generated` being rewritten — is missed. So a menu
+* invocation defers this exact block until `menu.ts`'s `runMenu` is about to
+* dispatch the ONE command the reader chose, right before it runs.
+*
+* `enterSessionEnvironment` is the block both callers share, generic over
+* what "dispatch the command" means to each: `launch.ts` imports `cli.ts`
+* fresh and calls its `main()`, `runMenu` already holds the dispatcher
+* `cli.ts` injected into it. `commandArgv` is the argv the caller is about to
+* dispatch — used for the two `LocalStackOfflineError` exemptions (a `db`
+* lifecycle command, and an empty argv) exactly as `launch.ts` used `rest`
+* for them before this was extracted.
+*
+* ## The hook `runMenu` calls
+*
+* `setMenuEnvHook`/`takeMenuEnvHook` are a module-level slot shared by
+* `launch.ts` and `menu.ts`: `cli.ts` calls `runMenu` with a fixed signature
+* that has no room for a per-invocation callback. `launch.ts` sets the hook
+* for a menu invocation before handing off to `cli.ts`; `runMenu` takes it
+* (reading clears it) right before its own dispatch, so a nested launcher
+* never inherits a stale one.
+*
+* ## Regenerating `.env.generated` before entry
+*
+* Before either caller's `enterEnvironment` call, this also gives a running
+* local stack a chance to fix its own absence: `deps.ensureGeneratedEnv`
+* (`db/generated-env.ts`'s `ensureGeneratedEnvFile`, wired by
+* `realEnvEntryDeps`) writes `.env.generated` from `supabase status -o env`
+* when the port is listening but the file is missing — the common shape of
+* a local stack another workspace started, sharing this repo's
+* `project_id` — so the entry below usually just succeeds instead of
+* throwing `LocalStackOfflineError` or warning about a file nobody wrote.
+* A `"foreign"` result (the stack on the port belongs to a DIFFERENT
+* project) prints its own hint and then falls through to the unchanged
+* error handling below, since the file is still missing either way.
+*/
+/**
+* The production wiring for `EnvEntryDeps`, shared by both call sites in
+* `launch.ts`.
+*/
+function realEnvEntryDeps(envLoad, envSession, startStack) {
+	return {
+		envLoad,
+		envSession,
+		startStack,
+		ensureGeneratedEnv: (tier, devDatabase) => ensureGeneratedEnvFile(tier, devDatabase, realEnsureGeneratedEnvDeps(envLoad.probeLocalStack))
+	};
+}
+/**
+* Commands that bring the local stack up or down themselves: `db
+* start|stop|restart`, the `supabase start|stop` passthrough, and the
+* restart-stack preset. An offer to start the stack before one of these would
+* be asking a question the command is about to answer.
+*/
+function isStackLifecycle(argv) {
+	const [first, second] = argv;
+	if (first === "db") return second === "start" || second === "stop" || second === "restart";
+	if (first === "supabase") return second === "start" || second === "stop";
+	return first === "preset" && second === "restart-stack";
+}
+/**
+* Commands that may continue in a degraded entry while the stack is down:
+* the ones that can fix it (`db`, `supabase`, the presets), and whose data
+* commands re-check the connection themselves and say what is missing.
+*/
+function ownsStack(argv) {
+	return argv[0] === "db" || argv[0] === "supabase" || argv[0] === "preset";
+}
+/**
+* Enters `tier` (and `devDatabase`'s overlay) for the current process,
+* handling `LocalStackOfflineError` (the TTY offer to start the local stack,
+* the `db`-exemption degraded-entry fallback) and `MissingEnvFileError` (the
+* clean-clone tolerance for `development`, fatal otherwise) exactly as
+* `launch.ts` always has. `dispatchCommand` is called exactly once, in every
+* non-fatal branch — including immediately, in place of any further entry
+* work, when a declined-then-accepted stack start already ran it — so its
+* return value is always this function's own return value.
+*/
+async function enterSessionEnvironment(tier, devDatabase, commandArgv, deps, dispatchCommand) {
+	const { envLoad, envSession } = deps;
+	const generated = await deps.ensureGeneratedEnv(tier, devDatabase);
+	if (generated.outcome === "wrote" || generated.outcome === "foreign") process.stderr.write(`${generated.line}\n`);
+	const reportEntered = (files, label) => {
+		process.stderr.write(`devtools: loaded ${files.length > 0 ? files.join(", ") : "no env files"} (${label})\n`);
+	};
+	const sessionLabel = devDatabase === void 0 ? tier : `${tier}:${devDatabase}`;
+	try {
+		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) {
+			process.stderr.write(`devtools: ${err.message}\n`);
+			const lifecycle = isStackLifecycle(commandArgv);
+			if (process.stdin.isTTY === true && commandArgv.length !== 0 && !lifecycle) {
+				if (unwrap(await confirm({ message: "Start the local Supabase stack now?" }))) {
+					if (devDatabase !== void 0) process.env.DEV_DB = devDatabase;
+					const { code, lines } = await deps.startStack();
+					for (const line of lines) process.stderr.write(`devtools: ${line}\n`);
+					if (code === 0) return await dispatchCommand();
+					process.stderr.write("devtools: the stack did not start — see the Supabase CLI output above.\n");
+					process.exit(1);
+				}
+			}
+			if (commandArgv.length !== 0 && !ownsStack(commandArgv)) 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 !== void 0) process.env.DEV_DB = devDatabase;
+			else if (inherited !== void 0) process.env.DEV_DB = inherited;
+			for (const warning of entered.warnings) process.stderr.write(`devtools: ${warning}\n`);
+			reportEntered(entered.files, tier);
+			return await dispatchCommand();
+		}
+		if (!(err instanceof envLoad.MissingEnvFileError)) throw err;
+		if (tier === "development") process.stderr.write(`devtools: ${err.message}\n`);
+		else {
+			process.stderr.write(`devtools: ${err.message}\n`);
+			process.exit(1);
+		}
+	}
+	return await dispatchCommand();
+}
+let menuEnvHook;
+/** Set by `launch.ts` for a menu invocation; `undefined` for a typed command
+*  (which entered already) and for any test that drives `runMenu` directly
+*  without going through `launch.ts` at all. */
+function setMenuEnvHook(hook) {
+	menuEnvHook = hook;
+}
+/** Read by `runMenu`, then cleared — see this module's header on why a
+*  nested launcher must not inherit a stale hook. */
+function takeMenuEnvHook() {
+	const hook = menuEnvHook;
+	menuEnvHook = void 0;
+	return hook;
+}
+//#endregion
+//#region ../cli-core/src/db/connection.ts
+/**
+* Hostnames that mean "the Docker stack on this machine". The same list
+* `docs/index-pages.ts` keeps for its delete-acknowledgment; duplicated
+* because that module answers a different question ("may I delete rows
+* here without --target remote?") and coupling the two would let a change
+* for one silently reshape the other.
+*/
+const LOCAL_DB_HOSTS = [
+	"localhost",
+	"127.0.0.1",
+	"[::1]",
+	"host.docker.internal"
+];
+function isLocalDbUrl(url) {
+	try {
+		return LOCAL_DB_HOSTS.includes(new URL(url).hostname);
+	} catch {
+		return false;
+	}
+}
+/** An env value, with unset and empty both meaning "not given". */
+function nonEmpty(value) {
+	return value === void 0 || value === "" ? void 0 : value;
+}
+/**
+* Whether the session means the Docker stack on this machine, from the
+* environment alone. Development with the remote qualifier is NOT local, and
+* nor is any hosted tier. With no qualifier, a `DB_URL` that is loopback (or
+* absent, the stack being down) means local.
+*
+* The distinction matters to `devtools supabase`: `.env` may name a remote
+* development project's `PROJECT_REF` even in a local session, and that ref
+* must never be filled in for it.
+*/
+function sessionIsLocal(env = process.env) {
+	if ((nonEmpty(env.DEPLOY_ENV) ?? "development") !== "development") return false;
+	if (env.DEV_DB === "remote") return false;
+	if (env.DEV_DB === "local") return true;
+	const dbUrl = env.DB_URL;
+	return dbUrl === void 0 || dbUrl === "" || isLocalDbUrl(dbUrl);
+}
+/** The session as the messages name it: `development:local`, `staging`, … */
+function sessionLabel(env = process.env) {
+	const tier = nonEmpty(env.DEPLOY_ENV) ?? "development";
+	if (tier !== "development") return tier;
+	return `development:${sessionIsLocal(env) ? "local" : "remote"}`;
+}
+/** The hostname for messages — never the URL itself, which carries the
+* password. */
+function dbHost(url) {
+	try {
+		return new URL(url).hostname || "unknown host";
+	} catch {
+		return "unknown host";
+	}
+}
+async function resolveDbConnection(opts = {}) {
+	const { DEPLOY_ENVIRONMENTS, fileFor, isDeployEnvironment } = await loadEnv();
+	const { DEV_DB_ENV, isDevDatabase } = await loadEnvLoad();
+	const env = opts.env ?? process.env;
+	const label = opts.label ?? "devtools db";
+	const report = (message) => {
+		if (!opts.quiet) process.stderr.write(message);
+	};
+	const rawTier = env.DEPLOY_ENV;
+	let tier;
+	if (rawTier === void 0 || rawTier === "") tier = "development";
+	else if (isDeployEnvironment(rawTier)) tier = rawTier;
+	else {
+		report(`${label}: DEPLOY_ENV="${rawTier}" is not one of ${DEPLOY_ENVIRONMENTS.join(", ")}.\n`);
+		return null;
+	}
+	let devDatabase;
+	const rawDevDb = env[DEV_DB_ENV];
+	if (tier === "development" && rawDevDb !== void 0 && rawDevDb !== "") {
+		if (!isDevDatabase(rawDevDb)) {
+			report(`${label}: ${DEV_DB_ENV}="${rawDevDb}" is not one of: local, remote.\n`);
+			return null;
+		}
+		devDatabase = rawDevDb;
+	}
+	const dbUrl = env.DB_URL;
+	if (dbUrl === void 0 || dbUrl === "") {
+		if (tier !== "development") report(`${label}: ${fileFor(tier)} has no DB_URL.\n`);
+		else if (devDatabase === "remote") report(`${label}: this session targets the remote development database, but .env has no DB_URL.\n`);
+		else report(`${label}: no DB_URL in this session — the local Supabase stack is not running. Run \`pnpm devtools db start\`, or relaunch with \`--tier development:remote\` (or staging/production) to act on a hosted database.
+`);
+		return null;
+	}
+	if (tier === "development" && devDatabase !== "remote" && !isLocalDbUrl(dbUrl)) {
+		report(`${label}: DB_URL points at ${dbHost(dbUrl)}, not the local stack — it is offline (or .env.generated is stale). Run \`pnpm devtools db start\`, or relaunch with \`--tier development:remote\` if you mean that database.
+`);
+		return null;
+	}
+	if (tier !== "development" && isLocalDbUrl(dbUrl)) {
+		report(`${label}: the session tier is ${tier} but DB_URL points at ${dbHost(dbUrl)} — a local address, the signature of inherited development values. Relaunch with \`pnpm devtools --tier ${tier}\` from a clean shell.\n`);
+		return null;
+	}
+	return {
+		tier,
+		devDatabase,
+		dbUrl,
+		projectRef: env.PROJECT_REF
+	};
+}
+//#endregion
+//#region ../cli-core/src/args.ts
+/**
+* Positional arguments, with flag values excluded.
+*
+* Its own module because of one bug it prevents. The first positional is the
+* subcommand, and `pull`, `push` and `audit` do very different things to live
+* credentials. A naive `filter((a) => !a.startsWith("--"))` reads a flag's
+* VALUE as a positional, so `env --file notes.env audit` fails loudly:
+* `notes.env` is not a subcommand and the command refuses. The quiet version
+* is the one that matters:
+*
+*     env --file push audit
+*
+* which runs `push`, writing to Bitwarden and GitHub, when the caller asked
+* for `audit`, which writes nothing at all.
+*/
+/**
+* Flags that consume the token after them.
+*/
+const VALUE_FLAGS = /* @__PURE__ */ new Set([
+	"--access-token",
+	"--format",
+	"--out",
+	"--version",
+	"--app",
+	"--apps",
+	"--base-url",
+	"--file",
+	"--source",
+	"--target",
+	"--tier",
+	"--cron",
+	"--workflow",
+	"--params",
+	"--port",
+	"--preview-url",
+	"--db-url",
+	"--user",
+	"--filter",
+	"--shell"
+]);
+function positionals(argv) {
+	const found = [];
+	for (let i = 0; i < argv.length; i += 1) {
+		const arg = argv[i];
+		if (!arg.startsWith("-")) {
+			found.push(arg);
+			continue;
+		}
+		const next = argv[i + 1];
+		if (VALUE_FLAGS.has(arg) && next !== void 0 && !next.startsWith("-")) i += 1;
+	}
+	return found;
+}
+/**
+* The value after `flag`, or `undefined` when the flag is absent or is
+* followed by another flag instead of a value.
+*/
+function flagValue(rest, flag) {
+	const index = rest.indexOf(flag);
+	if (index === -1) return void 0;
+	const value = rest[index + 1];
+	return value && !value.startsWith("--") ? value : void 0;
+}
+//#endregion
+//#region ../cli-core/src/environment.ts
+/**
+* What this machine currently is, read once before the menu draws itself.
+*
+* The wizard used to offer the same commands to everyone: someone whose Docker
+* daemon was not running was invited to reset a database that could not
+* answer, and someone whose stack was already up had no way to stop it at all,
+* because "stop" was not in the tree. Both are the same bug. The menu
+* described the CLI rather than the situation.
+*
+* So this reads three facts and `menu.ts` adapts to them. The facts are few
+* and cheap on purpose; see `probeEnvironment` for the budget and why.
+*
+* ## Unknown is not "no"
+*
+* Every probe can come back `"unknown"`, and that is what a failed probe
+* reports rather than guessing. Nothing is hidden or flagged on `"unknown"`: a
+* machine this cannot read gets the full menu, exactly as before. A tool that
+* hides a command because a `docker ps` timed out is worse than one that never
+* adapted at all, because the command it hides is the one you were looking
+* for.
+*/
+/**
+* Every probe is bounded, silent, and total.
+*
+* `timeout` because a Docker daemon that is starting up (or a VM that has just
+* been resumed) accepts the connection and then never answers, and the failure
+* that produces is a menu that hangs before printing anything, with no output
+* to explain what it is waiting for.
+*/
+function run(file, args) {
+	try {
+		return execFileSync(file, args, {
+			cwd: findRepoRoot(),
+			encoding: "utf8",
+			stdio: [
+				"ignore",
+				"pipe",
+				"ignore"
+			],
+			timeout: 3e3
+		});
+	} catch {
+		return null;
+	}
+}
+/**
+* Reads the machine.
+*
+* Two subprocesses at worst, one when Docker is down, plus an `existsSync`.
+* The budget is "cheaper than the first keystroke", because this runs before
+* the wizard's first screen and anything slower would be paid on every
+* invocation to save a few of them later.
+*
+* It does NOT call `supabase status`, which is the authoritative answer but
+* takes the better part of a second: it shells out through `pnpm exec` and
+* then talks to every service in the stack. `docker ps` answers the only
+* question the menu has (is it up?) in a fraction of that, and the commands
+* that need real credentials go through `resolveInstance` (`instance.ts`),
+* which reads the session's already-entered env at the moment it matters.
+*/
+function probeEnvironment(execute = run) {
+	const envFile = existsSync(join(findRepoRoot(), ".env")) ? "yes" : "no";
+	const docker = execute("docker", ["info"]) === null ? "no" : "yes";
+	if (docker === "no") return {
+		docker,
+		stack: "no",
+		envFile
+	};
+	const names = execute("docker", [
+		"ps",
+		"--format",
+		"{{.Names}}"
+	]);
+	if (names === null) return {
+		docker,
+		stack: "unknown",
+		envFile
+	};
+	const prefix = containerPrefix(readProjectId(findRepoRoot()));
+	return {
+		docker,
+		stack: names.split("\n").some((name) => name.trim().startsWith(prefix)) ? "yes" : "no",
+		envFile
+	};
+}
+/**
+* Whether a `Condition` from the command tree currently holds.
+*
+* The tree declares conditions as strings so that it stays inert data the docs
+* build can render (see `catalog.ts`); this is the one place that knows what
+* they mean. `"unknown"` propagates rather than collapsing to false, and both
+* callers below read it as "do nothing".
+*/
+function holds(condition, env) {
+	switch (condition) {
+		case "docker": return env.docker;
+		case "instance-running": return env.stack;
+		case "instance-stopped":
+			if (env.stack === "unknown") return "unknown";
+			return env.stack === "no" ? "yes" : "no";
+	}
+}
+/**
+* Whether the wizard should offer this command at all.
+*
+* False only for a command whose `when` is definitively unmet: `stop`
+* against a stack that is already stopped. This is reserved for commands that
+* would be *meaningless*, never merely inconvenient: one that would fail with
+* a good error message stays in the menu, because a contributor who cannot
+* find a command they know exists is worse off than one who runs it and is
+* told why it did not work.
+*
+* Hiding is a wizard-only decision. `--help` still lists these, the dispatcher
+* still accepts them, and the generated reference still documents them. The
+* menu is a guide to right now, and those three are the reference.
+*/
+function isOffered(node, env) {
+	return node.when === void 0 || holds(node.when, env) !== "no";
+}
+const LABELS = {
+	yes: "yes",
+	no: "no",
+	unknown: "could not tell"
+};
+/**
+* The three facts, as the wizard's opening note and as `status --local`.
+*
+* Printed before the first question rather than discovered through failures:
+* "Docker running  no" at the top of the screen is the whole explanation for
+* why the database commands below it are flagged, and it costs one glance.
+*/
+function describeEnvironment(env) {
+	return [
+		`Docker running   ${LABELS[env.docker]}`,
+		`Local stack up   ${LABELS[env.stack]}`,
+		`.env present     ${LABELS[env.envFile]}`
+	].join("\n");
+}
+//#endregion
+//#region ../cli-core/src/invocation.ts
+/**
+* Records the fully-resolved argv of the command being run, so the CLI can
+* close by printing a copy-pasteable line — the same command with every prompt
+* already answered — for anyone who reached it through the wizard or let a
+* missing flag fall to a prompt.
+*
+* ## Why a module-level recorder rather than a return value
+*
+* A command's inputs arrive from two places that never meet: the wizard walks
+* `commands.ts` and gathers the *declared* options into the argv it dispatches
+* (see `menu.ts`), while a runner resolves anything it prompts for *itself* —
+* `workflows run` picking a tier, `env init` picking projects — deep inside its
+* own call stack, where the dispatched argv is long out of reach. Threading a
+* return value back up through every runner would touch each one's signature;
+* a recorder every layer can reach touches only the layers that actually
+* prompt.
+*
+* The rule for a runner: whenever a prompt (not a flag the caller already
+* passed) decides a value, `recordResolved` the flag form of that decision. A
+* value that came in as a flag is already in the base argv, so recording it
+* again would double it — only the prompt branch records.
+*/
+/** The base argv plus whatever prompts resolved; `null` until an invocation begins. */
+let argv = null;
+/** Did the wizard, or an in-command prompt, actually decide anything here? */
+let interactive = false;
+/**
+* The deploy tier `src/launch.ts` resolved and entered for this session, or
+* `null` for the development default. Reproduced as a leading `--tier <tier>`
+* flag, the same global flag `launch.ts` strips off ANY invocation before
+* `cli.ts` ever runs — see its header — so this reproduces the tier for
+* EVERY command, `db` and `env` included, exactly as typing `--tier <tier>`
+* up front would.
+*/
+let enteredTier = null;
+/**
+* Start recording for one invocation.
+*
+* `base` is what the dispatcher received: the wizard's built argv, or the argv
+* the user typed. `fromMenu` marks the wizard path, where every step was a
+* prompt, so the rerun line is worth printing even if no runner records a
+* thing. A typed command starts non-interactive and only earns the line if a
+* runner resolves a missing flag from a prompt.
+*/
+function beginInvocation(base, fromMenu) {
+	argv = [...base];
+	interactive = fromMenu;
+	enteredTier = null;
+}
+/**
+* Record the deploy tier the wizard entered up front, so the rerun line carries
+* it. development is the ambient default, so a prefix for it would be noise and
+* is dropped.
+*/
+function recordEnteredTier(tier) {
+	enteredTier = tier === "development" ? null : tier;
+}
+/**
+* Append the flag form of a value a prompt just resolved, e.g.
+* `recordResolved("--tier", "development")`.
+*/
+function recordResolved(...fragment) {
+	if (argv === null || fragment.length === 0) return;
+	argv.push(...fragment);
+	interactive = true;
+}
+/**
+* The command to print, or `null` when there is nothing worth printing —
+* either no invocation ran, or the user typed a complete command and answered
+* no prompts, so echoing it back would be noise.
+*/
+function reproducibleCommand() {
+	if (argv === null || !interactive || argv.length === 0) return null;
+	return `pnpm devtools ${[...enteredTier ? ["--tier", enteredTier] : [], ...argv].join(" ")}`;
+}
+//#endregion
+//#region ../cli-core/src/menu.ts
+/**
+* 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 the catalog means an interactive command added there is in the
+* menu the same day, with its options. Commands marked `cli-only` do not appear here.
+*/
+/** Chosen when a submenu should return to the screen above it. */
+const BACK = Symbol("back");
+const BACK_OPTION = {
+	value: BACK,
+	label: "← Back"
+};
+/**
+* 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. */
+function hintFor(node) {
+	const said = node.hint ?? node.summary;
+	return node.scope ? `${SCOPES[node.scope].menu} · ${said}` : said;
+}
+async function pickGroup(catalog, env) {
+	const groups = catalog.groups.filter((group) => offered(group.commands, env).length > 0);
+	return unwrap(await select({
+		message: "What would you like to do?",
+		options: [...groups.map((group) => ({
+			value: group,
+			label: group.title,
+			hint: offered(group.commands, env).map((command) => command.name).join(", ")
+		})), {
+			value: null,
+			label: "Quit"
+		}]
+	}));
+}
+async function pickCommand(group, env) {
+	const commands = offered(group.commands, env);
+	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)
+		})), 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)
+		})), BACK_OPTION]
+	}));
+}
+/**
+* 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`.
+*/
+async function askOption(option) {
+	const prompt = option.prompt;
+	if (!prompt) return [];
+	if (prompt.kind === "confirm") return unwrap(await confirm({
+		message: prompt.message,
+		initialValue: prompt.initial
+	})) ? [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(catalog, env, startPath) {
+	if (startPath) {
+		const start = catalog.findCommand(startPath);
+		if (!start) return null;
+		const chosen = await descendFrom(start, [...startPath], env);
+		return chosen === BACK ? null : chosen;
+	}
+	for (;;) {
+		const group = await pickGroup(catalog, 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;
+	}
+}
+/**
+* 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.
+*/
+function bareGroupStartPath(catalog, argv) {
+	const path = positionals(argv);
+	if (path.length === 0) return null;
+	const node = catalog.findCommand(path);
+	if (!node || (node.subcommands ?? []).length === 0) return null;
+	return path;
+}
+/**
+* Runs the wizard, returning the `outro()` line its command earned.
+*
+* `dispatch` is the CLI's own argv handler, injected rather than imported so
+* that the CLI 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 it
+* before `cli.ts` — and therefore this module — is even imported, and
+* exports `DEPLOY_ENV`/`DEV_DB` right away, so by the time the wizard opens
+* `process.env` already names the session 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.
+*
+* Entering that tier — loading its `.env.<tier>` file onto `process.env` —
+* is what's deferred: `launch.ts` registers a hook (`env-entry.ts`'s
+* `setMenuEnvHook`) instead of entering up front, so whatever changed while
+* the reader was still walking the menu (the local stack coming up in
+* another terminal, `.env.generated` being rewritten) is picked up rather
+* than missed. `takeMenuEnvHook()` below runs it right before the chosen
+* command dispatches — the ONE place in a menu walk an env value is ever
+* actually read. `undefined` (no hook registered — a typed command entered
+* already, or a test drives `runMenu` directly) just dispatches straight
+* through, unchanged from before this existed.
+*/
+async function runMenu(catalog, dispatch, env = probeEnvironment(), options = {}) {
+	note(describeEnvironment(env), "This machine");
+	const chosen = await walk(catalog, env, options.startPath);
+	if (!chosen) return null;
+	beginInvocation(chosen.argv, true);
+	const enteredTier = process.env.DEPLOY_ENV ?? "development";
+	const devDb = process.env.DEV_DB;
+	recordEnteredTier(enteredTier === "development" && (devDb === "local" || devDb === "remote") ? `development:${devDb}` : enteredTier);
+	const enterEnvironment = takeMenuEnvHook();
+	if (enterEnvironment) return enterEnvironment(chosen.argv, () => dispatch(chosen.argv));
+	return dispatch(chosen.argv);
+}
+//#endregion
+export { catalog as C, renderHelp as E, unwrap as S, renderCommandList as T, setMenuEnvHook as _, recordResolved as a, explain as b, probeEnvironment as c, nonEmpty as d, resolveDbConnection as f, realEnvEntryDeps as g, enterSessionEnvironment as h, recordEnteredTier as i, flagValue as l, sessionLabel as m, runMenu as n, reproducibleCommand as o, sessionIsLocal as p, beginInvocation as r, describeEnvironment as s, bareGroupStartPath as t, positionals as u, bail as v, helpPath as w, explainError as x, errorMessage as y };