padrone 1.5.0 → 1.7.0

package/dist/index.d.mts

@@ -1,52 +1,121 @@
-import { A as Drained, B as REPL_SIGINT, C as PluginShutdownContext, D as WrapConfig, E as PluginValidateResult, F as PadroneProgressIndicator, I as PadroneProgressOptions, L as PadroneRuntime, M as PossibleCommands, N as InteractiveMode, O as WrapResult, P as InteractivePromptConfig, R as PadroneSpinnerConfig, S as PluginParseResult, T as PluginValidateContext, V as PadroneMcpPreferences, _ as PluginErrorContext, a as PadroneActionContext, b as PluginExecuteResult, c as PadroneCommandResult, d as PadronePlugin, f as PadroneProgram, g as PluginBaseContext, h as PadroneSchema, i as AsyncPadroneSchema, j as PickCommandByName, k as UpdateCheckConfig, l as PadroneDrainResult, m as PadroneProgressPrefs, n as AnyPadroneCommand, o as PadroneBuilder, p as PadroneProgressMessage, r as AnyPadroneProgram, s as PadroneCommand, t as AnyPadroneBuilder, u as PadroneParseResult, v as PluginErrorResult, w as PluginStartContext, x as PluginParseContext, y as PluginExecuteContext, z as PadroneSpinnerPreset } from "./types-Ch8Mk6Qb.mjs";
-import { a as ColorConfig, i as AnsiStyle, o as ColorTheme, r as HelpInfo, s as colorThemes } from "./formatter-DtHzbP22.mjs";
+import { a as ColorConfig, i as AnsiStyle, n as HelpFormat, o as ColorTheme, r as HelpInfo, s as colorThemes, t as HelpDetail } from "./formatter-DrvhDMrq.mjs";
+import { $ as PadroneProgressIndicator, A as InterceptorShutdownContext, B as WithCommand, C as InterceptorExecuteContext, D as InterceptorParseContext, E as InterceptorMeta, F as PadroneInterceptor, G as WrapResult, H as AsyncPadroneSchema, I as PadroneInterceptorFn, J as InteractiveMode, K as PadroneServePreferences, L as Drained, M as InterceptorValidateContext, N as InterceptorValidateResult, O as InterceptorParseResult, P as PadroneContextInterceptor, Q as PadroneBarConfig, R as PickCommandByName, S as InterceptorErrorResult, T as InterceptorFactory, U as PadroneSchema, V as WithInterceptor, W as WrapConfig, X as PadroneBarAnimation, Y as InteractivePromptConfig, Z as PadroneBarChar, _ as ExtractInterceptorContext, a as PadroneExtension, at as PadroneSpinnerConfig, b as InterceptorDefBuilder, c as PadroneDrainResult, d as AnyPadroneCommand, et as PadroneProgressOptions, f as CommandTypesBase, g as PadroneProgramMeta, h as PadroneCommand, i as PadroneBuilder, it as PadroneSignal, j as InterceptorStartContext, k as InterceptorPhases, l as PadroneParseResult, m as PadroneActionContext, n as AnyPadroneProgram, nt as PadroneProgressUpdate, o as PadroneProgram, ot as PadroneSpinnerPreset, p as GetArgsMeta, q as PadroneMcpPreferences, r as DefineCommand, rt as PadroneRuntime, s as PadroneCommandResult, st as REPL_SIGINT, t as AnyPadroneBuilder, tt as PadroneProgressShow, u as PadroneReplPreferences, v as ExtractInterceptorRequires, w as InterceptorExecuteResult, x as InterceptorErrorContext, y as InterceptorBaseContext, z as PossibleCommands } from "./index-D6-7dz0l.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
+import * as _$ink from "ink";
 
-//#region src/command-utils.d.ts
+//#region src/core/commands.d.ts
 /**
- * Brands a schema as async, signaling that its `validate()` may return a Promise.
- * When an async-branded schema is passed to `.arguments()`, `.configFile()`, or `.env()`,
- * the command's `parse()` and `cli()` will return Promises.
+ * Builds a completer function for the REPL from the command tree.
+ * Completes command names, subcommand names, option names (--foo), and aliases (-f).
+ * Also includes dot-prefixed built-in REPL commands (.exit, .clear, .scope, .help, .history).
+ */
+declare function buildReplCompleter(rootCommand: AnyPadroneCommand, builtins: {
+  inScope?: boolean;
+}): (line: string) => [string[], string];
+//#endregion
+//#region src/extension/help.d.ts
+type HelpArgs = {
+  command?: string[];
+  detail?: HelpDetail;
+  format?: HelpFormat;
+  all?: boolean;
+};
+type HelpCommand = PadroneCommand<'help', '', PadroneSchema<HelpArgs>, string, [], ['h', ''], false>;
+type WithHelp<T> = WithCommand<T, 'help', HelpCommand>;
+/**
+ * Extension that adds help support:
+ * - `help` command with aliases `h` and `` (empty = executes on root when no subcommand matches)
+ * - `--help` / `-h` flags
+ * - `<cmd> help` reverse syntax
+ * - Default help display when a command has no action
  *
- * @example
+ * Usage:
  * ```ts
- * const schema = asyncSchema(z.object({
- *   name: z.string(),
- * }).check(async (data) => {
- *   // async validation logic
- * }));
- *
- * const program = createPadrone('app')
- *   .command('greet', (c) => c.arguments(schema).action((args) => args.name));
+ * createPadrone('my-cli').extend(padroneHelp())
+ * ```
+ */
+declare function padroneHelp(): <T extends CommandTypesBase>(builder: T) => WithHelp<T>;
+//#endregion
+//#region src/extension/version.d.ts
+type VersionCommand = PadroneCommand<'version', '', PadroneSchema<void>, string, [], [], false>;
+type WithVersion<T> = WithCommand<T, 'version', VersionCommand>;
+/**
+ * Extension that adds version support:
+ * - `version` command
+ * - `--version` / `-v` / `-V` flags (root command only)
  *
- * // parse() now returns Promise<PadroneParseResult>
- * const result = await program.parse('greet --name world');
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneVersion())
  * ```
  */
