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

package/dist/observability.d.mts

@@ -0,0 +1,156 @@
+import { AxiomTransportConfig } from "@theholocron/observability/logger";
+import { LogLevel, Logger } from "@theholocron/observability/core";
+/** The global logging flags a CLI parses (`--log`, `--verbose`, `--quiet`). */
+interface LogFlags {
+  verbose?: boolean;
+  quiet?: boolean;
+  log?: LogLevel;
+}
+/** What a handler can supply once the CLI's config file is loaded. */
+interface BuildCliLoggerOpts {
+  /** Active command name, bound on the root as `command` for every line. */
+  command?: string;
+  /** The config file's log level, from a handler that has loaded a config. */
+  configLevel?: LogLevel;
+  /** The config file's non-secret Axiom dataset name. */
+  configAxiomDataset?: string;
+  /** The resolved org, for a namespaced credential lookup. */
+  org?: string;
+}
+/** The command name in effect, resolved for {@link CreateCliLoggerOptions.resolveAxiom}. */
+interface CliLoggerContext {
+  /** `opts.command`, else the command name remembered from an earlier build. */
+  command: string | undefined;
+}
+interface CreateCliLoggerOptions {
+  /** Upper-case env prefix of the CLI, e.g. `"HOLOCRON"` (reads `<PREFIX>_LOG_LEVEL`). */
+  envPrefix: string;
+  /**
+   * Resolve Axiom credentials for a build. Defaults to the package's
+   * `resolveAxiomFromEnv`. Return `undefined` to ship nowhere.
+   */
+  resolveAxiom?: (opts: BuildCliLoggerOpts, ctx: CliLoggerContext) => AxiomTransportConfig | undefined;
+}
+/** The bound logging functions a CLI re-exports. */
+interface CliLogger {
+  /**
+   * Build (or return the memoized) process-wide root logger. Rebuilt at most
+   * once more when a handler supplies config the flag/env-only first pass could
+   * not have known (the level, or a new Axiom dataset).
+   */
+  buildCliLogger: (argv: LogFlags, opts?: BuildCliLoggerOpts) => {
+    logger: Logger;
+    runId: string;
+  };
+  /** Lazily-memoized root `Logger` for call sites with no `argv` in scope. */
+  getLogger: () => Logger;
+  /** Print a fatal error with `style.fail` and also log it at error level. */
+  reportError: (message: string, log?: Logger) => void;
+  /** The current root logger's correlation id, if a root has been built. */
+  getRunId: () => string | undefined;
+  /** Test hook: drop the memoized root so the next call rebuilds it. */
+  resetCliLogger: () => void;
+  /** {@link resolveLogLevel} bound to this CLI's env prefix. */
+  resolveLogLevel: (argv: LogFlags, configLevel?: LogLevel) => LogLevel | undefined;
+}
+/**
+ * Create a CLI's logging functions around a memoized root `Logger`.
+ *
+ * Level comes from `--log` / `--verbose` / `--quiet`, then
+ * `<PREFIX>_LOG_LEVEL`, then the config file. Console output is quiet unless
+ * CI or a flag asks for it. `--quiet` and `--log` also turn the progress
+ * spinner off (`allowProgress`), as they own the terminal.
+ *
+ * @example
+ * const { buildCliLogger, getLogger, reportError } = createCliLogger({ envPrefix: "ACME" });
+ */
+export declare function createCliLogger(options: CreateCliLoggerOptions): CliLogger;
+/** The `telemetry` block of a CLI's config file: the committed override layer. */
+interface TelemetryConfig {
+  /** `false` installs the no-op sinks for the whole run. Default on. */
+  enabled?: boolean;
+  /** `"none"` disables usage analytics but leaves error reporting on. Default `"posthog"`. */
+  analytics?: "posthog" | "none";
+}
+interface CreateCliTelemetryOptions {
+  /**
+   * Upper-case env prefix of the CLI, e.g. `"HOLOCRON"`. Reads
+   * `<PREFIX>_TELEMETRY` (`false` opts out), the legacy `NO_<PREFIX>_TELEMETRY`
+   * and `<PREFIX>_ORG`; the Sentry release is `<prefix lower-cased>@<version>`.
+   */
+  envPrefix: string;
+  /** Resolve the Sentry DSN at `init` time. `""` disables error reporting. */
+  dsn: () => string;
+  /** Resolve the PostHog project key at `init` time. `""` disables usage analytics. */
+  posthogKey: () => string;
+  /** Resolve the PostHog ingest host at `init` time. */
+  posthogHost: () => string;
+  /** The logger's correlation id, attached to events as `runId`. */
+  getRunId?: () => string | undefined;
+}
+/** The bound telemetry functions a CLI re-exports. */
+interface CliTelemetry {
+  /** Install the live sinks unless the opt-out is set or a credential is empty. */
+  init: (version: string) => void;
+  /** Apply the config block: it only ever narrows what `init` turned on. */
+  applyConfig: (cfg: TelemetryConfig | undefined) => void;
+  /** Capture a usage event; properties run through the secret scrubber. */
+  event: (name: string, properties?: Record<string, unknown>) => void;
+  /** Start a command span; call the returned function with the outcome. */
+  startCommand: (name: string) => (ok: boolean) => void;
+  /** Report an error to the error sink. */
+  captureException: (err: unknown) => void;
+  /** End the error-reporting session. */
+  endSession: () => void;
+  /** Drain both sinks and return to the no-ops. */
+  flush: () => Promise<void>;
+  /** Test hook: drop sinks and command state back to the no-op defaults. */
+  resetTelemetry: () => void;
+}
+/**
+ * Create a CLI's self-telemetry: error reporting (Sentry) and usage analytics
+ * (PostHog) behind the `ErrorSink` / `AnalyticsSink` seam of
+ * `@theholocron/observability`. No-op sinks are installed until `init` finds
+ * telemetry enabled, and the single kill switch is `<PREFIX>_TELEMETRY=false`
+ * (legacy alias `NO_<PREFIX>_TELEMETRY`). The credentials are passed in, since
+ * this reads no environment for them.
+ *
+ * @example
+ * const telemetry = createCliTelemetry({
+ *   envPrefix: "ACME",
+ *   dsn: () => "https://key@o1.ingest.sentry.io/1",
+ *   posthogKey: () => "phc_key",
+ *   posthogHost: () => "https://us.i.posthog.com",
+ * });
+ */
+export declare function createCliTelemetry(options: CreateCliTelemetryOptions): CliTelemetry;
+/**
+ * Resolve whether human-visible console output (pretty or NDJSON) should run
+ * at all, independent of level: the `@theholocron/observability`
+ * `consoleOutput` override.
+ *
+ * Local and interactive runs are quiet by default: structured logger output
+ * stays off regardless of level, unless the user asked to see it with
+ * `--log <level>`, `--verbose` or `--quiet`. In CI it returns `undefined`,
+ * which keeps `createLogger`'s own `ci`/`tty` auto-detection untouched.
+ *
+ * @param argv - The parsed global logging flags.
+ */
+export declare function resolveConsoleOutput(argv: LogFlags): boolean | undefined;
+/**
+ * Resolve the explicit level to hand to `createLogger`, in priority order:
+ *
+ * 1. `--log <level>`           2. `--verbose` → `"debug"`   3. `--quiet` → `"error"`
+ * 4. `<PREFIX>_LOG_LEVEL` env var
+ * 5. the config file's log level (`configLevel`)
+ *
+ * Returns `undefined` when nothing applies, so `createLogger` falls back to
+ * `"info"`. Resolving the whole chain here (rather than passing `configLevel`
+ * straight through) keeps config below the env var.
+ *
+ * @param envPrefix - Upper-case env prefix of the CLI, e.g. `"HOLOCRON"`.
+ * @param argv - The parsed global logging flags.
+ * @param configLevel - The level from the CLI's config file, if one was loaded.
+ */
+export declare function resolveLogLevel(envPrefix: string, argv: LogFlags, configLevel?: LogLevel): LogLevel | undefined;
+export type { BuildCliLoggerOpts, CliLogger, CliLoggerContext, CliTelemetry, CreateCliLoggerOptions, CreateCliTelemetryOptions, LogFlags, TelemetryConfig };

