@devdogsuga/backstage 0.1.0

package/dist/catalog-BOBE4ee7.js

@@ -0,0 +1,1570 @@
+import { A as YES, D as DRY_RUN, O as JSON_FLAG, S as RepoNotFoundError, j as createCatalog, k as SCOPES, v as noteRan, w as findRepoRoot } from "./telemetry-Bjoz29Hl.js";
+import { o as isDryRun, r as qrCatalogOptions } from "./options-BTjOf5KP.js";
+import { o as unwrap } from "./ui-CdKo8mLw.js";
+import { n as positionals } from "./args-Cjr_Iqts.js";
+import { createRequire } from "node:module";
+import { pathToFileURL } from "node:url";
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { confirm, note, select, text } from "@clack/prompts";
+import "node:fs/promises";
+import { execFile, execFileSync, spawn } from "node:child_process";
+import { promisify } from "node:util";
+//#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 ../cli-core/src/repo/resolve.ts
+/**
+* Resolves an `@devdogsuga/*` package FROM the target repo, not from
+* devtools' own (dlx-isolated) `node_modules`.
+*
+* Ported from the `devtools-dlx` prototype
+* (`/home/sloan/scratchpad/devdogs/prototypes/devtools-dlx/FINDINGS.md`,
+* experiments 2 and 4 — read that file for the two gotchas this module
+* exists to avoid). The short version:
+*
+*   - `require.resolve(\`${specifier}/package.json\`)` throws
+*     `ERR_PACKAGE_PATH_NOT_EXPORTED` on packages (like `@devdogsuga/env`,
+*     `@devdogsuga/open-graph`) whose `exports` map does not list
+*     `"./package.json"`, even though the file is on disk.
+*   - A resolved path cannot be assumed to contain a literal
+*     `node_modules/<specifier>` segment — pnpm workspace-linked packages
+*     resolve to their REALPATH (e.g. `packages/open-graph/dist/index.js`),
+*     which has no such segment at all.
+*   - `require.resolve` ignores whatever `conditions` a caller has set on
+*     `tsx`'s `register()` — condition-based resolution (the
+*     `devdogs-source` condition) has to be done by hand, reading the
+*     target package's own `exports["."]` map.
+*
+* Both problems are solved the same way: walk up from the resolved file's
+* directory to the nearest `package.json` whose own `"name"` field matches
+* the specifier. That works for a real installed dependency AND a
+* workspace symlink, uniformly.
+*/
+/**
+* The installable package name a (possibly subpath) specifier belongs to:
+* `@devdogsuga/env/load` → `@devdogsuga/env`, `foo/bar` → `foo`. A repo's
+* package.json declares the PACKAGE as a dependency, never a subpath, so
+* `findDependent` has to search on this rather than the literal specifier a
+* caller wants to import.
+*/
+function packageNameOf(specifier) {
+	const parts = specifier.split("/");
+	return specifier.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+}
+/**
+* Scans `apps/*` and `packages/*` under `repoRoot` for the first
+* `package.json` whose `dependencies`/`devDependencies`/`peerDependencies`
+* names `specifier`'s package (see `packageNameOf`). Returns its path
+* relative to `repoRoot`, or `null` if nothing in the repo depends on it.
+*
+* Re-scans the filesystem on every call — fine for a short-lived CLI
+* invocation calling this a handful of times; see FINDINGS item 5 if this
+* is ever called in a hot loop.
+*/
+function findDependent(repoRoot, specifier) {
+	const packageName = packageNameOf(specifier);
+	for (const group of ["apps", "packages"]) {
+		const groupDir = join(repoRoot, group);
+		let entries;
+		try {
+			entries = readdirSync(groupDir);
+		} catch {
+			continue;
+		}
+		for (const entry of entries) {
+			const pkgJsonPath = join(groupDir, entry, "package.json");
+			if (!existsSync(pkgJsonPath)) continue;
+			let pkg;
+			try {
+				pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+			} catch {
+				continue;
+			}
+			if (packageName in {
+				...pkg.dependencies,
+				...pkg.devDependencies,
+				...pkg.peerDependencies
+			}) return join(group, entry, "package.json");
+		}
+	}
+	return null;
+}
+/** Walks up from `startDir` to the nearest `package.json` whose `"name"` matches `specifier`. */
+function findOwningPackageJson(startDir, specifier) {
+	const packageName = packageNameOf(specifier);
+	let dir = startDir;
+	for (;;) {
+		const candidate = join(dir, "package.json");
+		if (existsSync(candidate)) try {
+			if (JSON.parse(readFileSync(candidate, "utf8")).name === packageName) return candidate;
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) throw new Error(`resolveFromRepo: could not find ${specifier}'s own package.json by walking up from ${startDir}`);
+		dir = parent;
+	}
+}
+/**
+* Resolves `specifier` as `resolutionBase` (a workspace-relative
+* `package.json` path known to depend on it, from `findDependent()`) would
+* see it.
+*
+* `opts.condition`, when given, is NOT passed through to Node's resolver —
+* `require.resolve` ignores tsx's `register({ conditions })` entirely (see
+* this module's header). Instead the target package's own
+* `exports["."]` map is read directly and `exports["."][condition]` is
+* picked, falling back to `.default`.
+*/
+function resolveFromRepo(repoRoot, resolutionBase, specifier, opts) {
+	const baseFile = join(repoRoot, resolutionBase);
+	const require = createRequire(baseFile);
+	let resolvedPath;
+	if (opts?.condition) {
+		const defaultEntry = require.resolve(specifier);
+		const pkgJsonPath = findOwningPackageJson(dirname(defaultEntry), specifier);
+		const rootExport = JSON.parse(readFileSync(pkgJsonPath, "utf8")).exports?.["."];
+		const conditioned = rootExport && typeof rootExport === "object" ? rootExport[opts.condition] ?? rootExport.default : void 0;
+		if (typeof conditioned !== "string") throw new Error(`resolveFromRepo: ${specifier} has no "${opts.condition}" (or "default") export in its exports["."] map`);
+		resolvedPath = join(dirname(pkgJsonPath), conditioned);
+	} else resolvedPath = require.resolve(specifier);
+	const pkgJsonPath = findOwningPackageJson(dirname(resolvedPath), specifier);
+	const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+	return {
+		resolvedPath,
+		version: pkg.version ?? "0.0.0",
+		pkgJsonPath
+	};
+}
+//#endregion
+//#region ../cli-core/src/repo/peers.ts
+/**
+* Loads devtools' optional-peer `@devdogsuga/*` libraries — the ones
+* published to npm and consumed by the TARGET repo, which devtools reads at
+* runtime rather than bundling its own copy of (see this package's
+* `package.json`: `peerDependencies` + `peerDependenciesMeta.optional`, and
+* `FINDINGS.md` experiment 2).
+*
+* Every export here is memoized per module (one dynamic `import()` per
+* process, not per call) — this is what makes the module-identity guarantee
+* in FINDINGS experiment 3 hold: every devtools call site that needs
+* `@devdogsuga/env`'s registry gets the exact same module instance the
+* repo's own manifests populated via `declare()`/`define()`, because both
+* resolve to the identical absolute file path and Node's ESM cache is keyed
+* by resolved URL.
+*/
+const moduleCache = /* @__PURE__ */ new Map();
+/** The file URL each peer resolved to through the target repo, set only on
+*  that path (not on either plain bare-specifier fallback). See
+*  `repoPeerUrl()`. */
+const resolvedUrls = /* @__PURE__ */ new Map();
+/**
+* Dynamically imports `specifier` as the repo would resolve it, memoized so
+* repeated calls in one process return the SAME module instance (required
+* for the env-registry identity guarantee above).
+*
+* Falls back to a plain bare-specifier `import()` when devtools is not
+* running inside a DevDogsUGA checkout at all (`findRepoRoot()` throws
+* `RepoNotFoundError`). That is not a production affordance — under real
+* `pnpm dlx` use, `specifier` is an optional peer devtools' own package
+* never installs, so the fallback import fails with the ordinary
+* `MODULE_NOT_FOUND` either way. It exists so devtools' OWN test suite
+* (which has no target repo to discover, but does have every one of these
+* peers as a real Backstage workspace package) exercises this code against
+* the genuine package rather than needing every test to mock this module.
+*/
+function loadPeer(specifier) {
+	const cached = moduleCache.get(specifier);
+	if (cached) return cached;
+	const promise = (async () => {
+		if (process.env.DEVTOOLS_TEST_REPO_ROOT) return import(specifier);
+		let repoRoot;
+		try {
+			repoRoot = findRepoRoot();
+		} catch (err) {
+			if (err instanceof RepoNotFoundError) return import(specifier);
+			throw err;
+		}
+		const resolutionBase = findDependent(repoRoot, specifier);
+		if (!resolutionBase) throw new Error(`Nothing in this repo depends on ${specifier} — expected an app or package under apps/* or packages/* to declare it (dependencies/devDependencies/peerDependencies).`);
+		const { resolvedPath } = resolveFromRepo(repoRoot, resolutionBase, specifier);
+		const url = pathToFileURL(resolvedPath).href;
+		resolvedUrls.set(specifier, url);
+		return import(url);
+	})();
+	moduleCache.set(specifier, promise);
+	return promise;
+}
+/**
+* The file URL `specifier` was loaded from through the target repo, or
+* undefined if it has not been loaded yet or came from a plain bare-specifier
+* `import()` (the test-suite and not-in-a-repo fallbacks above).
+*
+* For code devtools imports that itself names a peer by bare specifier --
+* today only devtools' own `env.ts` manifest. From an installed copy that
+* specifier cannot resolve at all (an optional peer is never installed next
+* to devtools under `pnpm dlx`), and even where it can, the only copy that
+* keeps module identity is this one. `repo/peer-redirect.ts` uses it to
+* point the import here.
+*/
+function repoPeerUrl(specifier) {
+	return resolvedUrls.get(specifier);
+}
+let resolvedEnvModule;
+function loadEnv() {
+	return loadPeer("@devdogsuga/env").then((mod) => {
+		resolvedEnvModule = mod;
+		return mod;
+	});
+}
+/**
+* The synchronous companion to `loadEnv()`, for the handful of call sites
+* (`gh/environments.ts`'s `GITHUB_ENVIRONMENT_SPECS` getters) that cannot
+* become async without changing their own callers' contract — they read a
+* plain array off a getter, not a Promise. Safe ONLY after `loadEnv()` has
+* resolved at least once; every caller of these getters already requires
+* `env/discovery.ts`'s `loadRegistry()` (which calls `loadEnv()` itself) to
+* have run first, via `assertRegistryLoaded()`'s own guard.
+*/
+function getEnvSync() {
+	if (!resolvedEnvModule) throw new Error("getEnvSync() called before loadEnv() ever resolved — call loadRegistry() (env/discovery.ts) first.");
+	return resolvedEnvModule;
+}
+function loadEnvLoad() {
+	return loadPeer("@devdogsuga/env/load");
+}
+function loadEnvSession() {
+	return loadPeer("@devdogsuga/env/session");
+}
+//#endregion
+//#region ../cli-core/src/db/connection.ts
+/** An env value, with unset and empty both meaning "not given". */
+function nonEmpty(value) {
+	return value === void 0 || value === "" ? void 0 : value;
+}
+//#endregion
+//#region ../cli-core/src/process-group.ts
+/**
+* Running a child tool so that stopping it stops everything it started.
+*
+* `pnpm run dev` forks a shell that forks vinext that forks workerd. Killing
+* only the pnpm process (what a plain `child.kill()` does, and what a closed
+* terminal tab or a `kill` from another window delivers) orphans the rest,
+* and the orphan keeps its port. So the child gets its own process group, and
+* every stop signal this process receives is sent to the whole group.
+*
+* Ctrl-C needs the same care in reverse: a child in its own group is not in
+* the terminal's foreground group, so the terminal no longer delivers ^C to
+* it. The signal handlers below forward it.
+*
+* The group is only swept after the direct child exits when that exit was a
+* signal we forwarded; a child that exits on its own is left to have cleaned
+* up after itself, so a tool that deliberately leaves a daemon running keeps it.
+*/
+const FORWARDED = [
+	"SIGINT",
+	"SIGTERM",
+	"SIGHUP"
+];
+const SIGNAL_NUMBERS = {
+	SIGHUP: 1,
+	SIGINT: 2,
+	SIGTERM: 15,
+	SIGKILL: 9
+};
+/** How long a group gets to leave after SIGTERM before SIGKILL. */
+const GRACE_MS = 5e3;
+/** Sends `signal` to every process in `pid`'s group. False if it is already gone. */
+function signalGroup(pid, signal) {
+	try {
+		process.kill(process.platform === "win32" ? pid : -pid, signal);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function runInGroup(command, args, opts = {}) {
+	if (isDryRun()) {
+		process.stderr.write(`Would run: ${formatCommand(command, args)}\n`);
+		return Promise.resolve({
+			code: 0,
+			signal: null
+		});
+	}
+	return new Promise((resolve) => {
+		const child = spawn(command, [...args], {
+			stdio: opts.stdio ?? "inherit",
+			cwd: opts.cwd,
+			env: opts.env,
+			detached: process.platform !== "win32"
+		});
+		const pid = child.pid;
+		let forwarded = null;
+		let escalation;
+		const forward = (signal) => {
+			if (pid === void 0) return;
+			forwarded ??= signal;
+			signalGroup(pid, signal);
+			escalation ??= setTimeout(() => signalGroup(pid, "SIGKILL"), GRACE_MS);
+			escalation.unref();
+		};
+		if (opts.abort?.aborted) forward("SIGTERM");
+		else opts.abort?.addEventListener("abort", () => forward("SIGTERM"), { once: true });
+		const handlers = FORWARDED.map((signal) => {
+			const handler = () => forward(signal);
+			process.on(signal, handler);
+			return [signal, handler];
+		});
+		const onExit = () => {
+			if (pid !== void 0) signalGroup(pid, "SIGKILL");
+		};
+		process.on("exit", onExit);
+		const finish = (result) => {
+			noteRan(`${formatCommand(command, args)}  (exit ${result.code})`);
+			for (const [signal, handler] of handlers) process.off(signal, handler);
+			process.off("exit", onExit);
+			if (escalation) clearTimeout(escalation);
+			if (forwarded !== null && pid !== void 0) signalGroup(pid, "SIGKILL");
+			resolve(result);
+		};
+		child.on("error", (error) => {
+			process.stderr.write(`${error.message}\n`);
+			finish({
+				code: 1,
+				signal: null
+			});
+		});
+		child.on("exit", (code, signal) => {
+			const bySignal = signal ? 128 + (SIGNAL_NUMBERS[signal] ?? 0) : 1;
+			finish({
+				code: code ?? bySignal,
+				signal
+			});
+		});
+	});
+}
+const URL_CREDENTIALS = /\/\/[^/@\s]*@/;
+/**
+* The command as a person would type it, for printing. A database URL carries
+* its password, so the value after `--db-url` (and any URL with credentials)
+* is replaced rather than echoed.
+*/
+function formatCommand(command, args) {
+	const shown = [];
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (arg === "--db-url" && i + 1 < args.length) {
+			shown.push(arg, "<DB_URL>");
+			i += 1;
+		} else if (arg.startsWith("--db-url=")) shown.push("--db-url=<DB_URL>");
+		else shown.push(arg.replace(URL_CREDENTIALS, "//***@"));
+	}
+	return [command, ...shown].map((part) => /^[\w@%+=:,./<>*-]+$/.test(part) ? part : JSON.stringify(part)).join(" ");
+}
+/**
+* Prints the exact command that ran, AFTER it ran so the tool's own output
+* cannot bury it. On stderr, so a tool whose stdout is a pipe stays clean.
+*/
+function reportRan(command, args, result) {
+	if (isDryRun()) return;
+	const status = result.code === 0 ? "" : `  (exit ${result.code})`;
+	process.stderr.write(`Ran: ${formatCommand(command, args)}${status}\n`);
+}
+//#endregion
+//#region ../cli-core/src/db/run.ts
+/**
+* Shared helpers for running supabase CLI and pnpm commands from the repo root.
+*
+* The supabase CLI is a workspace devDependency (not a global install), so
+* every invocation goes through `pnpm exec supabase`. The cwd is always
+* findRepoRoot(), where `supabase/config.toml` lives.
+*/
+const runFile = promisify(execFile);
+/** Spawn a pnpm command with inherited stdio; resolves to the exit code. Pass
+* `env` to run the child against a loaded tier rather than process.env. The
+* child runs in its own process group, so stopping this process stops
+* whatever it started (see `process-group.ts`). */
+async function run$1(args, env) {
+	const result = await runInGroup("pnpm", args, {
+		cwd: findRepoRoot(),
+		...env ? { env } : {}
+	});
+	if (reporting) reportRan("pnpm", args, result);
+	return result.code;
+}
+let reporting = false;
+/** `pnpm exec supabase …` with inherited stdio. */
+const supabase = (...args) => run$1([
+	"exec",
+	"supabase",
+	...args
+]);
+/**
+* `supabase db push` over `dbUrl`, inherited stdio, resolving to the exit code.
+*
+* The one spelling of the migration push, shared by the contributor `db
+* migrate` path (`stack.ts`'s `pushMigrations`) and CI's `deploy migrate`.
+* `--yes` is the unattended apply CI wants; the contributor path omits it so a
+* human still confirms. Neither variant regenerates types — that is
+* `pushMigrations`' own second step, layered on top only where a checkout is
+* meant to be rewritten. A CI apply must NOT write back into the repo, which is
+* exactly why the bare push is factored out here rather than reused whole.
+*/
+function dbPush(dbUrl, opts = {}) {
+	const args = [
+		"db",
+		"push",
+		"--db-url",
+		dbUrl
+	];
+	if (opts.yes) args.push("--yes");
+	return supabase(...args);
+}
+/**
+* `supabase db push --dry-run` over `dbUrl`, returning the plan text (stdout
+* and stderr combined, as the workflow's old `2>&1` did).
+*
+* Throws on a non-zero exit — which for a dry run means the CONNECTION failed,
+* not that the plan came back empty. That throw is the invariant `deploy plan`
+* leans on, and the thing the old shell needed `set -o pipefail` to preserve: a
+* dead connection must fail the step rather than read as "no migrations to
+* apply". The child's own output is surfaced in the thrown message, because for
+* a dry run that output is precisely the reason the operator needs.
+*/
+async function dbPushDryRun(dbUrl) {
+	try {
+		const { stdout, stderr } = await runFile("pnpm", [
+			"exec",
+			"supabase",
+			"db",
+			"push",
+			"--db-url",
+			dbUrl,
+			"--dry-run"
+		], {
+			cwd: findRepoRoot(),
+			encoding: "utf8",
+			maxBuffer: 33554432
+		});
+		return `${stdout}${stderr}`;
+	} catch (err) {
+		const e = err;
+		const detail = `${e.stdout ?? ""}${e.stderr ?? ""}`.trim();
+		throw new Error(detail ? `supabase db push --dry-run failed:\n${detail}` : e.message ?? "supabase db push --dry-run failed");
+	}
+}
+//#endregion
+//#region ../cli-core/src/repo/supabase-project.ts
+/**
+* Reads `project_id` out of `<repoRoot>/supabase/config.toml`, or `null`
+* when the file is missing or unparsable.
+*
+* Regex, not a TOML parser: it is one line, the shape has been stable
+* across every CLI version this repo has seen, and a parser on a path some
+* callers pay before their first real subprocess is a cost that stays
+* invisible until it is why the tool feels slow.
+*/
+function readProjectId(repoRoot) {
+	try {
+		const path = join(repoRoot, "supabase", "config.toml");
+		return /^\s*project_id\s*=\s*"([^"]+)"/m.exec(readFileSync(path, "utf8"))?.[1] ?? null;
+	} catch {
+		return null;
+	}
+}
+/**
+* The Supabase CLI's container name prefix for a project id, or the bare
+* `supabase_db_` fallback when the id could not be read.
+*
+* Falling back to the bare prefix means a machine whose `config.toml`
+* cannot be read still detects *a* stack, at the cost of over-matching a
+* differently-named project — deliberate, and unchanged from this
+* function's original home in `environment.ts`: over-matching offers
+* `stop`/a foreign-stack hint for a stack that turns out to be this
+* project's own, which is harmless to see and decline, while
+* under-matching hides a real signal entirely.
+*/
+function containerPrefix(projectId) {
+	return projectId ? `supabase_db_${projectId}` : "supabase_db_";
+}
+//#endregion
+//#region ../cli-core/src/env-entry.ts
+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/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
+//#region src/completions/catalog.ts
+const completionsCommand = {
+	name: "completions",
+	dryRun: "read-only",
+	summary: "Output a shell completion script for backstage.",
+	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/deploy/catalog.ts
+/**
+* `deploy`'s place in the command tree: declaration only, nothing here runs.
+* The handler lives in `commands.ts` beside it.
+*/
+const DEPLOY_TIER = {
+	flag: "--tier",
+	value: "<t>",
+	summary: "staging or production. Or set DEPLOY_ENV.",
+	prompt: {
+		kind: "select",
+		message: "Which environment?",
+		choices: [{ value: "staging" }, {
+			value: "production",
+			hint: "⚠️  live"
+		}]
+	}
+};
+const SMOKE_APP = {
+	flag: "--app",
+	value: "<app>",
+	summary: "Which app to check. Defaults to platform."
+};
+function app(name) {
+	return {
+		name,
+		summary: `Deploy the ${name} app.`,
+		options: [
+			DEPLOY_TIER,
+			DRY_RUN,
+			YES
+		]
+	};
+}
+const deployCommand = {
+	name: "deploy",
+	dryRun: "handled",
+	summary: "Deploy an app, or run one step of a deploy.",
+	hint: "needs CLOUDFLARE_API_TOKEN and the tier's env",
+	subcommands: [
+		app("platform"),
+		app("schedule-builder"),
+		app("sandbox"),
+		{
+			name: "write-env",
+			summary: "Compose .env.<DEPLOY_ENV> from the GitHub environment.",
+			hint: "run it with --no-env: it creates the file the tier needs",
+			options: [{
+				flag: "--source",
+				value: "<manifest>",
+				summary: "Compose one manifest's slice instead of all."
+			}, DRY_RUN]
+		},
+		{
+			name: "preflight",
+			dryRun: "read-only",
+			summary: "Classify the project: paused (skip) vs broken (fail)."
+		},
+		{
+			name: "plan",
+			dryRun: "read-only",
+			summary: "Dry-run the migrations into the job summary.",
+			options: [{
+				flag: "--label",
+				value: "<title>",
+				summary: "Heading for the summary section."
+			}]
+		},
+		{
+			name: "migrate",
+			summary: "Apply the migrations to DB_URL.",
+			options: [DRY_RUN]
+		},
+		{
+			name: "smoke",
+			dryRun: "read-only",
+			summary: "Check a deployed app: public routes, auth redirect, Sentry.",
+			hint: "per-app data comes from workers.json",
+			options: [DEPLOY_TIER, SMOKE_APP]
+		},
+		{
+			name: "reconcile",
+			dryRun: "read-only",
+			summary: "Run the platform's config reconcile after a deploy.",
+			hint: "needs CRON_SECRET",
+			options: [DEPLOY_TIER, SMOKE_APP]
+		}
+	]
+};
+//#endregion
+//#region src/env/catalog.ts
+/**
+* `env`'s place in the command tree: declaration only, nothing here runs.
+* The handler lives in `commands.ts` beside it.
+*/
+const VAULT_TARGET = {
+	flag: "--target",
+	value: "<t>",
+	summary: "preflight, staging or production. Asked for when absent."
+};
+const ENV_FILE = {
+	flag: "--file",
+	value: "<path>",
+	summary: "Read and write this file instead of the target's own."
+};
+const ACCESS_TOKEN = {
+	flag: "--access-token",
+	value: "<token>",
+	summary: "Bitwarden Secrets Manager token. Prefer the vault or the env var."
+};
+const envCommand = {
+	name: "env",
+	summary: "One env file per target, synced to Bitwarden and GitHub.",
+	hint: "needs the Secrets Manager token",
+	subcommands: [
+		{
+			name: "pull",
+			summary: "Bitwarden → the target's file, in place.",
+			options: [
+				VAULT_TARGET,
+				ENV_FILE,
+				YES,
+				ACCESS_TOKEN
+			]
+		},
+		{
+			name: "push",
+			summary: "The target's file → Bitwarden and GitHub.",
+			options: [
+				VAULT_TARGET,
+				ENV_FILE,
+				YES,
+				ACCESS_TOKEN
+			]
+		},
+		{
+			name: "audit",
+			dryRun: "read-only",
+			summary: "Compare the file, Bitwarden, GitHub and Cloudflare; list orphaned Worker secrets.",
+			hint: "reads only, unless --prune",
+			options: [
+				VAULT_TARGET,
+				ENV_FILE,
+				YES,
+				ACCESS_TOKEN,
+				JSON_FLAG,
+				{
+					flag: "--prune",
+					summary: "Delete the Worker secrets no app declares. Asks first without --yes."
+				}
+			]
+		}
+	]
+};
+//#endregion
+//#region src/github/catalog.ts
+/**
+* `github`'s place in the command tree: declaration only, nothing here runs.
+* The handler lives in `commands.ts` beside it.
+*/
+const githubCommand = {
+	name: "github",
+	dryRun: "handled",
+	summary: "Reconcile the repository's rulesets and settings.",
+	hint: "rulesets: main, production, ~ALL, team/**, tags; settings: security, Actions, environments",
+	subcommands: [{
+		name: "rulesets",
+		summary: "Diff the fixed rulesets against live GitHub; --apply to write.",
+		hint: "dry-run plan by default",
+		envFree: true,
+		options: [
+			{
+				flag: "--org",
+				value: "<org>",
+				summary: "GitHub org. Defaults to DevDogsUGA."
+			},
+			{
+				flag: "--repo",
+				value: "<repo>",
+				summary: "Repository name. Defaults to DevDogsUGA."
+			},
+			{
+				flag: "--app-slug",
+				value: "<slug>",
+				summary: "The GitHub App whose id bypasses team/** creation. Defaults to devdogs-platform."
+			},
+			{
+				flag: "--apply",
+				summary: "Write the plan instead of only printing it."
+			},
+			YES,
+			JSON_FLAG
+		]
+	}, {
+		name: "settings",
+		summary: "Diff security/Actions/environment settings vs live GitHub.",
+		hint: "dry-run plan by default",
+		envFree: true,
+		options: [
+			{
+				flag: "--org",
+				value: "<org>",
+				summary: "GitHub org. Defaults to DevDogsUGA."
+			},
+			{
+				flag: "--repo",
+				value: "<repo>",
+				summary: "Repository name. Defaults to DevDogsUGA."
+			},
+			{
+				flag: "--apply",
+				summary: "Write fixable drift instead of only printing it."
+			},
+			YES,
+			JSON_FLAG
+		]
+	}]
+};
+//#endregion
+//#region src/graphics/catalog.ts
+const graphicsCommand = {
+	name: "graphics",
+	dryRun: "handled",
+	envFree: true,
+	summary: "Render a club image at one or more sizes.",
+	hint: "brand/*, app/*, event/*, or * for all",
+	options: [
+		{
+			flag: "--format",
+			value: "<a,b,…>",
+			summary: "Sizes to render: og, gdgc-wide, gdgc-square, savvycal, email-*, icon-*."
+		},
+		{
+			flag: "--all-formats",
+			summary: "Every size the named graphics support."
+		},
+		{
+			flag: "--out",
+			value: "<dir>",
+			summary: "Write everything into one directory, flat. Defaults to the current directory."
+		},
+		{
+			flag: "--dry-run",
+			summary: "List what would be written, and what each size is for."
+		}
+	]
+};
+//#endregion
+//#region src/newsletter/catalog.ts
+/**
+* `newsletter`'s place in the command tree: declaration only, nothing here
+* runs. The handler lives in `commands.ts` beside it.
+*
+* Every subcommand is `envFree`: the club mailbox is reached with the
+* officer's own Microsoft sign-in, not an env file or a deploy tier.
+*/
+const newsletterCommand = {
+	name: "newsletter",
+	summary: "Render, draft or send a DevDogs Changelog issue.",
+	hint: "needs the club mailbox sign-in for draft and send",
+	subcommands: [
+		{
+			name: "render",
+			envFree: true,
+			summary: "Write an issue as .eml and .html files.",
+			hint: "writes files only",
+			options: [{
+				flag: "--format",
+				value: "<eml,html>",
+				summary: "Which files. Defaults to both.",
+				prompt: {
+					kind: "select",
+					message: "Which files?",
+					choices: [
+						{
+							value: "eml,html",
+							label: "Both"
+						},
+						{
+							value: "eml",
+							label: "Outlook draft (.eml)"
+						},
+						{
+							value: "html",
+							label: "HTML preview"
+						}
+					]
+				}
+			}, {
+				flag: "--out",
+				value: "<dir>",
+				summary: "Directory for the files. Defaults to ./changelog-exports.",
+				prompt: {
+					kind: "text",
+					message: "Where should the files go?",
+					placeholder: "./changelog-exports",
+					optional: true
+				}
+			}]
+		},
+		{
+			name: "draft",
+			envFree: true,
+			summary: "Append an issue to the club mailbox's Drafts.",
+			hint: "review it in any Outlook"
+		},
+		{
+			name: "send",
+			envFree: true,
+			summary: "Send an issue from the club mailbox, as authored.",
+			hint: "asks first, naming the issue and every recipient",
+			options: [{
+				flag: "--to",
+				value: "<a@…,b@…>",
+				summary: "Recipients, comma-separated. Required; there is no default.",
+				prompt: {
+					kind: "text",
+					message: "Who should receive it? (comma-separated addresses)"
+				}
+			}, YES]
+		}
+	]
+};
+//#endregion
+//#region src/planner/catalog.ts
+/**
+* `planner`'s place in the command tree: declaration only, nothing here
+* runs. The handler lives in `commands.ts` beside it. Production-only: the
+* role it manages exists for the deploy pipeline's preflight tier.
+*/
+const DB_URL = {
+	flag: "--db-url",
+	value: "<url>",
+	summary: "Privileged connection. Defaults to .env.production's DB_URL.",
+	prompt: {
+		kind: "text",
+		message: "Connection URL? (blank uses .env.production's DB_URL)",
+		optional: true
+	}
+};
+const plannerCommand = {
+	name: "planner",
+	summary: "The migration_planner role the preflight tier may hold.",
+	hint: "needs the production database",
+	subcommands: [
+		{
+			name: "status",
+			dryRun: "read-only",
+			summary: "Can the preflight credential reach more than it should; the role's shape.",
+			hint: "reads only — start here; CI runs it with --no-env",
+			options: [DB_URL, JSON_FLAG]
+		},
+		{
+			name: "create",
+			summary: "Mint the role, verify it live, write .env.preflight.",
+			options: [DB_URL]
+		},
+		{
+			name: "reset-password",
+			summary: "Rotate the password. There is no retrieve.",
+			options: [DB_URL, YES]
+		},
+		{
+			name: "drop",
+			summary: "Remove the role and blank the dead URL.",
+			hint: "the recovery path",
+			options: [DB_URL, YES]
+		}
+	]
+};
+//#endregion
+//#region src/qr/catalog.ts
+const qrCommand = {
+	name: "qr",
+	dryRun: "handled",
+	envFree: true,
+	summary: "Make a QR code: any size, colour, logo and format.",
+	hint: "same options as /console/qr; svg, png, jpg, webp, avif, tiff",
+	options: [...qrCatalogOptions(), {
+		flag: "--dry-run",
+		summary: "List the files that would be written, and write nothing."
+	}]
+};
+const catalog = createCatalog({
+	usage: "pnpm backstage",
+	commonTasks: [
+		["env pull --target production", "Fill .env.production from the vault"],
+		["env audit --target production", "Compare every store, list orphans"],
+		["deploy platform --tier staging", "Deploy an app"],
+		["planner status", "Check the preflight credential"],
+		["graphics 'event/*' --out ~/images", "Render event images"],
+		["qr https://devdogsuga.org --format svg,png", "Make a QR code"]
+	],
+	groups: [
+		{
+			title: "Production deploys",
+			commands: [deployCommand]
+		},
+		{
+			title: "Secrets & environments",
+			commands: [envCommand]
+		},
+		{
+			title: "Database roles",
+			commands: [plannerCommand]
+		},
+		{
+			title: "Graphics & QR codes (no credentials)",
+			commands: [graphicsCommand, qrCommand]
+		},
+		{
+			title: "Your own sign-in (gh login, club mailbox)",
+			commands: [githubCommand, newsletterCommand]
+		},
+		{
+			title: "CLI utilities",
+			commands: [completionsCommand]
+		}
+	]
+});
+//#endregion
+export { repoPeerUrl as _, recordEnteredTier as a, renderHelp as b, setMenuEnvHook as c, formatCommand as d, nonEmpty as f, loadEnvSession as g, loadEnvLoad as h, beginInvocation as i, dbPush as l, loadEnv as m, bareGroupStartPath as n, recordResolved as o, getEnvSync as p, runMenu as r, reproducibleCommand as s, catalog as t, dbPushDryRun as u, helpPath as v, renderCommandList as y };