@theholocron/kyber 5.0.0-alpha.340 → 5.0.0-alpha.342

package/dist/menu.d.mts

@@ -0,0 +1,200 @@
+import { c as OptionPrompt, p as MenuItem, r as PositionalPrompt, s as OptionMode, u as ResolvedOptions } from "./index-DpXxO_wH.mjs";
+/**
+ * One command in an interactive menu: how it is named, listed, prompted for and spawned. A CLI declares its
+ * whole surface as a list of these and hands it to {@link launchMenu}; kyber never knows which commands exist.
+ */
+interface MenuEntry {
+  /** Full command name as typed at the CLI, e.g. `"auth set"`. */
+  name: string;
+  /** One-liner, matches the yargs registration's description. */
+  description: string;
+  /** Required positionals only, in order. Empty when the command needs none. */
+  positionals: PositionalPrompt[];
+  /**
+   * This command's yargs options, offered through the menu
+   * (`promptForOptions`) — in declaration order, which also governs
+   * `when` evaluation order . Global flags
+   * (`--token`/`--org`/`--cwd`/`--dry-run`) are never listed here; those
+   * are inherited from the parent invocation via `forwardedFlags`
+   * regardless of this command. Ignored when `modes` is set.
+   */
+  options?: OptionPrompt[];
+  /**
+   * Mutually exclusive workflows — a mode is
+   * picked first ("What would you like to do?"), and only that mode's
+   * own options are then offered, so nothing contingent on a different
+   * mode is ever shown. Use this only when `options` would otherwise
+   * need `when` to express a real either/or relationship between them
+   * (`package publish`'s steady-state / `--initial` / `--sync-trust`);
+   * plain `options` stays the simpler default for everything else.
+   */
+  modes?: OptionMode[];
+  /**
+   * This command's yargs options deliberately NOT offered through the
+   * menu, with the reason recorded in review rather than in code — kept
+   * so a future drift test can tell "considered and skipped" apart from
+   * "never considered."
+   */
+  skipOptions?: string[];
+  /**
+   * Whether this command's handler honours the global `--dry-run` flag.
+   * Drives `launchMenu`'s dry-run offer: a menu-launched command with this
+   * set gets asked "run a dry run first?" (skipped if `--dry-run` was
+   * already passed at the top level) and, after a successful dry run,
+   * "proceed with the real run?". Hand-maintained in parallel with each
+   * handler's own `dryRun: argv.dryRun` usage.
+   */
+  supportsDryRun?: boolean;
+  /**
+   * What the menu shows for this entry when it is a plain leaf, instead of its last word. For a variant of
+   * its parent that is run with a flag (`doctor all` is `doctor --all`), so it reads as a choice beside
+   * `doctor (run it)`.
+   */
+  menuLabel?: string;
+  /** The command opens a menu of its own (`probe`): shown with the same " ›" as a group, though nothing is nested under it. */
+  opensMenu?: boolean;
+  /**
+   * Override for {@link buildChildArgv}: the real CLI argv tokens to spawn,
+   * when they don't match a naive space-split of `name`. Every static
+   * entry's `name` already *is* its own argv (`"repo upgrade node"` →
+   * `["repo", "upgrade", "node"]`, three real yargs tokens) — this exists
+   * for dynamically-built entries (a per-repo task list, say), whose
+   * `name` uses a space per namespace segment purely to get free nesting
+   * out of {@link menuItems} (`"run sourceQuality staticAnalysis"`), but
+   * whose real invocation is one dotted positional
+   * (`["run", "sourceQuality.staticAnalysis"]`), not three separate ones.
+   */
+  spawnArgs?: string[];
+}
+/**
+ * `entry.spawnArgs` if set, else `entry.name` split into tokens — resolved
+ * positionals, then non-secret option flags, then forwarded flags, appended
+ * in that order. `resolved` is whatever `promptForOptions` returned —
+ * for a `modes`-based command, that's already the picked mode's own options
+ * (plus a synthetic entry for its `flag`, if any), so this renders either
+ * shape identically with no need to know which kind of command it came from.
+ */
+export declare function buildChildArgv(entry: MenuEntry, positionals: string[], resolved: ResolvedOptions, parentArgv: Record<string, unknown>, dryRunOverride?: boolean): string[];
+/** How {@link launchMenu} is bound to one particular CLI. */
+interface LaunchMenuConfig {
+  /** The CLI's binary name, used in the default non-interactive hint (`Run \`<bin> --help\` …`). */
+  bin: string;
+  /**
+   * Upper-case prefix of the env vars the menu hands a spawned child: secret options travel as
+   * `<envPrefix>_<OPTION>` and a dry-run preview is flagged with `<envPrefix>_DRY_RUN_PREVIEW`.
+   */
+  envPrefix: string;
+  /** The question shown at the first level. Defaults to the picker's own default. */
+  pickMessage?: string;
+  /** The error shown when stdin is not a TTY. Defaults to ``Run `<bin> --help` to see available commands.`` */
+  nonInteractiveMessage?: string;
+  /** The group to open first, as words (`["repo"]`); `[]` (the default) opens the top level. */
+  startPath?: string[];
+}
+/**
+ * Walk the nested menu over `entries` (starting at `config.startPath`, `[]` for the top), prompt for the picked
+ * command's required positionals and options, spawn it as a fresh invocation of the running CLI, and set
+ * `process.exitCode` from the child — the caller (a `$0` handler) returns normally afterward so the parent's own
+ * telemetry flush / update-notifier tail still runs.
+ *
+ * Picking a group opens its submenu, which has a "← back" item; a command ends the walk. See {@link menuItems}
+ * for how a level is built. Throws {@link NonInteractiveError} when stdin is not a TTY.
+ *
+ * For a command that honours `--dry-run` ({@link MenuEntry.supportsDryRun}) and wasn't opted out via
+ * `--skip-dry-run` ({@link shouldPreviewDryRun}), this always previews first — a dry run doesn't mutate anything,
+ * so there's nothing to ask permission for. A preview that exits non-zero stops here; one that reports
+ * {@link DRY_RUN_NOOP_EXIT_CODE} (nothing would change) stops here too, skipping the follow-up question since the
+ * real run would have nothing to do either. Otherwise it asks "proceed with the real run?" before the real spawn.
+ *
+ * Secret options are never put in argv: they reach the child as `<envPrefix>_<OPTION>` env vars (see
+ * {@link secretEnv}), and a preview child additionally gets {@link dryRunPreviewEnvVar}.
+ *
+ * @param entries - The whole command surface, as data.
+ * @param parentArgv - The parsed argv of the invocation that opened the menu; its global flags are forwarded.
+ * @param config - Binds the menu to one CLI: its binary name, env prefix and optional messages.
+ */
+export declare function launchMenu(entries: MenuEntry[], parentArgv: Record<string, unknown>, config: LaunchMenuConfig): Promise<void>;
+/** The per-call knobs of a bound menu: everything in {@link LaunchMenuConfig} except what {@link createMenu} already fixed. */
+export type BoundMenuOptions = Omit<LaunchMenuConfig, "bin" | "envPrefix">;
+/** A menu engine bound to one CLI by {@link createMenu}. */
+export interface Menu {
+  /** {@link launchMenu} with the CLI's `bin` and `envPrefix` already applied. */
+  launchMenu: (entries: MenuEntry[], parentArgv: Record<string, unknown>, options?: BoundMenuOptions) => Promise<void>;
+  /** The env var a dry-run preview child gets (`<envPrefix>_DRY_RUN_PREVIEW`); see {@link dryRunPreviewEnvVar}. */
+  dryRunPreviewEnvVar: string;
+}
+/**
+ * Bind the menu engine to one CLI once, so callers stop repeating `bin` and `envPrefix`: the returned
+ * `launchMenu(entries, parentArgv, options?)` is {@link launchMenu} with both applied, and `dryRunPreviewEnvVar` is the
+ * matching env var name a dry-run preview child receives.
+ *
+ * @param binding - The CLI's binary name and env prefix.
+ */
+export declare function createMenu({ bin, envPrefix }: Pick<LaunchMenuConfig, "bin" | "envPrefix">): Menu;
+/**
+ * Reserved exit code a dry-run-capable handler may use — only when the
+ * {@link dryRunPreviewEnvVar} is set — to report "ran clean, nothing would
+ * change." {@link launchMenu} treats it as success but skips the "proceed with
+ * the real run?" question, since there's nothing for the real run to do
+ * either.
+ */
+export declare const DRY_RUN_NOOP_EXIT_CODE = 2;
+/**
+ * The env var {@link launchMenu} sets on a dry-run preview child (`<ENV_PREFIX>_DRY_RUN_PREVIEW`), so its
+ * handler knows this specific `--dry-run` came from the menu's own preview-then-ask flow, not a direct
+ * `<bin> <cmd> --dry-run` invocation. A handler that supports it uses this — never bare `argv.dryRun` — to
+ * decide whether to report {@link DRY_RUN_NOOP_EXIT_CODE}: that exit code only has special meaning to
+ * `launchMenu` itself, so a direct/scripted `--dry-run` call must never produce it — doing so unconditionally
+ * would silently change the public exit-code contract for a successful dry run.
+ */
+export declare function dryRunPreviewEnvVar(envPrefix: string): string;
+/**
+ * `--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.
+ *
+ * `dryRunOverride`, when passed, wins over `argv.dryRun` — {@link launchMenu}'s
+ * dry-run offer needs to force `--dry-run` on for the preview spawn and
+ * force it back off for the real-run spawn that follows, regardless of
+ * what was on the original invocation.
+ */
+export declare function forwardedFlags(argv: Record<string, unknown>, dryRunOverride?: boolean): string[];
+/** Prefix of a menu item's `value` that opens a submenu rather than running a command. */
+export declare const GROUP = "group:";
+/** The "← back" item's value; only offered below the first level. */
+export declare const BACK = "back";
+/**
+ * One level of the menu, derived from the registered command names: the next word
+ * of every entry under `path` (`[]` is the top). A word is
+ *
+ * - a **command** when nothing is nested under it (`doctor`);
+ * - a **group** when commands are nested under it (`repo` → `repo setup`, `repo sync`, …),
+ *   which can nest as deep as the names go (`repo upgrade` → `repo upgrade node`);
+ *
+ * Every row is a single word, never a "<command> <subcommand>" path: `config show` is
+ * `config ›` then `show`, even when a group holds just one command.
+ *
+ * A path that is itself runnable (`repo sync`, `deploy`) gets a leading "<word> (run it)" item.
+ * Registration order is kept.
+ */
+export declare function menuItems(entries: MenuEntry[], path?: string[]): MenuItem[];
+/**
+ * Secret option answers, keyed by the env var their handler reads instead
+ * of argv (`ps` and shell history expose argv, never a child's own env) —
+ * `<ENV_PREFIX>_<KEY_IN_SCREAMING_SNAKE_CASE>`, e.g. `otp` with prefix
+ * `MYCLI` → `MYCLI_OTP`. Merged into the spawn's extra env alongside
+ * `NO_UPDATE_NOTIFIER` and (for a preview spawn) the
+ * {@link dryRunPreviewEnvVar}.
+ */
+export declare function secretEnv(resolved: ResolvedOptions, envPrefix: string): Record<string, string>;
+/**
+ * Whether {@link launchMenu} should auto-preview a picked command before running
+ * it for real — only when the command's handler actually honours
+ * `--dry-run` ({@link MenuEntry.supportsDryRun}) and the top-level
+ * invocation didn't pass `--skip-dry-run` to opt out of the preview
+ * entirely (an escape hatch for "I already know what I want, skip
+ * straight to the real run").
+ */
+export declare function shouldPreviewDryRun(entry: MenuEntry, parentArgv: Record<string, unknown>): boolean;
+export type { LaunchMenuConfig, MenuEntry };

