@theholocron/kyber 5.0.0-alpha.339 → 5.0.0-alpha.341

package/README.md

@@ -1,6 +1,6 @@
 # `@theholocron/kyber`
 
-The reusable parts of a command-line tool: terminal output, prompts, the update notifier, safe handling of tokens, a
+The reusable parts of a command-line tool: terminal output, prompts, the interactive menu, the update notifier, safe handling of tokens, a
 test harness and the global flags. They were written for the Holocron CLI and are moved here one subpath at a time, so
 the next CLI does not copy them (spec `tech-kyber`, #1727).
 
@@ -10,14 +10,16 @@ Published, so a second CLI can import it. `@theholocron/cli` is its first consum
 
 ## Subpaths
 
-| Subpath     | What it gives a CLI                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `/ui`       | Status glyphs and colours, padded status rows, a depth-limited JSON view, a spinner that only shows on a terminal, wait-for-Enter, open-in-file-browser, and the error for "a prompt was needed but there is no terminal".                                                                                                                                                                                                                                         |
-| `/notifier` | A cached, best-effort "a newer version exists" notice for an npm package: `checkForUpdates({ name, currentVersion, cacheDir })` returns a function that prints a boxed notice to stderr, or `null`. Silent in CI and with `NO_UPDATE_NOTIFIER`.                                                                                                                                                                                                                    |
-| `/secrets`  | Handling tokens safely, with no terminal UI: owner-only (`0600`) files, shredding a file that held tokens, "does git ignore this path", dotenv lines that survive quoting, reading a `.env` at the repo root, the clipboard, the OS keyring (`createKeyring({ service })`, best-effort, `@napi-rs/keyring` optional), an in-process store for credentials a provider returned, and `--token` / `--token vendor=value` parsing.                                     |
-| `/prompts`  | A searchable menu (`pickMenuItem`), and prompting for the positionals and options a command left out (`promptForPositionals`, `promptForOptions`): required options always asked, the rest behind one checkbox, mutually exclusive `modes`, secret options masked, and a value that is asked last (`askLast`). They take small structural types (`PositionalCommand`, `OptionsCommand`), not the CLI's command registry.                                           |
-| `/testing`  | A test harness for a CLI: `createCliRunner` runs a built binary in a fresh directory with an environment built from nothing, `runCommand` runs one yargs command module through a real parse, `ensureBuilt` is a Vitest global setup that builds only when `dist` is missing or stale, and `hermeticCreateRequire` resolves modules only from one directory.                                                                                                       |
-| `/flags`    | The options every command of a tool takes: `addGlobalOptions(parser, { describe?, cwd? })` declares `--dry-run`, a repeatable `--token` and `--cwd` once on the root; `tokenContext(values, report)` parses the `--token` values and reports a bad one without a stack trace; `groupMenu(parent, open)` is the hidden default command that makes a bare group (`tool repo`) do something useful; `InferArgs` types a command's handler arguments from its builder. |
+| Subpath     | What it gives a CLI                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `/ui`       | Status glyphs and colours, padded status rows, a depth-limited JSON view, a spinner that only shows on a terminal, wait-for-Enter, open-in-file-browser, the error for "a prompt was needed but there is no terminal", and the cleaning of error text before it reaches a terminal (`describeError`, `commandFailureMessage`, `logReason`, `sanitizeDetail`, `stripControl`).                                                                                                                                                                                                                                                                                                     |
+| `/notifier` | A cached, best-effort "a newer version exists" notice for an npm package: `checkForUpdates({ name, currentVersion, cacheDir })` returns a function that prints a boxed notice to stderr, or `null`. Silent in CI and with `NO_UPDATE_NOTIFIER`.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `/secrets`  | Handling tokens safely, with no terminal UI: owner-only (`0600`) files, shredding a file that held tokens, "does git ignore this path", dotenv lines that survive quoting, reading a `.env` at the repo root, the clipboard, the OS keyring (`createKeyring({ service })`, best-effort, `@napi-rs/keyring` optional), an in-process store for credentials a provider returned, `--token` / `--token vendor=value` parsing, and resolving a token from the flag, the environment, that store and the keyring (`createResolveToken`, `createFeatureResolver`, `AuthError`).                                                                                                         |
+| `/prompts`  | A searchable menu (`pickMenuItem`), and prompting for the positionals and options a command left out (`promptForPositionals`, `promptForOptions`): required options always asked, the rest behind one checkbox, mutually exclusive `modes`, secret options masked, and a value that is asked last (`askLast`). They take small structural types (`PositionalCommand`, `OptionsCommand`), not the CLI's command registry.                                                                                                                                                                                                                                                          |
+| `/menu`     | The interactive menu of a CLI, driven by data: `launchMenu(entries, argv, { bin, envPrefix })` shows a searchable, nested picker over a list of `MenuEntry`, asks for the positionals and options the command needs, then spawns the CLI again with the answers. A command that supports `--dry-run` is previewed first and then confirmed (`--skip-dry-run` opts out); a preview that reports `DRY_RUN_NOOP_EXIT_CODE` skips the question. Secret options never reach argv: they travel as `<envPrefix>_<OPTION>` env vars, and a preview child gets `dryRunPreviewEnvVar(envPrefix)`. Also `menuItems`, `buildChildArgv`, `forwardedFlags`, `secretEnv`, `shouldPreviewDryRun`. |
+| `/testing`  | A test harness for a CLI: `createCliRunner` runs a built binary in a fresh directory with an environment built from nothing, `runCommand` runs one yargs command module through a real parse, `ensureBuilt` is a Vitest global setup that builds only when `dist` is missing or stale, and `hermeticCreateRequire` resolves modules only from one directory.                                                                                                                                                                                                                                                                                                                      |
+| `/config`   | A `<name>.config.{ts,js,mjs,cjs,json}` for a new CLI: `createConfigSystem({ name, derive?, resolve, merge })` returns `defineConfig`, `loadConfig` (walks up to `.git`) and `compose()` (dedupe by `id`, all unmet `requires` in one `ConfigError`, per-key merge). Strategies: `lastWins`, `shallowMerge`, `union`, `mergeByKey`. `@theholocron/datapad` is an optional peer.                                                                                                                                                                                                                                                                                                    |
+| `/flags`    | The options every command of a tool takes: `addGlobalOptions(parser, { describe?, cwd? })` declares `--dry-run`, a repeatable `--token` and `--cwd` once on the root; `tokenContext(values, report)` parses the `--token` values and reports a bad one without a stack trace; `groupMenu(parent, open)` is the hidden default command that makes a bare group (`tool repo`) do something useful; `InferArgs` types a command's handler arguments from its builder.                                                                                                                                                                                                                |
 
 ## Usage
 
@@ -28,6 +30,16 @@ console.log(style.success("built"));
 console.log(statusRow("ok", ["lint", "no problems"]));
 ```
 
+```ts
+import { launchMenu, type MenuEntry } from "@theholocron/kyber/menu";
+
+const entries: MenuEntry[] = [
+  { name: "doctor", description: "Check the setup", positionals: [], supportsDryRun: true },
+  { name: "repo sync", description: "Sync the repo", positionals: [] },
+];
+await launchMenu(entries, argv, { bin: "tool", envPrefix: "TOOL" }); // a secret `otp` option reaches the child as TOOL_OTP
+```
+
 ```ts
 import { addGlobalOptions, tokenContext } from "@theholocron/kyber/flags";
 import { createKeyring } from "@theholocron/kyber/secrets";
@@ -37,7 +49,7 @@ const tokens = tokenContext(argv.token, console.error); // null (and exit code 1
 const keyring = createKeyring({ service: "com.example.tool" }); // best-effort: never throws
 ```
 
-Each subpath's heavy libraries (`chalk`, `ora`, `@inquirer/prompts`, `yargs`, `dotenv`, `clipboardy`, `@napi-rs/keyring`) are
+Each subpath's heavy libraries (`chalk`, `ora`, `@inquirer/prompts`, `yargs`, `dotenv`, `clipboardy`, `@napi-rs/keyring`, `@theholocron/datapad`) are
 optional peer dependencies: a CLI installs the ones for the subpaths it imports.
 
 `createProgress(print, enabled?, listen?)` takes an optional `listen` hook that can change the spinner's text while a step

package/dist/config.d.mts

@@ -0,0 +1,81 @@
+import { ConfigFileError, Loaded } from "@theholocron/datapad";
+/** How the values several fragments give one key combine. */
+interface Strategy<V> {
+  /** The value to start from. A strategy without one leaves the key out of the result until a fragment sets it. */
+  empty?: V;
+  /** Combine what has been merged so far with the next fragment's value. */
+  merge: (prev: V, next: V) => V;
+}
+/** A composable piece of config: an id to dedupe by, and the ids it needs alongside it. */
+interface ConfigFragment {
+  /** Unique identifier; a later fragment with the same id replaces an earlier one. */
+  id: string;
+  /** Ids that must be present in the same compose call. */
+  requires?: string[];
+}
+/** How each key of the composed result is merged from the fragments' values for that key. */
+type MergeStrategies<Composed> = { [K in keyof Composed]-?: Strategy<NonNullable<Composed[K]>>; };
+/**
+ * Thrown when a config is invalid, or when `compose()` is given fragments whose `requires` are not met. A caller that
+ * may load a second copy of this package matches it by `name`, not `instanceof`.
+ */
+export declare class ConfigError extends Error {
+  /** The error name, `ConfigError`. */
+  name: string;
+}
+/** What {@link createConfigSystem} needs to build a CLI's config system. */
+interface ConfigSystemOptions<Raw, Resolved, Composed> {
+  /** The CLI's name; its config file is `<name>.config.{ts,js,mjs,cjs,json}`. */
+  name: string;
+  /** Fill in defaults on the loaded config (from `package.json`, git, other files) before it is resolved. */
+  derive?: (found: Loaded<Raw>) => Raw | Promise<Raw>;
+  /** Check the config and turn it into the shape the CLI works with; throw `ConfigError` when it is invalid. */
+  resolve: (raw: Raw) => Resolved;
+  /** How `compose()` merges each key of the fragments into one `Composed` object. */
+  merge: MergeStrategies<Composed>;
+}
+/** A loaded and resolved config. */
+interface LoadedConfig<Resolved> {
+  /** The config after `resolve`. */
+  resolved: Resolved;
+  /** Absolute path to the file the config was read from. */
+  filepath: string;
+}
+/** The functions {@link createConfigSystem} returns. */
+interface ConfigSystem<Raw, Resolved, Fragment extends ConfigFragment, Composed> {
+  /** Returns the config unchanged; it exists to type and autocomplete a config file. */
+  defineConfig: (config: Raw) => Raw;
+  /**
+   * Find, load, derive and resolve the config, starting at `cwd` and walking up to the nearest `.git`. Throws
+   * `ConfigFileError` when none is found or a file cannot be loaded, or whatever `resolve` throws.
+   */
+  loadConfig: (cwd: string) => Promise<LoadedConfig<Resolved>>;
+  /** Merge fragments (or arrays of them) into one object that spreads into `defineConfig()`. */
+  compose: (...fragments: (Fragment | Fragment[])[]) => Composed;
+}
+/**
+ * Build the config system of a new CLI: a `<name>.config.{ts,js,mjs,cjs,json}` file, a typing helper for it, a loader
+ * that walks up to the repo root, and a `compose()` that merges reusable fragments.
+ *
+ * @example
+ * const { defineConfig, loadConfig, compose } = createConfigSystem<Raw, Resolved, Fragment, Composed>({
+ *   name: "mycli",
+ *   resolve: (raw) => validate(raw),
+ *   merge: { plugins: union<string>(), settings: shallowMerge(), title: lastWins() },
+ * });
+ */
+export declare function createConfigSystem<Raw, Resolved, Fragment extends ConfigFragment, Composed>(options: ConfigSystemOptions<Raw, Resolved, Composed>): ConfigSystem<Raw, Resolved, Fragment, Composed>;
+/** Merge strategy where the last fragment to set the key wins. The key is absent until a fragment sets it. */
+export declare function lastWins<V>(): Strategy<V>;
+/**
+ * Merge strategy for lists of entries that share an identity. An entry whose key was already seen replaces the earlier
+ * one in place; new keys append.
+ *
+ * @param keyOf - The key an entry merges under.
+ */
+export declare function mergeByKey<T>(keyOf: (entry: T) => string): Strategy<T[]>;
+/** Merge strategy that spreads each fragment's object over the last, so a later fragment overrides per top-level key. */
+export declare function shallowMerge<V extends object>(): Strategy<V>;
+/** Merge strategy that adds lists up, dropping repeats and keeping first-seen order. */
+export declare function union<T>(): Strategy<T[]>;
+export { ConfigFileError, type ConfigFragment, type ConfigSystem, type ConfigSystemOptions, type LoadedConfig, type MergeStrategies, type Strategy };

package/dist/config.mjs

@@ -0,0 +1,111 @@
+import { ConfigFileError, ConfigFileError as ConfigFileError$1, loadConfigFile } from "@theholocron/datapad";
+// src/config/config-error/config-error.ts
+/**
+* Thrown when a config is invalid, or when `compose()` is given fragments whose `requires` are not met. A caller that
+* may load a second copy of this package matches it by `name`, not `instanceof`.
+*/
+var ConfigError = class extends Error {
+	/** The error name, `ConfigError`. */
+	name = "ConfigError";
+};
+// src/config/compose-fragments/compose-fragments.ts
+/**
+* Combine config fragments into one object. Fragments dedupe by `id` (the last one with an id wins, in the position of
+* the first), every unmet `requires` is reported in ONE {@link ConfigError}, then each key merges with its strategy.
+*
+* @param strategies - A merge strategy per key of the composed result.
+* @param args - Fragments, or arrays of them.
+*/
+function composeFragments(strategies, args) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const fragment of args.flat()) byId.set(fragment.id, fragment);
+	const fragments = [...byId.values()];
+	const errors = [];
+	for (const fragment of fragments) for (const req of fragment.requires ?? []) if (!byId.has(req)) errors.push(`"${fragment.id}" requires "${req}"`);
+	if (errors.length > 0) throw new ConfigError(`compose(): unmet dependencies — ${errors.join(", ")}`);
+	const result = {};
+	for (const [key, strategy] of Object.entries(strategies)) {
+		let acc = strategy.empty;
+		for (const fragment of fragments) {
+			const value = fragment[key];
+			if (value === void 0) continue;
+			acc = acc === void 0 ? value : strategy.merge(acc, value);
+		}
+		if (acc !== void 0) result[key] = acc;
+	}
+	return result;
+}
+// src/config/create-config-system/create-config-system.ts
+/**
+* Build the config system of a new CLI: a `<name>.config.{ts,js,mjs,cjs,json}` file, a typing helper for it, a loader
+* that walks up to the repo root, and a `compose()` that merges reusable fragments.
+*
+* @example
+* const { defineConfig, loadConfig, compose } = createConfigSystem<Raw, Resolved, Fragment, Composed>({
+*   name: "mycli",
+*   resolve: (raw) => validate(raw),
+*   merge: { plugins: union<string>(), settings: shallowMerge(), title: lastWins() },
+* });
+*/
+function createConfigSystem(options) {
+	const { name, derive, resolve, merge } = options;
+	return {
+		defineConfig: (config) => config,
+		async loadConfig(cwd) {
+			const found = await loadConfigFile({
+				cwd,
+				name,
+				walkUp: true
+			});
+			if (!found) throw new ConfigFileError$1(`no ${name}.config.{ts,js,mjs,cjs,json} found in ${cwd}. Create one — see the README for the schema.`);
+			const raw = derive ? await derive(found) : found.config;
+			return {
+				resolved: resolve(raw),
+				filepath: found.filepath
+			};
+		},
+		compose: (...fragments) => composeFragments(merge, fragments)
+	};
+}
+// src/config/last-wins/last-wins.ts
+/** Merge strategy where the last fragment to set the key wins. The key is absent until a fragment sets it. */
+function lastWins() {
+	return { merge: (_prev, next) => next };
+}
+// src/config/merge-by-key/merge-by-key.ts
+/**
+* Merge strategy for lists of entries that share an identity. An entry whose key was already seen replaces the earlier
+* one in place; new keys append.
+*
+* @param keyOf - The key an entry merges under.
+*/
+function mergeByKey(keyOf) {
+	return {
+		empty: [],
+		merge: (prev, next) => {
+			const byKey = new Map(prev.map((e) => [keyOf(e), e]));
+			for (const e of next) byKey.set(keyOf(e), e);
+			return [...byKey.values()];
+		}
+	};
+}
+// src/config/shallow-merge/shallow-merge.ts
+/** Merge strategy that spreads each fragment's object over the last, so a later fragment overrides per top-level key. */
+function shallowMerge() {
+	return {
+		empty: {},
+		merge: (prev, next) => ({
+			...prev,
+			...next
+		})
+	};
+}
+// src/config/union/union.ts
+/** Merge strategy that adds lists up, dropping repeats and keeping first-seen order. */
+function union() {
+	return {
+		empty: [],
+		merge: (prev, next) => [.../* @__PURE__ */ new Set([...prev, ...next])]
+	};
+}
+export { ConfigError, ConfigFileError, createConfigSystem, lastWins, mergeByKey, shallowMerge, union };

package/dist/index-DpXxO_wH.d.mts

@@ -0,0 +1,214 @@
+/** A row in one level of a nested menu: a command to run, a group to open, or "back". */
+interface MenuItem {
+  /** The label shown in the picker. */
+  name: string;
+  /** What the picker resolves to: a command name, `group:<path>` to open a submenu, or `back`. */
+  value: string;
+  /** One line of help shown beside the label. */
+  description: string;
+  /** Lower-cased text the search box matches against (a group includes everything under it). */
+  haystack: string;
+}
+/**
+ * Searchable autocomplete over one menu level's `items`. `select()` would work too
+ * at these list sizes, but `search()` degrades gracefully as the surface grows and
+ * costs nothing when it doesn't. Resolves to the picked item's `value`.
+ */
+declare function pickMenuItem(items: MenuItem[], message?: string): Promise<string>;
+/**
+ * `@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 item.
+ */
+declare function searchChoices(items: MenuItem[], term: string | undefined): Array<{
+  name: string;
+  value: string;
+  description: string;
+  short: string;
+}>;
+/** A resolved option answer — the shapes `buildChildArgv`/`secretEnv` turn into argv tokens or env entries. */
+type OptionAnswer = string | boolean | string[];
+/** One option to offer: how to ask for it and how the answer is turned into a flag. */
+interface OptionPrompt {
+  /** The yargs option's camelCased argv key, e.g. `"otp"`. */
+  key: string;
+  /** The literal flag as typed at the CLI, e.g. `"--otp"`. */
+  flag: string;
+  /** The kind of prompt: a yes/no, free text, a pick from `choices`, or masked text. */
+  type: "confirm" | "input" | "select" | "password";
+  /** The question shown to the user. */
+  message: string;
+  /**
+   * Required when `type === "select"`. A plain list for a fixed set, or a
+   * thunk for a set resolved at prompt time — same shape as
+   * `PositionalPrompt.choices`.
+   */
+  choices?: string[] | (() => string[]);
+  /** The answer proposed when the user just presses Enter. */
+  default?: string | boolean;
+  /**
+   * Collected with a masked `password()` prompt and delivered to the
+   * child through an environment variable instead of argv (`ps` and
+   * shell history expose argv) — never written to the dry-run preview
+   * echo, telemetry, or logs. Always paired with `type: "password"`.
+   */
+  secret?: boolean;
+  /**
+   * Always included, like a required positional — never behind the
+   * multi-select, and never subject to `when`. Combines with `askLast`
+   * cleanly: `required` only decides whether this sits behind the
+   * checkbox, not when its value gets collected.
+   */
+  required?: boolean;
+  /** Boolean whose yargs default is `true` — answering "no" emits `--no-<flag>` instead of omitting the flag. */
+  negatable?: boolean;
+  /** Array option taking exactly `arity` values (e.g. `--sync-trust <old> <new>`) — prompted once per value. */
+  arity?: number;
+  /**
+   * Defer collecting this option's value until right before the real
+   * (non-dry-run) spawn, instead of upfront with everything else
+   * (holocron#1052 follow-up) — for a time-sensitive secret (an OTP code)
+   * that can go stale if typed too early: a dry-run preview and a human
+   * confirming "proceed with the real run?" can both take a while, and
+   * neither one actually needs the value anyway. Works whether this
+   * option also has `required: true` (always included, no checkbox pick
+   * needed) or not (offered through the checkbox as usual) — `askLast`
+   * only ever changes *when* the value is collected, never whether it's
+   * included. See `promptForDeferredOptions`.
+   */
+  askLast?: boolean;
+  /**
+   * Evaluated against answers collected so far, in declaration order —
+   * `false` skips prompting (and so emitting) this option entirely, as if
+   * it had never been selected. Not applied to `required` options. For a
+   * command whose options have real either/or relationships, prefer
+   * {@link OptionMode} instead — nothing contingent is ever shown in the
+   * first place, rather than silently dropped after being picked.
+   */
+  when?: (answers: Readonly<Record<string, OptionAnswer>>) => boolean;
+}
+/**
+ * One of a command's mutually exclusive workflows (holocron#1052 follow-up)
+ * — `package publish`'s steady-state publish, `--initial` bootstrap, and
+ * `--sync-trust` maintenance mode are three different things to do, not
+ * three independent flags. The mode picked first decides which options are
+ * even offered, so nothing contingent on another mode is ever shown.
+ */
+interface OptionMode {
+  /** Unique within the command's `modes` — identifies the pick, never shown. */
+  key: string;
+  /** Shown as this mode's choice label in the "what would you like to do?" prompt — keep it short; put caveats in `description` instead. */
+  message: string;
+  /**
+   * Longer explanation shown as helper text under this choice only while
+   * it's highlighted (`select()`'s own per-choice `description`) — the
+   * place for a caveat ("use only for a package's very first publish")
+   * that would make `message` too long to scan at a glance.
+   */
+  description?: string;
+  /**
+   * Emitted unconditionally once this mode is picked, before any of its
+   * own options — e.g. `"--initial"` for a bootstrap-publish mode. Omit
+   * for a mode that implies no flag of its own (steady-state here: no
+   * flag means "neither of the others").
+   */
+  flag?: string;
+  /** This mode's own options, prompted exactly like a flat command's `options` — required ones always asked, the rest behind one checkbox. */
+  options?: OptionPrompt[];
+}
+/**
+ * `promptForOptions`' result: every {@link OptionPrompt} relevant to
+ * rendering, in order, paired with the answers collected for them.
+ * `options` is the flat `OptionsCommand.options` list directly for a
+ * flat command, or the picked mode's own `options` (plus a synthetic
+ * entry for its `flag`, when it has one) for a `modes`-based command —
+ * `buildChildArgv`/`secretEnv` render either shape identically, with no
+ * need to know which kind of command produced it.
+ */
+interface ResolvedOptions {
+  /** The options that apply, in the order they were asked. */
+  options: OptionPrompt[];
+  /** What was answered, by each option's `key`. */
+  answers: Record<string, OptionAnswer>;
+  /** Picked `askLast: true` options with no value yet — resolve via `promptForDeferredOptions` right before the real spawn. Undefined/empty is the common case: nothing deferred. */
+  deferred?: OptionPrompt[];
+}
+/** The part of a command that {@link promptForOptions} needs: its name and the options (or modes) to offer. */
+interface OptionsCommand {
+  /** Full command name as typed at the CLI, e.g. `"package publish"`. */
+  name: string;
+  /** Declared options, in order. Undefined/empty means nothing to offer — no prompt at all. Ignored when `modes` is set. */
+  options?: OptionPrompt[];
+  /**
+   * Mutually exclusive workflows — when set, a mode is picked first and
+   * `options` above is ignored entirely; only the picked mode's own
+   * options are then offered. Use this only for a command whose options
+   * have a real either/or relationship; plain `options` covers
+   * everything else and stays the simpler default.
+   */
+  modes?: OptionMode[];
+}
+/**
+ * Resolves `entry`'s options into a {@link ResolvedOptions} ready for
+ * `buildChildArgv`/`secretEnv` — delegating to {@link promptForModes} when
+ * `entry.modes` is set, or treating `entry.options` as a flat list
+ * otherwise. See `promptForFlatOptions` for the flat-list prompting
+ * algorithm itself. `result.deferred` still needs
+ * {@link promptForDeferredOptions} before the real spawn.
+ */
+declare function promptForOptions(entry: OptionsCommand, argv: Record<string, unknown>): Promise<ResolvedOptions>;
+/**
+ * Collects a value for each of `deferred` — the `askLast: true` options
+ * `promptForOptions` deliberately left unresolved. Call this as the very
+ * last thing before the real (non-dry-run) spawn, never before: a dry-run
+ * preview never reaches the real npm call these options exist for (an OTP
+ * is never checked during `--dry-run`), and a time-sensitive code typed
+ * any earlier — before a dry-run preview runs, before "proceed with the
+ * real run?" waits on a human — risks going stale before it's actually
+ * used. A no-op (no prompt at all) when `deferred` is empty.
+ */
+declare function promptForDeferredOptions(deferred: OptionPrompt[]): Promise<Record<string, OptionAnswer>>;
+/** One positional argument to ask for when it was not given on the command line. */
+interface PositionalPrompt {
+  /** The yargs positional's camelCased argv key (e.g. `"newVersion"`). */
+  key: string;
+  /**
+   * The literal token in the command string, when it differs from `key`
+   * (yargs positionals are kebab-case there — `<new-version>` — but
+   * camelCased in argv). Shown in the non-interactive fallback message.
+   * Defaults to `key`.
+   */
+  cliArg?: string;
+  /** Label shown to the user. */
+  message: string;
+  /** Free text, or a pick from `choices`. */
+  type: "input" | "select";
+  /**
+   * Required when `type === "select"`. A plain list for a fixed set, or a
+   * thunk for a set resolved at prompt time (e.g. `auth unset`'s provider
+   * choices are whatever currently has a stored token — there's no fixed
+   * provider list, providers are open-ended plugin packages).
+   */
+  choices?: string[] | (() => string[]);
+  /** Optional `input()` validation — e.g. numeric positionals. */
+  validate?: (value: string) => boolean | string;
+}
+/** The part of a command that {@link promptForPositionals} needs: its name and the positionals to ask for. */
+interface PositionalCommand {
+  /** Full command name as typed at the CLI, e.g. `"auth set"`. */
+  name: string;
+  /** Required positionals only, in order. */
+  positionals: PositionalPrompt[];
+}
+/**
+ * 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).
+ */
+declare function promptForPositionals(entry: PositionalCommand, argv: Record<string, unknown>): Promise<string[]>;
+export { promptForOptions as a, OptionPrompt as c, pickMenuItem as d, searchChoices as f, promptForDeferredOptions as i, OptionsCommand as l, PositionalCommand as n, OptionAnswer as o, MenuItem as p, PositionalPrompt as r, OptionMode as s, promptForPositionals as t, ResolvedOptions as u };