package/dist/observability.mjs

@@ -0,0 +1,254 @@
+import { allowProgress, style } from "./ui.mjs";
+import { createLogger, isCI, parseLogLevel, resolveAxiomFromEnv } from "@theholocron/observability/logger";
+import { createEnvLookup } from "@theholocron/env-utils/lookup";
+import { createHash } from "node:crypto";
+import { hostname, userInfo } from "node:os";
+import { PostHogSink } from "@theholocron/observability/analytics";
+import { NoopAnalyticsSink, NoopErrorSink, redactObject } from "@theholocron/observability/core";
+import { SentrySink } from "@theholocron/observability/errors";
+// src/observability/resolve-console-output/resolve-console-output.ts
+/**
+* Resolve whether human-visible console output (pretty or NDJSON) should run
+* at all, independent of level: the `@theholocron/observability`
+* `consoleOutput` override.
+*
+* Local and interactive runs are quiet by default: structured logger output
+* stays off regardless of level, unless the user asked to see it with
+* `--log <level>`, `--verbose` or `--quiet`. In CI it returns `undefined`,
+* which keeps `createLogger`'s own `ci`/`tty` auto-detection untouched.
+*
+* @param argv - The parsed global logging flags.
+*/
+function resolveConsoleOutput(argv) {
+	if (argv.log || argv.verbose || argv.quiet) return true;
+	return isCI() ? void 0 : false;
+}
+// src/observability/resolve-log-level/resolve-log-level.ts
+const env$1 = createEnvLookup();
+/**
+* Resolve the explicit level to hand to `createLogger`, in priority order:
+*
+* 1. `--log <level>`           2. `--verbose` → `"debug"`   3. `--quiet` → `"error"`
+* 4. `<PREFIX>_LOG_LEVEL` env var
+* 5. the config file's log level (`configLevel`)
+*
+* Returns `undefined` when nothing applies, so `createLogger` falls back to
+* `"info"`. Resolving the whole chain here (rather than passing `configLevel`
+* straight through) keeps config below the env var.
+*
+* @param envPrefix - Upper-case env prefix of the CLI, e.g. `"HOLOCRON"`.
+* @param argv - The parsed global logging flags.
+* @param configLevel - The level from the CLI's config file, if one was loaded.
+*/
+function resolveLogLevel(envPrefix, argv, configLevel) {
+	if (argv.log) return argv.log;
+	if (argv.verbose) return "debug";
+	if (argv.quiet) return "error";
+	return parseLogLevel(env$1.get(`${envPrefix}_LOG_LEVEL`)) ?? configLevel;
+}
+// src/observability/create-cli-logger/create-cli-logger.ts
+/**
+* Create a CLI's logging functions around a memoized root `Logger`.
+*
+* Level comes from `--log` / `--verbose` / `--quiet`, then
+* `<PREFIX>_LOG_LEVEL`, then the config file. Console output is quiet unless
+* CI or a flag asks for it. `--quiet` and `--log` also turn the progress
+* spinner off (`allowProgress`), as they own the terminal.
+*
+* @example
+* const { buildCliLogger, getLogger, reportError } = createCliLogger({ envPrefix: "ACME" });
+*/
+function createCliLogger(options) {
+	const { envPrefix, resolveAxiom = () => resolveAxiomFromEnv() } = options;
+	let root;
+	let rootLevel;
+	let rootCommand;
+	let rootAxiomKey;
+	const levelFor = (argv, configLevel) => resolveLogLevel(envPrefix, argv, configLevel);
+	function buildCliLogger(argv, opts = {}) {
+		const { command, configLevel } = opts;
+		allowProgress(!argv.quiet && !argv.log);
+		if (command) rootCommand = command;
+		const level = levelFor(argv, configLevel);
+		const consoleOutput = resolveConsoleOutput(argv);
+		const axiom = resolveAxiom(opts, { command: command ?? rootCommand });
+		const axiomKey = axiom?.dataset;
+		const rebuildForConfig = configLevel !== void 0 && level !== rootLevel && !argv.verbose && !argv.quiet && !argv.log;
+		if (!root || rebuildForConfig || axiomKey !== void 0 && axiomKey !== rootAxiomKey) {
+			const built = createLogger({
+				...level ? { level } : {},
+				...axiom ? { axiom } : {},
+				...consoleOutput !== void 0 ? { consoleOutput } : {}
+			});
+			root = {
+				logger: rootCommand ? built.logger.child({ command: rootCommand }) : built.logger,
+				runId: built.runId
+			};
+			rootLevel = level;
+			rootAxiomKey = axiomKey;
+		}
+		return root;
+	}
+	function getLogger() {
+		return (root ??= createLogger({ consoleOutput: resolveConsoleOutput({}) })).logger;
+	}
+	return {
+		buildCliLogger,
+		getLogger,
+		reportError(message, log = getLogger()) {
+			console.error(style.fail(message));
+			log.error(message);
+		},
+		getRunId: () => root?.runId,
+		resetCliLogger() {
+			root = void 0;
+			rootLevel = void 0;
+			rootCommand = void 0;
+			rootAxiomKey = void 0;
+		},
+		resolveLogLevel: levelFor
+	};
+}
+// src/observability/create-cli-telemetry/create-cli-telemetry.ts
+const env = createEnvLookup();
+/**
+* Anonymous, stable per-machine id: `sha256(hostname + username)` truncated.
+* One-way, so no raw hostname or username is ever transmitted.
+*/
+function machineId() {
+	try {
+		return createHash("sha256").update(`${hostname()} ${userInfo().username}`).digest("hex").slice(0, 32);
+	} catch {
+		return "unknown";
+	}
+}
+/**
+* Create a CLI's self-telemetry: error reporting (Sentry) and usage analytics
+* (PostHog) behind the `ErrorSink` / `AnalyticsSink` seam of
+* `@theholocron/observability`. No-op sinks are installed until `init` finds
+* telemetry enabled, and the single kill switch is `<PREFIX>_TELEMETRY=false`
+* (legacy alias `NO_<PREFIX>_TELEMETRY`). The credentials are passed in, since
+* this reads no environment for them.
+*
+* @example
+* const telemetry = createCliTelemetry({
+*   envPrefix: "ACME",
+*   dsn: () => "https://key@o1.ingest.sentry.io/1",
+*   posthogKey: () => "phc_key",
+*   posthogHost: () => "https://us.i.posthog.com",
+* });
+*/
+function createCliTelemetry(options) {
+	const { envPrefix, dsn, posthogKey, posthogHost, getRunId = () => void 0 } = options;
+	let errors = new NoopErrorSink();
+	let analytics = new NoopAnalyticsSink();
+	let commandStartedAt = 0;
+	let currentCommand = "unknown";
+	let lastErrorType;
+	let currentSpan;
+	const isEnabled = () => env.get(`${envPrefix}_TELEMETRY`) !== "false" && !env.get(`NO_${envPrefix}_TELEMETRY`);
+	function baseProps() {
+		const runId = getRunId();
+		return {
+			command: currentCommand,
+			ci: Boolean(env.get("CI")),
+			...runId ? { runId } : {}
+		};
+	}
+	function event(name, properties = {}) {
+		analytics.capture(machineId(), name, redactObject({
+			...baseProps(),
+			...properties
+		}));
+	}
+	function resetSinks() {
+		errors = new NoopErrorSink();
+		analytics = new NoopAnalyticsSink();
+	}
+	return {
+		init(version) {
+			const resolvedDsn = dsn();
+			if (isEnabled() && resolvedDsn !== "") {
+				errors = new SentrySink();
+				errors.init({
+					dsn: resolvedDsn,
+					release: `${envPrefix.toLowerCase()}@${version}`,
+					environment: env.get("CI") ? "ci" : "local",
+					tags: {
+						os: process.platform,
+						node: process.version,
+						ci: String(Boolean(env.get("CI")))
+					}
+				});
+			}
+			const resolvedKey = posthogKey();
+			if (isEnabled() && resolvedKey !== "") {
+				analytics = new PostHogSink({
+					key: resolvedKey,
+					host: posthogHost()
+				});
+				const org = env.get(`${envPrefix}_ORG`);
+				analytics.identify(machineId(), {
+					ci: Boolean(env.get("CI")),
+					os: process.platform,
+					node: process.version,
+					cli: version,
+					...org ? { org } : {}
+				});
+			}
+		},
+		applyConfig(cfg) {
+			if (!cfg) return;
+			const drain = (p) => {
+				p.catch(() => {});
+			};
+			if (cfg.enabled === false) {
+				drain(errors.flush());
+				drain(analytics.shutdown());
+				resetSinks();
+				return;
+			}
+			if (cfg.analytics === "none") {
+				drain(analytics.shutdown());
+				analytics = new NoopAnalyticsSink();
+			}
+		},
+		event,
+		startCommand(name) {
+			currentCommand = name;
+			commandStartedAt = Date.now();
+			lastErrorType = void 0;
+			currentSpan = errors.startSpan(name);
+			event("command_started", { dry_run: process.argv.includes("--dry-run") });
+			return (ok) => {
+				currentSpan?.setStatus(ok);
+				currentSpan?.end();
+				event(ok ? "command_completed" : "command_failed", {
+					status: ok ? "ok" : "fail",
+					duration_ms: Date.now() - commandStartedAt,
+					...ok || !lastErrorType ? {} : { error_type: lastErrorType }
+				});
+			};
+		},
+		captureException(err) {
+			lastErrorType = err instanceof Error ? err.constructor.name : "Error";
+			errors.captureException(err);
+		},
+		endSession() {
+			errors.endSession();
+		},
+		async flush() {
+			await errors.flush();
+			await analytics.shutdown();
+			resetSinks();
+		},
+		resetTelemetry() {
+			resetSinks();
+			commandStartedAt = 0;
+			currentCommand = "unknown";
+			lastErrorType = void 0;
+			currentSpan = void 0;
+		}
+	};
+}
+export { createCliLogger, createCliTelemetry, resolveConsoleOutput, resolveLogLevel };

package/dist/prompts.d.mts

@@ -1,214 +1,2 @@
-/** 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 };
+import { a as promptForOptions, c as OptionPrompt, d as pickMenuItem, f as searchChoices, i as promptForDeferredOptions, l as OptionsCommand, n as PositionalCommand, o as OptionAnswer, p as MenuItem, r as PositionalPrompt, s as OptionMode, t as promptForPositionals, u as ResolvedOptions } from "./index-DpXxO_wH.mjs";
+export { type MenuItem, type OptionAnswer, type OptionMode, type OptionPrompt, type OptionsCommand, type PositionalCommand, type PositionalPrompt, type ResolvedOptions, pickMenuItem, promptForDeferredOptions, promptForOptions, promptForPositionals, searchChoices };

package/dist/prompts.mjs

@@ -1,6 +1,6 @@
 import { t as NonInteractiveError } from "./non-interactive-error-Mm_Mn79M.mjs";
-import search from "@inquirer/search";
 import { checkbox, confirm, input, password, select } from "@inquirer/prompts";
+import search from "@inquirer/search";
 // src/prompts/menu/menu.ts
 /**
 * Searchable autocomplete over one menu level's `items`. `select()` would work too