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

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,8 +1,8 @@
+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 { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 import yargs from "yargs";
 // src/testing/cli-runner/cli-runner.ts

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,35 @@ 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>;
+/** What {@link createRetryNotice} reads from one retry. Structurally compatible with `@theholocron/http-client`'s `RetryEvent`. */
+interface RetryNoticeEvent {
+  /** The service being called, when the client knows it. */
+  vendor?: string | undefined;
+  /** The attempt about to be made. */
+  attempt: number;
+  /** How many attempts there are in all. */
+  of: number;
+}
+/** Registers a handler for retries and returns a function that removes it. */
+type RetrySubscribe = (handler: (event: RetryNoticeEvent) => void) => () => void;
+/**
+ * Builds a {@link ProgressListener} that says on the spinner when a request is being sent again, so a slow step is
+ * not mistaken for a stuck one. `subscribe` is the HTTP client's retry hook (e.g. `onRetry`), which keeps kyber free
+ * of any client dependency.
+ */
+export declare function createRetryNotice(subscribe: RetrySubscribe): ProgressListener;
+/**
+ * {@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 +170,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. */
@@ -148,4 +202,4 @@ export declare const style: {
  * streams are parameters so a test can answer for the user.
  */
 export declare function waitForEnter(message: string, input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream): Promise<"enter" | "closed">;
-export type { Container, Key, Line, Path, Progress, ProgressListener, RenderOptions, RowStatus, ViewJsonOptions, ViewState };
+export type { Container, Key, Line, Path, Progress, ProgressListener, RenderOptions, RetryNoticeEvent, RetrySubscribe, RowStatus, ViewJsonOptions, ViewState };

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 {
@@ -326,6 +391,17 @@ function createProgress(print, enabled = progressEnabled, listen) {
 function withProgress(label, fn, listen) {
 	return createProgress(() => {}, progressEnabled, listen).run(label, fn);
 }
+// src/ui/retry-notice/retry-notice.ts
+/**
+* Builds a {@link ProgressListener} that says on the spinner when a request is being sent again, so a slow step is
+* not mistaken for a stuck one. `subscribe` is the HTTP client's retry hook (e.g. `onRetry`), which keeps kyber free
+* of any client dependency.
+*/
+function createRetryNotice(subscribe) {
+	return (label, setText) => subscribe((e) => {
+		setText(`${label} (retrying ${e.vendor ?? "the request"}, attempt ${e.attempt} of ${e.of})`);
+	});
+}
 // src/ui/style/style.ts
 /** Formats a message with a status marker and colour: one helper per kind of line a command prints. */
 const style = {
@@ -388,4 +464,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, createRetryNotice, describeError, expandToDepth, logReason, openPath, pad, progressEnabled, reduceKey, renderTree, sanitizeDetail, setProgressListener, statusRow, stripControl, style, viewJson, waitForEnter, withProgress, withSpinner };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@theholocron/kyber",
-  "version": "5.0.0-alpha.340",
-  "description": "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.",
+  "version": "5.0.0-alpha.342",
+  "description": "The reusable parts of a command-line tool: terminal output, prompts, the interactive menu, the update notifier, safe handling of tokens, a test harness and the global flags.",
   "keywords": [
     "cli",
     "holocron",
@@ -20,16 +20,31 @@
   "sideEffects": false,
   "type": "module",
   "exports": {
+    "./config": {
+      "types": "./dist/config.d.mts",
+      "import": "./dist/config.mjs",
+      "default": "./dist/config.mjs"
+    },
     "./flags": {
       "types": "./dist/flags.d.mts",
       "import": "./dist/flags.mjs",
       "default": "./dist/flags.mjs"
     },
+    "./menu": {
+      "types": "./dist/menu.d.mts",
+      "import": "./dist/menu.mjs",
+      "default": "./dist/menu.mjs"
+    },
     "./notifier": {
       "types": "./dist/notifier.d.mts",
       "import": "./dist/notifier.mjs",
       "default": "./dist/notifier.mjs"
     },
+    "./observability": {
+      "types": "./dist/observability.d.mts",
+      "import": "./dist/observability.mjs",
+      "default": "./dist/observability.mjs"
+    },
     "./prompts": {
       "types": "./dist/prompts.d.mts",
       "import": "./dist/prompts.mjs",
@@ -54,6 +69,9 @@
   "files": [
     "dist"
   ],
+  "dependencies": {
+    "@theholocron/env-utils": "^1.17.0-alpha.1"
+  },
   "devDependencies": {
     "@inquirer/prompts": "^8.7.5",
     "@inquirer/search": "^4.3.6",
@@ -73,9 +91,11 @@
     "vitest": "^5.0.5",
     "yargs": "^18.1.0",
     "@theholocron/tsconfig": "^8.9.0-alpha.8",
-    "@theholocron/vitest-config": "^8.9.0-alpha.8",
+    "@theholocron/eslint-config": "^8.9.0-alpha.8",
+    "@theholocron/observability": "0.7.0-alpha.1",
     "@theholocron/tsdown-config": "^8.9.0-alpha.8",
-    "@theholocron/eslint-config": "^8.9.0-alpha.8"
+    "@theholocron/vitest-config": "^8.9.0-alpha.8",
+    "@theholocron/datapad": "5.0.0-alpha.342"
   },
   "peerDependencies": {
     "@inquirer/prompts": "^8.0.0",
@@ -85,7 +105,9 @@
     "clipboardy": "^5.0.0",
     "dotenv": "^17.0.0",
     "ora": "^9.0.0",
-    "yargs": "^18.0.0"
+    "yargs": "^18.0.0",
+    "@theholocron/datapad": "^5.0.0-alpha.342",
+    "@theholocron/observability": "^0.7.0-alpha.1"
   },
   "peerDependenciesMeta": {
     "@inquirer/prompts": {
@@ -97,6 +119,12 @@
     "@napi-rs/keyring": {
       "optional": true
     },
+    "@theholocron/datapad": {
+      "optional": true
+    },
+    "@theholocron/observability": {
+      "optional": true
+    },
     "chalk": {
       "optional": true
     },