+declare function padroneVersion(): <T extends CommandTypesBase>(builder: T) => WithVersion<T>;
+//#endregion
+//#region src/core/results.d.ts
+/**
+ * Brands a schema as async, signaling that its `validate()` may return a Promise.
+ * When an async-branded schema is passed to `.arguments()`, `.configFile()`, or `.env()`,
+ * the command's `parse()` and `cli()` will return Promises.
+ */
 declare function asyncSchema<T extends PadroneSchema>(schema: T): T & {
   '~async': true;
 };
+//#endregion
+//#region src/core/create.d.ts
 /**
- * Builds a completer function for the REPL from the command tree.
- * Completes command names, subcommand names, option names (--foo), and aliases (-f).
- * Also includes dot-prefixed built-in REPL commands (.exit, .clear, .scope, .help, .history).
+ * Options for configuring which built-in extensions are applied by default.
  */
-declare function buildReplCompleter(rootCommand: AnyPadroneCommand, builtins: {
-  inScope?: boolean;
-}): (line: string) => [string[], string];
-//#endregion
-//#region src/create.d.ts
-declare function createPadrone<TProgramName extends string>(name: TProgramName): PadroneProgram<TProgramName, '', ''>;
-//#endregion
-//#region src/errors.d.ts
+type PadroneBuiltins = {
+  /** Enable `help` command, `--help` / `-h` flags, and default help display. Defaults to `true`. */help?: boolean; /** Enable `version` command and `--version` / `-v` / `-V` flags. Defaults to `true`. */
+  version?: boolean; /** Enable `repl` command and `--repl` flag. Defaults to `true`. */
+  repl?: boolean; /** Enable `--color` / `--no-color` flag support. Defaults to `true`. */
+  color?: boolean; /** Enable "Did you mean?" suggestions for unknown commands and options. Defaults to `true`. */
+  suggestions?: boolean; /** Enable signal handling (SIGINT, SIGTERM, SIGHUP). Defaults to `true`. */
+  signal?: boolean; /** Enable automatic result output for `cli()`. Defaults to `true`. */
+  autoOutput?: boolean; /** Enable stdin piping support. Defaults to `true`. */
+  stdin?: boolean; /** Enable interactive prompting for missing arguments. Defaults to `true`. */
+  interactive?: boolean;
+};
+type PadroneOptions = {
+  builtins?: PadroneBuiltins;
+};
+type DefaultBuiltins = {};
+type BuiltinCommands<B> = [...(B extends {
+  help: false;
+} ? [] : [HelpCommand]), ...(B extends {
+  version: false;
+} ? [] : [VersionCommand])];
+declare function createPadrone<TProgramName extends string, const TBuiltins extends PadroneBuiltins = DefaultBuiltins>(name: TProgramName, options?: {
+  builtins?: TBuiltins;
+}): PadroneProgram<TProgramName, '', '', PadroneSchema<void>, void, BuiltinCommands<TBuiltins>>;
 /**
- * Structured error hierarchy for Padrone CLI framework.
+ * Identity helper that contextually types a command builder callback while preserving its full return type.
+ * Use this when defining commands in separate files — the parent program retains exact type information
+ * about the subcommand's args, result, and nested commands.
  *
- * All Padrone errors extend `PadroneError`, which carries an exit code,
- * optional suggestions, and context about which command/phase produced the error.
- * This allows callers to distinguish user errors (bad input) from bugs (unexpected throws)
- * and to present formatted, actionable error messages.
+ * @example
+ * ```ts
+ * // my-command.ts
+ * export const myCommand = defineCommand((c) =>
+ *   c.arguments(z.object({ name: z.string() }))
+ *    .action((args) => console.log(args.name))
+ * );
+ *
+ * // cli.ts
+ * createPadrone('test').command('my-command', myCommand)
+ * ```
+ *
+ * @example With context
+ * ```ts
+ * export const myCommand = defineCommand<{ db: Database }>((c) =>
+ *   c.arguments(z.object({ id: z.string() }))
+ *    .action((args, ctx) => ctx.context.db.find(args.id))
+ * );
+ * ```
  */
