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

package/README.md

@@ -10,16 +10,17 @@ Published, so a second CLI can import it. `@theholocron/cli` is its first consum
 
 ## Subpaths
 
-| Subpath     | What it gives a CLI                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `/ui`       | Status glyphs and colours, padded status rows, a depth-limited JSON view, a spinner that only shows on a terminal, wait-for-Enter, open-in-file-browser, the error for "a prompt was needed but there is no terminal", and the cleaning of error text before it reaches a terminal (`describeError`, `commandFailureMessage`, `logReason`, `sanitizeDetail`, `stripControl`).                                                                                                                                                                                                                                                                                                     |
-| `/notifier` | A cached, best-effort "a newer version exists" notice for an npm package: `checkForUpdates({ name, currentVersion, cacheDir })` returns a function that prints a boxed notice to stderr, or `null`. Silent in CI and with `NO_UPDATE_NOTIFIER`.                                                                                                                                                                                                                                                                                                                                                                                                                                   |
-| `/secrets`  | Handling tokens safely, with no terminal UI: owner-only (`0600`) files, shredding a file that held tokens, "does git ignore this path", dotenv lines that survive quoting, reading a `.env` at the repo root, the clipboard, the OS keyring (`createKeyring({ service })`, best-effort, `@napi-rs/keyring` optional), an in-process store for credentials a provider returned, `--token` / `--token vendor=value` parsing, and resolving a token from the flag, the environment, that store and the keyring (`createResolveToken`, `createFeatureResolver`, `AuthError`).                                                                                                         |
-| `/prompts`  | A searchable menu (`pickMenuItem`), and prompting for the positionals and options a command left out (`promptForPositionals`, `promptForOptions`): required options always asked, the rest behind one checkbox, mutually exclusive `modes`, secret options masked, and a value that is asked last (`askLast`). They take small structural types (`PositionalCommand`, `OptionsCommand`), not the CLI's command registry.                                                                                                                                                                                                                                                          |
-| `/menu`     | The interactive menu of a CLI, driven by data: `launchMenu(entries, argv, { bin, envPrefix })` shows a searchable, nested picker over a list of `MenuEntry`, asks for the positionals and options the command needs, then spawns the CLI again with the answers. A command that supports `--dry-run` is previewed first and then confirmed (`--skip-dry-run` opts out); a preview that reports `DRY_RUN_NOOP_EXIT_CODE` skips the question. Secret options never reach argv: they travel as `<envPrefix>_<OPTION>` env vars, and a preview child gets `dryRunPreviewEnvVar(envPrefix)`. Also `menuItems`, `buildChildArgv`, `forwardedFlags`, `secretEnv`, `shouldPreviewDryRun`. |
-| `/testing`  | A test harness for a CLI: `createCliRunner` runs a built binary in a fresh directory with an environment built from nothing, `runCommand` runs one yargs command module through a real parse, `ensureBuilt` is a Vitest global setup that builds only when `dist` is missing or stale, and `hermeticCreateRequire` resolves modules only from one directory.                                                                                                                                                                                                                                                                                                                      |
-| `/config`   | A `<name>.config.{ts,js,mjs,cjs,json}` for a new CLI: `createConfigSystem({ name, derive?, resolve, merge })` returns `defineConfig`, `loadConfig` (walks up to `.git`) and `compose()` (dedupe by `id`, all unmet `requires` in one `ConfigError`, per-key merge). Strategies: `lastWins`, `shallowMerge`, `union`, `mergeByKey`. `@theholocron/datapad` is an optional peer.                                                                                                                                                                                                                                                                                                    |
-| `/flags`    | The options every command of a tool takes: `addGlobalOptions(parser, { describe?, cwd? })` declares `--dry-run`, a repeatable `--token` and `--cwd` once on the root; `tokenContext(values, report)` parses the `--token` values and reports a bad one without a stack trace; `groupMenu(parent, open)` is the hidden default command that makes a bare group (`tool repo`) do something useful; `InferArgs` types a command's handler arguments from its builder.                                                                                                                                                                                                                |
+| 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 (and `createRetryNotice(subscribe)`, which says on it when a request is retried, given the HTTP client's retry hook), wait-for-Enter, open-in-file-browser, the error for "a prompt was needed but there is no terminal", and the cleaning of error text before it reaches a terminal (`describeError`, `commandFailureMessage`, `logReason`, `sanitizeDetail`, `stripControl`).                                                                                                                                                                                                                                                                                                            |
+| `/notifier`      | A cached, best-effort "a newer version exists" notice for an npm package: `checkForUpdates({ name, currentVersion, cacheDir })` returns a function that prints a boxed notice to stderr, or `null`. Silent in CI and with `NO_UPDATE_NOTIFIER`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `/secrets`       | Handling tokens safely, with no terminal UI: owner-only (`0600`) files, shredding a file that held tokens, "does git ignore this path", dotenv lines that survive quoting, reading a `.env` at the repo root, the clipboard, the OS keyring (`createKeyring({ service })`, best-effort, `@napi-rs/keyring` optional), an in-process store for credentials a provider returned, `--token` / `--token vendor=value` parsing, and resolving a token from the flag, the environment, that store and the keyring (`createResolveToken`, `createFeatureResolver`, `AuthError`).                                                                                                                                                                                                                                     |
+| `/prompts`       | A searchable menu (`pickMenuItem`), and prompting for the positionals and options a command left out (`promptForPositionals`, `promptForOptions`): required options always asked, the rest behind one checkbox, mutually exclusive `modes`, secret options masked, and a value that is asked last (`askLast`). They take small structural types (`PositionalCommand`, `OptionsCommand`), not the CLI's command registry.                                                                                                                                                                                                                                                                                                                                                                                      |
+| `/menu`          | The interactive menu of a CLI, driven by data: `launchMenu(entries, argv, { bin, envPrefix })` shows a searchable, nested picker over a list of `MenuEntry`, asks for the positionals and options the command needs, then spawns the CLI again with the answers. A command that supports `--dry-run` is previewed first and then confirmed (`--skip-dry-run` opts out); a preview that reports `DRY_RUN_NOOP_EXIT_CODE` skips the question. Secret options never reach argv: they travel as `<envPrefix>_<OPTION>` env vars, and a preview child gets `dryRunPreviewEnvVar(envPrefix)`. `createMenu({ bin, envPrefix })` binds it once (returning `launchMenu(entries, argv, options?)` and `dryRunPreviewEnvVar`). Also `menuItems`, `buildChildArgv`, `forwardedFlags`, `secretEnv`, `shouldPreviewDryRun`. |
+| `/testing`       | A test harness for a CLI: `createCliRunner` runs a built binary in a fresh directory with an environment built from nothing, `runCommand` runs one yargs command module through a real parse, `ensureBuilt` is a Vitest global setup that builds only when `dist` is missing or stale, and `hermeticCreateRequire` resolves modules only from one directory.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `/observability` | The logging and telemetry wiring of a CLI: `createCliLogger({ envPrefix, resolveAxiom? })` returns a memoized root logger (`buildCliLogger`, `getLogger`, `reportError`, `getRunId`, `resolveLogLevel`) whose level comes from `--log` / `--verbose` / `--quiet`, then `<PREFIX>_LOG_LEVEL`, then the config file, and is quiet on a terminal unless asked; `createCliTelemetry({ envPrefix, dsn, posthogKey, posthogHost })` returns Sentry error reporting and PostHog analytics behind `<PREFIX>_TELEMETRY=false`. `@theholocron/observability` is an optional peer.                                                                                                                                                                                                                                       |
+| `/config`        | A `<name>.config.{ts,js,mjs,cjs,json}` for a new CLI: `createConfigSystem({ name, derive?, resolve, merge })` returns `defineConfig`, `loadConfig` (walks up to `.git`) and `compose()` (dedupe by `id`, all unmet `requires` in one `ConfigError`, per-key merge). Strategies: `lastWins`, `shallowMerge`, `union`, `mergeByKey`. `@theholocron/datapad` is an optional peer.                                                                                                                                                                                                                                                                                                                                                                                                                                |
+| `/flags`         | The options every command of a tool takes: `addGlobalOptions(parser, { describe?, cwd? })` declares `--dry-run`, a repeatable `--token` and `--cwd` once on the root; `tokenContext(values, report)` parses the `--token` values and reports a bad one without a stack trace; `groupMenu(parent, open)` is the hidden default command that makes a bare group (`tool repo`) do something useful; `InferArgs` types a command's handler arguments from its builder.                                                                                                                                                                                                                                                                                                                                            |
 
 ## Usage
 
@@ -49,7 +50,7 @@ const tokens = tokenContext(argv.token, console.error); // null (and exit code 1
 const keyring = createKeyring({ service: "com.example.tool" }); // best-effort: never throws
 ```
 
-Each subpath's heavy libraries (`chalk`, `ora`, `@inquirer/prompts`, `yargs`, `dotenv`, `clipboardy`, `@napi-rs/keyring`, `@theholocron/datapad`) are
+Each subpath's heavy libraries (`chalk`, `ora`, `@inquirer/prompts`, `yargs`, `dotenv`, `clipboardy`, `@napi-rs/keyring`, `@theholocron/datapad`, `@theholocron/observability`) are
 optional peer dependencies: a CLI installs the ones for the subpaths it imports.
 
 `createProgress(print, enabled?, listen?)` takes an optional `listen` hook that can change the spinner's text while a step

package/dist/menu.d.mts

@@ -75,35 +75,6 @@ interface MenuEntry {
  * shape identically with no need to know which kind of command it came from.
  */
 export declare function buildChildArgv(entry: MenuEntry, positionals: string[], resolved: ResolvedOptions, parentArgv: Record<string, unknown>, dryRunOverride?: boolean): string[];
-/**
- * Reserved exit code a dry-run-capable handler may use — only when the
- * {@link dryRunPreviewEnvVar} is set — to report "ran clean, nothing would
- * change." {@link launchMenu} treats it as success but skips the "proceed with
- * the real run?" question, since there's nothing for the real run to do
- * either.
- */
-export declare const DRY_RUN_NOOP_EXIT_CODE = 2;
-/**
- * The env var {@link launchMenu} sets on a dry-run preview child (`<ENV_PREFIX>_DRY_RUN_PREVIEW`), so its
- * handler knows this specific `--dry-run` came from the menu's own preview-then-ask flow, not a direct
- * `<bin> <cmd> --dry-run` invocation. A handler that supports it uses this — never bare `argv.dryRun` — to
- * decide whether to report {@link DRY_RUN_NOOP_EXIT_CODE}: that exit code only has special meaning to
- * `launchMenu` itself, so a direct/scripted `--dry-run` call must never produce it — doing so unconditionally
- * would silently change the public exit-code contract for a successful dry run.
- */
-export declare function dryRunPreviewEnvVar(envPrefix: string): string;
-/**
- * `--token` (repeatable), `--org`, `--cwd`, `--dry-run` — the global flags a
- * menu-launched child should inherit from the parent invocation. Everything
- * else (command-specific options) was never captured by the top-level `$0`
- * handler in the first place, so there's nothing else to forward.
- *
- * `dryRunOverride`, when passed, wins over `argv.dryRun` — {@link launchMenu}'s
- * dry-run offer needs to force `--dry-run` on for the preview spawn and
- * force it back off for the real-run spawn that follows, regardless of
- * what was on the original invocation.
- */
-export declare function forwardedFlags(argv: Record<string, unknown>, dryRunOverride?: boolean): string[];
 /** How {@link launchMenu} is bound to one particular CLI. */
 interface LaunchMenuConfig {
   /** The CLI's binary name, used in the default non-interactive hint (`Run \`<bin> --help\` …`). */
