@theholocron/cli 4.17.1 → 4.18.0

package/dist/cli.mjs

@@ -3,7 +3,7 @@ import { createRequire } from "node:module";
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import path, { basename, dirname, join, relative, resolve } from "node:path";
 import { checkbox, input, select } from "@inquirer/prompts";
-import { KNOWN_WORKFLOWS, createAstromech, extractPreviewConfig, reusableTemplates } from "@theholocron/astromech";
+import { KNOWN_WORKFLOWS, createAstromech, extractPreviewConfig, readWorkspacePackages, reusableTemplates } from "@theholocron/astromech";
 import { loadTasksConfig } from "@theholocron/astromech/config";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
@@ -14,7 +14,7 @@ import { pathToFileURL } from "node:url";
 import { createLogger, parseLogLevel, resolveAxiomFromEnv } from "@theholocron/observability/logger";
 import ora from "ora";
 import chalk from "chalk";
-import { execFile, execFileSync, spawnSync } from "node:child_process";
+import { execFile, execFileSync, spawn, spawnSync } from "node:child_process";
 import { homedir, hostname, userInfo } from "node:os";
 import { access, copyFile, mkdir, readFile, readdir, rm, stat, symlink, unlink, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
@@ -26,6 +26,7 @@ import { NoopAnalyticsSink, NoopErrorSink, redactObject } from "@theholocron/obs
 import { SentrySink } from "@theholocron/observability/errors";
 import { promisify } from "node:util";
 import { ConfigFileError, loadConfigFile } from "@theholocron/datapad";
+import search from "@inquirer/search";
 //#region src/env.ts
 /** Singleton env for simple global lookups throughout the CLI. */
 const env = createEnvLookup();
@@ -3570,86 +3571,6 @@ function createIgnoreConfig() {
 	return `${workflowHeader$6()}${alexignore_default}`;
 }
 //#endregion
-//#region src/templates/configs/codecov/codecov.yml
-var codecov_default = "codecov:\n  require_ci_to_pass: true\n\ncoverage:\n  precision: 2\n  round: down\n  status:\n    project:\n      default:\n        target: auto\n        threshold: 2%\n        # Infra-only PRs (dep bumps, config, lockfile) touch no coverable code,\n        # so codecov produces no report to compare. Pass instead of blocking\n        # forever on a required check that will never post.\n        if_not_found: success\n    patch:\n      default:\n        target: 80%\n        if_not_found: success\n\ncomment:\n  layout: \"reach,diff,flags,components\"\n  behavior: default\n  require_changes: true\n\ncomponent_management:\n  default_rules:\n    statuses:\n      - type: patch\n        target: 80%\n        if_not_found: success\n  individual_components:\n";
-//#endregion
-//#region src/templates/configs/codecov/utils.ts
-const INDIVIDUAL_COMPONENTS_MARKER = "  individual_components:";
-function codecovComponentBlock(packages) {
-	if (packages.length === 0) return "\n    []\n";
-	return "\n" + packages.flatMap(({ slug }) => [
-		`    - component_id: ${slug}`,
-		`      name: "${slug}"`,
-		`      paths:`,
-		`        - packages/${slug}/**`,
-		``
-	]).join("\n");
-}
-/**
-* Ensure every codecov status default carries `if_not_found: success`, so an
-* infra-only PR (dep bump, config, lockfile — no coverable change) passes
-* instead of hanging forever on a required check codecov never posts.
-*
-* Injects the key on the line after each `target:` that sits inside a status
-* block (`coverage.status.*.default` or a `statuses:` list item — indent ≥ 8,
-* or ≥ 8 for a `- type:` list entry), when the immediate sibling lines do not
-* already declare it.
-*/
-function ensureIfNotFound(yaml) {
-	const lines = yaml.split("\n");
-	const out = [];
-	for (let i = 0; i < lines.length; i++) {
-		const line = lines[i];
-		out.push(line);
-		const m = /^(\s{8,})target:\s+\S+\s*$/.exec(line);
-		if (!m) continue;
-		const indent = m[1];
-		let alreadySet = false;
-		for (let j = i + 1; j < lines.length; j++) {
-			const sib = lines[j];
-			if (sib.trim() === "") continue;
-			const sibIndent = sib.match(/^\s*/)[0].length;
-			if (sibIndent < indent.length) break;
-			if (sibIndent === indent.length && /^\s*if_not_found\s*:/.test(sib)) {
-				alreadySet = true;
-				break;
-			}
-			if (sibIndent === indent.length && /^\s*(- |\w)/.test(sib) && !/^\s*(threshold|flags|paths|branches)\s*:/.test(sib)) break;
-		}
-		if (!alreadySet) out.push(`${indent}if_not_found: success`);
-	}
-	return out.join("\n");
-}
-function mergeCodecovComponents(existing, packages) {
-	const idx = existing.indexOf(INDIVIDUAL_COMPONENTS_MARKER);
-	if (idx === -1) return ensureIfNotFound(existing);
-	return ensureIfNotFound(existing.slice(0, idx + 24)) + codecovComponentBlock(packages);
-}
-async function readWorkspacePackages(repoRoot) {
-	const packagesDir = join(repoRoot, "packages");
-	const entries = await readdir(packagesDir, { withFileTypes: true }).catch(() => null);
-	if (!entries) return [];
-	const packages = [];
-	for (const entry of entries) {
-		if (!entry.isDirectory()) continue;
-		try {
-			const raw = await readFile(join(packagesDir, entry.name, "package.json"), "utf8");
-			const pkg = JSON.parse(raw);
-			if (typeof pkg.name === "string") packages.push({
-				slug: entry.name,
-				name: pkg.name
-			});
-		} catch {}
-	}
-	return packages.sort((a, b) => a.slug.localeCompare(b.slug));
-}
-//#endregion
-//#region src/templates/configs/codecov/create-config.ts
-const { scaffoldHeader } = createHeader({ source: "packages/cli/src/templates/configs/codecov/create-config.ts" });
-function createConfig$5(packages) {
-	return `${scaffoldHeader()}${codecov_default.trimEnd()}${codecovComponentBlock(packages)}`;
-}
-//#endregion
 //#region src/templates/configs/devmoji/create-config.ts
 const { workflowHeader: workflowHeader$5 } = createHeader({ source: "packages/cli/src/templates/configs/devmoji/create-config.ts" });
 function createConfig$4() {
@@ -4720,7 +4641,6 @@ async function runSetup(input) {
 		}
 		{
 			const hasTestWorkflow = (config.tasks ?? []).map((e) => typeof e === "string" ? e : e.name).includes("test");
-			const packages = await readWorkspacePackages(input.context.repoRoot);
 			const existing = await readFile(join(input.context.repoRoot, "codecov.yml"), "utf8").catch(() => null);
 			if (!hasTestWorkflow && existing == null) steps.push({
 				capability: "source",
@@ -4729,9 +4649,10 @@ async function runSetup(input) {
 				message: "no test workflow configured"
 			});
 			else steps.push(await runStep("source", "write codecov.yml", dryRun, async () => {
-				const content = existing != null ? mergeCodecovComponents(existing, packages) : createConfig$5(packages);
+				const content = createAstromech({ cwd: input.context.repoRoot }).codecovConfig(existing);
 				await source.writeRepoFile("codecov.yml", content);
-				return packages.length > 0 ? `${packages.length} components` : "no components";
+				const packageCount = readWorkspacePackages(input.context.repoRoot).length;
+				return packageCount > 0 ? `${packageCount} components` : "no components";
 			}));
 			print(formatStep(steps[steps.length - 1]));
 		}
@@ -6958,6 +6879,350 @@ function parseGitRemoteUrl(url) {
 	if (sshMatch) return sshMatch[1];
 }
 //#endregion
+//#region src/interactive-menu.ts
+/**
+* The interactive fallback — replaces every "run --help to see commands"
+* dead end with a prompt. Three layers, all driven by {@link COMMAND_REGISTRY}:
+*
+*   1. `holocron` with no command      → searchable picker over every command
+*   2. a parent command with no sub    → `select()` over that group's commands
+*   3. a leaf command missing a        → `input()` / `select()` per positional
+*      required positional
+*
+* Layers 1–2 are driven from `cli.ts`'s `$0` handlers via {@link launchMenu}:
+* pick a command, prompt for its required positionals, then **spawn a fresh
+* `holocron <command> …` child process** (`stdio: "inherit"`) rather than
+* re-entering yargs' own parse pipeline — see the spec's "spawn vs re-parse"
+* section (theholocron/holocron#438) for why. Layer 3 is driven directly from
+* each leaf command's own handler in `cli.ts`, calling
+* {@link promptForPositionals} for just that one command — no spawn needed,
+* the handler already has everything else it needs.
+*
+* Every prompt is preceded by a `process.stdin.isTTY` check. A non-TTY run
+* (CI, a script, a pipe) throws {@link NonInteractiveError} instead of
+* hanging on `@inquirer/prompts` (which otherwise throws its own
+* `ExitPromptError` the moment stdin closes) — `cli.ts`'s `USER_FACING_ERRORS`
+* catch prints its message cleanly, restoring the old demandCommand-style
+* hard failure for non-interactive callers.
+*/
+/** Raised when a prompt is needed but stdin isn't a TTY — see the module doc. */
+var NonInteractiveError = class extends Error {
+	name = "NonInteractiveError";
+};
+const numeric = (value) => /^\d+$/.test(value) ? true : "enter a number";
+/**
+* The full command surface, hand-maintained in parallel with `cli.ts`'s
+* yargs registrations (this module does not introspect yargs at runtime).
+* `run <task>` is deliberately excluded — it's CI/scripting-oriented, and an
+* interactive prompt in front of it would work against that.
+*/
+const COMMAND_REGISTRY = [
+	{
+		name: "version",
+		description: "Print the CLI version",
+		positionals: []
+	},
+	{
+		name: "clone",
+		description: "Clone all repos in a GitHub org as siblings under a single directory",
+		positionals: []
+	},
+	{
+		name: "doctor",
+		description: "Load the config and run a smoke check against every provider",
+		positionals: []
+	},
+	{
+		name: "setup",
+		description: "Apply infra setup actions across every configured capability",
+		positionals: []
+	},
+	{
+		name: "secret set",
+		description: "Set a single secret via the configured `secrets` capability",
+		positionals: [{
+			key: "name",
+			message: "Secret name:",
+			type: "input"
+		}]
+	},
+	{
+		name: "secrets sync",
+		description: "Read a vault environment + fan KEY=VALUEs out to secrets + deployment env vars",
+		positionals: [{
+			key: "environmentId",
+			message: "Vault environment id:",
+			type: "input"
+		}]
+	},
+	{
+		name: "deploy",
+		description: "Trigger a deployment via the configured `deployment` capability",
+		positionals: [{
+			key: "branch",
+			message: "Branch to deploy:",
+			type: "input"
+		}]
+	},
+	{
+		name: "cleanup-preview",
+		description: "List and delete Cloudflare Pages preview deployments for a GitHub PR",
+		positionals: [{
+			key: "pr",
+			message: "PR number:",
+			type: "input",
+			validate: numeric
+		}]
+	},
+	{
+		name: "bump-versions",
+		description: "Bump all non-private package versions in lockstep (semantic-release prepareCmd)",
+		positionals: [{
+			key: "newVersion",
+			cliArg: "new-version",
+			message: "New version:",
+			type: "input"
+		}]
+	},
+	{
+		name: "publish",
+		description: "Publish @theholocron/* packages to npm",
+		positionals: []
+	},
+	{
+		name: "sync",
+		description: "Sync state from config to the provider and local files (labels, properties, teams, topics, keywords, description, homepage, readme, workflows, scripts, wiki)",
+		positionals: []
+	},
+	{
+		name: "ci",
+		description: "Run the merge-gating checks locally, in CI order — 'will CI pass?'",
+		positionals: []
+	},
+	{
+		name: "sync-github",
+		description: "Sync workflow templates and composite actions to theholocron/.github",
+		positionals: []
+	},
+	{
+		name: "sync-readme",
+		description: "Sync the Installation + Usage block in README.md from package.json",
+		positionals: []
+	},
+	{
+		name: "config show",
+		description: "Print the resolved holocron config",
+		positionals: []
+	},
+	{
+		name: "new",
+		description: "Scaffold a new repo from a GitHub template (e.g. cli, react, nextjs, node, monorepo, base)",
+		positionals: []
+	},
+	{
+		name: "plugin create",
+		description: "Scaffold a new @theholocron/holocron-plugin-<slug> package",
+		positionals: [{
+			key: "slug",
+			message: "Package slug (kebab-case):",
+			type: "input"
+		}, {
+			key: "vendor",
+			message: "Vendor display name (PascalCase):",
+			type: "input"
+		}]
+	},
+	{
+		name: "skills install",
+		description: "Copy skills from @theholocron/skills into .agents/ with agent symlinks",
+		positionals: [],
+		group: "skills"
+	},
+	{
+		name: "skills remove",
+		description: "Remove installed skills via npx skills remove",
+		positionals: [],
+		group: "skills"
+	},
+	{
+		name: "skills update",
+		description: "Update installed skills to their latest upstream versions via npx skills update",
+		positionals: [],
+		group: "skills"
+	},
+	{
+		name: "upgrade node",
+		description: "Scan the repo and update every Node.js version pin to a new major",
+		positionals: [{
+			key: "to",
+			message: "Target Node.js major version:",
+			type: "input",
+			validate: numeric
+		}],
+		group: "upgrade"
+	},
+	{
+		name: "upgrade deps",
+		description: "Bump every @theholocron/* pin to latest and migrate holocron.config.ts to the current preset API",
+		positionals: [],
+		group: "upgrade"
+	},
+	{
+		name: "auth set",
+		description: "Verify + store a bootstrap token for a provider",
+		positionals: [{
+			key: "provider",
+			message: "Provider name:",
+			type: "input"
+		}],
+		group: "auth"
+	},
+	{
+		name: "auth unset",
+		description: "Remove a stored bootstrap token",
+		positionals: [{
+			key: "provider",
+			message: "Provider:",
+			type: "select",
+			choices: listStoredProviders
+		}],
+		group: "auth"
+	},
+	{
+		name: "auth check",
+		description: "Re-verify a stored bootstrap token",
+		positionals: [{
+			key: "provider",
+			message: "Provider:",
+			type: "select",
+			choices: listStoredProviders
+		}],
+		group: "auth"
+	},
+	{
+		name: "auth list",
+		description: "List every provider with a stored bootstrap token",
+		positionals: [],
+		group: "auth"
+	}
+];
+/** Look up a {@link CommandEntry} by its full name — for Layer 3 call sites in `cli.ts`. */
+function getEntry(name) {
+	const entry = COMMAND_REGISTRY.find((e) => e.name === name);
+	if (!entry) throw new Error(`interactive-menu: no COMMAND_REGISTRY entry named "${name}"`);
+	return entry;
+}
+/**
+* Searchable autocomplete over `entries` — the Layer 1 top-level picker, and
+* (passed a `group`-filtered subset) the Layer 2 parent-command picker.
+* `select()` would work too at these list sizes, but `search()` degrades
+* gracefully as the surface grows and costs nothing when it doesn't.
+*/
+async function pickCommand(entries, message = "What would you like to do?") {
+	const byName = new Map(entries.map((e) => [e.name, e]));
+	const picked = await search({
+		message,
+		source: (term) => searchChoices(entries, term)
+	});
+	return byName.get(picked);
+}
+/**
+* `@inquirer/search`'s `source` callback, factored out as a plain function —
+* unit-testable directly instead of only through a mocked `search()` call.
+* Empty/undefined `term` (nothing typed yet) returns every entry.
+*/
+function searchChoices(entries, term) {
+	return (!term ? entries : entries.filter((e) => matches(e, term))).map((e) => ({
+		name: e.name,
+		value: e.name,
+		description: e.description
+	}));
+}
+function matches(entry, term) {
+	const needle = term.toLowerCase();
+	return entry.name.toLowerCase().includes(needle) || entry.description.toLowerCase().includes(needle);
+}
+/**
+* For each of `entry.positionals` not already present in `argv`, prompts for
+* it (`input()` or `select()`, per the positional's `type`) and returns the
+* resolved values in positional order — ready to append to a spawned child's
+* argv, or to use directly in the current handler (Layer 3).
+*
+* Throws {@link NonInteractiveError} the first time it would need to prompt
+* on a non-TTY stdin, and again if a `select` positional's choices resolve
+* empty (nothing to pick from — e.g. `auth unset` with no stored tokens).
+*/
+async function promptForPositionals(entry, argv) {
+	const out = [];
+	for (const positional of entry.positionals) {
+		const existing = argv[positional.key];
+		if (existing !== void 0 && existing !== "") {
+			out.push(String(existing));
+			continue;
+		}
+		if (!process.stdin.isTTY) throw new NonInteractiveError(`\`${entry.name}\` needs "${positional.key}" — pass it directly: holocron ${entry.name} <${positional.cliArg ?? positional.key}>`);
+		if (positional.type === "select") {
+			const choices = typeof positional.choices === "function" ? positional.choices() : positional.choices ?? [];
+			if (choices.length === 0) throw new NonInteractiveError(`\`${entry.name}\`: no ${positional.key} to choose from — nothing stored yet`);
+			out.push(await select({
+				message: positional.message,
+				choices: choices.map((c) => ({ value: c }))
+			}));
+		} else out.push(await input({
+			message: positional.message,
+			...positional.validate ? { validate: positional.validate } : {}
+		}));
+	}
+	return out;
+}
+/**
+* `--token` (repeatable), `--org`, `--cwd`, `--dry-run` — the global flags a
+* menu-launched child should inherit from the parent invocation. Everything
+* else (command-specific options) was never captured by the top-level `$0`
+* handler in the first place, so there's nothing else to forward.
+*/
+function forwardedFlags(argv) {
+	const out = [];
+	const tokens = argv.token;
+	for (const t of tokens ?? []) out.push("--token", t);
+	if (typeof argv.org === "string") out.push("--org", argv.org);
+	if (typeof argv.cwd === "string") out.push("--cwd", argv.cwd);
+	if (argv.dryRun === true) out.push("--dry-run");
+	return out;
+}
+/** `entry.name` split into tokens, resolved positionals appended, then forwarded flags. */
+function buildChildArgv(entry, positionals, parentArgv) {
+	return [
+		...entry.name.split(" "),
+		...positionals,
+		...forwardedFlags(parentArgv)
+	];
+}
+/** Spawn `holocron <...args>` inheriting stdio; resolve with its exit code. */
+function spawnChild(args) {
+	return new Promise((resolve) => {
+		const child = spawn(process.execPath, [process.argv[1], ...args], { stdio: "inherit" });
+		child.on("exit", (code) => resolve(code ?? 0));
+		child.on("error", () => resolve(1));
+	});
+}
+/**
+* Layers 1 and 2: pick a command from `entries`, prompt for its required
+* positionals, spawn it as a fresh `holocron` invocation, and set
+* `process.exitCode` from the child — the caller (a `$0` handler in
+* `cli.ts`) returns normally afterward so the parent's own telemetry
+* flush / update-notifier tail still runs. The parent's own
+* `command_completed` event fires with command name "unknown" (the
+* middleware ran before any command was picked) — left as-is rather than
+* suppressed; it's a real, useful signal ("the menu got used").
+*/
+async function launchMenu(entries, parentArgv, pickMessage, nonInteractiveMessage = "Run `holocron --help` to see available commands.") {
+	if (!process.stdin.isTTY) throw new NonInteractiveError(nonInteractiveMessage);
+	const picked = await pickCommand(entries, pickMessage);
+	const childArgv = buildChildArgv(picked, await promptForPositionals(picked, {}), parentArgv);
+	process.exitCode = await spawnChild(childArgv);
+}
+//#endregion
 //#region src/update-notifier.ts
 const PACKAGE_NAME = "@theholocron/cli";
 const CACHE_TTL_MS = 1440 * 60 * 1e3;
@@ -7083,7 +7348,11 @@ const resolveSyncToken = createFeatureResolver({
 * Error class names whose `.message` is a complete, actionable sentence —
 * the top-level catch prints it and suppresses the stack trace.
 */
-const USER_FACING_ERRORS = /* @__PURE__ */ new Set(["WorkspaceContextError", "ConfigFileError"]);
+const USER_FACING_ERRORS = /* @__PURE__ */ new Set([
+	"WorkspaceContextError",
+	"ConfigFileError",
+	"NonInteractiveError"
+]);
 const { version: CLI_VERSION } = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
 /** Whether to print the correlation id at command end (`--debug` / `--verbose`). */
 let printRunId = false;
@@ -7271,9 +7540,10 @@ try {
 			},
 			...argv.name ? { name: argv.name } : {}
 		}).status === "fail") process.exitCode = 1;
-	}).demandCommand(1, "Run `holocron skills --help` to see available skills subcommands."), () => {}).command("secret set <name> [value]", "Set a single secret via the configured `secrets` capability", (y) => y.positional("name", {
+	}).command("$0", false, () => {}, async (argv) => {
+		await launchMenu(COMMAND_REGISTRY.filter((e) => e.group === "skills"), argv, "skills — choose a subcommand:", "Run `holocron skills --help` to see available skills subcommands.");
+	}), () => {}).command("secret set [name] [value]", "Set a single secret via the configured `secrets` capability", (y) => y.positional("name", {
 		type: "string",
-		demandOption: true,
 		describe: "Secret name (e.g., NPM_TOKEN)"
 	}).positional("value", {
 		type: "string",
@@ -7292,6 +7562,7 @@ try {
 	}), async (argv) => {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
+		const [name] = await promptForPositionals(getEntry("secret set"), argv);
 		const scopeArg = argv.scope;
 		const scope = parseScope(scopeArg);
 		const loaded = await loadConfig(argv.cwd);
@@ -7304,15 +7575,14 @@ try {
 				...tokens,
 				org: resolveOrg(argv, loaded.resolved)
 			},
-			name: argv.name,
+			name,
 			...argv.value ? { value: argv.value } : {},
 			...argv.fromStdin ? { fromStdin: true } : {},
 			...argv.fromEnv ? { fromEnv: argv.fromEnv } : {},
 			scope
 		})).status === "fail") process.exitCode = 1;