+declare function defineCommand<TContext = unknown, TOut extends CommandTypesBase = CommandTypesBase>(fn: (builder: PadroneBuilder<string, string, string, PadroneSchema<void>, void, [], any, false, TContext>) => TOut): typeof fn;
+//#endregion
+//#region src/core/errors.d.ts
 type PadroneErrorOptions = {
   /** Process exit code. Defaults to 1. */exitCode?: number; /** Actionable suggestions shown to the user (e.g. "Use --env production"). */
   suggestions?: string[]; /** The command path that produced the error (e.g. "deploy staging"). */
@@ -138,8 +207,738 @@ declare class ConfigError extends PadroneError {
 declare class ActionError extends PadroneError {
   constructor(message: string, options?: PadroneErrorOptions);
 }
+/**
+ * Thrown when command execution is interrupted by a process signal (SIGINT, SIGTERM, SIGHUP).
+ * Carries the signal name and the conventional exit code (128 + signal number).
+ */
+declare class SignalError extends PadroneError {
+  readonly signal: PadroneSignal;
+  constructor(signal: PadroneSignal, options?: {
+    cause?: unknown;
+  });
+}
+//#endregion
+//#region src/core/interceptors.d.ts
+/**
+ * Creates a self-contained interceptor value by attaching static metadata to the factory function.
+ * The returned value can be passed directly to `.intercept()` or exported from a package.
+ *
+ * Two-arg form — define metadata and factory in one call:
+ * ```ts
+ * export const myInterceptor = defineInterceptor(
+ *   { name: 'my-interceptor', order: 10 },
+ *   () => ({
+ *     execute(ctx, next) { return next(); },
+ *   }),
+ * );
+ * ```
+ *
+ * Single-arg form — chain `.requires<T>()` for typed context, then `.factory()`:
+ * ```ts
+ * export const myInterceptor = defineInterceptor({ name: 'with-db' })
+ *   .requires<{ db: DB }>()
+ *   .factory(() => ({
+ *     execute(ctx, next) {
+ *       ctx.context.db; // typed!
+ *       return next();
+ *     },
+ *   }));
+ * ```
+ */
+declare function defineInterceptor<TArgs = unknown, TResult = unknown>(meta: InterceptorMeta, factory: InterceptorFactory<TArgs, TResult>): PadroneInterceptorFn<TArgs, TResult>;
+declare function defineInterceptor(meta: InterceptorMeta): InterceptorDefBuilder;
+//#endregion
+//#region src/output/styling.d.ts
+/**
+ * Styling functions for semantic text roles.
+ * Used by formatters to apply visual styles (ANSI, HTML, Markdown, etc.)
+ * to different types of content.
+ */
+type Styler = {
+  command: (text: string) => string;
+  arg: (text: string) => string;
+  type: (text: string) => string;
+  description: (text: string) => string;
+  label: (text: string) => string;
+  section: (text: string) => string;
+  meta: (text: string) => string;
+  example: (text: string) => string;
+  exampleValue: (text: string) => string;
+  deprecated: (text: string) => string;
+};
+/**
+ * Layout configuration for formatters.
+ */
+type LayoutConfig = {
+  newline: string;
+  indent: (level: number) => string;
+  join: (parts: string[]) => string;
+  wrapDocument?: (content: string) => string;
+};
+/** Resolved formatting context used by output primitives. */
+type OutputFormat = 'text' | 'ansi' | 'json' | 'markdown' | 'html';
+type OutputContext = {
+  format: OutputFormat;
+  styler: Styler;
+  layout: LayoutConfig;
+  terminalWidth?: number;
+};
+//#endregion
+//#region src/output/primitives.d.ts
+type TableOptions = {
+  /** Explicit column keys to display (default: infer from first row's keys). */columns?: string[]; /** Column key → display header name mapping. */
+  headers?: Record<string, string>; /** Column key → text alignment. */
+  align?: Record<string, 'left' | 'right' | 'center'>; /** Maximum column width before truncation. */
+  maxColumnWidth?: number; /** Show borders (default: true for ansi/text, false for others). */
+  border?: boolean;
+};
+type TreeNode = {
+  label: string;
+  children?: TreeNode[];
+};
+type TreeOptions = {
+  /** Characters per indent level (default: 2). */indent?: number; /** Show tree guide lines (default: true for ansi/text). */
+  guides?: boolean;
+};
+type ListItem = string | {
+  label: string;
+  description?: string;
+};
+type ListOptions = {
+  /** Bullet character (default: '•' for ansi, '-' for text). */bullet?: string; /** Use numbered list instead of bullets. */
+  numbered?: boolean; /** Indent level (default: 0). */
+  indent?: number;
+};
+type KeyValueOptions = {
+  /** Separator between key and value (default: ': '). */separator?: string; /** Align values by padding keys to the same width. */
+  align?: boolean; /** Key → display label mapping. */
+  labels?: Record<string, string>;
+};
+//#endregion
+//#region src/output/output-indicator.d.ts
+/**
+ * Runtime output helper injected into action context as `ctx.context.output`.
+ * Provides format-aware output primitives (table, tree, list, key-value).
+ *
+ * Each method renders data using the resolved format (ANSI, text, JSON, markdown, HTML)
+ * and writes it to the runtime's output function.
+ */
+type PadroneOutputIndicator = {
+  /** Render data as a table. */table(data: Record<string, unknown>[], options?: TableOptions): void; /** Render data as a tree. */
+  tree(data: TreeNode | TreeNode[], options?: TreeOptions): void; /** Render data as a list. */
+  list(data: ListItem[], options?: ListOptions): void; /** Render data as aligned key-value pairs. */
+  kv(data: Record<string, unknown>, options?: KeyValueOptions): void; /** Write raw output (same as runtime.output but sets the "already called" flag). */
+  raw(...args: unknown[]): void; /** Whether any output method has been called. */
+  readonly called: boolean;
+};
+/** Declarative output configuration for a command. */
+type OutputPrimitiveType = 'table' | 'tree' | 'list' | 'kv' | 'json';
+type OutputConfig = OutputPrimitiveType | {
+  type: OutputPrimitiveType;
+  options?: TableOptions | TreeOptions | ListOptions | KeyValueOptions;
+};
+//#endregion
+//#region src/extension/auto-output.d.ts
+type PadroneAutoOutputOptions = {
+  /** Disable auto-output entirely. */disabled?: boolean;
+  /**
+   * Declarative output format for the command's return value.
+   * When set, auto-output formats the return value through the specified primitive
+   * instead of passing it raw to `runtime.output`.
+   * Ignored when the action calls `ctx.context.output.*` explicitly.
+   *
+   * ```ts
+   * // Format return value as a table
+   * c.extend(padroneAutoOutput({ output: 'table' }))
+   *
+   * // Format with options
+   * c.extend(padroneAutoOutput({ output: { type: 'table', options: { border: false } } }))
+   * ```
+   */
+  output?: OutputConfig;
+};
+/**
+ * Extension that automatically writes a command's return value to output after execution.
+ *
+ * - Values are passed directly to the runtime's `output` function (no stringification).
+ * - Promises are awaited before output.
+ * - Iterators and async iterators are consumed, outputting each yielded value as it arrives.
+ *   The result is replaced with the collected array so `drain()` still works.
+ * - `undefined` and `null` results produce no output.
+ *
+ * Also injects `ctx.context.output` with format-aware output primitives (table, tree, list, kv).
+ * When action handlers use these methods, auto-output skips to avoid double output.
+ *
+ * Included in the default extensions. Can also be applied per-command:
+ * ```ts
+ * createPadrone('my-cli')
+ *   .command('users', (c) =>
+ *     c.extend(padroneAutoOutput({ output: 'table' }))
+ *       .action(() => fetchUsers())
+ *   )
+ * ```
+ */
+declare function padroneAutoOutput(options?: PadroneAutoOutputOptions): <T extends CommandTypesBase>(builder: T) => T;
+//#endregion
+//#region src/extension/color.d.ts
+/**
+ * Extension that handles `--color` / `--no-color` flags:
+ * - `--color` or `--color=true` → use default theme
+ * - `--color=false` or `--no-color` → disable colors (text format)
+ * - `--color=<theme>` → use the named theme
+ *
+ * Modifies the runtime's format and theme accordingly.
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneColor())
+ * ```
+ */
+declare function padroneColor(): <T extends CommandTypesBase>(builder: T) => T;
+//#endregion
+//#region src/extension/completion.d.ts
+type CompletionArgs = {
+  shell?: string;
+  setup?: boolean;
+};
+type CompletionCommand = PadroneCommand<'completion', '', PadroneSchema<CompletionArgs>, string, [], [], true>;
+type WithCompletion<T> = WithCommand<T, 'completion', CompletionCommand>;
+/**
+ * Extension that adds the `completion` command for shell completion script generation.
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneCompletion())
+ * ```
+ */
+declare function padroneCompletion(): <T extends CommandTypesBase>(builder: T) => WithCompletion<T>;
+//#endregion
+//#region src/extension/config.d.ts
+type PadroneConfigOptions = {
+  /** Config file names to auto-detect (e.g. `['config.json', '.myapprc']`). First found is used. */files?: string | string[]; /** Schema to validate and transform config file data into the args shape. */
+  schema?: StandardSchemaV1; /** Disable this extension. */
+  disabled?: boolean; /** Whether to add `--config` / `-c` flag support. Defaults to `true`. */
+  flag?: boolean; /** Whether subcommands inherit this interceptor. Defaults to `true`. */
+  inherit?: boolean;
+  /**
+   * Search for config files in the user's platform-specific config directory.
+   * - `true` — use the program name as the subdirectory (e.g. program `'myapp'` → `~/.config/myapp/`).
+   * - `string` — use a custom app name as the subdirectory.
+   * - `false` — disable (default).
+   *
+   * Directories searched (after cwd):
+   * - **Linux**: `$XDG_CONFIG_HOME/<app>` or `~/.config/<app>`
+   * - **macOS**: `~/Library/Application Support/<app>` (or `$XDG_CONFIG_HOME/<app>` when set)
+   * - **Windows**: `%APPDATA%\<app>`
+   *
+   * Config files found in cwd always take precedence over XDG paths.
+   */
+  xdg?: string | boolean;
+  /**
+   * Custom config loader. When provided, replaces the built-in file system loader.
+   * Useful for testing or non-CLI environments.
+   */
+  loadConfig?: (files: string | string[], xdgAppName?: string) => Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined>;
+};
+/**
+ * Extension that handles config file loading, validation, and merging into command arguments.
+ *
+ * Features:
+ * - `--config` / `-c` flag for explicit config file path (can be disabled via `flag: false`)
+ * - Auto-detection of config files from a list of candidate names
+ * - Optional schema validation and transformation of config data
+ * - Directly accesses the file system (gracefully no-ops in non-CLI environments)
+ *
+ * Config values have the lowest precedence (CLI > stdin > env > config).
+ *
+ * Not included in the default built-in extensions — must be explicitly added:
+ * ```ts
+ * createPadrone('my-cli')
+ *   .extend(padroneConfig({
+ *     files: ['config.json', '.myapprc'],
+ *     schema: z.object({ port: z.number(), host: z.string() }),
+ *   }))
+ * ```
+ */
+declare function padroneConfig(options?: PadroneConfigOptions): <T extends CommandTypesBase>(builder: T) => T;
+//#endregion
+//#region src/extension/env.d.ts
+type PadroneEnvOptions = {
+  /** Env modes to load (e.g. `['production']`). Loads `.env.{mode}` files. */modes?: string[]; /** Whether to load `.env.local` and `.env.{mode}.local` files. @default true */
+  local?: boolean; /** Directory to search for `.env` files. @default process.cwd() */
+  dir?: string; /** When `true`, file values override `process.env` values. @default false */
+  override?: boolean; /** When `false`, the base `.env` (and `.env.local`) files are not loaded. @default true */
+  base?: boolean;
+};
+/**
+ * Extension that reads environment variables, validates them against a schema,
+ * and merges the transformed values into command arguments.
+ *
+ * Supports loading `.env` files with mode-based overrides and variable expansion.
+ *
+ * ```ts
+ * // Schema only (reads process.env)
+ * .extend(padroneEnv(
+ *   z.object({ PORT: z.string() }).transform(e => ({ port: Number(e.PORT) }))
+ * ))
+ *
+ * // Schema + .env file loading
+ * .extend(padroneEnv(
+ *   z.object({ PORT: z.string() }).transform(e => ({ port: Number(e.PORT) })),
+ *   { modes: ['production'] }
+ * ))
+ *
+ * // .env file loading only (no schema validation)
+ * .extend(padroneEnv({ modes: ['production'] }))
+ * ```
+ *
+ * Env values have lower precedence than CLI args and stdin, but higher than config files.
+ */
+declare function padroneEnv(schema: StandardSchemaV1): <T extends CommandTypesBase>(builder: T) => T;
+declare function padroneEnv(schema: StandardSchemaV1, options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => T;
+declare function padroneEnv(options: PadroneEnvOptions): <T extends CommandTypesBase>(builder: T) => T;
+//#endregion
+//#region src/extension/ink.d.ts
+/** Checks whether a value is a React element (JSX) by inspecting its `$$typeof` symbol. */
+declare function isReactElement(value: unknown): boolean;
+type InkOptions = {
+  /** Whether to wait for the Ink app to unmount before resolving. Defaults to `true`. */waitUntilExit?: boolean; /** Options forwarded to Ink's `render()`. */
+  render?: _$ink.RenderOptions;
+};
+/**
+ * Extension that renders React (Ink) components returned from command actions.
+ *
+ * When a command's action returns a React element (JSX), this extension
+ * renders it using Ink instead of passing it to the normal output path.
+ *
+ * Requires `ink` and `react` as peer dependencies.
+ *
+ * ```ts
+ * import { createPadrone, padroneInk } from 'padrone';
+ *
+ * const program = createPadrone('my-tui')
+ *   .extend(padroneInk())
+ *   .command('dashboard', (c) =>
+ *     c.action(() => <Dashboard />)
+ *   );
+ * ```
+ */
+declare function padroneInk(options?: InkOptions): <T extends CommandTypesBase>(builder: T) => T;
+//#endregion
+//#region src/extension/interactive.d.ts
+/**
+ * Extension that handles interactive prompting for missing arguments.
+ * Extracts `--interactive` / `-i` flags, resolves effective interactivity,
+ * and prompts for missing fields before passing filled args to validation.
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneInteractive())
+ * ```
+ */
+declare function padroneInteractive(): <T extends CommandTypesBase>(builder: T) => T;
+//#endregion
+//#region src/extension/logger.d.ts
+/** Log level values ordered by severity. */
+type PadroneLogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/** Logger instance injected into the command context. */
+type PadroneLogger = {
+  trace: (...args: unknown[]) => void;
+  debug: (...args: unknown[]) => void;
+  info: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void; /** The current effective log level. */
+  level: PadroneLogLevel; /** Create a child logger with a prefix label. */
+  child: (label: string) => PadroneLogger;
+};
+/** Configuration for the logger extension. */
+type PadroneLoggerConfig = {
+  /** Minimum log level to output. Defaults to `'info'`. */level?: PadroneLogLevel; /** Prefix prepended to every log message. */
+  prefix?: string; /** Include timestamps in log output. Defaults to `false`. */
+  timestamps?: boolean;
+};
+/** Builder/program type after applying `padroneLogger()`. Adds `{ logger: PadroneLogger }` to the command context. */
+type WithLogger<T> = WithInterceptor<T, {
+  logger: PadroneLogger;
+}>;
+/**
+ * Extension that injects a structured logger into the command context.
+ *
+ * The logger respects a configurable log level threshold, supports prefixed
+ * child loggers, and routes output through the runtime's `output`/`error`
+ * functions so it works in any environment (terminal, test, web).
+ *
+ * Supports CLI flags for runtime level overrides:
+ * - `--trace` → sets level to `trace`
+ * - `--verbose` or `--debug` → sets level to `debug`
+ * - `--silent` or `--quiet` → sets level to `silent`
+ * - `--log-level=<level>` → sets an explicit level (`trace`, `debug`, `info`, `warn`, `error`, `silent`)
+ *
+ * CLI flags take precedence over the programmatic config.
+ *
+ * Provides `{ logger: PadroneLogger }` on the command context.
+ * Access it in action handlers as `ctx.context.logger`.
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli')
+ *   .extend(padroneLogger({ level: 'info' }))
+ *   .command('sync', (c) =>
+ *     c.action((_args, ctx) => {
+ *       ctx.context.logger.info('starting sync');
+ *       const db = ctx.context.logger.child('db');
+ *       db.debug('connecting...');
+ *     })
+ *   )
+ * ```
+ *
+ * Then run:
+ * ```sh
+ * my-cli sync --verbose      # debug level
+ * my-cli sync --quiet        # silent
+ * my-cli sync --log-level=warn
+ * ```
+ */
+declare function padroneLogger<T extends CommandTypesBase>(config?: PadroneLoggerConfig): (builder: T) => WithLogger<T>;
+//#endregion
+//#region src/extension/man.d.ts
+type ManArgs = {
+  setup?: boolean;
+  remove?: boolean;
+};
+type ManCommand = PadroneCommand<'man', '', PadroneSchema<ManArgs>, string, [], [], true>;
+type WithMan<T> = WithCommand<T, 'man', ManCommand>;
+/**
+ * Extension that adds the `man` command for man page generation.
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneMan())
+ * ```
+ */
+declare function padroneMan(): <T extends CommandTypesBase>(builder: T) => WithMan<T>;
+//#endregion
+//#region src/extension/mcp.d.ts
+type McpArgs = {
+  transport?: string;
+  port?: string;
+  host?: string;
+  basePath?: string;
+};
+type McpCommand = PadroneCommand<'mcp', '', PadroneSchema<McpArgs>, void, [], [], true>;
+type WithMcp<T> = WithCommand<T, 'mcp', McpCommand>;
+/**
+ * Extension that adds the `mcp` command for starting a Model Context Protocol server.
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneMcp())
+ * ```
+ */
+declare function padroneMcp(defaults?: PadroneMcpPreferences): <T extends CommandTypesBase>(builder: T) => WithMcp<T>;
+//#endregion
+//#region src/extension/progress-renderer.d.ts
+/** Factory function that creates a `PadroneProgressIndicator`. */
+type PadroneProgressRenderer = (message: string, options?: PadroneProgressOptions) => PadroneProgressIndicator;
+/**
+ * Creates a terminal progress indicator (spinner, bar, or both).
+ * Returns a no-op indicator in non-TTY/CI environments.
+ */
+declare function createTerminalProgress(message: string, options?: PadroneProgressOptions): PadroneProgressIndicator;
+//#endregion
+//#region src/extension/progress.d.ts
+/** A progress message value: a plain string, `null` to suppress, or an object with a message and custom indicator icon. */
+type PadroneProgressMessage = string | null | {
+  message?: string | null;
+  indicator?: string;
+};
+/** Per-phase message configuration for progress indicators. */
+type PadroneProgressMessages<TRes = unknown> = {
+  /** Message shown during async validation. Defaults to `''` (spinner only). */validation?: string; /** Message shown while the command's action is running. */
+  progress?: string; /** Message shown when the command succeeds. `null` to suppress. Defaults to the `progress` message. */
+  success?: PadroneProgressMessage | ((result: TRes) => PadroneProgressMessage); /** Message shown when the command fails. `null` to suppress. Defaults to the error message. */
+  error?: PadroneProgressMessage | ((error: unknown) => PadroneProgressMessage);
+};
+/**
+ * Progress indicator configuration with messages, visual options, and renderer.
+ */
+type PadroneProgressConfig<TRes = unknown> = {
+  /** Per-phase messages. A string sets the `progress` message; an object configures individual phases. */message?: string | PadroneProgressMessages<TRes>; /** Spinner configuration. Default `show` is `'auto'` (visible when bar is not shown). `true` forces spinner to always show (even alongside a bar). */
+  spinner?: PadroneSpinnerConfig; /** Enable a progress bar. `true` for defaults (`show: 'always'`), or a `PadroneBarConfig` object. `false` to disable entirely. When omitted, bar defaults to `show: 'auto'`. */
+  bar?: boolean | PadroneBarConfig; /** Show elapsed time since the indicator started. Can also be started on demand via `update({ time: true })`. */
+  time?: boolean; /** Show estimated time remaining based on progress rate. Requires numeric `update()` calls. */
+  eta?: boolean;
+  /**
+   * Custom renderer factory. Called to create the progress indicator.
+   * Defaults to the built-in terminal renderer (`createTerminalProgress`).
+   */
+  renderer?: PadroneProgressRenderer;
+};
+/**
+ * Shared progress defaults that can be provided via context instead of repeating
+ * at each call site. Per-instance message fields are excluded — those always come
+ * from the constructor argument.
+ *
+ * Provide via context as `{ progressConfig: PadroneProgressDefaults }`.
+ */
+type PadroneProgressDefaults = Pick<PadroneProgressConfig, 'message' | 'spinner' | 'bar' | 'time' | 'eta' | 'renderer'>;
+/** Builder/program type after applying `padroneProgress()`. Adds `{ progress: PadroneProgressIndicator }` to the command context. */
+type WithProgress<T> = WithInterceptor<T, {
+  progress: PadroneProgressIndicator;
+}>;
+/**
+ * Extension that adds an auto-managed progress indicator to the command pipeline.
+ *
+ * - `string` — a single message used for all states.
+ * - `PadroneProgressConfig` — separate messages for validation, progress, success, and error.
+ *
+ * The indicator is automatically started before validation, updated at each phase transition,
+ * and stopped on success (`.succeed()`) or failure (`.fail()`).
+ *
+ * Provides `{ progress: PadroneProgressIndicator }` on the command context.
+ * Access it in action handlers as `ctx.context.progress`.
+ *
+ * Uses the built-in terminal renderer by default. Pass a custom `renderer` for non-terminal
+ * environments (web UIs, testing, etc).
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli')
+ *   .command('sync', (c) =>
+ *     c.extend(padroneProgress('Syncing...'))
+ *       .action((_args, ctx) => {
+ *         ctx.context.progress.update('halfway');
+ *       })
+ *   )
+ * ```
+ */
+declare function padroneProgress<T extends CommandTypesBase>(config?: string | PadroneProgressConfig): (builder: T) => WithProgress<T>;
+//#endregion
+//#region src/extension/repl.d.ts
+type ReplArgs = {
+  scope?: string;
+};
+type ReplCommand = PadroneCommand<'repl', '', PadroneSchema<ReplArgs>, void, [], [], true>;
+type WithRepl<T> = WithCommand<T, 'repl', ReplCommand>;
+/**
+ * Extension that adds REPL support:
+ * - `repl` command that starts an interactive REPL
+ * - `--repl` flag that starts the REPL from any invocation
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneRepl())
+ * ```
+ */
+declare function padroneRepl(defaults?: PadroneReplPreferences & {
+  disabled?: boolean;
+}): <T extends CommandTypesBase>(builder: T) => WithRepl<T>;
+//#endregion
+//#region src/extension/serve.d.ts
+type ServeArgs = {
+  port?: string;
+  host?: string;
+  basePath?: string;
+};
+type ServeCommand = PadroneCommand<'serve', '', PadroneSchema<ServeArgs>, void, [], [], true>;
+type WithServe<T> = WithCommand<T, 'serve', ServeCommand>;
+/**
+ * Extension that adds the `serve` command for starting a REST HTTP server.
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli').extend(padroneServe())
+ * ```
+ */
+declare function padroneServe(defaults?: PadroneServePreferences): <T extends CommandTypesBase>(builder: T) => WithServe<T>;
+//#endregion
+//#region src/extension/signal.d.ts
+/**
+ * Extension that wires process signal handling (SIGINT, SIGTERM, SIGHUP) into the interceptor lifecycle.
+ *
+ * - Creates an `AbortController` whose signal is propagated to all downstream phases.
+ * - Subscribes to `runtime.onSignal` to forward OS signals to the abort controller.
+ * - Implements SIGINT double-tap: two SIGINTs within 2 seconds force-exits the process.
+ * - Attaches `signal` and `exitCode` to results and errors when interrupted.
+ * - Cleans up the signal subscription on completion or failure.
+ *
+ * Included in the default extensions. Runs at order `-2000` (outermost).
+ */
+declare function padroneSignalHandling(options?: {
+  disabled?: boolean;
+}): <T extends CommandTypesBase>(builder: T) => T;
+//#endregion
+//#region src/extension/stdin.d.ts
+/**
+ * Extension that reads stdin data into the argument field specified by `meta.stdin`.
+ * Included by default via `createPadrone()`.
+ *
+ * Read mode is inferred from the schema type:
+ * - `string` field → reads all stdin as a single string
+ * - `string[]` field → reads stdin line-by-line into an array
+ * - `AsyncIterable` field → returns a stream for line-by-line async consumption
+ *
+ * Stdin is only read when piped (not a TTY) and the field wasn't already provided via CLI flags.
+ */
+declare function padroneStdin(options?: {
+  disabled?: boolean;
+}): <T extends CommandTypesBase>(builder: T) => T;
+//#endregion
+//#region src/extension/suggestions.d.ts
+declare function padroneSuggestions(): <T extends CommandTypesBase>(builder: T) => T;
+//#endregion
+//#region src/extension/timing.d.ts
+interface PadroneTimingOptions {
+  /** Enable timing by default without requiring `--time` flag. Default: `false`. */
+  enabled?: boolean;
+}
+/**
+ * Extension that tracks command execution time.
+ *
+ * - `--time` / `--timing` → enables timing output
+ * - `--no-time` / `--no-timing` → disables timing output
+ *
+ * Pass `{ enabled: true }` to enable timing by default (can be disabled via `--no-time`).
+ *
+ * Usage:
+ * ```ts
+ * // Opt-in via flag
+ * createPadrone('my-cli').extend(padroneTiming())
+ *
+ * // Always on, opt-out via --no-time
+ * createPadrone('my-cli').extend(padroneTiming({ enabled: true }))
+ * ```
+ */
+declare function padroneTiming(options?: PadroneTimingOptions): <T extends CommandTypesBase>(builder: T) => T;
+//#endregion
+//#region src/extension/tracing.d.ts
+/** Minimal subset of OTEL `SpanStatusCode`. */
+type SpanStatusCode = 0 | 1 | 2;
+/** Minimal subset of OTEL `SpanStatus`. */
+type SpanStatus = {
+  code: SpanStatusCode;
+  message?: string;
+};
+/** Minimal subset of OTEL `Span`. */
+interface OtelSpan {
+  setAttribute(key: string, value: string | number | boolean): this;
+  addEvent(name: string, attributes?: Record<string, string | number | boolean>): this;
+  setStatus(status: SpanStatus): this;
+  recordException(error: unknown): this;
+  end(): void;
+  spanContext(): {
+    traceId: string;
+    spanId: string;
+  };
+}
+/** Minimal subset of OTEL `Tracer`. */
+interface OtelTracer {
+  startSpan(name: string): OtelSpan;
+}
+/** Minimal subset of OTEL `TracerProvider`. */
+interface OtelTracerProvider {
+  getTracer(name: string, version?: string): OtelTracer;
+}
+/** Tracing handle injected into the command context. */
+type PadroneTracer = {
+  /** The underlying OTEL tracer. */tracer: OtelTracer; /** Root span covering the full command execution. */
+  rootSpan: OtelSpan; /** Run `fn` inside a child span that is automatically ended when `fn` returns (or rejects). */
+  span: <T>(name: string, fn: (span: OtelSpan) => T) => T;
+};
+/** Configuration for the tracing extension. */
+type PadroneTracingConfig = {
+  /** OTEL `TracerProvider`. Required — there is no global fallback. */provider: OtelTracerProvider; /** Service / tracer name. Defaults to the CLI program name. */
+  serviceName?: string;
+};
+/** Builder/program type after applying `padroneTracing()`. Adds `{ tracing: PadroneTracer }` to the command context. */
+type WithTracing<T> = WithInterceptor<T, {
+  tracing: PadroneTracer;
+}>;
+/**
+ * Extension that adds OpenTelemetry tracing to command execution.
+ *
+ * Creates a root span for each command invocation and provides a `PadroneTracer`
+ * on the command context for creating child spans in action handlers.
+ *
+ * When used with `padroneLogger()`, the logger automatically emits span events
+ * for each log call — no extra configuration needed. The logger detects the
+ * tracing context and bridges log output to span events.
+ *
+ * Uses minimal OTEL-compatible interfaces — pass any `TracerProvider` that
+ * implements `getTracer()`. Works with `@opentelemetry/api` or compatible
+ * libraries.
+ *
+ * Provides `{ tracing: PadroneTracer }` on the command context.
+ * Access it in action handlers as `ctx.context.tracing`.
+ *
+ * Usage:
+ * ```ts
+ * import { trace } from '@opentelemetry/api';
+ *
+ * createPadrone('my-cli')
+ *   .extend(padroneTracing({ provider: trace.getTracerProvider() }))
+ *   .extend(padroneLogger())
+ *   .command('deploy', (c) =>
+ *     c.action((_args, ctx) => {
+ *       ctx.context.logger.info('deploying');  // also emits a span event
+ *       ctx.context.tracing.span('build', (span) => {
+ *         span.setAttribute('target', 'production');
+ *       });
+ *     })
+ *   )
+ * ```
+ */
+declare function padroneTracing<T extends CommandTypesBase>(config: PadroneTracingConfig): (builder: T) => WithTracing<T>;
+//#endregion
+//#region src/feature/update-check.d.ts
+/**
+ * Configuration for the update check feature.
+ */
+type UpdateCheckConfig = {
+  /**
+   * The npm package name to check. Defaults to the program name.
+   */
+  packageName?: string;
+  /**
+   * Registry to check for updates.
+   * - `'npm'` — checks the npm registry (default)
+   * - A URL string — custom registry endpoint that returns JSON with a `version` or `dist-tags.latest` field
+   */
+  registry?: 'npm' | string;
+  /**
+   * How often to check for updates. Accepts shorthand like `'1d'`, `'12h'`, `'30m'`.
+   * Defaults to `'1d'` (once per day).
+   */
+  interval?: string;
+  /**
+   * Path to the cache file for storing the last check timestamp and latest version.
+   * Defaults to `~/.config/<programName>-update-check.json`.
+   */
+  cache?: string;
+  /**
+   * Environment variable name to disable update checks (e.g. `'MYAPP_NO_UPDATE_CHECK'`).
+   * When set to a truthy value, update checks are skipped.
+   * Defaults to `'<PROGRAM_NAME>_NO_UPDATE_CHECK'` (uppercased, hyphens to underscores).
+   */
+  disableEnvVar?: string;
+};
 //#endregion
-//#region src/stream.d.ts
+//#region src/extension/update-check.d.ts
+/**
+ * Extension that adds background update checking:
+ * - Checks for newer versions on npm (or custom registry) in the background
+ * - Shows an update notification after command execution
+ * - Respects `--no-update-check` flag to suppress
+ *
+ * Usage:
+ * ```ts
+ * createPadrone('my-cli')
+ *   .extend(padroneUpdateCheck({ packageName: 'my-cli' }))
+ * ```
+ */
+declare function padroneUpdateCheck(config?: UpdateCheckConfig): <T extends CommandTypesBase>(builder: T) => T;
+//#endregion
+//#region src/util/stream.d.ts
 interface AsyncStreamMeta {
   [x: string]: unknown;
   readonly asyncStream: number;
@@ -167,7 +966,7 @@ interface AsyncStreamMeta {
  */
 declare function asyncStream<T = string>(itemSchema?: PadroneSchema<T>): AsyncStreamMeta;
 //#endregion
-//#region src/type-helpers.d.ts
+//#region src/util/type-helpers.d.ts
 /**
  * Extracts the input type of the arguments schema from a command.
  * @example
@@ -184,6 +983,40 @@ type InferArgsInput<T extends AnyPadroneCommand> = T['~types']['argsInput'];
  * ```
  */
 type InferArgsOutput<T extends AnyPadroneCommand> = T['~types']['argsOutput'];
+/**
+ * Extracts the user-defined context type from a command (excludes interceptor-provided context).
+ * @example
+ * ```ts
+ * type Ctx = InferContext<typeof myCommand>;
+ * ```
+ */
+type InferContext<T extends AnyPadroneCommand> = T['~types']['context'];
+/**
+ * Extracts the interceptor-provided context type from a command.
+ * @example
+ * ```ts
+ * type Provided = InferContextProvided<typeof myCommand>;
+ * ```
+ */
+type InferContextProvided<T extends AnyPadroneCommand> = T['~types']['contextProvided'];
+/**
+ * Extracts the context type that a context-providing interceptor injects.
+ * @example
+ * ```ts
+ * type AuthCtx = InferInterceptorContext<typeof withAuth>;
+ * ```
+ */
+type InferInterceptorContext<T extends PadroneContextInterceptor<any>> = T['~context'];
+/**
+ * Extracts the required context type from an interceptor with `.requires()`.
+ * @example
+ * ```ts
+ * type Requires = InferInterceptorRequires<typeof withAuth>;
+ * ```
+ */
+type InferInterceptorRequires<T extends PadroneInterceptorFn & {
+  '~contextRequires': any;
+}> = T['~contextRequires'] extends ((ctx: infer R) => void) ? R : unknown;
 /**
  * Gets a command type by its path from a program or command tree.
  * Supports both full paths (e.g., "config set") and alias paths.
@@ -201,5 +1034,5 @@ type InferArgsOutput<T extends AnyPadroneCommand> = T['~types']['argsOutput'];
  */
 type InferCommand<T extends AnyPadroneCommand | AnyPadroneProgram, TPath extends PossibleCommands<T extends AnyPadroneCommand ? [T] : T['~types']['commands'], true, true>> = T extends AnyPadroneProgram ? PickCommandByName<[PadroneCommand<'', '', any, any, T['~types']['commands']>], TPath> : T extends AnyPadroneCommand ? PickCommandByName<[T], TPath> : never;
 //#endregion
-export { ActionError, type AnsiStyle, type AnyPadroneBuilder, type AnyPadroneCommand, type AnyPadroneProgram, type AsyncPadroneSchema, type AsyncStreamMeta, type ColorConfig, type ColorTheme, ConfigError, type Drained, type HelpInfo, type InferArgsInput, type InferArgsOutput, type InferCommand, type InteractiveMode, type InteractivePromptConfig, type PadroneActionContext, type PadroneBuilder, type PadroneCommand, type PadroneCommandResult, type PadroneDrainResult, PadroneError, type PadroneErrorOptions, type PadroneMcpPreferences, type PadroneParseResult, type PadronePlugin, type PadroneProgram, type PadroneProgressPrefs as PadroneProgressConfig, type PadroneProgressIndicator, type PadroneProgressMessage, type PadroneProgressOptions, type PadroneRuntime, type PadroneSchema, type PadroneSpinnerConfig, type PadroneSpinnerPreset, type PluginBaseContext, type PluginErrorContext, type PluginErrorResult, type PluginExecuteContext, type PluginExecuteResult, type PluginParseContext, type PluginParseResult, type PluginShutdownContext, type PluginStartContext, type PluginValidateContext, type PluginValidateResult, REPL_SIGINT, RoutingError, type UpdateCheckConfig, ValidationError, type WrapConfig, type WrapResult, asyncSchema, asyncStream, buildReplCompleter, colorThemes, createPadrone };
+export { ActionError, type AnsiStyle, type AnyPadroneBuilder, type AnyPadroneCommand, type AnyPadroneProgram, type AsyncPadroneSchema, type AsyncStreamMeta, type ColorConfig, type ColorTheme, type CommandTypesBase, ConfigError, type DefineCommand, type Drained, type ExtractInterceptorContext, type ExtractInterceptorRequires, type GetArgsMeta, type HelpCommand, type HelpInfo, type InferArgsInput, type InferArgsOutput, type InferCommand, type InferContext, type InferContextProvided, type InferInterceptorContext, type InferInterceptorRequires, type InkOptions, type InteractiveMode, type InteractivePromptConfig, type InterceptorBaseContext, type InterceptorDefBuilder, type InterceptorErrorContext, type InterceptorErrorResult, type InterceptorExecuteContext, type InterceptorExecuteResult, type InterceptorFactory, type InterceptorMeta, type InterceptorParseContext, type InterceptorParseResult, type InterceptorPhases, type InterceptorShutdownContext, type InterceptorStartContext, type InterceptorValidateContext, type InterceptorValidateResult, type KeyValueOptions, type ListItem, type ListOptions, type OtelSpan, type OtelTracer, type OtelTracerProvider, type OutputContext, type OutputFormat, type PadroneActionContext, type PadroneBarAnimation, type PadroneBarChar, type PadroneBarConfig, type PadroneBuilder, type PadroneCommand, type PadroneCommandResult, type PadroneContextInterceptor, type PadroneDrainResult, PadroneError, type PadroneErrorOptions, type PadroneExtension, type PadroneInterceptor, type PadroneInterceptorFn, type PadroneLogLevel, type PadroneLogger, type PadroneLoggerConfig, type PadroneMcpPreferences, type PadroneOptions, type PadroneOutputIndicator, type PadroneParseResult, type PadroneProgram, type PadroneProgramMeta, type PadroneProgressConfig, type PadroneProgressDefaults, type PadroneProgressIndicator, type PadroneProgressMessage, type PadroneProgressMessages, type PadroneProgressOptions, type PadroneProgressRenderer, type PadroneProgressShow, type PadroneProgressUpdate, type PadroneRuntime, type PadroneSchema, type PadroneSignal, type PadroneSpinnerConfig, type PadroneSpinnerPreset, type PadroneTracer, type PadroneTracingConfig, REPL_SIGINT, RoutingError, SignalError, type TableOptions, type TreeNode, type TreeOptions, type UpdateCheckConfig, ValidationError, type VersionCommand, type WithCompletion, type WithHelp, type WithLogger, type WithMan, type WithMcp, type WithProgress, type WithRepl, type WithServe, type WithTracing, type WithVersion, type WrapConfig, type WrapResult, asyncSchema, asyncStream, buildReplCompleter, colorThemes, createPadrone, createTerminalProgress, defineCommand, defineInterceptor, isReactElement, padroneAutoOutput, padroneColor, padroneCompletion, padroneConfig, padroneEnv, padroneHelp, padroneInk, padroneInteractive, padroneLogger, padroneMan, padroneMcp, padroneProgress, padroneRepl, padroneServe, padroneSignalHandling, padroneStdin, padroneSuggestions, padroneTiming, padroneTracing, padroneUpdateCheck, padroneVersion };
 //# sourceMappingURL=index.d.mts.map