@@ -143,6 +114,52 @@ interface LaunchMenuConfig {
  * @param config - Binds the menu to one CLI: its binary name, env prefix and optional messages.
  */
 export declare function launchMenu(entries: MenuEntry[], parentArgv: Record<string, unknown>, config: LaunchMenuConfig): Promise<void>;
+/** The per-call knobs of a bound menu: everything in {@link LaunchMenuConfig} except what {@link createMenu} already fixed. */
+export type BoundMenuOptions = Omit<LaunchMenuConfig, "bin" | "envPrefix">;
+/** A menu engine bound to one CLI by {@link createMenu}. */
+export interface Menu {
+  /** {@link launchMenu} with the CLI's `bin` and `envPrefix` already applied. */
+  launchMenu: (entries: MenuEntry[], parentArgv: Record<string, unknown>, options?: BoundMenuOptions) => Promise<void>;
+  /** The env var a dry-run preview child gets (`<envPrefix>_DRY_RUN_PREVIEW`); see {@link dryRunPreviewEnvVar}. */
+  dryRunPreviewEnvVar: string;
+}
+/**
+ * Bind the menu engine to one CLI once, so callers stop repeating `bin` and `envPrefix`: the returned
+ * `launchMenu(entries, parentArgv, options?)` is {@link launchMenu} with both applied, and `dryRunPreviewEnvVar` is the
+ * matching env var name a dry-run preview child receives.
+ *
+ * @param binding - The CLI's binary name and env prefix.
+ */
+export declare function createMenu({ bin, envPrefix }: Pick<LaunchMenuConfig, "bin" | "envPrefix">): Menu;
+/**
+ * Reserved exit code a dry-run-capable handler may use — only when the
+ * {@link dryRunPreviewEnvVar} is set — to report "ran clean, nothing would
+ * change." {@link launchMenu} treats it as success but skips the "proceed with
+ * the real run?" question, since there's nothing for the real run to do
+ * either.
+ */
+export declare const DRY_RUN_NOOP_EXIT_CODE = 2;
+/**
+ * The env var {@link launchMenu} sets on a dry-run preview child (`<ENV_PREFIX>_DRY_RUN_PREVIEW`), so its
+ * handler knows this specific `--dry-run` came from the menu's own preview-then-ask flow, not a direct
+ * `<bin> <cmd> --dry-run` invocation. A handler that supports it uses this — never bare `argv.dryRun` — to
+ * decide whether to report {@link DRY_RUN_NOOP_EXIT_CODE}: that exit code only has special meaning to
+ * `launchMenu` itself, so a direct/scripted `--dry-run` call must never produce it — doing so unconditionally
+ * would silently change the public exit-code contract for a successful dry run.
+ */
+export declare function dryRunPreviewEnvVar(envPrefix: string): string;
+/**
+ * `--token` (repeatable), `--org`, `--cwd`, `--dry-run` — the global flags a
+ * menu-launched child should inherit from the parent invocation. Everything
+ * else (command-specific options) was never captured by the top-level `$0`
+ * handler in the first place, so there's nothing else to forward.
+ *
+ * `dryRunOverride`, when passed, wins over `argv.dryRun` — {@link launchMenu}'s
+ * dry-run offer needs to force `--dry-run` on for the preview spawn and
+ * force it back off for the real-run spawn that follows, regardless of
+ * what was on the original invocation.
+ */
+export declare function forwardedFlags(argv: Record<string, unknown>, dryRunOverride?: boolean): string[];
 /** Prefix of a menu item's `value` that opens a submenu rather than running a command. */
 export declare const GROUP = "group:";
 /** The "← back" item's value; only offered below the first level. */

package/dist/menu.mjs

@@ -75,15 +75,6 @@ function buildChildArgv(entry, positionals, resolved, parentArgv, dryRunOverride
 		...forwardedFlags(parentArgv, dryRunOverride)
 	];
 }
