@devdogsuga/devtools 0.1.35 → 0.1.37

package/dist/{menu-DnqlX22U.js → menu-C7gh8v-s.js}

@@ -1,8 +1,8 @@
-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 { c as YES, d as positionals, i as suppressFailureLog, l as createCatalog, o as JSON_FLAG, s as SCOPES } from "./failure-log-B5GG_8T1.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-B7JMicl-.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-El7OainP.js";
+import { c as reportDevtoolsError, f as isNonInteractive } from "./telemetry-Do13RFhc.js";
 import { cancel, confirm, isCancel, log, note, select, text } from "@clack/prompts";
 import { existsSync } from "node:fs";
 import { writeFile } from "node:fs/promises";
@@ -78,15 +78,28 @@ function scopedBody(commands) {
 			open = command.scope;
 			lines.push(`${INDENT}${SCOPES[open].help}:`);
 		}
-		lines.push(`${INDENT.repeat(2)}${command.name.padEnd(width)}  ${command.summary}`);
+		lines.push(`${INDENT.repeat(2)}${command.name.padEnd(width)}  ${describe(command)}`);
 	}
 	return lines;
 }
 function optionRows(options) {
 	return options.map((option) => [optionLabel(option), option.summary]);
 }
+/** A command's summary as a list prints it, with what else it answers to. */
+function describe(command) {
+	const aliases = (command.aliases ?? []).map((alias) => alias.name);
+	const also = aliases.length > 0 ? ` (also: ${aliases.join(", ")})` : "";
+	const deprecated = command.deprecated ? " (deprecated)" : "";
+	return `${command.summary}${also}${deprecated}`;
+}
 function childRows(children) {
-	return children.map((child) => [child.name, child.deprecated ? `${child.summary} (deprecated)` : child.summary]);
+	return children.map((child) => [child.name, describe(child)]);
+}
+/** `cron` is `jobs --kind sync`, for a command page's alias line. */
+function aliasLine(node) {
+	const aliases = node.aliases ?? [];
+	if (aliases.length === 0) return void 0;
+	return `Also typed as ${aliases.map((alias) => alias.implies?.length ? `${alias.name} (${node.name} … ${alias.implies.join(" ")})` : alias.name).join(", ")}.`;
 }
 /** `pnpm devtools --help`: the groups, and nothing below them. */
 function renderRoot(catalog) {
@@ -121,6 +134,8 @@ function renderCommand(catalog, path, node) {
 		"",
 		node.summary
 	];
+	const also = aliasLine(node);
+	if (also) lines.push("", also);
 	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)));
@@ -137,8 +152,9 @@ function renderCommand(catalog, path, node) {
 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);