-	}).command("secrets sync <environmentId>", "Read a vault environment + fan KEY=VALUEs out to secrets + deployment env vars", (y) => y.positional("environmentId", {
+	}).command("secrets sync [environmentId]", "Read a vault environment + fan KEY=VALUEs out to secrets + deployment env vars", (y) => y.positional("environmentId", {
 		type: "string",
-		demandOption: true,
 		describe: "Vault environment id to read (1P Environment id, etc.)"
 	}).option("project-id", {
 		type: "string",
@@ -7324,6 +7594,7 @@ try {
 	}), async (argv) => {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
+		const [environmentId] = await promptForPositionals(getEntry("secrets sync"), argv);
 		const loaded = await loadConfig(argv.cwd);
 		applyResolvedConfig(argv, loaded.resolved);
 		if ((await runSecretsSync({
@@ -7334,13 +7605,12 @@ try {
 				...tokens,
 				org: resolveOrg(argv, loaded.resolved)
 			},
-			environmentId: argv.environmentId,
+			environmentId,
 			...argv.projectId ? { projectId: argv.projectId } : {},
 			targets: argv.target
 		})).summary.fail > 0) process.exitCode = 1;
-	}).command("deploy <branch>", "Trigger a deployment via the configured `deployment` capability", (y) => y.positional("branch", {
+	}).command("deploy [branch]", "Trigger a deployment via the configured `deployment` capability", (y) => y.positional("branch", {
 		type: "string",
-		demandOption: true,
 		describe: "Git branch to deploy"
 	}).option("project-id", {
 		type: "string",
@@ -7353,6 +7623,7 @@ try {
 	}), async (argv) => {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
+		const [branch] = await promptForPositionals(getEntry("deploy"), argv);
 		const loaded = await loadConfig(argv.cwd);
 		applyResolvedConfig(argv, loaded.resolved);
 		if ((await runDeploy({
@@ -7364,12 +7635,11 @@ try {
 				org: resolveOrg(argv, loaded.resolved)
 			},
 			projectId: argv.projectId,
-			branch: argv.branch,
+			branch,
 			...argv.target ? { target: argv.target } : {}
 		})).status === "fail") process.exitCode = 1;
-	}).command("cleanup-preview <pr>", "List and delete Cloudflare Pages preview deployments for a GitHub PR", (y) => y.positional("pr", {
+	}).command("cleanup-preview [pr]", "List and delete Cloudflare Pages preview deployments for a GitHub PR", (y) => y.positional("pr", {
 		type: "number",
-		demandOption: true,
 		describe: "PR number to clean up"
 	}).option("project", {
 		type: "string",
@@ -7381,6 +7651,7 @@ try {
 	}), async (argv) => {
 		const tokens = tokenContext(argv.token);
 		if (!tokens) return;
+		const [pr] = await promptForPositionals(getEntry("cleanup-preview"), argv);
 		const loaded = await loadConfig(argv.cwd);
 		applyResolvedConfig(argv, loaded.resolved);
 		if ((await runCleanupPreview({
@@ -7391,17 +7662,17 @@ try {
 				...tokens,
 				org: resolveOrg(argv, loaded.resolved)
 			},
-			prNumber: argv.pr,
+			prNumber: Number(pr),
 			project: argv.project,
 			...argv.repo ? { repo: argv.repo } : {}
 		})).status === "fail") process.exitCode = 1;
-	}).command("bump-versions <new-version>", "Bump all non-private package versions in lockstep (semantic-release prepareCmd)", (y) => y.positional("new-version", {
+	}).command("bump-versions [new-version]", "Bump all non-private package versions in lockstep (semantic-release prepareCmd)", (y) => y.positional("new-version", {
 		type: "string",
-		demandOption: true,
 		describe: "Version to set (e.g., 4.2.0 or 2.0.0-alpha.1)"
 	}), async (argv) => {
+		const [newVersion] = await promptForPositionals(getEntry("bump-versions"), argv);
 		if ((await runNpmBumpVersions({
-			version: argv.newVersion,
+			version: newVersion,
 			cwd: argv.cwd,
 			dryRun: argv.dryRun
 		})).status === "fail") process.exitCode = 1;
@@ -7824,13 +8095,11 @@ try {
 			}
 			throw err;
 		}
-	}).command("plugin create <slug> <vendor>", "Scaffold a new @theholocron/holocron-plugin-<slug> package", (y) => y.positional("slug", {
+	}).command("plugin create [slug] [vendor]", "Scaffold a new @theholocron/holocron-plugin-<slug> package", (y) => y.positional("slug", {
 		type: "string",
-		demandOption: true,
 		describe: "Package slug (kebab-case)"
 	}).positional("vendor", {
 		type: "string",
-		demandOption: true,
 		describe: "Vendor display name (PascalCase)"
 	}).option("capability", {
 		type: "string",
@@ -7850,7 +8119,7 @@ try {
 		describe: "Run post-scaffold pnpm install + typecheck + lint + test (default true; --no-verify skips)"
 	}), async (argv) => {
 		try {
-			const vendor = argv.vendor;
+			const [slug, vendor] = await promptForPositionals(getEntry("plugin create"), argv);
 			const { capability, vendorEnv, baseUrl } = await resolvePluginCreateInputs({
 				capability: argv.capability,
 				vendorEnv: argv.vendorEnv,
@@ -7867,7 +8136,7 @@ try {
 				inputBaseUrl: () => input({ message: `REST base URL for the ${vendor} API (e.g. https://api.myvendor.com):` })
 			});
 			if (runPluginCreate({
-				slug: argv.slug,
+				slug,
 				vendorName: vendor,
 				capability,
 				vendorEnv,
@@ -7885,14 +8154,14 @@ try {
 			}
 			throw err;
 		}
-	}).command("upgrade", "Upgrade toolchain version pins across the repo", (y) => y.command("node <to>", "Scan the repo and update every Node.js version pin to a new major", (yy) => yy.positional("to", {
+	}).command("upgrade", "Upgrade toolchain version pins across the repo", (y) => y.command("node [to]", "Scan the repo and update every Node.js version pin to a new major", (yy) => yy.positional("to", {
 		type: "number",
-		demandOption: true,
 		describe: "Target Node.js major version (e.g., 22)"
 	}).option("from", {
 		type: "number",
 		describe: "Current major version to replace. Auto-detected from .nvmrc / engines.node when omitted."
 	}), async (argv) => {
+		const [to] = await promptForPositionals(getEntry("upgrade node"), argv);
 		let extra = [];
 		try {
 			const raw = readFileSync(join(argv.cwd, "holocron.config.json"), "utf8");
@@ -7900,7 +8169,7 @@ try {
 			if (Array.isArray(extraRaw)) extra = extraRaw;
 		} catch {}
 		const report = await runUpgradeNode({
-			to: argv.to,
+			to: Number(to),
 			...argv.from != null ? { from: argv.from } : {},
 			cwd: argv.cwd,
 			dryRun: argv.dryRun,
@@ -7924,31 +8193,31 @@ try {
 			if (report.message) getLogger().error(`upgrade deps: ${report.message}`);
 			process.exitCode = 1;
 		}
-	}).demandCommand(1, "Run `holocron upgrade --help` to see available upgrade subcommands."), () => {}).command("auth <subcommand>", "Manage bootstrap credentials in the OS keyring", (y) => y.command("set <provider> [value]", "Verify + store a bootstrap token for a provider", (yy) => yy.positional("provider", {
-		type: "string",
-		demandOption: true
-	}).positional("value", { type: "string" }), async (argv) => {
+	}).command("$0", false, () => {}, async (argv) => {
+		await launchMenu(COMMAND_REGISTRY.filter((e) => e.group === "upgrade"), argv, "upgrade — choose a subcommand:", "Run `holocron upgrade --help` to see available upgrade subcommands.");
+	}), () => {}).command("auth <subcommand>", "Manage bootstrap credentials in the OS keyring", (y) => y.command("set [provider] [value]", "Verify + store a bootstrap token for a provider", (yy) => yy.positional("provider", { type: "string" }).positional("value", { type: "string" }), async (argv) => {
+		const [provider] = await promptForPositionals(getEntry("auth set"), argv);
 		if ((await runAuthSet({
-			provider: argv.provider,
+			provider,
 			...argv.value ? { positional: argv.value } : {},
 			...argv.org ? { org: argv.org } : {}
 		})).status === "fail") process.exitCode = 1;
-	}).command("unset <provider>", "Remove a stored bootstrap token", (yy) => yy.positional("provider", {
-		type: "string",
-		demandOption: true
-	}), (argv) => {
-		runAuthUnset({ provider: argv.provider });
-	}).command("check <provider>", "Re-verify a stored bootstrap token", (yy) => yy.positional("provider", {
-		type: "string",
-		demandOption: true
-	}), async (argv) => {
+	}).command("unset [provider]", "Remove a stored bootstrap token", (yy) => yy.positional("provider", { type: "string" }), async (argv) => {
+		const [provider] = await promptForPositionals(getEntry("auth unset"), argv);
+		runAuthUnset({ provider });
+	}).command("check [provider]", "Re-verify a stored bootstrap token", (yy) => yy.positional("provider", { type: "string" }), async (argv) => {
+		const [provider] = await promptForPositionals(getEntry("auth check"), argv);
 		if ((await runAuthCheck({
-			provider: argv.provider,
+			provider,
 			...argv.org ? { org: argv.org } : {}
 		})).status === "fail") process.exitCode = 1;
 	}).command("list", "List every provider with a stored bootstrap token", () => {}, async () => {
 		await runAuthList();
-	}).demandCommand(1, "Run `holocron auth --help` to see available auth subcommands."), () => {}).demandCommand(1, "Run `holocron --help` to see available commands.").strict().help().epilogue(`Execution contexts:
+	}).command("$0", false, () => {}, async (argv) => {
+		await launchMenu(COMMAND_REGISTRY.filter((e) => e.group === "auth"), argv, "auth — choose a subcommand:", "Run `holocron auth --help` to see available auth subcommands.");
+	}), () => {}).command("$0", false, () => {}, async (argv) => {
+		await launchMenu(COMMAND_REGISTRY.filter((e) => !e.group), argv);
+	}).strict().help().epilogue(`Execution contexts:
   global      works from a bare 'npm i -g': ${commandsInContext("global").join(", ")}\n  repo-aware  needs ./holocron.config in cwd: ${commandsInContext("repo-aware").join(", ")}\n  workspace   also needs the plugin packages: ${commandsInContext("workspace").join(", ")}\n  https://theholocron.github.io/holocron/execution-contexts`).fail((msg, err) => {
 		if (err instanceof Error && USER_FACING_ERRORS.has(err.name)) {
 			captureException(err);