-// src/menu/dry-run-noop-exit-code/dry-run-noop-exit-code.ts
-/**
-* Reserved exit code a dry-run-capable handler may use — only when the
-* {@link dryRunPreviewEnvVar} is set — to report "ran clean, nothing would
-* change." {@link launchMenu} treats it as success but skips the "proceed with
-* the real run?" question, since there's nothing for the real run to do
-* either.
-*/
-const DRY_RUN_NOOP_EXIT_CODE = 2;
 // src/menu/dry-run-preview-env-var/dry-run-preview-env-var.ts
 /**
 * The env var {@link launchMenu} sets on a dry-run preview child (`<ENV_PREFIX>_DRY_RUN_PREVIEW`), so its
@@ -96,6 +87,15 @@ const DRY_RUN_NOOP_EXIT_CODE = 2;
 function dryRunPreviewEnvVar(envPrefix) {
 	return `${envPrefix}_DRY_RUN_PREVIEW`;
 }
+// src/menu/dry-run-noop-exit-code/dry-run-noop-exit-code.ts
+/**
+* Reserved exit code a dry-run-capable handler may use — only when the
+* {@link dryRunPreviewEnvVar} is set — to report "ran clean, nothing would
+* change." {@link launchMenu} treats it as success but skips the "proceed with
+* the real run?" question, since there's nothing for the real run to do
+* either.
+*/
+const DRY_RUN_NOOP_EXIT_CODE = 2;
 // src/menu/menu-items/menu-items.ts
 /** Prefix of a menu item's `value` that opens a submenu rather than running a command. */
 const GROUP = "group:";