+	const canonical = catalog.canonicalPath(path);
+	if (!node || !canonical) return renderRoot(catalog);
+	return renderCommand(catalog, canonical, node);
 }
 /**
 * The command names in `argv` that precede any flag.
@@ -175,7 +191,8 @@ function commandList(catalog) {
 				path: path.join(" "),
 				summary: node.summary,
 				surface: cliOnly ? "cli-only" : "interactive",
-				...node.deprecated ? { deprecated: node.deprecated } : {}
+				...node.deprecated ? { deprecated: node.deprecated } : {},
+				...node.aliases?.length ? { aliases: node.aliases.map((alias) => alias.name) } : {}
 			});
 			visit(node.subcommands ?? [], path, cliOnly);
 		}
@@ -254,73 +271,10 @@ const checkCommand = {
 	]
 };
 //#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",
+	title: "Troubleshoot my setup",
 	dryRun: "read-only",
 	summary: "Check this machine's environment against what the repo needs.",
 	hint: "node, pnpm, Docker, .env, hosted Supabase, OAuth — read-only",
@@ -335,7 +289,9 @@ const doctorCommand = {
 };
 const envCommand = {
 	name: "env",
+	title: "Manage local env files",
 	summary: "Create, regenerate and clear the local env files.",
+	hint: "create, regenerate or clear .env files",
 	subcommands: [
 		{
 			name: "init",
@@ -400,6 +356,129 @@ const envCommand = {
 	]
 };
 //#endregion
+//#region src/jobs/catalog.ts
+/**
+* `jobs`' place in the command tree: declaration only, nothing here runs.
+* The handler lives in `commands.ts` beside it.
+*
+* One command for both kinds of background job an app runs on Cloudflare:
+* quick syncs (cron triggers that call a route) and long-running jobs
+* (Workflows). They used to be the separate `cron` and `workflows` commands,
+* which asked a contributor to know how a job is built before they could run
+* it. Both names stay, as aliases that narrow `jobs` to their own kind, so
+* every existing `cron run` and `workflows serve` keeps working.
+*/
+/**
+* Narrows `run` and `list` to one kind. What the `cron` and `workflows`
+* aliases stand for, and promptless: the picker's headings already split the
+* two kinds, so a wizard question in front of it would ask the same thing
+* twice.
+*/
+const KIND = {
+	flag: "--kind",
+	value: "<k>",
+	summary: "sync or long-running. Both when absent."
+};
+const APP = {
+	flag: "--app",
+	value: "<slug>",
+	summary: "Limit to one app."
+};
+const PORT = {
+	flag: "--port",
+	value: "<n>",
+	summary: "Local Workflow runtime port. Defaults to 8787."
+};
+const jobsCommand = {
+	name: "jobs",
+	title: "Background jobs",
+	summary: "Run, list or serve the apps' cron syncs and Workflows.",
+	hint: "run one now, list them, or keep a Workflow runtime open",
+	aliases: [{
+		name: "cron",
+		implies: ["--kind", "sync"]
+	}, {
+		name: "workflows",
+		implies: ["--kind", "long-running"]
+	}],
+	subcommands: [
+		{
+			name: "run",
+			title: "Run a job now",
+			summary: "Choose a job and run it now on a tier.",
+			hint: "pick from the apps' Worker configuration",
+			options: [
+				{
+					...APP,
+					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: "Run this quick sync without opening the picker."
+				},
+				{
+					flag: "--workflow",
+					value: "<name>",
+					summary: "Run this long-running job without opening the picker."
+				},
+				{
+					flag: "--params",
+					value: "<json>",
+					summary: "JSON parameters passed to a Workflow instance."
+				},
+				PORT,
+				KIND,
+				YES
+			]
+		},
+		{
+			name: "list",
+			title: "List every job and when it runs",
+			dryRun: "read-only",
+			summary: "Every job, its schedule, and any schedule that never fires.",
+			hint: "the audit view",
+			options: [
+				APP,
+				{
+					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" }
+						]
+					}
+				},
+				KIND,
+				JSON_FLAG
+			]
+		},
+		{
+			name: "serve",
+			title: "Keep a local Workflow runtime open",
+			summary: "Run an app's Workflows locally until Ctrl+C, even via cron.",
+			hint: "secure alternative to bare wrangler dev",
+			options: [{
+				...APP,
+				summary: "Serve the development Workflows for this app."
+			}, PORT]
+		}
+	]
+};
+//#endregion
 //#region src/roles/catalog.ts
 /**
 * `roles`' place in the command tree: declaration only, nothing here runs.
@@ -411,6 +490,7 @@ const envCommand = {
 */
 const rolesCommand = {
 	name: "roles",
+	title: "Manage platform roles",
 	summary: "See who holds each role, and grant or revoke one.",
 	hint: "list, grant, revoke",
 	subcommands: [
@@ -437,6 +517,7 @@ const rolesCommand = {
 //#region src/oauth/catalog.ts
 const oauthCommand = {
 	name: "oauth",
+	title: "Set up \"Sign in with DevDogs\"",
 	summary: "Configure \"Sign in with DevDogs\" for this directory.",
 	hint: "works outside a DevDogsUGA checkout too",
 	envFree: true,
@@ -494,51 +575,54 @@ const psqlCommand = {
 //#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.
+* The Supabase jobs' places 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>`.
+* Each sequences several tool calls (or asks a question between them) and
+* prints the commands it ran. They were once subcommands of `preset`; now each
+* is a top-level command under its own name, so the menu's first screen can
+* offer them directly. `preset` is refused with the new name (`cli.ts`'s
+* `RETIRED`).
 */
-const presetCommand = {
-	name: "preset",
+const restartStackCommand = {
+	name: "restart-stack",
+	title: "Restart local Supabase",
 	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]
-		}
-	]
+	summary: "Restart the local Supabase stack.",
+	hint: "supabase stop, then start; picks up config.toml",
+	scope: "machine",
+	when: "instance-running"
+};
+const newMigrationCommand = {
+	name: "new-migration",
+	title: "Create a new migration",
+	dryRun: "handled",
+	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."
+	}]
+};
+const applyMigrationsCommand = {
+	name: "apply-migrations",
+	title: "Apply migrations to the database",
+	dryRun: "handled",
+	summary: "Apply new migrations to the session's database.",
+	hint: "supabase db push, then offers types:db",
+	scope: "endpoint",
+	options: [YES]
+};
+const pushConfigCommand = {
+	name: "push-config",
+	title: "Push Supabase settings",
+	dryRun: "handled",
+	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
@@ -550,7 +634,7 @@ const presetCommand = {
 * 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
+* not a question `run` asks itself elsewhere (unlike `jobs 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.
@@ -578,11 +662,10 @@ 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"]
+		["apply-migrations", "Push migrations, then offer types:db"],
+		["jobs run", "Choose and run a background job"]
 	],
 	groups: [
 		{
@@ -590,21 +673,25 @@ const catalog = createCatalog({
 			commands: [
 				{
 					name: "setup",
+					title: "Set up this checkout",
 					summary: "Check prerequisites and seed .env.",
 					hint: "run this first"
 				},
-				oauthCommand,
 				{
 					name: "script",
+					title: "Run a package script",
 					dryRun: "handled",
 					summary: "Pick a package, then one of its scripts, and run it.",
 					hint: "pnpm -F <package> run <script>"
 				},
+				oauthCommand,
+				doctorCommand,
 				{
 					name: "run",
 					dryRun: "handled",
 					summary: "Run a pnpm workspace task, asking which apps first.",
 					hint: "deprecated: pnpm -r run <task>",
+					surface: "cli-only",
 					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: [
 						{
@@ -642,84 +729,22 @@ const catalog = createCatalog({
 			]
 		},
 		{
-			title: "Runtime & infrastructure",
+			title: "Supabase",
 			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."
-							}]
-						}
-					]
-				}
+				restartStackCommand,
+				newMigrationCommand,
+				applyMigrationsCommand,
+				pushConfigCommand
 			]
 		},
+		{
+			title: "Background jobs",
+			commands: [jobsCommand]
+		},
+		{
+			title: "Configuration & integrations",
+			commands: [envCommand, rolesCommand]
+		},
 		{
 			title: "The real tools",
 			commands: [
@@ -729,14 +754,6 @@ const catalog = createCatalog({
 				psqlCommand
 			]
 		},
-		{
-			title: "Configuration & integrations",
-			commands: [envCommand, rolesCommand]
-		},
-		{
-			title: "Environment",
-			commands: [doctorCommand]
-		},
 		{
 			title: "CI & CLI utilities",
 			commands: [checkCommand, completionsCommand]
@@ -973,23 +990,31 @@ function realEnvEntryDeps(envLoad, envSession, startStack) {
 }
 /**
 * 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
+* start|stop|restart`, the `supabase start|stop` passthrough, and
+* `restart-stack`. 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";
+	return first === "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.
+* the ones that can fix it (`db`, `supabase`, the Supabase jobs), and whose
+* data commands re-check the connection themselves and say what is missing.
 */
+const STACK_OWNERS = /* @__PURE__ */ new Set([
+	"db",
+	"supabase",
+	"restart-stack",
+	"new-migration",
+	"apply-migrations",
+	"push-config"
+]);
 function ownsStack(argv) {
-	return argv[0] === "db" || argv[0] === "supabase" || argv[0] === "preset";
+	return argv[0] !== void 0 && STACK_OWNERS.has(argv[0]);
 }
 /**
 * Enters `tier` (and `devDatabase`'s overlay) for the current process,
@@ -1172,71 +1197,6 @@ async function resolveDbConnection(opts = {}) {
 	};
 }
 //#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.
@@ -1389,7 +1349,7 @@ function describeEnvironment(env) {
 * 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
+* `jobs 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
@@ -1445,13 +1405,22 @@ function recordResolved(...fragment) {
 	interactive = true;
 }
 /**
+* One argv token as a POSIX shell reads it back. A cron expression is the case
+* that forced this: `--cron 0 0 * * *` pasted unquoted is three stray words
+* and two globs.
+*/
+function shellQuote(token) {
+	if (/^[\w@%+=:,./-]+$/.test(token)) return token;
+	return `'${token.replaceAll("'", `'\\''`)}'`;
+}
+/**
 * 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(" ")}`;
+	return `pnpm devtools ${[...enteredTier ? ["--tier", enteredTier] : [], ...argv].map(shellQuote).join(" ")}`;
 }
 //#endregion
 //#region ../cli-core/src/menu.ts
@@ -1471,6 +1440,16 @@ function reproducibleCommand() {
 *
 * 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.
+*
+* ## One flat first screen
+*
+* The first screen lists every top-level command, in the catalog's order,
+* under its `title`: "Restart local Supabase" rather than `restart-stack`.
+* There used to be a screen of groups above it, which put a door between the
+* reader and every command and named the doors after how the CLI is built
+* rather than what the reader came to do. The command's real name rides in
+* the hint (`restart-stack · …`), so a walk still teaches what to type next
+* time. Aliases are never drawn: the menu builds an argv for a real command.
 */
 /** Chosen when a submenu should return to the screen above it. */
 const BACK = Symbol("back");
@@ -1495,39 +1474,38 @@ 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);
+/**
+* One command's entry on a screen: its title, with its real name leading the
+* hint so the reader learns what to type. A command with no title is labelled
+* by its name, which then has no reason to appear twice.
+*/
+function entryFor(node) {
+	return node.title ? {
+		label: node.title,
+		hint: `${node.name} · ${hintFor(node)}`
+	} : {
+		label: node.name,
+		hint: hintFor(node)
+	};
+}
+async function pickTopLevel(catalog, env) {
 	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(", ")
+		options: [...offered(catalog.topLevel, env).map((command) => ({
+			value: command,
+			...entryFor(command)
 		})), {
 			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}:`,
+		message: `${node.title ?? node.name}:`,
 		options: [...offered(node.subcommands ?? [], env).map((child) => ({
 			value: child,
-			label: child.name,
-			hint: hintFor(child)
+			...entryFor(child)
 		})), BACK_OPTION]
 	}));
 }
@@ -1573,7 +1551,7 @@ async function askOptions(node) {
 * 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
+* this once a top-level command is 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
@@ -1581,7 +1559,7 @@ async function askOptions(node) {
 * hidden is treated as the leaf it has become instead of opening a screen
 * holding only "Back".
 */
-async function descendFrom(start, pathNames, env) {
+async function descendFrom(start, pathNames, env, carried = []) {
 	let node = start;
 	const path = [...pathNames];
 	while (offered(node.subcommands ?? [], env).length > 0) {
@@ -1592,7 +1570,11 @@ async function descendFrom(start, pathNames, env) {
 	}
 	return {
 		node,
-		argv: [...path, ...await askOptions(node)]
+		argv: [
+			...path,
+			...await askOptions(node),
+			...carried
+		]
 	};
 }
 /**
@@ -1600,24 +1582,24 @@ async function descendFrom(start, pathNames, env) {
 * 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
+* — `["jobs"]` for `devtools jobs` — and lands here instead of at the first
+* screen. There is no screen above a resumed node (the caller already named
+* it by typing `jobs`), 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`.
+* the first screen. `startFlags` are the flags typed beside it, carried onto
+* the end of the argv the walk builds.
 */
-async function walk(catalog, env, startPath) {
+async function walk(catalog, env, startPath, startFlags = []) {
 	if (startPath) {
 		const start = catalog.findCommand(startPath);
-		if (!start) return null;
-		const chosen = await descendFrom(start, [...startPath], env);
+		const path = catalog.canonicalPath(startPath);
+		if (!start || !path) return null;
+		const chosen = await descendFrom(start, path, env, startFlags);
 		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 first = await pickTopLevel(catalog, env);
+		if (!first) return null;
 		const chosen = await descendFrom(first, [first.name], env);
 		if (chosen === BACK) continue;
 		return chosen;
@@ -1638,6 +1620,19 @@ function bareGroupStartPath(catalog, argv) {
 	return path;
 }
 /**
+* The flags in `argv` beside a bare group's `path`, for `runMenu`'s
+* `startFlags`: what `devtools jobs --kind sync` (or the `cron` alias that
+* stands for it) keeps once the wizard resumes at `jobs`.
+*/
+function bareGroupStartFlags(argv, path) {
+	const rest = [...argv];
+	for (const name of path) {
+		const at = rest.indexOf(name);
+		if (at !== -1) rest.splice(at, 1);
+	}
+	return rest;
+}
+/**
 * Runs the wizard, returning the `outro()` line its command earned.
 *
 * `dispatch` is the CLI's own argv handler, injected rather than imported so
@@ -1648,7 +1643,8 @@ function bareGroupStartPath(catalog, argv) {
 * from the command line.
 *
 * `options.startPath`, from `bareGroupStartPath`, skips straight to that
-* node's subcommand screen — see `walk`'s `startPath` branch.
+* node's subcommand screen — see `walk`'s `startPath` branch — and
+* `options.startFlags` (from `bareGroupStartFlags`) rides along to the end.
 *
 * 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
@@ -1670,7 +1666,7 @@ function bareGroupStartPath(catalog, argv) {
 */
 async function runMenu(catalog, dispatch, env = probeEnvironment(), options = {}) {
 	note(describeEnvironment(env), "This machine");
-	const chosen = await walk(catalog, env, options.startPath);
+	const chosen = await walk(catalog, env, options.startPath, options.startFlags);
 	if (!chosen) return null;
 	beginInvocation(chosen.argv, true);
 	const enteredTier = process.env.DEPLOY_ENV ?? "development";
@@ -1681,4 +1677,4 @@ async function runMenu(catalog, dispatch, env = probeEnvironment(), options = {}
 	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 };
+export { helpPath as C, catalog as S, renderHelp as T, bail as _, recordEnteredTier as a, explainError as b, describeEnvironment as c, resolveDbConnection as d, sessionIsLocal as f, setMenuEnvHook as g, realEnvEntryDeps as h, beginInvocation as i, probeEnvironment as l, enterSessionEnvironment as m, bareGroupStartPath as n, recordResolved as o, sessionLabel as p, runMenu as r, reproducibleCommand as s, bareGroupStartFlags as t, nonEmpty as u, errorMessage as v, renderCommandList as w, unwrap as x, explain as y };