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

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

package/dist/secrets.d.mts

@@ -13,6 +13,14 @@ export declare class TokenParseError extends Error {
  * Values may contain "=" (e.g. base64 strings) — only the first "=" is treated as a separator.
  */
 export declare function parseTokenArgs(tokens: string[]): ParsedTokenArgs;
+/**
+ * Thrown by a token resolver when no token was found in any source. Its message says how to supply one. A caller that
+ * may load a second copy of this package matches it by `name`, not `instanceof`.
+ */
+export declare class AuthError extends Error {
+  /** The error name, `AuthError`. */
+  name: string;
+}
 /** Puts `text` on the system clipboard through `clipboardy`, which uses the platform's own tool. Loaded only when called. */
 export declare function copyToClipboard(text: string): Promise<void>;
 /**
@@ -90,6 +98,78 @@ export declare function readDotenvFile(repoRoot: string): Record<string, string>
  * none of these is `null`, and the caller says so rather than exporting a different token.
  */
 export declare function dotenvLine(name: string, value: string): string | null;
+/** Where a token resolver looks for a token, beyond what it was configured with. */
+interface ResolveTokenInput {
+  /** The `--token` flag. */
+  cliToken?: string;
+  /** The environment to read. Default `process.env`; a test passes its own. */
+  env?: NodeJS.ProcessEnv;
+  /** Looks an account up in the keyring. Replaces the configured lookup and the credential store; a test passes its own. */
+  keyring?: (account: string) => string | null;
+  /** The active org. It selects the keyring account `<service>.<org>` first. Default: the variable `orgEnvName` names. */
+  org?: string;
+}
+/** How {@link createResolveToken} finds one vendor's token. */
+interface ResolveTokenConfig {
+  /** The tool's own variable for this token, such as `MYTOOL_GITHUB_TOKEN`. */
+  envName: string;
+  /** The vendor's own variable for it, such as `GITHUB_TOKEN`. */
+  vendorEnvName: string;
+  /** The keyring account the token is stored under, such as `github`. */
+  keyringService: string;
+  /** The whole message of the {@link AuthError} thrown when no source has a token, saying how to supply one. */
+  errorMessage: string;
+  /** Looks an account up in the keyring, such as the `get` of {@link createKeyring}. Default: the keyring is not asked. */
+  keyring?: (account: string) => string | null;
+  /** The variable that names the active org, such as `MYTOOL_ORG`. Default: no org-scoped lookup unless `input.org` is given. */
+  orgEnvName?: string;
+}
+/** What {@link createResolveToken} returns: call it for the token, or it throws {@link AuthError}. */
+type TokenResolver = (input?: ResolveTokenInput) => string;
+/**
+ * A function that finds one vendor's token, for a tool to call once at module level.
+ *
+ * @remarks
+ * It tries, in order: `input.cliToken` (the `--token` flag), `envName`, `vendorEnvName`, the variables the `credentials`
+ * providers returned (see {@link setCredentials}), the keyring account `<service>.<org>` (only when an org is known),
+ * then the account `<service>`. An empty string counts as unset everywhere. It throws {@link AuthError} with
+ * `errorMessage` when none has a token. An `input.keyring` replaces the credential store and the keyring together.
+ *
+ * @example
+ * ```ts
+ * const resolveToken = createResolveToken({
+ *   envName: "MYTOOL_GITHUB_TOKEN",
+ *   vendorEnvName: "GITHUB_TOKEN",
+ *   keyringService: "github",
+ *   errorMessage: "no GitHub token found. Pass --token, or set MYTOOL_GITHUB_TOKEN or GITHUB_TOKEN.",
+ *   keyring: (account) => keyring.get(account),
+ *   orgEnvName: "MYTOOL_ORG",
+ * });
+ * ```
+ */
+export declare function createResolveToken(config: ResolveTokenConfig): TokenResolver;
+/** How {@link createFeatureResolver} finds the token for one feature. */
+interface FeatureResolverConfig {
+  /** The variable for this feature's token, such as `MYTOOL_ISSUES_TOKEN`. */
+  envName: string;
+  /** The keyring account it is stored under, such as `github.issues`. */
+  keyringKey: string;
+  /** The vendor named in the "no token" message, such as `GitHub`. */
+  vendor: string;
+  /** The command that stores a token, for the "no token" message, given the keyring account: `mytool auth set <key> <token>`. */
+  setCommand?: (keyringKey: string) => string;
+  /** Looks an account up in the keyring, such as the `get` of {@link createKeyring}. Default: the keyring is not asked. */
+  keyring?: (account: string) => string | null;
+}
+/** What {@link createFeatureResolver} returns: call it for the token, or it throws {@link AuthError}. */
+type FeatureTokenResolver = (input?: ResolveTokenInput) => string;
+/**
+ * A strict resolver for one feature's token. It tries `input.cliToken`, then `envName`, then the variable of that name
+ * from the `credentials` providers, then the keyring account `keyringKey`. There is no fallback to a broad token: when
+ * the feature's own token is absent it throws {@link AuthError} naming the exact variable to set. An `input.keyring`
+ * replaces the credential store and the keyring together.
+ */
+export declare function createFeatureResolver(config: FeatureResolverConfig): FeatureTokenResolver;
 /**
  * What git says about a path: `ignored` when a rule ignores it, `tracked` when git would track it, `no-repo` when the
  * path is not in a git repository (or git is not installed, in which case nothing can commit it), and `unknown` when
@@ -188,4 +268,4 @@ export declare function createPrivateFile(path: string, text: string, write?: (f
  * `remove` is how the path is deleted; it is a parameter so a test can look at the file just before it goes.
  */
 export declare function shredFile(path: string, identity: FileIdentity, remove?: (path: string) => void): ShredOutcome;
-export type { FileIdentity, GitIgnoreState, Keyring, KeyringBinding, KeyringEntry, KeyringOptions, ParsedTokenArgs, ShredOutcome };
+export type { FeatureResolverConfig, FeatureTokenResolver, FileIdentity, GitIgnoreState, Keyring, KeyringBinding, KeyringEntry, KeyringOptions, ParsedTokenArgs, ResolveTokenConfig, ResolveTokenInput, ShredOutcome, TokenResolver };

package/dist/secrets.mjs

@@ -1,10 +1,19 @@
 import { n as parseTokenArgs, t as TokenParseError } from "./token-args-BgrCq_kK.mjs";
 import { createRequire } from "node:module";
+import { execFileSync } from "node:child_process";
 import { closeSync, constants, fchmodSync, fstatSync, fsyncSync, lstatSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { randomBytes } from "node:crypto";
 import { parse } from "dotenv";
-import { execFileSync } from "node:child_process";
+// src/secrets/auth-error/auth-error.ts
+/**
+* Thrown by a token resolver when no token was found in any source. Its message says how to supply one. A caller that
+* may load a second copy of this package matches it by `name`, not `instanceof`.
+*/
+var AuthError = class extends Error {
+	/** The error name, `AuthError`. */
+	name = "AuthError";
+};
 // src/secrets/copy-to-clipboard/copy-to-clipboard.ts
 /** Puts `text` on the system clipboard through `clipboardy`, which uses the platform's own tool. Loaded only when called. */
 async function copyToClipboard(text) {
@@ -210,6 +219,37 @@ function dotenvLine(name, value) {
 	const quote = QUOTES.find((q) => !value.includes(q));
 	return quote ? `${name}=${quote}${value}${quote}` : null;
 }
+// src/secrets/first-env/first-env.ts
+/**
+* The first non-empty value among `names` in `env` (the process environment when none is given). An empty string counts
+* as unset, so a blank `TOKEN=` line does not hide the next name.
+*/
+function firstEnv(env, ...names) {
+	const source = env ?? process.env;
+	for (const name of names) {
+		const value = source[name];
+		if (value) return value;
+	}
+}
+// src/secrets/feature-resolver/feature-resolver.ts
+/**
+* A strict resolver for one feature's token. It tries `input.cliToken`, then `envName`, then the variable of that name
+* from the `credentials` providers, then the keyring account `keyringKey`. There is no fallback to a broad token: when
+* the feature's own token is absent it throws {@link AuthError} naming the exact variable to set. An `input.keyring`
+* replaces the credential store and the keyring together.
+*/
+function createFeatureResolver(config) {
+	const stored = (account) => getCredential(config.envName) ?? config.keyring?.(account) ?? null;
+	return function resolveFeatureToken(input = {}) {
+		const lookup = input.keyring ?? stored;
+		const token = input.cliToken || firstEnv(input.env, config.envName) || lookup(config.keyringKey);
+		if (!token) {
+			const how = config.setCommand ? `, or run: ${config.setCommand(config.keyringKey)}` : "";
+			throw new AuthError(`no ${config.vendor} token found for this operation. Pass --token <token>, set ${config.envName}${how}`);
+		}
+		return token;
+	};
+}
 // src/secrets/git-ignored/git-ignored.ts
 /**
 * Ask git whether it ignores `path` (see {@link GitIgnoreState}). A caller that must not leave a file where it could be
@@ -326,4 +366,36 @@ function createKeyring(options) {
 		}
 	};
 }
-export { DOTENV_FILE, TokenParseError, clearCredentials, copyToClipboard, createKeyring, createPrivateFile, dotenvLine, getCredential, hasCredentials, isGitIgnored, parseTokenArgs, readDotenvFile, setCredentials, shredFile, writeCredentialsFile };
+// src/secrets/resolve-token/resolve-token.ts
+/**
+* A function that finds one vendor's token, for a tool to call once at module level.
+*
+* @remarks
+* It tries, in order: `input.cliToken` (the `--token` flag), `envName`, `vendorEnvName`, the variables the `credentials`
+* providers returned (see {@link setCredentials}), the keyring account `<service>.<org>` (only when an org is known),
+* then the account `<service>`. An empty string counts as unset everywhere. It throws {@link AuthError} with
+* `errorMessage` when none has a token. An `input.keyring` replaces the credential store and the keyring together.
+*
+* @example
+* ```ts
+* const resolveToken = createResolveToken({
+*   envName: "MYTOOL_GITHUB_TOKEN",
+*   vendorEnvName: "GITHUB_TOKEN",
+*   keyringService: "github",
+*   errorMessage: "no GitHub token found. Pass --token, or set MYTOOL_GITHUB_TOKEN or GITHUB_TOKEN.",
+*   keyring: (account) => keyring.get(account),
+*   orgEnvName: "MYTOOL_ORG",
+* });
+* ```
+*/
+function createResolveToken(config) {
+	const stored = (account) => getCredential(config.envName, config.vendorEnvName) ?? config.keyring?.(account) ?? null;
+	return function resolveToken(input = {}) {
+		const lookup = input.keyring ?? stored;
+		const org = input.org ?? (config.orgEnvName ? firstEnv(input.env, config.orgEnvName) : void 0);
+		const token = input.cliToken || firstEnv(input.env, config.envName, config.vendorEnvName) || (org ? lookup(`${config.keyringService}.${org}`) : null) || lookup(config.keyringService);
+		if (!token) throw new AuthError(config.errorMessage);
+		return token;
+	};
+}
+export { AuthError, DOTENV_FILE, TokenParseError, clearCredentials, copyToClipboard, createFeatureResolver, createKeyring, createPrivateFile, createResolveToken, dotenvLine, getCredential, hasCredentials, isGitIgnored, parseTokenArgs, readDotenvFile, setCredentials, shredFile, writeCredentialsFile };

package/dist/testing.mjs

@@ -1,6 +1,6 @@
+import { execFileSync, spawn } from "node:child_process";
 import { existsSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { dirname, join, sep } from "node:path";
-import { execFileSync, spawn } from "node:child_process";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { fileURLToPath } from "node:url";

package/dist/ui.d.mts

@@ -1,3 +1,16 @@
+/**
+ * The line to print for an error that reached the top of a command: {@link describeError | describeError}'s text, and
+ * never empty, so a failure always says something. An error with no message prints its class name; anything else with
+ * no text prints "the command failed".
+ */
+export declare function commandFailureMessage(err: unknown): string;
+/**
+ * What to print for a caught value: its message with control characters stripped (a provider's text can carry them),
+ * and, when the error has a non-empty `details` (the raw response body of an API error, say), that body after it,
+ * sanitized and length-capped. A bare "GET /x → 403" then says why, and the vendor's text cannot flood or manipulate the
+ * terminal. Anything that is not an `Error` is printed with `String()`.
+ */
+export declare function describeError(err: unknown): string;
 /** A JSON-pointer-ish path: `""` is the root, children append `/<key>`. */
 type Path = string;
 /** One rendered line of the viewer. */
@@ -57,6 +70,12 @@ export declare function reduceKey(state: ViewState, key: Key, value: unknown, ro
  * coloured tree, collapsed past `depth`. `interactive` opens a folding viewer (the default on a TTY).
  */
 export declare function viewJson(value: unknown, options?: ViewJsonOptions): Promise<void>;
+/**
+ * What to put in structured logs: the plain message of the underlying error, with no response body. The detail
+ * {@link describeError} adds is for the person at the terminal; a provider's raw body has no business in telemetry. A
+ * wrapper error carries the original as `cause`, so this looks through one level.
+ */
+export declare function logReason(err: unknown): string;
 /**
  * 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
@@ -93,6 +112,12 @@ type ProgressListener = (label: string, setText: (text: string) => void) => () =
 export declare function withSpinner<T>(label: string, fn: () => Promise<T>): Promise<T>;
 /** Turn progress off for the run (`--quiet`, `--log`), so nothing extra shares the terminal with what those print. */
 export declare function allowProgress(on: boolean): void;
+/**
+ * Hooks `listener` into every step that does not pass its own, such as a notice that a request is being sent again.
+ * Called once at start-up, so each call site stays a plain {@link createProgress} or {@link withProgress}. Pass
+ * `undefined` to take it off again.
+ */
+export declare function setProgressListener(listener: ProgressListener | undefined): void;
 /**
  * Whether to draw a progress line: only when a person is watching a terminal (stdout and stderr both), not in CI, and not
  * switched off. Everywhere else the output stays the plain line-per-step text that scripts and the docs rely on.
@@ -100,12 +125,18 @@ export declare function allowProgress(on: boolean): void;
 export declare function progressEnabled(): boolean;
 /**
  * A spinner for one step at a time that a step can print through. Steps that only return a result use {@link
- * withProgress}; a step that prints its own result line while it runs prints through `print`. A `listen` hook can change the
- * spinner's text while the step runs, for instance to say that a request is being sent again.
+ * withProgress}; a step that prints its own result line while it runs prints through `print`. A `listen` hook, or else the
+ * one set with {@link setProgressListener}, can change the spinner's text while the step runs, for instance to say that
+ * a request is being sent again.
  */
 export declare function createProgress(print: (line: string) => void, enabled?: () => boolean, listen?: ProgressListener): Progress;
 /** `fn` under a cleared-when-done spinner named `label`, on a terminal only. */
 export declare function withProgress<T>(label: string, fn: () => Promise<T>, listen?: ProgressListener): Promise<T>;
+/**
+ * {@link stripControl}, then cut to 200 characters with an ellipsis. For a vendor's response body or any other text of
+ * unknown size that lands in the terminal.
+ */
+export declare function sanitizeDetail(text: string): string;
 /** How a row of a check or setup run came out: it passed, it failed, or it was skipped. */
 type RowStatus = "ok" | "fail" | "skip";
 /** Right-pads `s` to `width` with spaces — never truncates. */
@@ -122,6 +153,12 @@ export declare function pad(s: string, width: number): string;
  * destination / reason) so every status table in the CLI reads the same way.
  */
 export declare function statusRow(status: RowStatus, columns: string[]): string;
+/**
+ * Control characters (newlines and the C1 range included, whose 0x9b is an 8-bit CSI) turned into spaces and whitespace
+ * collapsed, with no length cap. For text from outside the process that is about to reach a terminal, where a crafted
+ * value could otherwise forge extra lines or inject escape sequences.
+ */
+export declare function stripControl(text: string): string;
 /** Formats a message with a status marker and colour: one helper per kind of line a command prints. */
 export declare const style: {
   /** A green `✓` for something that worked. */

package/dist/ui.mjs

@@ -3,6 +3,51 @@ import chalk from "chalk";
 import { spawn } from "node:child_process";
 import ora from "ora";
 import { createInterface } from "node:readline";
+// src/ui/strip-control/strip-control.ts
+/**
+* Control characters (newlines and the C1 range included, whose 0x9b is an 8-bit CSI) turned into spaces and whitespace
+* collapsed, with no length cap. For text from outside the process that is about to reach a terminal, where a crafted
+* value could otherwise forge extra lines or inject escape sequences.
+*/
+function stripControl(text) {
+	return text.replace(/[\x00-\x1f\x7f-\x9f]/g, " ").replace(/\s+/g, " ").trim();
+}
+// src/ui/sanitize-detail/sanitize-detail.ts
+/** The longest a detail is kept, so one oversized body cannot flood a report. */
+const MAX_DETAIL_LENGTH = 200;
+/**
+* {@link stripControl}, then cut to 200 characters with an ellipsis. For a vendor's response body or any other text of
+* unknown size that lands in the terminal.
+*/
+function sanitizeDetail(text) {
+	const stripped = stripControl(text);
+	return stripped.length > MAX_DETAIL_LENGTH ? `${stripped.slice(0, MAX_DETAIL_LENGTH)}…` : stripped;
+}
+// src/ui/describe-error/describe-error.ts
+/**
+* What to print for a caught value: its message with control characters stripped (a provider's text can carry them),
+* and, when the error has a non-empty `details` (the raw response body of an API error, say), that body after it,
+* sanitized and length-capped. A bare "GET /x → 403" then says why, and the vendor's text cannot flood or manipulate the
+* terminal. Anything that is not an `Error` is printed with `String()`.
+*/
+function describeError(err) {
+	const base = stripControl(err instanceof Error ? err.message : String(err));
+	const details = err instanceof Error ? err.details : void 0;
+	if (details) {
+		const detail = sanitizeDetail(String(details));
+		if (detail) return `${base}: ${detail}`;
+	}
+	return base;
+}
+// src/ui/command-failure/command-failure.ts
+/**
+* The line to print for an error that reached the top of a command: {@link describeError | describeError}'s text, and
+* never empty, so a failure always says something. An error with no message prints its class name; anything else with
+* no text prints "the command failed".
+*/
+function commandFailureMessage(err) {
+	return describeError(err) || (err instanceof Error ? err.name : "the command failed");
+}
 // src/ui/json-view/json-view.ts
 function isContainer(value) {
 	return typeof value === "object" && value !== null;
@@ -221,6 +266,16 @@ async function viewJson(value, options = {}) {
 	const lines = renderTree(value, { expanded: expandToDepth(value, depth) });
 	console.log(lines.map((l) => l.text).join("\n"));
 }
+// src/ui/log-reason/log-reason.ts
+/**
+* What to put in structured logs: the plain message of the underlying error, with no response body. The detail
+* {@link describeError} adds is for the person at the terminal; a provider's raw body has no business in telemetry. A
+* wrapper error carries the original as `cause`, so this looks through one level.
+*/
+function logReason(err) {
+	const root = err instanceof Error && err.cause !== void 0 ? err.cause : err;
+	return root instanceof Error ? root.message : String(root);
+}
 // src/ui/open-path/open-path.ts
 /** Platform-appropriate command to open a path in the OS's file browser. */
 function openCommand(path) {
@@ -275,11 +330,20 @@ async function withSpinner(label, fn) {
 	}
 }
 let allowed = true;
+let defaultListener;
 /** Turn progress off for the run (`--quiet`, `--log`), so nothing extra shares the terminal with what those print. */
 function allowProgress(on) {
 	allowed = on;
 }
 /**
+* Hooks `listener` into every step that does not pass its own, such as a notice that a request is being sent again.
+* Called once at start-up, so each call site stays a plain {@link createProgress} or {@link withProgress}. Pass
+* `undefined` to take it off again.
+*/
+function setProgressListener(listener) {
+	defaultListener = listener;
+}
+/**
 * Whether to draw a progress line: only when a person is watching a terminal (stdout and stderr both), not in CI, and not
 * switched off. Everywhere else the output stays the plain line-per-step text that scripts and the docs rely on.
 */
@@ -288,8 +352,9 @@ function progressEnabled() {
 }
 /**
 * A spinner for one step at a time that a step can print through. Steps that only return a result use {@link
-* withProgress}; a step that prints its own result line while it runs prints through `print`. A `listen` hook can change the
-* spinner's text while the step runs, for instance to say that a request is being sent again.
+* withProgress}; a step that prints its own result line while it runs prints through `print`. A `listen` hook, or else the
+* one set with {@link setProgressListener}, can change the spinner's text while the step runs, for instance to say that
+* a request is being sent again.
 */
 function createProgress(print, enabled = progressEnabled, listen) {
 	let active;
@@ -302,7 +367,7 @@ function createProgress(print, enabled = progressEnabled, listen) {
 				discardStdin: false
 			}).start();
 			active = spinner;
-			const stopListening = listen?.(label, (text) => {
+			const stopListening = (listen ?? defaultListener)?.(label, (text) => {
 				spinner.text = text;
 			});
 			try {
@@ -388,4 +453,4 @@ function waitForEnter(message, input = process.stdin, output = process.stderr) {
 		});
 	});
 }
-export { NonInteractiveError, allowProgress, createProgress, expandToDepth, openPath, pad, progressEnabled, reduceKey, renderTree, statusRow, style, viewJson, waitForEnter, withProgress, withSpinner };
+export { NonInteractiveError, allowProgress, commandFailureMessage, createProgress, describeError, expandToDepth, logReason, openPath, pad, progressEnabled, reduceKey, renderTree, sanitizeDetail, setProgressListener, statusRow, stripControl, style, viewJson, waitForEnter, withProgress, withSpinner };