@theholocron/kyber 0.0.0-stage → 5.0.0-alpha.336

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Newton Koumantzelis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# `@theholocron/kyber`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The reusable parts of a command-line tool: terminal output, prompts, 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).
+
+Published, so a second CLI can import it. `@theholocron/cli` is its first consumer and `cli-template` is the next.
+
+> The kyber crystal is the part in a lightsaber that makes it work.
+
+## 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. |
+
+## Usage
+
+```ts
+import { createProgress, statusRow, style, viewJson } from "@theholocron/kyber/ui";
+
+console.log(style.success("built"));
+console.log(statusRow("ok", ["lint", "no problems"]));
+```
+
+```ts
+import { addGlobalOptions, tokenContext } from "@theholocron/kyber/flags";
+import { createKeyring } from "@theholocron/kyber/secrets";
+
+const parser = addGlobalOptions(yargs(hideBin(process.argv)), { describe: { cwd: "Where tool.config.json is" } });
+const tokens = tokenContext(argv.token, console.error); // null (and exit code 1) for a malformed --token
+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
+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
+runs, for instance to say that a request is being sent again; the Holocron CLI uses it for its retry notice.

package/dist/flags.d.mts

@@ -0,0 +1,38 @@
+import { t as ParsedTokenArgs } from "./token-args.type-arNIDKsQ.mjs";
+import { Argv, CommandModule } from "yargs";
+/** The options {@link addGlobalOptions} declares, as a command handler receives them. */
+interface GlobalArgs {
+  /** `--dry-run`: print what would change instead of changing it. */
+  dryRun: boolean;
+  /** `--token`, repeated: a bare value, or `vendor=value`; see `parseTokenArgs`. */
+  token?: string[];
+  /** `--cwd`: the directory the command works from. */
+  cwd: string;
+}
+/** What {@link addGlobalOptions} can be told. */
+interface GlobalOptionsOptions {
+  /** The help text of each option, where the tool's meaning differs from the general one. */
+  describe?: Partial<Record<"dryRun" | "token" | "cwd", string>>;
+  /** The default for `--cwd`. Default `process.cwd()`, read when the options are declared. */
+  cwd?: string;
+}
+/**
+ * Declares the options every command of a tool takes, once, on the root parser: `--dry-run`, a repeatable `--token`
+ * (a bare value, or `vendor=value`, parsed by `parseTokenArgs`) and `--cwd`. A tool adds its own to the same parser;
+ * a command module's arguments extend {@link GlobalArgs}.
+ */
+export declare function addGlobalOptions(parser: Argv, options?: GlobalOptionsOptions): Argv;
+/**
+ * The hidden default command (`$0`) of a command group, so that typing just the group (`tool repo`) does something
+ * useful: `open` is called with the group's name and the parsed arguments, usually to open a menu of its subcommands.
+ */
+export declare const groupMenu: (parent: string, open: (parent: string, argv: Record<string, unknown>) => Promise<void>) => CommandModule<never, never>;
+/** The arguments a command's `*.args.ts` builder produces: what its handler receives, besides the global options. */
+type InferArgs<Builder> = Builder extends ((...args: never[]) => Argv<infer Args>) ? Args : never;
+/**
+ * Parses the values of a repeatable `--token` flag. An empty or missing flag is `{}`. A value that does not parse is
+ * reported through `report` (as `--token: <why>`), sets `process.exitCode` to 1 and gives `null`, so the command can stop
+ * without a stack trace; any other error is thrown.
+ */
+export declare function tokenContext(rawTokens: string[] | undefined, report: (message: string) => void): ParsedTokenArgs | null;
+export type { GlobalArgs, GlobalOptionsOptions, InferArgs };

package/dist/flags.mjs

@@ -0,0 +1,56 @@
+import { n as parseTokenArgs, t as TokenParseError } from "./token-args-BgrCq_kK.mjs";
+// src/flags/global-options/global-options.ts
+/**
+* Declares the options every command of a tool takes, once, on the root parser: `--dry-run`, a repeatable `--token`
+* (a bare value, or `vendor=value`, parsed by `parseTokenArgs`) and `--cwd`. A tool adds its own to the same parser;
+* a command module's arguments extend {@link GlobalArgs}.
+*/
+function addGlobalOptions(parser, options = {}) {
+	const describe = options.describe ?? {};
+	return parser.option("dry-run", {
+		type: "boolean",
+		default: false,
+		describe: describe.dryRun ?? "Print what would change without changing it. Read-only commands ignore it."
+	}).option("token", {
+		type: "string",
+		array: true,
+		describe: describe.token ?? "Token override. Bare form: --token <value>. Keyed form: --token vendor=value (repeat for each vendor)."
+	}).option("cwd", {
+		type: "string",
+		default: options.cwd ?? process.cwd(),
+		describe: describe.cwd ?? "The directory to work from"
+	});
+}
+// src/flags/group-menu/group-menu.ts
+/**
+* The hidden default command (`$0`) of a command group, so that typing just the group (`tool repo`) does something
+* useful: `open` is called with the group's name and the parsed arguments, usually to open a menu of its subcommands.
+*/
+const groupMenu = (parent, open) => ({
+	command: "$0",
+	describe: false,
+	builder: (y) => y,
+	handler: async (argv) => {
+		await open(parent, argv);
+	}
+});
+// src/flags/token-context/token-context.ts
+/**
+* Parses the values of a repeatable `--token` flag. An empty or missing flag is `{}`. A value that does not parse is
+* reported through `report` (as `--token: <why>`), sets `process.exitCode` to 1 and gives `null`, so the command can stop
+* without a stack trace; any other error is thrown.
+*/
+function tokenContext(rawTokens, report) {
+	if (!rawTokens?.length) return {};
+	try {
+		return parseTokenArgs(rawTokens);
+	} catch (err) {
+		if (err instanceof TokenParseError) {
+			report(`--token: ${err.message}`);
+			process.exitCode = 1;
+			return null;
+		}
+		throw err;
+	}
+}
+export { addGlobalOptions, groupMenu, tokenContext };

package/dist/non-interactive-error-Mm_Mn79M.mjs

@@ -0,0 +1,12 @@
+// src/ui/non-interactive-error/non-interactive-error.ts
+/**
+* Raised when a prompt is needed but stdin isn't a TTY. A non-TTY run (CI, a
+* script, a pipe) throws this instead of hanging on `@inquirer/prompts`, which
+* otherwise throws its own `ExitPromptError` the moment stdin closes. `cli.ts`'s
+* `USER_FACING_ERRORS` catch prints the message cleanly.
+*/
+var NonInteractiveError = class extends Error {
+	/** The error's name, `NonInteractiveError`, so a catch can tell it from any other error. */
+	name = "NonInteractiveError";
+};
+export { NonInteractiveError as t };

package/dist/notifier.d.mts

@@ -0,0 +1,33 @@
+/** What the notifier remembers between runs, so the registry is asked once a day. */
+interface CacheEntry {
+  /** The newest version the registry named on this run's channel. */
+  latestVersion: string;
+  /** When it was asked, in milliseconds since the epoch. */
+  checkedAt: number;
+}
+/** What {@link checkForUpdates} needs to look for a newer version of a package. */
+interface UpdateCheckOptions {
+  /** The package on npm to look up, and to name in the notice. */
+  name: string;
+  /** The version that is running now. A prerelease is compared on its own channel. */
+  currentVersion: string;
+  /** The directory the answer is kept in, created when it is first written. One per tool. */
+  cacheDir: string;
+  /** The variables that switch the notice off (`CI`, `NO_UPDATE_NOTIFIER`). Default `process.env`. */
+  env?: Record<string, string | undefined>;
+  /** How the notice tells people to update. Default `npm install -g <name>`. */
+  installCommand?: string;
+}
+/**
+ * Whether `latest` is newer than `current`: release parts compare as numbers, a stable release is newer than any
+ * prerelease of it, and prereleases compare segment by segment. A leading `v` is ignored.
+ */
+export declare function isUpdateAvailable(current: string, latest: string): boolean;
+/**
+ * Looks for a newer version of a package on npm, at most once a day, and returns a function that prints a boxed notice to
+ * stderr, or `null` when there is nothing to say. It is best-effort: a network error, a bad answer or an unwritable cache
+ * is `null`, never a thrown error. It says nothing in CI or when `NO_UPDATE_NOTIFIER` is set. A prerelease is compared
+ * with the newest version on its own channel (`2.0.0-alpha.3` with the `alpha` tag).
+ */
+export declare function checkForUpdates(options: UpdateCheckOptions): Promise<(() => void) | null>;
+export type { CacheEntry, UpdateCheckOptions };

package/dist/notifier.mjs

@@ -0,0 +1,121 @@
+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;
+const FETCH_TIMEOUT_MS = 3e3;
+function readCache(cacheDir) {
+	try {
+		return JSON.parse(readFileSync(join(cacheDir, CACHE_FILE), "utf8"));
+	} catch {
+		return null;
+	}
+}
+function writeCache(cacheDir, entry) {
+	try {
+		mkdirSync(cacheDir, { recursive: true });
+		writeFileSync(join(cacheDir, CACHE_FILE), JSON.stringify(entry));
+	} catch {}
+}
+async function fetchLatestVersion(name, channel) {
+	try {
+		const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(name)}`, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+		if (!res.ok) return null;
+		const data = await res.json();
+		return data["dist-tags"][channel] ?? data["dist-tags"]["latest"] ?? null;
+	} catch {
+		return null;
+	}
+}
+function getChannel(version) {
+	return /^[^-]+-([a-zA-Z]+)/.exec(version)?.[1] ?? "latest";
+}
+/**
+* Whether `latest` is newer than `current`: release parts compare as numbers, a stable release is newer than any
+* prerelease of it, and prereleases compare segment by segment. A leading `v` is ignored.
+*/
+function isUpdateAvailable(current, latest) {
+	const normalize = (v) => v.replace(/^v/, "");
+	const c = normalize(current);
+	const l = normalize(latest);
+	if (c === l) return false;
+	const splitPre = (v) => {
+		const idx = v.indexOf("-");
+		return idx === -1 ? [v, ""] : [v.slice(0, idx), v.slice(idx + 1)];
+	};
+	const [cRelease, cPre] = splitPre(c);
+	const [lRelease, lPre] = splitPre(l);
+	const parseRelease = (r) => r.split(".").map(Number);
+	const cParts = parseRelease(cRelease);
+	const lParts = parseRelease(lRelease);
+	for (let i = 0; i < Math.max(cParts.length, lParts.length); i++) {
+		const cv = cParts[i] ?? 0;
+		const lv = lParts[i] ?? 0;
+		if (lv > cv) return true;
+		if (lv < cv) return false;
+	}
+	if (!lPre && cPre) return true;
+	if (lPre && !cPre) return false;
+	const cPreParts = cPre.split(".");
+	const lPreParts = lPre.split(".");
+	for (let i = 0; i < Math.max(cPreParts.length, lPreParts.length); i++) {
+		const cv = cPreParts[i] ?? "";
+		const lv = lPreParts[i] ?? "";
+		const cvNum = Number(cv);
+		const lvNum = Number(lv);
+		if (!isNaN(cvNum) && !isNaN(lvNum)) {
+			if (lvNum > cvNum) return true;
+			if (lvNum < cvNum) return false;
+		} else {
+			if (lv > cv) return true;
+			if (lv < cv) return false;
+		}
+	}
+	return false;
+}
+function formatNotice(current, latest, installCmd) {
+	const raw1 = `Update available: ${current} → ${latest}`;
+	const raw2 = `Run ${installCmd} to update`;
+	const width = Math.max(raw1.length, raw2.length) + 4;
+	const bar = chalk.yellow("─".repeat(width));
+	const border = chalk.yellow("│");
+	const pad = (raw, styled) => `${border} ${styled}${" ".repeat(width - 2 - raw.length)} ${border}`;
+	return [
+		"",
+		chalk.yellow(`╭${bar}╮`),
+		pad(raw1, `Update available: ${chalk.dim(current)} → ${chalk.green(latest)}`),
+		pad(raw2, `Run ${chalk.cyan(installCmd)} to update`),
+		chalk.yellow(`╰${bar}╯`),
+		""
+	].join("\n");
+}
+/**
+* Looks for a newer version of a package on npm, at most once a day, and returns a function that prints a boxed notice to
+* stderr, or `null` when there is nothing to say. It is best-effort: a network error, a bad answer or an unwritable cache
+* is `null`, never a thrown error. It says nothing in CI or when `NO_UPDATE_NOTIFIER` is set. A prerelease is compared
+* with the newest version on its own channel (`2.0.0-alpha.3` with the `alpha` tag).
+*/
+async function checkForUpdates(options) {
+	const { name, currentVersion, cacheDir } = options;
+	const env = options.env ?? process.env;
+	if (env["CI"] || env["NO_UPDATE_NOTIFIER"]) return null;
+	const channel = getChannel(currentVersion);
+	const cache = readCache(cacheDir);
+	const now = Date.now();
+	let latestVersion = null;
+	if (cache && now - cache.checkedAt < CACHE_TTL_MS) latestVersion = cache.latestVersion;
+	else {
+		latestVersion = await fetchLatestVersion(name, channel);
+		if (latestVersion) writeCache(cacheDir, {
+			latestVersion,
+			checkedAt: now
+		});
+	}
+	if (!latestVersion || !isUpdateAvailable(currentVersion, latestVersion)) return null;
+	const installCommand = options.installCommand ?? `npm install -g ${name}`;
+	return () => {
+		process.stderr.write(formatNotice(currentVersion, latestVersion, installCommand) + "\n");
+	};
+}
+export { checkForUpdates, isUpdateAvailable };

package/dist/prompts.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`.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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).
+ */
+export declare function promptForPositionals(entry: PositionalCommand, argv: Record<string, unknown>): Promise<string[]>;
+export type { MenuItem, OptionAnswer, OptionMode, OptionPrompt, OptionsCommand, PositionalCommand, PositionalPrompt, ResolvedOptions };