package/dist/menu.mjs

@@ -0,0 +1,322 @@
+import { t as NonInteractiveError } from "./non-interactive-error-Mm_Mn79M.mjs";
+import { pickMenuItem, promptForDeferredOptions, promptForOptions, promptForPositionals } from "./prompts.mjs";
+import { confirm } from "@inquirer/prompts";
+import { spawn } from "node:child_process";
+// src/menu/forwarded-flags/forwarded-flags.ts
+/**
+* `--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.
+*
+* `dryRunOverride`, when passed, wins over `argv.dryRun` — {@link launchMenu}'s
+* dry-run offer needs to force `--dry-run` on for the preview spawn and
+* force it back off for the real-run spawn that follows, regardless of
+* what was on the original invocation.
+*/
+function forwardedFlags(argv, dryRunOverride) {
+	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 (dryRunOverride ?? argv.dryRun === true) out.push("--dry-run");
+	return out;
+}
+// src/menu/is-secret-option/is-secret-option.ts
+/**
+* Whether `option`'s answer must be delivered via env, never argv — true for
+* an explicit `secret: true`, and also for any `type: "password"` option
+* even if `secret` was left unset. `promptForOptions` already treats these
+* two as interchangeable triggers for masking the input itself;
+* {@link buildChildArgv}/{@link secretEnv} need to agree, or a password-typed
+* option that forgot to also set `secret: true` would mask the keystrokes
+* on screen while still leaking the typed value into the child's argv.
+*/
+function isSecretOption(option) {
+	return Boolean(option.secret) || option.type === "password";
+}
+// src/menu/option-argv/option-argv.ts
+/**
+* `option`'s own argv tokens for `value` (never called for a `secret`
+* option — those are delivered via {@link secretEnv} instead, never argv).
+*
+* - boolean `true` → `--flag`; `false` → `--no-flag` when the yargs
+*   default is `true` (`negatable: true` — answering "no" must actively
+*   override it, not just omit the flag and silently keep the default),
+*   otherwise omitted (the yargs default is already `false`).
+* - string/select → `--flag value`, omitted when empty.
+* - `arity`-valued array → `--flag v1 v2 ...`.
+*/
+function optionArgv(option, value) {
+	if (value === void 0) return [];
+	if (typeof value === "boolean") {
+		if (value) return [option.flag];
+		return option.negatable ? [`--no-${option.flag.replace(/^--/, "")}`] : [];
+	}
+	if (Array.isArray(value)) return value.length === 0 ? [] : [option.flag, ...value];
+	return value === "" ? [] : [option.flag, value];
+}
+// src/menu/build-child-argv/build-child-argv.ts
+/**
+* `entry.spawnArgs` if set, else `entry.name` split into tokens — resolved
+* positionals, then non-secret option flags, then forwarded flags, appended
+* in that order. `resolved` is whatever `promptForOptions` returned —
+* for a `modes`-based command, that's already the picked mode's own options
+* (plus a synthetic entry for its `flag`, if any), so this renders either
+* shape identically with no need to know which kind of command it came from.
+*/
+function buildChildArgv(entry, positionals, resolved, parentArgv, dryRunOverride) {
+	const optionArgs = resolved.options.flatMap((option) => isSecretOption(option) ? [] : optionArgv(option, resolved.answers[option.key]));
+	return [
+		...entry.spawnArgs ?? entry.name.split(" "),
+		...positionals,
+		...optionArgs,
+		...forwardedFlags(parentArgv, dryRunOverride)
+	];
+}
+// src/menu/dry-run-preview-env-var/dry-run-preview-env-var.ts
+/**
+* The env var {@link launchMenu} sets on a dry-run preview child (`<ENV_PREFIX>_DRY_RUN_PREVIEW`), so its
+* handler knows this specific `--dry-run` came from the menu's own preview-then-ask flow, not a direct
+* `<bin> <cmd> --dry-run` invocation. A handler that supports it uses this — never bare `argv.dryRun` — to
+* decide whether to report {@link DRY_RUN_NOOP_EXIT_CODE}: that exit code only has special meaning to
+* `launchMenu` itself, so a direct/scripted `--dry-run` call must never produce it — doing so unconditionally
+* would silently change the public exit-code contract for a successful dry run.
+*/
+function dryRunPreviewEnvVar(envPrefix) {
+	return `${envPrefix}_DRY_RUN_PREVIEW`;
+}
+// src/menu/dry-run-noop-exit-code/dry-run-noop-exit-code.ts
+/**
+* Reserved exit code a dry-run-capable handler may use — only when the
+* {@link dryRunPreviewEnvVar} is set — to report "ran clean, nothing would
+* change." {@link launchMenu} treats it as success but skips the "proceed with
+* the real run?" question, since there's nothing for the real run to do
+* either.
+*/
+const DRY_RUN_NOOP_EXIT_CODE = 2;
+// src/menu/menu-items/menu-items.ts
+/** Prefix of a menu item's `value` that opens a submenu rather than running a command. */
+const GROUP = "group:";
+/** The "← back" item's value; only offered below the first level. */
+const BACK = "back";
+/**
+* One level of the menu, derived from the registered command names: the next word
+* of every entry under `path` (`[]` is the top). A word is
+*
+* - a **command** when nothing is nested under it (`doctor`);
+* - a **group** when commands are nested under it (`repo` → `repo setup`, `repo sync`, …),
+*   which can nest as deep as the names go (`repo upgrade` → `repo upgrade node`);
+*
+* Every row is a single word, never a "<command> <subcommand>" path: `config show` is
+* `config ›` then `show`, even when a group holds just one command.
+*
+* A path that is itself runnable (`repo sync`, `deploy`) gets a leading "<word> (run it)" item.
+* Registration order is kept.
+*/
+function menuItems(entries, path = []) {
+	const prefix = path.join(" ");
+	const own = prefix ? entries.find((e) => e.name === prefix) : void 0;
+	const under = prefix ? entries.filter((e) => e.name.startsWith(`${prefix} `)) : entries;
+	const haystackOf = (list) => list.map((e) => `${e.name} ${e.description}`.toLowerCase()).join(" ");
+	const items = [];
+	if (own) items.push({
+		name: `${path[path.length - 1]} (run it)`,
+		value: own.name,
+		description: own.description,
+		haystack: haystackOf([own])
+	});
+	const words = [...new Set(under.map((e) => e.name.split(" ")[path.length]))];
+	for (const word of words) {
+		const full = [...path, word].join(" ");
+		const family = under.filter((e) => e.name === full || e.name.startsWith(`${full} `));
+		const self = family.find((e) => e.name === full);
+		const nested = family.filter((e) => e.name !== full);
+		if (nested.length === 0 && self) items.push({
+			name: self.menuLabel ?? (self.opensMenu ? `${word} ›` : word),
+			value: full,
+			description: self.description,
+			haystack: haystackOf([self])
+		});
+		else {
+			const children = [...new Set(nested.map((e) => e.name.split(" ")[path.length + 1]))];
+			items.push({
+				name: `${word} ›`,
+				value: `${GROUP}${full}`,
+				description: children.join(", "),
+				haystack: haystackOf(family)
+			});
+		}
+	}
+	return items;
+}
+// src/menu/resolve-for-real-spawn/resolve-for-real-spawn.ts
+/**
+* Collects `resolved.deferred`'s values and folds them into
+* `resolved.answers` — call this once, right before building the real
+* (non-dry-run) spawn's argv, never any earlier: a dry-run preview and
+* a human confirming "proceed with the real run?" can both take a while,
+* and a time-sensitive secret (an OTP) typed before either risks going
+* stale before it's actually used. A no-op when nothing was deferred.
+*/
+async function resolveForRealSpawn(resolved) {
+	if (!resolved.deferred || resolved.deferred.length === 0) return resolved;
+	const deferredAnswers = await promptForDeferredOptions(resolved.deferred);
+	return {
+		...resolved,
+		answers: {
+			...resolved.answers,
+			...deferredAnswers
+		}
+	};
+}
+// src/menu/secret-env/secret-env.ts
+/**
+* Secret option answers, keyed by the env var their handler reads instead
+* of argv (`ps` and shell history expose argv, never a child's own env) —
+* `<ENV_PREFIX>_<KEY_IN_SCREAMING_SNAKE_CASE>`, e.g. `otp` with prefix
+* `MYCLI` → `MYCLI_OTP`. Merged into the spawn's extra env alongside
+* `NO_UPDATE_NOTIFIER` and (for a preview spawn) the
+* {@link dryRunPreviewEnvVar}.
+*/
+function secretEnv(resolved, envPrefix) {
+	const out = {};
+	for (const option of resolved.options) {
+		if (!isSecretOption(option)) continue;
+		const value = resolved.answers[option.key];
+		if (typeof value !== "string" || value === "") continue;
+		out[`${envPrefix}_${option.key.replace(/([A-Z])/g, "_$1").toUpperCase()}`] = value;
+	}
+	return out;
+}
+// src/menu/should-preview-dry-run/should-preview-dry-run.ts
+/**
+* Whether {@link launchMenu} should auto-preview a picked command before running
+* it for real — only when the command's handler actually honours
+* `--dry-run` ({@link MenuEntry.supportsDryRun}) and the top-level
+* invocation didn't pass `--skip-dry-run` to opt out of the preview
+* entirely (an escape hatch for "I already know what I want, skip
+* straight to the real run").
+*/
+function shouldPreviewDryRun(entry, parentArgv) {
+	return Boolean(entry.supportsDryRun) && parentArgv.skipDryRun !== true;
+}
+// src/menu/spawn-child/spawn-child.ts
+/**
+* Spawn the running CLI again with `args`, inheriting stdio; resolve with its exit code.
+*
+* `NO_UPDATE_NOTIFIER` is forced on in the child's env — the parent's own
+* update-notifier tail still runs after this resolves (see {@link launchMenu}),
+* so without this the freshly-spawned child independently runs its own
+* update check too and the notice prints twice: once from the child right
+* after its command output, once more from the parent once the child exits.
+* `extraEnv` layers on top — used for the {@link dryRunPreviewEnvVar} on the
+* dry-run preview spawn and for secret option answers.
+*/
+function spawnChild(args, extraEnv) {
+	return new Promise((resolve) => {
+		const child = spawn(process.execPath, [process.argv[1], ...args], {
+			stdio: "inherit",
+			env: {
+				...process.env,
+				NO_UPDATE_NOTIFIER: "1",
+				...extraEnv
+			}
+		});
+		child.on("exit", (code) => resolve(code ?? 0));
+		child.on("error", () => resolve(1));
+	});
+}
+// src/menu/launch-menu/launch-menu.ts
+/**
+* Walk the nested menu over `entries` (starting at `config.startPath`, `[]` for the top), prompt for the picked
+* command's required positionals and options, spawn it as a fresh invocation of the running CLI, and set
+* `process.exitCode` from the child — the caller (a `$0` handler) returns normally afterward so the parent's own
+* telemetry flush / update-notifier tail still runs.
+*
+* Picking a group opens its submenu, which has a "← back" item; a command ends the walk. See {@link menuItems}
+* for how a level is built. Throws {@link NonInteractiveError} when stdin is not a TTY.
+*
+* For a command that honours `--dry-run` ({@link MenuEntry.supportsDryRun}) and wasn't opted out via
+* `--skip-dry-run` ({@link shouldPreviewDryRun}), this always previews first — a dry run doesn't mutate anything,
+* so there's nothing to ask permission for. A preview that exits non-zero stops here; one that reports
+* {@link DRY_RUN_NOOP_EXIT_CODE} (nothing would change) stops here too, skipping the follow-up question since the
+* real run would have nothing to do either. Otherwise it asks "proceed with the real run?" before the real spawn.
+*
+* Secret options are never put in argv: they reach the child as `<envPrefix>_<OPTION>` env vars (see
+* {@link secretEnv}), and a preview child additionally gets {@link dryRunPreviewEnvVar}.
+*
+* @param entries - The whole command surface, as data.
+* @param parentArgv - The parsed argv of the invocation that opened the menu; its global flags are forwarded.
+* @param config - Binds the menu to one CLI: its binary name, env prefix and optional messages.
+*/
+async function launchMenu(entries, parentArgv, config) {
+	const { bin, envPrefix, pickMessage, nonInteractiveMessage = `Run \`${bin} --help\` to see available commands.`, startPath = [] } = config;
+	if (!process.stdin.isTTY) throw new NonInteractiveError(nonInteractiveMessage);
+	const stack = [startPath];
+	let picked;
+	while (!picked) {
+		const path = stack[stack.length - 1];
+		const items = menuItems(entries, path);
+		if (stack.length > 1) items.push({
+			name: "← back",
+			value: BACK,
+			description: "Return to the previous menu",
+			haystack: "back"
+		});
+		const message = stack.length === 1 ? pickMessage : `${path.join(" ")} — choose a subcommand:`;
+		const value = await pickMenuItem(items, message);
+		if (value === "back") stack.pop();
+		else if (value.startsWith("group:")) stack.push(value.slice(6).split(" "));
+		else picked = entries.find((e) => e.name === value);
+	}
+	const positionals = await promptForPositionals(picked, {});
+	const resolvedOptions = await promptForOptions(picked, {});
+	const extraEnv = secretEnv(resolvedOptions, envPrefix);
+	if (shouldPreviewDryRun(picked, parentArgv)) {
+		const dryExit = await spawnChild(buildChildArgv(picked, positionals, resolvedOptions, parentArgv, true), {
+			[dryRunPreviewEnvVar(envPrefix)]: "1",
+			...extraEnv
+		});
+		if (dryExit === 2) {
+			process.exitCode = 0;
+			return;
+		}
+		if (dryExit !== 0) {
+			process.exitCode = dryExit;
+			return;
+		}
+		if (!await confirm({
+			message: "Dry run complete — proceed with the real run?",
+			default: false
+		})) {
+			process.exitCode = 0;
+			return;
+		}
+		const forReal = await resolveForRealSpawn(resolvedOptions);
+		process.exitCode = await spawnChild(buildChildArgv(picked, positionals, forReal, parentArgv, false), secretEnv(forReal, envPrefix));
+		return;
+	}
+	const forReal = await resolveForRealSpawn(resolvedOptions);
+	process.exitCode = await spawnChild(buildChildArgv(picked, positionals, forReal, parentArgv), secretEnv(forReal, envPrefix));
+}
+// src/menu/create-menu/create-menu.ts
+/**
+* Bind the menu engine to one CLI once, so callers stop repeating `bin` and `envPrefix`: the returned
+* `launchMenu(entries, parentArgv, options?)` is {@link launchMenu} with both applied, and `dryRunPreviewEnvVar` is the
+* matching env var name a dry-run preview child receives.
+*
+* @param binding - The CLI's binary name and env prefix.
+*/
+function createMenu({ bin, envPrefix }) {
+	return {
+		launchMenu: (entries, parentArgv, options = {}) => launchMenu(entries, parentArgv, {
+			bin,
+			envPrefix,
+			...options
+		}),
+		dryRunPreviewEnvVar: dryRunPreviewEnvVar(envPrefix)
+	};
+}
+export { BACK, DRY_RUN_NOOP_EXIT_CODE, GROUP, buildChildArgv, createMenu, dryRunPreviewEnvVar, forwardedFlags, launchMenu, menuItems, secretEnv, shouldPreviewDryRun };

package/dist/notifier.mjs

@@ -1,6 +1,6 @@
+import chalk from "chalk";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import chalk from "chalk";
 // src/notifier/update-notifier/update-notifier.ts
 const CACHE_FILE = "update-check.json";
 const CACHE_TTL_MS = 864e5;