@@ -301,4 +301,22 @@ async function launchMenu(entries, parentArgv, config) {
 	const forReal = await resolveForRealSpawn(resolvedOptions);
 	process.exitCode = await spawnChild(buildChildArgv(picked, positionals, forReal, parentArgv), secretEnv(forReal, envPrefix));
 }
-export { BACK, DRY_RUN_NOOP_EXIT_CODE, GROUP, buildChildArgv, dryRunPreviewEnvVar, forwardedFlags, launchMenu, menuItems, secretEnv, shouldPreviewDryRun };
+// src/menu/create-menu/create-menu.ts
+/**
+* Bind the menu engine to one CLI once, so callers stop repeating `bin` and `envPrefix`: the returned
+* `launchMenu(entries, parentArgv, options?)` is {@link launchMenu} with both applied, and `dryRunPreviewEnvVar` is the
+* matching env var name a dry-run preview child receives.
+*
+* @param binding - The CLI's binary name and env prefix.
+*/
+function createMenu({ bin, envPrefix }) {
+	return {
+		launchMenu: (entries, parentArgv, options = {}) => launchMenu(entries, parentArgv, {
+			bin,
+			envPrefix,
+			...options
+		}),
+		dryRunPreviewEnvVar: dryRunPreviewEnvVar(envPrefix)
+	};
+}
+export { BACK, DRY_RUN_NOOP_EXIT_CODE, GROUP, buildChildArgv, createMenu, dryRunPreviewEnvVar, forwardedFlags, launchMenu, menuItems, secretEnv, shouldPreviewDryRun };

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/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 { 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

@@ -132,6 +132,23 @@ export declare function progressEnabled(): boolean;
 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.
@@ -185,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

@@ -391,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 = {
@@ -453,4 +464,4 @@ function waitForEnter(message, input = process.stdin, output = process.stderr) {
 		});
 	});
 }
-export { NonInteractiveError, allowProgress, commandFailureMessage, createProgress, describeError, expandToDepth, logReason, openPath, pad, progressEnabled, reduceKey, renderTree, sanitizeDetail, setProgressListener, statusRow, stripControl, 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,6 +1,6 @@
 {
   "name": "@theholocron/kyber",
-  "version": "5.0.0-alpha.341",
+  "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",
@@ -40,6 +40,11 @@
       "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",
@@ -64,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",
@@ -82,11 +90,12 @@
     "typescript": "^5.9.3",
     "vitest": "^5.0.5",
     "yargs": "^18.1.0",
-    "@theholocron/datapad": "5.0.0-alpha.341",
+    "@theholocron/tsconfig": "^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/vitest-config": "^8.9.0-alpha.8",
-    "@theholocron/eslint-config": "^8.9.0-alpha.8",
-    "@theholocron/tsconfig": "^8.9.0-alpha.8"
+    "@theholocron/datapad": "5.0.0-alpha.342"
   },
   "peerDependencies": {
     "@inquirer/prompts": "^8.0.0",
@@ -97,7 +106,8 @@
     "dotenv": "^17.0.0",
     "ora": "^9.0.0",
     "yargs": "^18.0.0",
-    "@theholocron/datapad": "^5.0.0-alpha.341"
+    "@theholocron/datapad": "^5.0.0-alpha.342",
+    "@theholocron/observability": "^0.7.0-alpha.1"
   },
   "peerDependenciesMeta": {
     "@inquirer/prompts": {
@@ -112,6 +122,9 @@
     "@theholocron/datapad": {
       "optional": true
     },
+    "@theholocron/observability": {
+      "optional": true
+    },
     "chalk": {
       "optional": true
     },