padrone 1.5.0 → 1.6.0

package/dist/{types-Ch8Mk6Qb.d.mts → index-BaU3X6dY.d.mts}

@@ -1,8 +1,8 @@
-import { a as ColorConfig, n as HelpFormat, o as ColorTheme, t as HelpDetail } from "./formatter-DtHzbP22.mjs";
+import { a as ColorConfig, n as HelpFormat, o as ColorTheme, t as HelpDetail } from "./formatter-DrvhDMrq.mjs";
 import { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
 import { Tool } from "ai";
 
-//#region src/args.d.ts
+//#region src/types/args-meta.d.ts
 type Letter = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
 /** A single letter character, valid as a short CLI flag (e.g. `'v'`, `'n'`, `'V'`). */
 type SingleChar = Letter | Uppercase<Letter>;
@@ -119,37 +119,36 @@ interface PadroneArgsSchemaMeta<TObj = Record<string, any>> {
   optionalInteractive?: true | readonly (keyof TObj & string)[];
 }
 //#endregion
-//#region src/help.d.ts
-type HelpPreferences = {
-  format?: HelpFormat | 'auto';
-  detail?: HelpDetail;
-  theme?: ColorTheme | ColorConfig; /** Show all global commands and flags in full detail */
-  all?: boolean;
-};
-//#endregion
-//#region src/mcp.d.ts
-type PadroneMcpPreferences = {
-  /** Server name. Defaults to the program name. */name?: string; /** Server version. Defaults to the program version. */
-  version?: string;
-  /**
-   * Transport mode.
-   * - `'http'` — Start a Streamable HTTP server (default). Responds with `application/json` or `text/event-stream` based on the client's `Accept` header. Use `port` and `host` to configure.
-   * - `'stdio'` — Communicate over stdin/stdout with newline-delimited JSON.
-   */
-  transport?: 'http' | 'stdio'; /** HTTP port. Defaults to `3000`. Only used with `transport: 'http'`. */
-  port?: number; /** HTTP host. Defaults to `'127.0.0.1'`. Only used with `transport: 'http'`. */
-  host?: string; /** Base path for the MCP endpoint. Defaults to `'/mcp'`. Only used with `transport: 'http'`. */
-  basePath?: string; /** CORS allowed origin. Defaults to `'*'`. Set to a specific origin or `false` to disable CORS headers. Only used with HTTP transports. */
-  cors?: string | false;
+//#region src/core/runtime.d.ts
+/** Process signals that Padrone can handle for graceful shutdown. */
+type PadroneSignal = 'SIGINT' | 'SIGTERM' | 'SIGHUP';
+/** Value accepted by `PadroneProgressIndicator.update()`. */
+type PadroneProgressUpdate = string | number | {
+  message?: string;
+  progress?: number;
+  indeterminate?: boolean;
+  time?: boolean;
 };
-//#endregion
-//#region src/runtime.d.ts
 /**
  * A progress indicator instance (spinner, progress bar, etc).
  * Created by the runtime's `progress` factory and used to show loading state during command execution.
  */
 type PadroneProgressIndicator = {
-  /** Update the displayed message. */update: (message: string) => void; /** Mark as succeeded and stop. Pass `null` to stop without rendering a final message. */
+  /**
+   * Update the indicator.
+   * - `string` — update the displayed message.
+   * - `number` — set progress ratio (0–1). Values outside this range are clamped.
+   * - `{ message?, progress?, indeterminate? }` — update message, progress, or both.
+   *
+   * Set `indeterminate: true` to force the bar into indeterminate mode (shows animation, no percentage).
+   * This makes the bar visible even in `show: 'auto'` mode without providing a number.
+   * Omitting `progress` (or passing a string) leaves the bar in its current state.
+   * Setting `progress` when bar mode is not enabled is a no-op for the bar portion.
+   *
+   * Set `time: true` to start the elapsed timer on demand (useful when `time` was not set in options).
+   * Set `time: false` to hide the elapsed timer.
+   */
+  update: (value: PadroneProgressUpdate) => void; /** Mark as succeeded and stop. Pass `null` to stop without rendering a final message. */
   succeed: (message?: string | null, options?: {
     indicator?: string;
   }) => void; /** Mark as failed and stop. Pass `null` to stop without rendering a final message. */
@@ -160,23 +159,57 @@ type PadroneProgressIndicator = {
   pause: () => void; /** Redraw the indicator after a `pause()`. */
   resume: () => void;
 };
+/** Controls when a progress element (spinner or bar) is visible. */
+type PadroneProgressShow = 'auto' | 'always' | 'never';
 /** Built-in spinner presets. */
 type PadroneSpinnerPreset = 'dots' | 'line' | 'arc' | 'bounce';
 /**
  * Spinner configuration for progress indicators.
  * - A preset name (e.g., `'dots'`) to use built-in frames.
- * - An object with custom `frames` and/or `interval`.
- * - `false` to disable the spinner animation (static text only).
+ * - `true` — default spinner with `show: 'always'` (visible even alongside a bar).
+ * - An object with custom `frames`, `interval`, and/or `show`.
+ * - `false` to disable the spinner (`show: 'never'`).
+ *
+ * Default `show` is `'auto'`: visible when the bar is not shown.
  */
-type PadroneSpinnerConfig = PadroneSpinnerPreset | {
+type PadroneSpinnerConfig = PadroneSpinnerPreset | boolean | {
   frames?: string[];
   interval?: number;
-} | false;
+  show?: PadroneProgressShow;
+};
 /**
  * Options passed to the runtime's `progress` factory.
  */
+/** Common fill/empty character pairs for progress bars. */
+type PadroneBarChar = '█' | '░' | '▓' | '▒' | '─' | '━' | '■' | '□' | '#' | '-' | '=' | '·' | '▰' | '▱' | (string & {});
+/**
+ * Built-in indeterminate bar animation presets.
+ * - `'bounce'` — a filled segment slides back and forth (default).
+ * - `'slide'` — a filled segment slides left-to-right and wraps around.
+ * - `'pulse'` — the entire bar fades in and out using gradient characters (`░▒▓█▓▒░`).
+ */
+type PadroneBarAnimation = 'bounce' | 'slide' | 'pulse';
+/**
+ * Progress bar configuration.
+ */
+type PadroneBarConfig = {
+  /** Total width of the bar in characters. Defaults to `20`. */width?: number; /** Character used for the filled portion of the bar. Defaults to `'█'`. */
+  filled?: PadroneBarChar; /** Character used for the empty portion of the bar. Defaults to `'░'`. */
+  empty?: PadroneBarChar; /** Indeterminate animation style. Defaults to `'bounce'`. */
+  animation?: PadroneBarAnimation;
+  /**
+   * When the bar is visible. Defaults to `'always'` when bar is enabled, `'auto'` when bar is not explicitly configured.
+   * - `'always'` — bar is always shown (indeterminate until a number is provided).
+   * - `'auto'` — bar is shown only after `update()` is called with a number.
+   * - `'never'` — bar is never shown.
+   */
+  show?: PadroneProgressShow;
+};
 type PadroneProgressOptions = {
-  spinner?: PadroneSpinnerConfig; /** Character/string shown before the success message. Defaults to `'✔'`. */
+  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'` (appears when a number is provided). */
+  bar?: boolean | PadroneBarConfig; /** Show elapsed time since the indicator started. Defaults to `false`. */
+  time?: boolean; /** Show estimated time remaining based on progress rate. Requires numeric `update()` calls. Defaults to `false`. */
+  eta?: boolean; /** Character/string shown before the success message. Defaults to `'✔'`. */
   successIndicator?: string; /** Character/string shown before the error message. Defaults to `'✖'`. */
   errorIndicator?: string;
 };
@@ -215,9 +248,7 @@ type PadroneRuntime = {
   argv?: () => string[]; /** Return environment variables (replaces process.env). */
   env?: () => Record<string, string | undefined>; /** Default help output format. */
   format?: HelpFormat | 'auto'; /** Color theme for ANSI/console help output. A theme name or partial color config. */
-  theme?: ColorTheme | ColorConfig; /** Load and parse a config file by path. Return undefined if not found or unparsable. */
-  loadConfigFile?: (path: string) => Record<string, unknown> | undefined; /** Find the first existing file from a list of candidate names. */
-  findFile?: (names: string[]) => string | undefined;
+  theme?: ColorTheme | ColorConfig;
   /**
    * Standard input abstraction. Provides methods to read piped data from stdin.
    * When not provided, defaults to reading from `process.stdin`.
@@ -247,12 +278,6 @@ type PadroneRuntime = {
    * When `interactive` is `true` and this is not provided, defaults to an Enquirer-based terminal prompt.
    */
   prompt?: (config: InteractivePromptConfig) => Promise<unknown>;
-  /**
-   * Create a progress indicator (spinner, progress bar, etc).
-   * Used by commands that set `progress` in their config, or manually via `ctx.progress()` in actions.
-   * When not provided, auto-progress is silently skipped and `ctx.progress()` returns a no-op indicator.
-   */
-  progress?: (message: string, options?: PadroneProgressOptions) => PadroneProgressIndicator;
   /**
    * Read a line of input from the user. Used by `repl()` for custom runtimes
    * (web UIs, chat interfaces, testing).
@@ -263,24 +288,57 @@ type PadroneRuntime = {
    * with command history (up/down arrows) and tab completion.
    */
   readLine?: (prompt: string) => Promise<string | typeof REPL_SIGINT | null>;
+  /**
+   * Register a callback for process signals. Returns an unsubscribe function.
+   * The default runtime wires this to `process.on('SIGINT' | 'SIGTERM' | 'SIGHUP')`.
+   * Non-Node runtimes (web UIs, tests) can map their own cancellation semantics.
+   *
+   * When not provided, signal handling is disabled for this runtime.
+   */
+  onSignal?: (callback: (signal: PadroneSignal) => void) => () => void;
+  /**
+   * Terminal/output capabilities. Used for ANSI detection, text wrapping, and TTY checks.
+   * The default runtime auto-detects from `process.stdout`. Non-terminal runtimes
+   * (web UIs, tests) should provide explicit values.
+   */
+  terminal?: {
+    /** Number of columns in the terminal. Used for text wrapping. */columns?: number; /** Whether stdout is a TTY. Affects ANSI color output and interactive features. */
+    isTTY?: boolean;
+  };
+  /**
+   * Force-exit the process. The default runtime wires this to `process.exit()`.
+   * Non-Node runtimes can throw an error or no-op.
+   */
+  exit?: (code: number) => never;
 };
 /**
  * Internal resolved runtime where all fields are guaranteed to be present.
  * The `prompt`, `interactive`, and `readLine` fields remain optional since not all runtimes provide them.
  */
-type ResolvedPadroneRuntime = Required<Omit<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin' | 'progress' | 'theme'>> & Pick<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin' | 'progress' | 'theme'>;
-/**
- * Creates a persistent Node.js readline session for the REPL.
- * Enables up/down arrow history navigation and tab completion.
- * Used internally by `repl()` when no custom `readLine` is provided.
- */
+type ResolvedPadroneRuntime = Required<Omit<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin' | 'theme' | 'onSignal' | 'terminal' | 'exit'>> & Pick<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin' | 'theme' | 'onSignal' | 'terminal' | 'exit'>;
 /**
  * Sentinel value returned by the terminal REPL session when Ctrl+C is pressed.
  * Distinguished from empty string (user pressed enter) and null (EOF/Ctrl+D).
  */
 declare const REPL_SIGINT: unique symbol;
 //#endregion
-//#region src/serve.d.ts
+//#region src/feature/mcp.d.ts
+type PadroneMcpPreferences = {
+  /** Server name. Defaults to the program name. */name?: string; /** Server version. Defaults to the program version. */
+  version?: string;
+  /**
+   * Transport mode.
+   * - `'http'` — Start a Streamable HTTP server (default). Responds with `application/json` or `text/event-stream` based on the client's `Accept` header. Use `port` and `host` to configure.
+   * - `'stdio'` — Communicate over stdin/stdout with newline-delimited JSON.
+   */
+  transport?: 'http' | 'stdio'; /** HTTP port. Defaults to `3000`. Only used with `transport: 'http'`. */
+  port?: number; /** HTTP host. Defaults to `'127.0.0.1'`. Only used with `transport: 'http'`. */
+  host?: string; /** Base path for the MCP endpoint. Defaults to `'/mcp'`. Only used with `transport: 'http'`. */
+  basePath?: string; /** CORS allowed origin. Defaults to `'*'`. Set to a specific origin or `false` to disable CORS headers. Only used with HTTP transports. */
+  cors?: string | false;
+};
+//#endregion
+//#region src/feature/serve.d.ts
 type PadroneServePreferences = {
   /** Port to listen on. Default: 3000 */port?: number; /** Host to bind to. Default: '127.0.0.1' */
   host?: string; /** Base path prefix for all routes. Default: '/' */
@@ -296,7 +354,94 @@ type PadroneServePreferences = {
   onError?: (error: unknown, req: Request) => Response;
 };
 //#endregion
-//#region src/type-utils.d.ts
+//#region src/feature/wrap.d.ts
+/**
+ * Configuration for wrapping an external CLI tool.
+ */
+type WrapConfig<TCommandArgs extends PadroneSchema = PadroneSchema, TWrapArgs extends PadroneSchema = TCommandArgs> = {
+  /**
+   * The command to execute (e.g., 'git', 'docker', 'npm').
+   */
+  command: string;
+  /**
+   * Optional fixed arguments that always precede the arguments (e.g., ['commit'] for 'git commit').
+   */
+  args?: string[];
+  /**
+   * Positional argument configuration for the external command.
+   * If not provided, defaults to the wrapping command's positional configuration.
+   */
+  positional?: string[];
+  /**
+   * Whether to inherit stdio streams (stdin, stdout, stderr) from the parent process.
+   * Default: true
+   */
+  inheritStdio?: boolean;
+  /**
+   * Optional schema that transforms command arguments to external CLI arguments.
+   * The schema's input type should match the command arguments, and its output type defines
+   * the arguments expected by the external command.
+   * If not provided, command arguments are passed through as-is.
+   */
+  schema?: TWrapArgs | ((commandArguments: TCommandArgs) => TWrapArgs);
+};
+/**
+ * Result from executing a wrapped CLI tool.
+ */
+type WrapResult = {
+  /**
+   * The exit code of the process.
+   */
+  exitCode: number;
+  /**
+   * Standard output from the process (only if inheritStdio is false).
+   */
+  stdout?: string;
+  /**
+   * Standard error from the process (only if inheritStdio is false).
+   */
+  stderr?: string;
+  /**
+   * Whether the process exited successfully (exit code 0).
+   */
+  success: boolean;
+};
+//#endregion
+//#region src/output/help.d.ts
+type HelpPreferences = {
+  format?: HelpFormat | 'auto';
+  detail?: HelpDetail;
+  theme?: ColorTheme | ColorConfig; /** Show all global commands and flags in full detail */
+  all?: boolean; /** Terminal width for text wrapping. Defaults to terminal columns or 80. */
+  width?: number; /** Terminal capabilities for auto-detection of ANSI and width. */
+  terminal?: {
+    columns?: number;
+    isTTY?: boolean;
+  }; /** Environment variables for auto-detection (e.g., NO_COLOR, CI). */
+  env?: Record<string, string | undefined>;
+};
+//#endregion
+//#region src/types/schema.d.ts
+/**
+ * A schema that supports both validation (StandardSchemaV1) and JSON schema generation (StandardJSONSchemaV1).
+ * This is the type required for command arguments in Padrone.
+ */
+type PadroneSchema<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output> & StandardJSONSchemaV1<Input, Output>;
+/**
+ * A schema branded as async. When passed to `.arguments()`, `.configFile()`, or `.env()`,
+ * the command is automatically marked as async, causing `parse()` and `cli()` to return Promises.
+ *
+ * Use the `asyncSchema()` helper to brand an existing schema:
+ * ```ts
+ * import { asyncSchema } from 'padrone';
+ * const schema = asyncSchema(z.object({ name: z.string() }).check(async (v) => { ... }));
+ * ```
+ */
+type AsyncPadroneSchema<Input = unknown, Output = Input> = PadroneSchema<Input, Output> & {
+  '~async': true;
+};
+//#endregion
+//#region src/util/type-utils.d.ts
 type SafeString = string & {};
 type IsUnknown<T> = unknown extends T ? true : false;
 type IsAny<T> = any extends T ? true : false;
@@ -371,17 +516,61 @@ type GetCommandPathsAndAliases<TCommand extends AnyPadroneCommand> = TCommand['~
 /**
  * Find a direct child command in a tuple by name.
  * Unlike PickCommandByName, this does NOT flatten — it only checks direct children by their `name` field.
+ * Uses indexed access (O(1) depth) instead of recursive tuple walking.
  */
-type FindDirectChild<TCommands extends AnyPadroneCommand[], TName extends string> = TCommands extends [infer First extends AnyPadroneCommand, ...infer Rest extends AnyPadroneCommand[]] ? First['~types']['name'] extends TName ? First : FindDirectChild<Rest, TName> : never;
+type FindDirectChild<TCommands extends AnyPadroneCommand[], TName extends string> = Extract<TCommands[number], {
+  '~types': {
+    name: TName;
+  };
+}>;
 /**
  * Replace a command in a tuple by name, or append if not found.
  * Used by `.command()` override semantics: re-registering a name replaces that entry.
+ * Uses mapped type (O(1) depth) instead of recursive tuple walking.
  */
 type ReplaceOrAppendCommand<TCommands extends [...AnyPadroneCommand[]], TName extends string, TNew extends AnyPadroneCommand> = HasDirectChild<TCommands, TName> extends true ? ReplaceInTuple<TCommands, TName, TNew> : [...TCommands, TNew];
-type HasDirectChild<TCommands extends AnyPadroneCommand[], TName extends string> = TCommands extends [infer First extends AnyPadroneCommand, ...infer Rest extends AnyPadroneCommand[]] ? First['~types']['name'] extends TName ? true : HasDirectChild<Rest, TName> : false;
-type ReplaceInTuple<TCommands extends AnyPadroneCommand[], TName extends string, TNew extends AnyPadroneCommand> = TCommands extends [infer First extends AnyPadroneCommand, ...infer Rest extends AnyPadroneCommand[]] ? First['~types']['name'] extends TName ? [TNew, ...Rest] : [First, ...ReplaceInTuple<Rest, TName, TNew>] : [];
+type HasDirectChild<TCommands extends AnyPadroneCommand[], TName extends string> = TName extends TCommands[number]['~types']['name'] ? true : false;
+type ReplaceInTuple<TCommands extends AnyPadroneCommand[], TName extends string, TNew extends AnyPadroneCommand> = { [K in keyof TCommands]: TCommands[K] extends AnyPadroneCommand ? TCommands[K]['~types']['name'] extends TName ? TNew : TCommands[K] : TCommands[K] };
+/**
+ * Utility type for extensions that add a command to a builder/program.
+ * Replaces the boilerplate `With*<T>` pattern used across all extension files.
+ */
+type WithCommand<T, TName extends string, TCmd extends AnyPadroneCommand> = T extends {
+  '~types': {
+    programName: infer PN extends string;
+    name: infer N extends string;
+    parentName: infer PaN extends string;
+    argsSchema: infer A extends PadroneSchema;
+    result: infer R;
+    commands: infer C extends [...AnyPadroneCommand[]];
+    async: infer AS extends boolean;
+    context: infer CTX;
+    contextProvided: infer CTXP;
+  };
+} ? T extends {
+  run: any;
+} ? PadroneProgram<PN, N, PaN, A, R, ReplaceOrAppendCommand<C, TName, TCmd>, any, AS, CTX, CTXP> : PadroneBuilder<PN, N, PaN, A, R, ReplaceOrAppendCommand<C, TName, TCmd>, any, AS, CTX, CTXP> : T;
+/**
+ * Utility type for extensions that register a context-providing interceptor.
+ * Extends `TContextProvided` with `TProvides` while preserving all other builder/program type params.
+ */
+type WithInterceptor<T, TProvides> = T extends {
+  '~types': {
+    programName: infer PN extends string;
+    name: infer N extends string;
+    parentName: infer PaN extends string;
+    argsSchema: infer A extends PadroneSchema;
+    result: infer R;
+    commands: infer C extends [...AnyPadroneCommand[]];
+    async: infer AS extends boolean;
+    context: infer CTX;
+    contextProvided: infer CTXP;
+  };
+} ? T extends {
+  run: any;
+} ? PadroneProgram<PN, N, PaN, A, R, C, any, AS, CTX, CTXP & TProvides> : PadroneBuilder<PN, N, PaN, A, R, C, any, AS, CTX, CTXP & TProvides> : T;
 type PickCommandByName<TCommands extends AnyPadroneCommand[], TName extends string | AnyPadroneCommand> = TName extends AnyPadroneCommand ? TName : FlattenCommands<TCommands> extends infer Cmd extends AnyPadroneCommand ? Cmd extends AnyPadroneCommand ? TName extends GetCommandPathsAndAliases<Cmd> ? Cmd : never : never : never;
-type FlattenCommands<TCommands extends AnyPadroneCommand[]> = TCommands extends [] ? never : TCommands extends [infer FirstCommand, ...infer RestCommands] ? (RestCommands extends AnyPadroneCommand[] ? FlattenCommands<RestCommands> : never) | (FirstCommand extends AnyPadroneCommand ? FlattenCommands<FirstCommand['~types']['commands']> | FirstCommand : never) : IsAny<TCommands[number]> extends true ? never : TCommands[number];
+type FlattenCommands<TCommands extends AnyPadroneCommand[]> = TCommands extends [] ? never : number extends TCommands['length'] ? IsAny<TCommands[number]> extends true ? never : TCommands[number] : TCommands[number] extends infer Cmd extends AnyPadroneCommand ? Cmd | FlattenCommands<Cmd['~types']['commands']> : never;
 /**
  * Get all command paths including alias paths for all commands.
  */
@@ -411,159 +600,273 @@ type CommandIsUnknownable<TCommand> = IsGeneric<TCommand> extends true ? true :
  * Used by `mount()` to update all nested command paths when a program is mounted as a subcommand.
  */
 type RepathCommands<TCommands extends [...AnyPadroneCommand[]], TNewParentPath extends string> = TCommands extends [infer First extends AnyPadroneCommand, ...infer Rest extends AnyPadroneCommand[]] ? [RepathCommand<First, TNewParentPath>, ...RepathCommands<Rest, TNewParentPath>] : [];
-type RepathCommand<TCommand extends AnyPadroneCommand, TNewParentName extends string> = PadroneCommand<TCommand['~types']['name'], TNewParentName, TCommand['~types']['argsSchema'], TCommand['~types']['result'], RepathCommands<TCommand['~types']['commands'], FullCommandName<TCommand['~types']['name'], TNewParentName>>, TCommand['~types']['aliases'], TCommand['~types']['configSchema'], TCommand['~types']['envSchema'], TCommand['~types']['async']>;
+type RepathCommand<TCommand extends AnyPadroneCommand, TNewParentName extends string> = PadroneCommand<TCommand['~types']['name'], TNewParentName, TCommand['~types']['argsSchema'], TCommand['~types']['result'], RepathCommands<TCommand['~types']['commands'], FullCommandName<TCommand['~types']['name'], TNewParentName>>, TCommand['~types']['aliases'], TCommand['~types']['async'], TCommand['~types']['context'], TCommand['~types']['contextProvided']>;
 type PickCommandByPossibleCommands<TCommands extends AnyPadroneCommand[], TCommand extends PossibleCommands<TCommands, true, true> | SafeString> = CommandIsUnknownable<TCommand> extends true ? FlattenCommands<TCommands> : TCommand extends AnyPadroneCommand ? TCommand : TCommand extends string ? TCommand extends GetCommandPathsOrAliases<TCommands> ? PickCommandByName<TCommands, TCommand> : SplitLastSpace<TCommand> extends [infer Prefix extends string, infer Rest] ? IsNever<Rest> extends true ? PickCommandByName<TCommands, Prefix> : PickCommandByPossibleCommands<TCommands, Prefix> : never : never;
 //#endregion
-//#region src/update-check.d.ts
+//#region src/types/interceptor.d.ts
+/** Base context shared across all interceptor phases within a single execution. */
+type InterceptorBaseContext<TContext = unknown> = {
+  /** The resolved command for this execution. In the parse phase, this is the root program. */command: AnyPadroneCommand; /** The raw CLI input string (undefined when invoked without input). */
+  input: string | undefined; /** Cancellation signal that fires when the process receives a termination signal. */
+  signal: AbortSignal; /** User-defined context object, resolved through the command's parent chain. */
+  context: TContext; /** The resolved runtime for this execution. Interceptors can override this before calling `next()`. */
+  runtime: ResolvedPadroneRuntime; /** The program instance. Available for extensions that need program-level methods. */
+  program: AnyPadroneProgram; /** The invocation method that triggered this execution (e.g. 'cli', 'eval', 'run'). */
+  caller: PadroneActionContext['caller'];
+};
+/** Context for the parse phase. */
+type InterceptorParseContext<TContext = unknown> = InterceptorBaseContext<TContext>;
+/** Result returned by the parse phase's `next()`. */
+type InterceptorParseResult = {
+  command: AnyPadroneCommand;
+  rawArgs: Record<string, unknown>;
+  positionalArgs: string[];
+};
+/** Context for the validate phase. */
+type InterceptorValidateContext<TContext = unknown> = InterceptorBaseContext<TContext> & {
+  /** Raw named arguments extracted by the parser. Mutable — modify before `next()` to inject/override values. */rawArgs: Record<string, unknown>; /** Positional argument strings extracted by the parser. */
+  positionalArgs: string[]; /** Interactive mode override (set by the interactive extension when `--interactive` / `-i` flag is used). */
+  interactive?: boolean; /** Interactive mode preference from eval/cli options. Available for the interactive extension. */
+  evalInteractive?: boolean;
+};
+/** Result returned by the validate phase's `next()`. */
+type InterceptorValidateResult<TArgs = unknown> = {
+  args: TArgs;
+  argsResult: StandardSchemaV1.Result<TArgs>;
+};
+/** Context for the execute phase. Includes validate context fields (rawArgs, positionalArgs). */
+type InterceptorExecuteContext<TArgs = unknown, TContext = unknown> = InterceptorValidateContext<TContext> & {
+  /** Validated arguments that will be passed to the action. Mutable — modify before `next()` to override. */args: TArgs;
+};
+/** Result returned by the execute phase's `next()`. */
+type InterceptorExecuteResult<TResult = unknown> = {
+  result: TResult;
+};
+/** Context for the start phase. Runs before parsing, wraps the entire pipeline. */
+type InterceptorStartContext<TContext = unknown> = InterceptorBaseContext<TContext>;
+/** Context for the error phase. Called when the pipeline throws. Includes pipeline state accumulated before the error. */
+type InterceptorErrorContext<TContext = unknown> = InterceptorBaseContext<TContext> & {
+  /** The error that was thrown. */error: unknown; /** Raw named arguments (available if parse completed). */
+  rawArgs?: Record<string, unknown>; /** Positional argument strings (available if parse completed). */
+  positionalArgs?: string[]; /** Validated arguments (available if validate completed). */
+  args?: unknown;
+};
+/** Result returned by the error phase's `next()`. */
+type InterceptorErrorResult<TResult = unknown> = {
+  /** The error (possibly transformed). Set to `undefined` to suppress the error. */error?: unknown; /** A replacement result when suppressing the error. */
+  result?: TResult;
+};
+/** Context for the shutdown phase. Always runs after the pipeline (success or failure). Includes pipeline state accumulated before completion. */
+type InterceptorShutdownContext<TResult = unknown, TContext = unknown> = InterceptorBaseContext<TContext> & {
+  /** The error, if the pipeline failed (after error phase processing). */error?: unknown; /** The pipeline result, if it succeeded. */
+  result?: TResult; /** Raw named arguments (available if parse completed). */
+  rawArgs?: Record<string, unknown>; /** Positional argument strings (available if parse completed). */
+  positionalArgs?: string[]; /** Validated arguments (available if validate completed). */
+  args?: unknown;
+};
+/** Overrides passable to `next()`. Provides autocomplete for common fields; accepts any phase-specific fields. */
+type InterceptorNextOverrides = Partial<InterceptorBaseContext> & Record<string, unknown>;
 /**
- * Configuration for the update check feature.
+ * A phase handler function for the interceptor middleware chain.
+ *
+ * - `TCtx` — the context object available to the handler.
+ * - `TNextResult` — the typed result returned by `next()`, giving the handler type-safe access to downstream output.
+ * - `TReturn` — the type the handler itself returns. Defaults to `TNextResult` but can be wider,
+ *   allowing interceptors to transform or replace the result (e.g., error-recovery interceptors returning a different type).
  */
-type UpdateCheckConfig = {
-  /**
-   * The npm package name to check. Defaults to the program name.
-   */
-  packageName?: string;
+type InterceptorPhaseHandler<TCtx, TNextResult, TReturn = TNextResult> = (ctx: TCtx, next: (overrides?: InterceptorNextOverrides) => TNextResult | Promise<TNextResult>) => TReturn | Promise<TReturn>;
+/** Static metadata for an interceptor. Always available at registration time without calling the factory. */
+type InterceptorMeta = {
+  /** Display name for this interceptor. Used for identification in logs and debugging. */name: 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
+   * Optional unique identifier for deduplication. When multiple interceptors share the same `id`,
+   * only the last one registered is kept. Useful for allowing downstream code to override
+   * an interceptor without accumulating duplicates.
    */
-  registry?: 'npm' | string;
+  id?: string;
   /**
-   * How often to check for updates. Accepts shorthand like `'1d'`, `'12h'`, `'30m'`.
-   * Defaults to `'1d'` (once per day).
+   * Ordering hint. Lower values run as outer layers (earlier before `next()`, later after).
+   * Interceptors with the same order preserve registration order. Defaults to `0`.
    */
-  interval?: string;
+  order?: number;
   /**
-   * Path to the cache file for storing the last check timestamp and latest version.
-   * Defaults to `~/.config/<programName>-update-check.json`.
+   * When `true`, the interceptor is skipped during execution. Combined with `id`-based deduplication,
+   * this lets downstream code disable an interceptor by re-registering it with `disabled: true`.
    */
-  cache?: string;
+  disabled?: boolean;
   /**
-   * 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).
+   * When `false`, the interceptor applies only to the command it was registered on
+   * and is not inherited by subcommands. Defaults to `true`.
    */
-  disableEnvVar?: string;
+  inherit?: boolean;
 };
-//#endregion
-//#region src/wrap.d.ts
 /**
- * Configuration for wrapping an external CLI tool.
+ * Phase handler definitions returned by an interceptor factory.
+ * The factory's closure provides typed, scoped cross-phase state.
+ *
+ * Type parameters:
+ * - `TArgs` — the validated arguments type (output of the args schema).
+ * - `TResult` — the command's return type.
  */
-type WrapConfig<TCommandArgs extends PadroneSchema = PadroneSchema, TWrapArgs extends PadroneSchema = TCommandArgs> = {
-  /**
-   * The command to execute (e.g., 'git', 'docker', 'npm').
-   */
-  command: string;
+type InterceptorPhases<TArgs = unknown, TResult = unknown, TContext = unknown> = {
   /**
-   * Optional fixed arguments that always precede the arguments (e.g., ['commit'] for 'git commit').
-   */
-  args?: string[];
-  /**
-   * Positional argument configuration for the external command.
-   * If not provided, defaults to the wrapping command's positional configuration.
+   * Runs before the pipeline (parse → validate → execute). `next()` proceeds to the pipeline.
+   * Root interceptors only. Use for startup tasks like telemetry, update checks, or global config loading.
    */
-  positional?: string[];
+  start?: InterceptorPhaseHandler<InterceptorStartContext<TContext>, unknown>; /** Intercepts command routing and raw argument extraction. */
+  parse?: InterceptorPhaseHandler<InterceptorParseContext<TContext>, InterceptorParseResult>; /** Intercepts argument preprocessing and schema validation. Interactive prompting is handled by the interactive extension. */
+  validate?: InterceptorPhaseHandler<InterceptorValidateContext<TContext>, InterceptorValidateResult<TArgs>, InterceptorValidateResult>; /** Intercepts handler execution. */
+  execute?: InterceptorPhaseHandler<InterceptorExecuteContext<TArgs, TContext>, InterceptorExecuteResult<TResult>, InterceptorExecuteResult>;
   /**
-   * Whether to inherit stdio streams (stdin, stdout, stderr) from the parent process.
-   * Default: true
+   * Called when the pipeline throws an error. `next()` passes to the next error handler
+   * (innermost returns `{ error }` unchanged). Return `{ result }` without `error` to suppress.
    */
-  inheritStdio?: boolean;
+  error?: InterceptorPhaseHandler<InterceptorErrorContext<TContext>, InterceptorErrorResult<TResult>, InterceptorErrorResult>;
   /**
-   * Optional schema that transforms command arguments to external CLI arguments.
-   * The schema's input type should match the command arguments, and its output type defines
-   * the arguments expected by the external command.
-   * If not provided, command arguments are passed through as-is.
+   * Always runs after the pipeline completes (success or failure). `next()` calls the next shutdown handler.
+   * Use for cleanup: closing connections, flushing logs, etc.
    */
-  schema?: TWrapArgs | ((commandArguments: TCommandArgs) => TWrapArgs);
+  shutdown?: InterceptorPhaseHandler<InterceptorShutdownContext<TResult, TContext>, void>;
 };
 /**
- * Result from executing a wrapped CLI tool.
+ * Factory function that creates phase handlers for an interceptor.
+ * Called once per command execution — the closure provides typed, scoped cross-phase state across phases.
  */
-type WrapResult = {
-  /**
-   * The exit code of the process.
-   */
-  exitCode: number;
-  /**
-   * Standard output from the process (only if inheritStdio is false).
-   */
-  stdout?: string;
-  /**
-   * Standard error from the process (only if inheritStdio is false).
-   */
-  stderr?: string;
+type InterceptorFactory<TArgs = unknown, TResult = unknown, TContext = unknown> = () => InterceptorPhases<TArgs, TResult, TContext>;
+/**
+ * A self-contained interceptor value: a factory function with static metadata as own properties.
+ * Created via `defineInterceptor(meta, factory)`. This is the distributable form — a single
+ * importable value that packages can export.
+ *
+ * Also accepted directly by `.intercept()` as the single-argument form.
+ * Call `.provides<T>()` to brand it as a context-providing interceptor.
+ */
+type PadroneInterceptorFn<TArgs = unknown, TResult = unknown, TContext = unknown> = InterceptorFactory<TArgs, TResult, TContext> & InterceptorMeta & {
+  /** Brand this interceptor as providing additional context of type `TProvides`. No-op at runtime; purely a type-level cast. */provides: <TProvides>() => PadroneContextInterceptor<TProvides, TArgs, TResult, TContext>;
   /**
-   * Whether the process exited successfully (exit code 0).
+   * Brand this interceptor as requiring context of type `TRequires` to be available.
+   * `.intercept()` will produce a compile error if the required context is not satisfied.
+   * Use optional properties for soft requirements: `.requires<{ db: DB; logger?: Logger }>()`.
+   * No-op at runtime; purely a type-level cast.
    */
-  success: boolean;
+  requires: <TRequires>() => PadroneInterceptorFn<TArgs, TResult, TContext> & InterceptorRequiresBrand<TRequires>;
+};
+/**
+ * A Padrone interceptor in its single-value distributable form.
+ * Alias for `PadroneInterceptorFn` — this is the primary public type.
+ *
+ * Create with `defineInterceptor(meta, factory)` or pass `(meta, factory)` directly to `.intercept()`.
+ */
+type PadroneInterceptor<TArgs = unknown, TResult = unknown, TContext = unknown> = PadroneInterceptorFn<TArgs, TResult, TContext>;
+/**
+ * A context-providing interceptor. Carries a phantom `'~context'` brand declaring what it adds
+ * to the command context. When registered via `.intercept()`, the builder's context type is
+ * intersected with `TProvides`.
+ *
+ * Created by calling `.provides<T>()` on a `PadroneInterceptorFn`.
+ * Chain `.requires<T>()` to also declare context dependencies.
+ */
+type PadroneContextInterceptor<TProvides = unknown, TArgs = unknown, TResult = unknown, TContext = unknown> = Omit<PadroneInterceptorFn<TArgs, TResult, TContext>, 'requires'> & InterceptorFactory<TArgs, TResult, TContext> & {
+  /** Phantom brand — declares the context type this interceptor provides. */'~context': TProvides; /** Like `.requires()` on `PadroneInterceptorFn` but preserves the `'~context'` brand. */
+  requires: <TRequires>() => PadroneContextInterceptor<TProvides, TArgs, TResult, TContext> & InterceptorRequiresBrand<TRequires>;
+};
+/**
+ * Phantom brand for context requirements. Uses a contravariant function type so that
+ * `.intercept()` overloads can check `TAvailableContext extends TRequires` via assignability.
+ */
+type InterceptorRequiresBrand<TRequires> = {
+  '~contextRequires': (ctx: TRequires) => void;
+};
+/** Extracts the provided context type from a context-providing interceptor, or `unknown` if not branded. */
+type ExtractInterceptorContext<T> = T extends {
+  '~context': infer C;
+} ? C : unknown;
+/** Extracts the required context type from an interceptor, or `unknown` if no requirements. */
+type ExtractInterceptorRequires<T> = T extends {
+  '~contextRequires': (ctx: infer R) => void;
+} ? R : unknown;
+/**
+ * Checks whether an interceptor's context requirements are satisfied by the available context.
+ * Returns `true` if the interceptor has no requirements or if the available context extends the requirements.
+ */
+type InterceptorRequiresCheck<TInterceptor, TAvailableContext> = TInterceptor extends {
+  '~contextRequires': (ctx: infer TReq) => void;
+} ? TAvailableContext extends TReq ? true : false : true;
+/** Error brand returned by `.intercept()` when the interceptor's required context is not satisfied. */
+type InterceptorRequiresError = {
+  readonly '~error': 'Required context not satisfied. Ensure required interceptors are registered before this one.';
+};
+/**
+ * Builder returned by `defineInterceptor(meta)` (single-arg form).
+ * Call `.requires<T>()` to declare (and type) the context dependency, then `.factory()` to provide the phase handlers.
+ */
+type InterceptorDefBuilder<TContext = unknown, TBrand = unknown> = {
+  /** Declare the context type this interceptor requires. Sets `TContext` for phase handler typing. */requires: <TRequires>() => InterceptorDefBuilder<TRequires, InterceptorRequiresBrand<TRequires>>; /** Provide the interceptor factory. Phase handlers receive the typed `TContext` from `.requires()`. */
+  factory: <TArgs = unknown, TResult = unknown>(factory: InterceptorFactory<TArgs, TResult, TContext>) => PadroneInterceptorFn<TArgs, TResult, TContext> & TBrand;
+};
+/**
+ * Internal stored form on command objects. Separates static metadata from the factory
+ * so that deduplication and sorting can happen without calling the factory.
+ */
+type RegisteredInterceptor = {
+  meta: InterceptorMeta;
+  factory: InterceptorFactory<any, any, any>;
 };
 //#endregion
-//#region src/types.d.ts
+//#region src/types/command.d.ts
 type UnknownRecord = Record<string, unknown>;
-type EmptyRecord = Record<string, never>;
-type DefaultArgs = UnknownRecord | void;
+type DefaultArgs$1 = UnknownRecord | void;
+/**
+ * Read-only metadata about a Padrone program.
+ * Returned by `program.info` to expose program-level properties without leaking internal command internals.
+ */
+type PadroneProgramMeta<TName extends string = string> = {
+  /** The program name (CLI binary name). */name: TName; /** Display title shown in help output. */
+  title?: string; /** Program description. */
+  description?: string; /** Program version string. */
+  version?: string; /** Usage examples shown in help output. */
+  examples?: string[]; /** Whether the program is deprecated. */
+  deprecated?: boolean | string; /** Names of registered subcommands. */
+  commands: string[];
+};
 /**
  * Context object passed as the second argument to command action handlers.
  * Contains the resolved runtime, the executing command, and the program instance.
  */
-type PadroneActionContext = {
+type PadroneActionContext<TContext = unknown> = {
   /** The resolved runtime for this command (I/O, env, config, etc.). */runtime: ResolvedPadroneRuntime; /** The command being executed. */
   command: AnyPadroneCommand; /** The root program instance. */
   program: AnyPadroneProgram;
   /**
-   * The active auto-managed progress indicator, or a no-op if none is configured.
-   * Use `.update()` to change the in-progress message mid-execution.
+   * Cancellation signal that fires when the process receives SIGINT, SIGTERM, or SIGHUP.
+   * Use with `fetch()`, child processes, or any API that accepts `AbortSignal`.
+   * Check `signal.aborted` to test if cancellation was requested.
+   * The `signal.reason` is a `PadroneSignal` string ('SIGINT', 'SIGTERM', or 'SIGHUP').
    */
-  progress: PadroneProgressIndicator;
+  signal: AbortSignal; /** User-defined context object. Set via `.context()` on the builder and provided at `cli()`/`eval()` time. */
+  context: TContext; /** Which API entry point triggered this execution. */
+  caller: 'cli' | 'eval' | 'run' | 'repl' | 'serve' | 'mcp' | 'tool';
 };
 /**
- * A schema that supports both validation (StandardSchemaV1) and JSON schema generation (StandardJSONSchemaV1).
- * This is the type required for command arguments in Padrone.
- */
-type PadroneSchema<Input = unknown, Output = Input> = StandardSchemaV1<Input, Output> & StandardJSONSchemaV1<Input, Output>;
-/**
- * A schema branded as async. When passed to `.arguments()`, `.configFile()`, or `.env()`,
- * the command is automatically marked as async, causing `parse()` and `cli()` to return Promises.
- *
- * Use the `asyncSchema()` helper to brand an existing schema:
- * ```ts
- * import { asyncSchema } from 'padrone';
- * const schema = asyncSchema(z.object({ name: z.string() }).check(async (v) => { ... }));
- * ```
- */
-type AsyncPadroneSchema<Input = unknown, Output = Input> = PadroneSchema<Input, Output> & {
-  '~async': true;
-};
-/**
- * Helper type to set aliases on a command type.
- * Uses intersection to override just the aliases while preserving all other type information.
+ * Configuration for a command.
  */
-type WithAliases<TCommand extends AnyPadroneCommand, TAliases extends string[]> = Omit<TCommand, 'aliases' | '~types'> & {
-  aliases?: TAliases;
-  '~types': Omit<TCommand['~types'], 'aliases'> & {
-    aliases: TAliases;
-  };
+type PadroneCommandConfig = {
+  /** A short title for the command, displayed in help. */title?: string; /** A longer description of what the command does. */
+  description?: string; /** The version of the command. */
+  version?: string; /** Whether the command is deprecated, or a message explaining the deprecation. */
+  deprecated?: boolean | string; /** Whether the command should be hidden from help output. */
+  hidden?: boolean; /** Group name for organizing this command under a labeled section in help output. */
+  group?: string; /** Usage examples shown in help output. Each entry is a command-line invocation string. */
+  examples?: string[];
+  /**
+   * Whether this command performs a mutation (create, update, delete).
+   * - In `serve()`: mutation commands accept POST only; non-mutation commands accept GET and POST.
+   * - In `mcp()`: sets `annotations.destructiveHint` on the tool definition.
+   * - In `tool()`: defaults `needsApproval` to `true` when not explicitly set.
+   */
+  mutation?: boolean;
 };
-/**
- * Resolves aliases for a command override: if new aliases are provided (non-empty), use them;
- * otherwise, preserve the existing command's aliases.
- */
-type ResolvedAliases<TCommands extends [...AnyPadroneCommand[]], TNameNested extends string, TAliases extends string[]> = TAliases extends [] ? FindDirectChild<TCommands, TNameNested> extends infer E extends AnyPadroneCommand ? E['~types']['aliases'] : [] : TAliases;
-/**
- * Resolves the initial builder type for a `.command()` call.
- * If TNameNested already exists in TCommands, the builder starts pre-populated with that command's types.
- * Otherwise, a fresh builder with default types is used.
- */
-type InitialCommandBuilder<TProgramName extends string, TNameNested extends string, TParentPath extends string, TParentArgs extends PadroneSchema, TCommands extends [...AnyPadroneCommand[]]> = [FindDirectChild<TCommands, TNameNested>] extends [never] ? PadroneBuilder<TProgramName, TNameNested, TParentPath, PadroneSchema<void>, void, [], TParentArgs, PadroneSchema<void>, PadroneSchema<void>, false> : FindDirectChild<TCommands, TNameNested> extends infer E extends AnyPadroneCommand ? PadroneBuilder<TProgramName, TNameNested, TParentPath, E['~types']['argsSchema'], E['~types']['result'], E['~types']['commands'], TParentArgs, E['~types']['configSchema'], E['~types']['envSchema'], E['~types']['async']> : PadroneBuilder<TProgramName, TNameNested, TParentPath, PadroneSchema<void>, void, [], TParentArgs, PadroneSchema<void>, PadroneSchema<void>, false>;
-type AnyPadroneBuilder = InitialCommandBuilder<string, string, string, any, [...AnyPadroneCommand[]]>;
-/**
- * Like InitialCommandBuilder but uses `any` for args/config/env in the fresh case.
- * Used as the default for TBuilder when no builderFn is provided.
- */
-type DefaultCommandBuilder<TProgramName extends string, TNameNested extends string, TParentPath extends string, TParentArgs extends PadroneSchema, TCommands extends [...AnyPadroneCommand[]]> = [FindDirectChild<TCommands, TNameNested>] extends [never] ? PadroneBuilder<TProgramName, TNameNested, TParentPath, any, void, [], TParentArgs, any, any, false> : FindDirectChild<TCommands, TNameNested> extends infer E extends AnyPadroneCommand ? PadroneBuilder<TProgramName, TNameNested, TParentPath, E['~types']['argsSchema'], E['~types']['result'], E['~types']['commands'], TParentArgs, E['~types']['configSchema'], E['~types']['envSchema'], E['~types']['async']> : PadroneBuilder<TProgramName, TNameNested, TParentPath, any, void, [], TParentArgs, any, any, false>;
-type PadroneCommand<TName extends string = string, TParentName extends string = '', TArgs extends PadroneSchema = PadroneSchema<DefaultArgs>, TRes = void, TCommands extends [...AnyPadroneCommand[]] = [], TAliases extends string[] = string[], TConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = PadroneSchema<void>, TEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = PadroneSchema<void>, TAsync extends boolean = false> = {
+type PadroneCommand<TName extends string = string, TParentName extends string = '', TArgs extends PadroneSchema = PadroneSchema<DefaultArgs$1>, TRes = void, TCommands extends [...AnyPadroneCommand[]] = [], TAliases extends string[] = string[], TAsync extends boolean = false, TContext = unknown, TContextProvided = unknown> = {
   name: TName;
   path: FullCommandName<TName, TParentName>;
   title?: string;
@@ -574,29 +877,15 @@ type PadroneCommand<TName extends string = string, TParentName extends string =
   hidden?: boolean; /** Group name for organizing this command under a labeled section in help output. */
   group?: string; /** Whether this command performs a mutation (create, update, delete). Affects HTTP method in serve (POST-only) and MCP tool annotations (destructiveHint). */
   mutation?: boolean;
-  needsApproval?: boolean | ((args: TArgs) => Promise<boolean> | boolean);
-  autoOutput?: boolean; /** Usage examples shown in help output. Each entry is a command-line invocation string. */
+  needsApproval?: boolean | ((args: TArgs) => Promise<boolean> | boolean); /** Usage examples shown in help output. Each entry is a command-line invocation string. */
   examples?: string[];
-  /**
-   * Auto-start a progress indicator when the command's execute phase begins.
-   * - `true` — generic message based on command name.
-   * - `string` — custom message for all states.
-   * - `PadroneProgressConfig` — separate messages for progress, success, and error states.
-   *
-   * The indicator is automatically stopped on success (`.succeed()`) or failure (`.fail()`).
-   * Requires a `progress` factory on the runtime — silently skipped if not available.
-   */
-  progress?: boolean | string | PadroneProgressPrefs;
   argsSchema?: TArgs;
-  configSchema?: TConfig;
-  envSchema?: TEnv;
   meta?: GetArgsMeta<TArgs>;
-  action?: (args: StandardSchemaV1.InferOutput<TArgs>, ctx: PadroneActionContext) => TRes; /** List of possible config file names to search for. */
-  configFiles?: string[]; /** Runtime flag indicating this command uses async validation. Set by `.async()` or `asyncSchema()`. */
+  action?: (args: StandardSchemaV1.InferOutput<TArgs>, ctx: PadroneActionContext<TContext & TContextProvided>) => TRes; /** Runtime flag indicating this command uses async validation. Set by `.async()` or `asyncSchema()`. */
   isAsync?: boolean; /** Runtime configuration for I/O abstraction. */
-  runtime?: PadroneRuntime; /** Plugins registered on this command. Collected from the parent chain at execution time. */
-  plugins?: PadronePlugin<any, any>[]; /** Update check configuration. Only used on the root program. */
-  updateCheck?: UpdateCheckConfig;
+  runtime?: PadroneRuntime; /** Transform function that maps parent context to this command's context. Set by `.context(transform)`. */
+  contextTransform?: (ctx: unknown) => unknown; /** Interceptors registered on this command. Collected from the parent chain at execution time. */
+  interceptors?: RegisteredInterceptor[];
   parent?: AnyPadroneCommand;
   commands?: TCommands; /** @deprecated Internal use only */
   '~types': {
@@ -609,9 +898,9 @@ type PadroneCommand<TName extends string = string, TParentName extends string =
     argsOutput: StandardSchemaV1.InferOutput<TArgs>;
     result: TRes;
     commands: TCommands;
-    configSchema: TConfig;
-    envSchema: TEnv;
     async: TAsync;
+    context: TContext;
+    contextProvided: TContextProvided;
   };
 };
 type AnyPadroneCommand = PadroneCommand<string, any, any, any, [...AnyPadroneCommand[]], string[], any, any, any>;
@@ -624,438 +913,9 @@ type CommandTypesBase = {
     command: AnyPadroneCommand;
   };
 };
-/**
- * Configuration for a command.
- */
-/**
- * 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;
-};
-/**
- * Progress indicator configuration with per-state messages and optional dynamic callbacks.
- *
- * The `success` and `error` fields accept either a static value or a callback function:
- * - `string` — static message.
- * - `null` — suppress the message entirely.
- * - `{ message, indicator }` — custom message with a per-call indicator icon override.
- * - `(result) => PadroneProgressMessage` / `(error) => PadroneProgressMessage` — dynamic from the actual result/error.
- */
-type PadroneProgressPrefs<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); /** Spinner configuration: a preset name, custom frames/interval, or `false` to disable. */
-  spinner?: PadroneSpinnerConfig;
-};
-type PadroneCommandConfig = {
-  /** A short title for the command, displayed in help. */title?: string; /** A longer description of what the command does. */
-  description?: string; /** The version of the command. */
-  version?: string; /** Whether the command is deprecated, or a message explaining the deprecation. */
-  deprecated?: boolean | string; /** Whether the command should be hidden from help output. */
-  hidden?: boolean; /** Group name for organizing this command under a labeled section in help output. */
-  group?: string;
-  /**
-   * Automatically write this command's return value to output in CLI/eval/REPL mode.
-   * Overrides the `autoOutput` setting in eval/cli preferences for this command.
-   * See `PadroneEvalPreferences.autoOutput` for serialization details.
-   */
-  autoOutput?: boolean; /** Usage examples shown in help output. Each entry is a command-line invocation string. */
-  examples?: string[];
-  /**
-   * Whether this command performs a mutation (create, update, delete).
-   * - In `serve()`: mutation commands accept POST only; non-mutation commands accept GET and POST.
-   * - In `mcp()`: sets `annotations.destructiveHint` on the tool definition.
-   * - In `tool()`: defaults `needsApproval` to `true` when not explicitly set.
-   */
-  mutation?: boolean;
-};
-/**
- * Conditional type that returns either PadroneBuilder or PadroneProgram based on TReturn.
- * Used to avoid repetition in PadroneBuilderMethods return types.
- */
-type BuilderOrProgram<TReturn extends 'builder' | 'program', TProgramName extends string, TName extends string, TParentName extends string, TArgs extends PadroneSchema, TRes, TCommands extends [...AnyPadroneCommand[]], TParentArgs extends PadroneSchema, TConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>>, TEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>>, TAsync extends boolean> = TReturn extends 'builder' ? PadroneBuilder<TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync> : PadroneProgram<TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
-/**
- * Base builder methods shared between PadroneBuilder and PadroneProgram.
- * These methods are used for defining command structure (arguments, config, env, action, subcommands).
- */
-type PadroneBuilderMethods<TProgramName extends string, TName extends string, TParentName extends string, TArgs extends PadroneSchema, TRes, TCommands extends [...AnyPadroneCommand[]], TParentArgs extends PadroneSchema, TConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>>, TEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>>, TAsync extends boolean, /** The return type for builder methods - either PadroneBuilder or PadroneProgram */TReturn extends 'builder' | 'program'> = {
-  /**
-   * Enables automatic update checking against a package registry.
-   * When enabled, the program checks for a newer version in the background
-   * and displays a notification after command output if an update is available.
-   *
-   * - Non-blocking: check runs in background, never delays command execution.
-   * - Non-intrusive: shows a one-line notice after command output, not before.
-   * - Respects CI: disabled when `CI=true` or non-TTY.
-   * - Respects user preference: `--no-update-check` flag or env var.
-   * - Caches last check timestamp to avoid hitting the registry on every invocation.
-   *
-   * @example
-   * ```ts
-   * createPadrone('myapp')
-   *   .version('1.2.3')
-   *   .updateCheck({
-   *     registry: 'npm',         // or custom URL
-   *     interval: '1d',          // check at most once per day
-   *     cache: '~/.myapp-update' // where to store last check
-   *   })
-   * ```
-   */
-  updateCheck: (config?: UpdateCheckConfig) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
-  /**
-   * Registers a plugin that intercepts command execution phases (parse, validate, execute).
-   * Plugins are applied in order: first registered = outermost wrapper (runs first before `next()`).
-   * Use `plugin.order` for explicit ordering (lower = outermost).
-   *
-   * On the program, parse/validate/execute plugins all apply.
-   * On subcommands, only validate and execute plugins apply (parse is handled by the root program).
-   */
-  use: (plugin: PadronePlugin<StandardSchemaV1.InferOutput<TArgs>, TRes>) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
-  configure: (config: PadroneCommandConfig) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
-  /**
-   * Configures the runtime adapter for I/O abstraction.
-   * Allows the CLI framework to work outside of a terminal (e.g., web UIs, chat interfaces, testing).
-   * Unspecified fields fall back to the Node.js/Bun defaults.
-   *
-   * @example
-   * ```ts
-   * .runtime({
-   *   output: (text) => panel.append(text),
-   *   error: (text) => panel.appendError(text),
-   *   format: 'html',
-   * })
-   * ```
-   */
-  runtime: (runtime: PadroneRuntime) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
-  /**
-   * Explicitly marks this command as using async validation.
-   * When a command is async, `parse()` and `cli()` return Promises.
-   *
-   * This is an alternative to using `asyncSchema()` on individual schemas.
-   * Use this when your schema has async refinements but you don't want to
-   * (or can't) brand the schema itself.
-   *
-   * @example
-   * ```ts
-   * .arguments(z.object({ name: z.string() }).check(async (v) => { ... }))
-   * .async()
-   * .action((args) => { ... })
-   * ```
-   */
-  async: () => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, true>;
-  /**
-   * Defines the arguments schema for the command, including positional arguments.
-   * Can accept either a schema directly or a function that takes parent args schema as a base and returns a schema.
-   * Use the `positional` array in meta to specify which arguments are positional args.
-   * Use '...name' prefix for variadic (rest) arguments, matching JS/TS rest syntax.
-   *
-   * @example
-   * ```ts
-   * // Direct schema
-   * .arguments(z.object({
-   *   source: z.string(),
-   *   files: z.string().array(),
-   *   dest: z.string(),
-   *   recursive: z.boolean().default(false),
-   * }), {
-   *   positional: ['source', '...files', 'dest'],
-   * })
-   * ```
-   *
-   * @example
-   * ```ts
-   * // Function-based schema extending parent arguments
-   * .arguments((parentArgs) => {
-   *   return z.object({
-   *     ...parentArgs.shape,
-   *     verbose: z.boolean().default(false),
-   *   });
-   * })
-   * ```
-   */
-  arguments: <TNewArgs extends PadroneSchema = PadroneSchema<void>, TMeta extends GetArgsMeta<TNewArgs> = GetArgsMeta<TNewArgs>>(schema?: TNewArgs | ((parentSchema: TParentArgs) => TNewArgs), meta?: TMeta) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TNewArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, OrAsyncMeta<OrAsync<TAsync, TNewArgs>, TMeta>>;
-  /**
-   * Configures config file path(s) and schema for parsing config files.
-   * @example
-   * ```ts
-   * .configFile('config.json', z.object({ port: z.number() }))
-   * ```
-   */
-  configFile: <TNewConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = TArgs>(file: string | string[] | undefined, schema?: TNewConfig | ((argsSchema: TArgs) => TNewConfig)) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TNewConfig, TEnv, OrAsync<TAsync, TNewConfig>>;
-  /**
-   * Configures environment variable schema for parsing env vars into arguments.
-   * The schema should transform environment variables (typically SCREAMING_SNAKE_CASE)
-   * into the argument names used by the command.
-   * @example
-   * ```ts
-   * .env(z.object({ MY_APP_PORT: z.coerce.number() }).transform(e => ({ port: e.MY_APP_PORT })))
-   * ```
-   */
-  env: <TNewEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = TArgs>(schema: TNewEnv | ((argsSchema: TArgs) => TNewEnv)) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TNewEnv, OrAsync<TAsync, TNewEnv>>;
-  /**
-   * Configures an auto-managed progress indicator for this command.
-   * The indicator starts before validation and is automatically stopped on success or failure.
-   *
-   * - `true` — generic message based on command name.
-   * - `string` — custom message for all states.
-   * - `PadroneProgressConfig` — full control: per-state messages, dynamic callbacks, spinner config.
-   *
-   * Requires a `progress` factory on the runtime — silently skipped if not available.
-   *
-   * @example
-   * ```ts
-   * .progress('Deploying...')
-   * .progress({
-   *   progress: 'Deploying...',
-   *   success: (result) => `Deployed ${result.version}`,
-   *   error: (err) => `Deploy failed: ${err.message}`,
-   *   spinner: 'line',
-   * })
-   * ```
-   */
-  progress: (config?: boolean | string | PadroneProgressPrefs<Awaited<TRes>>) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
-  /**
-   * Defines the handler function to be executed when the command is run.
-   * When overriding an existing command, the previous handler is passed as the third `base` parameter.
-   */
-  action: <TNewRes>(handler?: (args: StandardSchemaV1.InferOutput<TArgs>, ctx: PadroneActionContext, base: (args: StandardSchemaV1.InferOutput<TArgs>, ctx: PadroneActionContext) => TRes) => TNewRes) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TNewRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
-  /**
-   * Wraps an external CLI tool with optional schema transformation.
-   * The config can include a schema that transforms command arguments to external CLI arguments.
-   *
-   * @experimental This API is experimental and may change in future releases.
-   *
-   * @example
-   * ```ts
-   * // No transformation - pass arguments as-is
-   * .arguments(z.object({
-   *   message: z.string(),
-   * }))
-   * .wrap({
-   *   command: 'echo',
-   * })
-   * ```
-   *
-   * @example
-   * ```ts
-   * // With transformation schema
-   * .arguments(z.object({
-   *   message: z.string(),
-   *   all: z.boolean().optional(),
-   * }), {
-   *   positional: ['message'],
-   * })
-   * .wrap({
-   *   command: 'git',
-   *   args: ['commit'],
-   *   positional: ['m'],
-   *   schema: z.object({
-   *     message: z.string(),
-   *     all: z.boolean().optional(),
-   *   }).transform(args => ({
-   *     m: args.message,
-   *     a: args.all,
-   *   })),
-   * })
-   * ```
-   *
-   * @example
-   * ```ts
-   * // Using function-based schema for type inference
-   * .arguments(z.object({
-   *   image: z.string(),
-   *   detach: z.boolean().optional(),
-   * }))
-   * .wrap({
-   *   command: 'docker',
-   *   args: ['run'],
-   *   positional: ['image'],
-   *   schema: (schema) => schema.transform(args => ({
-   *     d: args.detach,
-   *     image: args.image,
-   *   })),
-   * })
-   * ```
-   */
-  wrap: <TWrapArgs extends PadroneSchema = TArgs>(config: WrapConfig<TArgs, TWrapArgs>) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, Promise<WrapResult>, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
-  /**
-   * Creates or extends a nested command within the current command.
-   * If a command with the same name already exists, it is extended:
-   * - Configuration is merged (new values override old).
-   * - The builder callback receives a builder pre-populated with the existing command's state.
-   * - `.action()` receives the previous handler as the third `base` parameter.
-   * - `.arguments()` callback receives the existing schema as its parameter.
-   * - Subcommands are recursively merged by name.
-   *
-   * @example
-   * ```ts
-   * // Fresh command
-   * .command('list', (c) => c.action(() => 'list'))
-   *
-   * // Override — extend an existing command
-   * .command('list', (c) => c.action((args, ctx, base) => {
-   *   const original = base(args, ctx);
-   *   return `modified: ${original}`;
-   * }))
-   *
-   * // Name with aliases
-   * .command(['list', 'ls', 'l'], (c) => c.action(() => 'list'))
-   * ```
-   */
-  command: <TNameNested extends string, TAliases extends string[] = [], TBuilder extends CommandTypesBase = DefaultCommandBuilder<TProgramName, TNameNested, FullCommandName<TName, TParentName>, TArgs, TCommands>>(name: TNameNested | readonly [TNameNested, ...TAliases], builderFn?: (builder: InitialCommandBuilder<TProgramName, TNameNested, FullCommandName<TName, TParentName>, TArgs, TCommands>) => TBuilder) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands extends [] ? [WithAliases<TBuilder['~types']['command'], TAliases>] : AnyPadroneCommand[] extends TCommands ? [WithAliases<TBuilder['~types']['command'], TAliases>] : ReplaceOrAppendCommand<TCommands, TNameNested, WithAliases<TBuilder['~types']['command'], ResolvedAliases<TCommands, TNameNested, TAliases>>>, TParentArgs, TConfig, TEnv, TAsync>;
-  /**
-   * Mounts an existing Padrone program as a subcommand.
-   * The program's root-level properties (name, path, parent) are replaced to fit the mount point.
-   * All subcommands are recursively re-pathed. Root-level `version` is dropped.
-   *
-   * @example
-   * ```ts
-   * const admin = createPadrone('admin')
-   *   .command('users', (c) => c.action(() => 'users'))
-   *   .command('roles', (c) => c.action(() => 'roles'));
-   *
-   * const app = createPadrone('app')
-   *   .mount('admin', admin)
-   *   // Now: app admin users, app admin roles
-   *
-   * // With aliases
-   * const app2 = createPadrone('app')
-   *   .mount(['admin', 'adm'], admin)
-   * ```
-   */
-  mount: <TNameNested extends string, TAliases extends string[] = [], TProgram extends CommandTypesBase = CommandTypesBase>(name: TNameNested | readonly [TNameNested, ...TAliases], program: TProgram) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands extends [] ? [WithAliases<PadroneCommand<TNameNested, FullCommandName<TName, TParentName>, TProgram['~types']['command']['~types']['argsSchema'], TProgram['~types']['command']['~types']['result'], RepathCommands<TProgram['~types']['command']['~types']['commands'], FullCommandName<TNameNested, FullCommandName<TName, TParentName>>>, [], TProgram['~types']['command']['~types']['configSchema'], TProgram['~types']['command']['~types']['envSchema'], TProgram['~types']['command']['~types']['async']>, TAliases>] : AnyPadroneCommand[] extends TCommands ? [WithAliases<PadroneCommand<TNameNested, FullCommandName<TName, TParentName>, TProgram['~types']['command']['~types']['argsSchema'], TProgram['~types']['command']['~types']['result'], RepathCommands<TProgram['~types']['command']['~types']['commands'], FullCommandName<TNameNested, FullCommandName<TName, TParentName>>>, [], TProgram['~types']['command']['~types']['configSchema'], TProgram['~types']['command']['~types']['envSchema'], TProgram['~types']['command']['~types']['async']>, TAliases>] : ReplaceOrAppendCommand<TCommands, TNameNested, WithAliases<PadroneCommand<TNameNested, FullCommandName<TName, TParentName>, TProgram['~types']['command']['~types']['argsSchema'], TProgram['~types']['command']['~types']['result'], RepathCommands<TProgram['~types']['command']['~types']['commands'], FullCommandName<TNameNested, FullCommandName<TName, TParentName>>>, [], TProgram['~types']['command']['~types']['configSchema'], TProgram['~types']['command']['~types']['envSchema'], TProgram['~types']['command']['~types']['async']>, ResolvedAliases<TCommands, TNameNested, TAliases>>>, TParentArgs, TConfig, TEnv, TAsync>; /** @deprecated Internal use only */
-  '~types': {
-    programName: TProgramName;
-    name: TName;
-    parentName: TParentName;
-    path: FullCommandName<TName, TParentName>;
-    aliases: [];
-    argsSchema: TArgs;
-    result: TRes;
-    commands: TCommands;
-    async: TAsync;
-    command: PadroneCommand<TName, TParentName, TArgs, TRes, TCommands, [], TConfig, TEnv, TAsync>;
-  };
-};
-type PadroneBuilder<TProgramName extends string = '', TName extends string = string, TParentName extends string = '', TArgs extends PadroneSchema = PadroneSchema<DefaultArgs>, TRes = void, TCommands extends [...AnyPadroneCommand[]] = [], TParentArgs extends PadroneSchema = PadroneSchema<void>, TConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = PadroneSchema<void>, TEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = PadroneSchema<void>, TAsync extends boolean = false> = PadroneBuilderMethods<TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync, 'builder'>;
-type PadroneProgram<TProgramName extends string = '', TName extends string = string, TParentName extends string = '', TArgs extends PadroneSchema = PadroneSchema<DefaultArgs>, TRes = void, TCommands extends [...AnyPadroneCommand[]] = [], TParentArgs extends PadroneSchema = PadroneSchema<void>, TConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = PadroneSchema<void>, TEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = PadroneSchema<void>, TAsync extends boolean = false> = PadroneBuilderMethods<TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync, 'program'> & {
-  /**
-   * Runs a command programmatically by name with provided arguments (including positional args).
-   */
-  run: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], true, true>>(name: TCommand | SafeString, args: NoInfer<GetArguments<'in', PickCommandByName<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>>>) => PadroneCommandResult<PickCommandByName<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>>;
-  /**
-   * Evaluates a command string: parses, validates, and executes.
-   * On validation errors, returns a result with issues instead of throwing.
-   * This is the method used by `repl()` internally, and the right choice for
-   * programmatic invocation, testing, chat interfaces, or any context where
-   * you have a command string and want a result — not a process exit.
-   *
-   * @example
-   * ```ts
-   * const result = await program.eval('greet --name Alice');
-   * if (result.argsResult?.issues) { /* handle validation errors *\/ }
-   * ```
-   */
-  eval: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], true, true>>(input: TCommand | SafeString, prefs?: PadroneEvalPreferences) => MaybePromiseCommandResult<PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>, PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>['~types']['async']>;
-  /**
-   * Runs the program as a CLI entry point, parsing `process.argv`.
-   * On validation errors, throws and prints help.
-   * For programmatic invocation with a command string, use `eval()` instead.
-   */
-  cli: (prefs?: PadroneCliPreferences<PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>) => MaybePromiseCommandResult<FlattenCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>, TAsync>;
-  /**
-   * Parses CLI input (or the provided input string) into command and arguments without executing anything.
-   */
-  parse: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], true, false>>(input?: TCommand | SafeString) => MaybePromise<PadroneParseResult<PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>>, PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>['~types']['async']>;
-  /**
-   * Converts command and arguments back into a CLI string.
-   */
-  stringify: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], false, true>>(command?: TCommand | SafeString, args?: GetArguments<'out', PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>>) => string;
-  /**
-   * Finds a command by name, returning `undefined` if not found.
-   */
-  find: <const TFind extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], false, true>>(command: TFind | SafeString) => PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TFind> | undefined;
-  /**
-   * Generates a type-safe API for invoking commands programmatically.
-   */
-  api: () => PadroneAPI<PadroneCommand<'', '', TArgs, TRes, TCommands>>;
-  /**
-   * Starts a REPL (Read-Eval-Print Loop) for running commands interactively.
-   * Returns an AsyncIterable that yields a `PadroneCommandResult` for each successfully executed command.
-   * Errors are printed via `runtime.error()` and the loop continues.
-   * The loop ends when the user sends EOF (Ctrl+D), types `.exit`/`.quit`,
-   * or presses Ctrl+C twice within 2 seconds.
-   *
-   * @example
-   * ```ts
-   * for await (const result of program.repl()) {
-   *   console.log(result.command.name, result.result);
-   * }
-   * ```
-   *
-   * TODO: REPL future enhancements:
-   * - History persistence: save/load history across sessions (currently in-memory only)
-   * - Middleware/hooks: onBeforeCommand, onAfterCommand, error interceptors (design alongside general middleware system)
-   */
-  repl: (options?: PadroneReplPreferences<PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>) => AsyncIterable<PadroneCommandResult<FlattenCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>> & {
-    drain: () => Promise<PadroneDrainResult<PadroneCommandResult<FlattenCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>[]>>;
-  };
-  /**
-   * Returns a tool definition that can be passed to AI SDK.
-   */
-  tool: () => Tool<{
-    command: string;
-  }>;
-  /**
-   * Returns the help information for the program or a specific command.
-   */
-  help: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], false, true>>(command?: TCommand, prefs?: HelpPreferences) => string;
-  /**
-   * Generates and returns a shell completion script.
-   * If shell is not specified, automatically detects the current shell and provides instructions.
-   * @param shell - The shell type (bash, zsh, fish, powershell). If not provided, auto-detects.
-   * @returns The shell completion script as a string.
-   * @example
-   * ```ts
-   * // Get bash completion script
-   * const bashScript = program.completion('bash');
-   *
-   * // Auto-detect shell and get completion script with instructions
-   * const script = program.completion();
-   * ```
-   */
-  completion: (shell?: 'bash' | 'zsh' | 'fish' | 'powershell') => Promise<string>;
-  /**
-   * Starts a Model Context Protocol (MCP) server that exposes commands as tools for AI assistants.
-   * Communicates over stdio using JSON-RPC with Content-Length framing.
-   * Returns a Promise that resolves when the connection closes.
-   *
-   * @experimental This API is experimental and may change in future releases.
-   *
-   * @example
-   * ```ts
-   * await program.mcp();
-   * ```
-   */
-  mcp: (prefs?: PadroneMcpPreferences) => Promise<void>;
-  /**
-   * Starts a REST HTTP server that exposes commands as endpoints.
-   * Each command becomes a route: `users list` → `GET/POST /users/list`.
-   * Commands with `mutation: true` only accept POST.
-   *
-   * @experimental This API is experimental and may change in future releases.
-   *
-   * @example
-   * ```ts
-   * await program.serve({ port: 3000 });
-   * ```
-   */
-  serve: (prefs?: PadroneServePreferences) => Promise<void>;
-};
-type AnyPadroneProgram = PadroneProgram<string, string, string, any, any, [...AnyPadroneCommand[]]>;
+type GetArgsMeta<TArgs extends PadroneSchema> = PadroneArgsSchemaMeta<NonNullable<StandardSchemaV1.InferInput<TArgs>>>;
+//#endregion
+//#region src/types/preferences.d.ts
 /**
  * Options for `repl()` to customize the REPL session.
  */
@@ -1097,12 +957,6 @@ type PadroneReplPreferences<TScope extends string = string> = {
    * Users can change scope at runtime with `.scope <subcommand>` and `.scope ..`/`..`.
    */
   scope?: TScope;
-  /**
-   * Automatically write each command's return value to output.
-   * See `PadroneEvalPreferences.autoOutput` for details on how values are serialized.
-   * Defaults to `true`.
-   */
-  autoOutput?: boolean;
 };
 /**
  * Options that can be passed to `eval()` to control execution behavior.
@@ -1117,32 +971,29 @@ type PadroneEvalPreferences = {
    * - `false`: suppress all interactive prompts.
    */
   interactive?: boolean;
-  /**
-   * Automatically write the command's return value to output.
-   *
-   * - 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.
-   * - `undefined` and `null` results produce no output.
-   *
-   * Defaults to `true`. Set to `false` to disable.
-   */
-  autoOutput?: boolean;
   /**
    * Override the runtime for this execution.
    * Partial — only the provided fields replace the command's resolved runtime.
    * Useful for capturing output, injecting test doubles, or running in non-terminal contexts (e.g. AI tool calls).
    */
   runtime?: PadroneRuntime;
+  /**
+   * User-defined context object passed to command action handlers via `ctx.context`.
+   * The context flows through the command tree and can be transformed by subcommands via `.context(transform)`.
+   */
+  context?: unknown; /** @internal Which API entry point triggered this execution. */
+  caller?: PadroneActionContext['caller'];
 };
 /**
  * Options that can be passed to `cli()` to control execution behavior.
  */
-type PadroneCliPreferences<TScope extends string = string> = PadroneEvalPreferences & {
-  /** REPL preferences used when `--repl` flag is passed. Set to `false` to disable the `--repl` flag. */repl?: PadroneReplPreferences<TScope> | false; /** MCP server preferences used when `mcp` command is used. Set to `false` to disable. */
-  mcp?: PadroneMcpPreferences | false; /** REST server preferences used when `serve` command is used. Set to `false` to disable. */
-  serve?: PadroneServePreferences | false;
-};
+type PadroneCliPreferences = PadroneEvalPreferences;
+//#endregion
+//#region src/types/result.d.ts
+type EmptyRecord = Record<string, never>;
+type NormalizeArguments<TArgs> = IsGeneric<TArgs> extends true ? void | EmptyRecord : TArgs;
+type GetArguments<TDir extends 'in' | 'out', TCommand extends AnyPadroneCommand> = TDir extends 'in' ? NormalizeArguments<TCommand['~types']['argsInput']> : NormalizeArguments<TCommand['~types']['argsOutput']>;
+type GetResults<TCommand extends AnyPadroneCommand> = ReturnType<NonNullable<TCommand['action']>>;
 /**
  * Result of `drain()` — a discriminated union that never throws.
  * On success, `value` holds the fully resolved/collected result; on failure, `error` holds the error.
@@ -1163,14 +1014,18 @@ type PadroneDrainResult<TResult> = {
  */
 type PadroneCommandResult<TCommand extends AnyPadroneCommand = AnyPadroneCommand> = (PadroneParseResult<TCommand> & {
   result: GetResults<TCommand>;
-  error?: never; /** Flattens the result: awaits Promises, collects iterables, catches errors. Never throws. */
+  error?: never; /** The signal that caused cancellation, if any. */
+  signal?: PadroneSignal; /** Suggested exit code (e.g. 130 for SIGINT). Present when a signal caused termination. */
+  exitCode?: number; /** Flattens the result: awaits Promises, collects iterables, catches errors. Never throws. */
   drain: () => Promise<PadroneDrainResult<GetResults<TCommand>>>;
 }) | {
   command?: TCommand;
   args?: GetArguments<'out', TCommand>;
   argsResult?: StandardSchemaV1.Result<GetArguments<'out', TCommand>>;
   error: unknown;
-  result?: never; /** Returns `{ error }` since there is no result to drain. */
+  result?: never; /** The signal that caused cancellation, if any. */
+  signal?: PadroneSignal; /** Suggested exit code (e.g. 130 for SIGINT). Present when a signal caused termination. */
+  exitCode?: number; /** Returns `{ error }` since there is no result to drain. */
   drain: () => Promise<PadroneDrainResult<GetResults<TCommand>>>;
 };
 /**
@@ -1187,121 +1042,137 @@ type PadroneParseResult<TCommand extends AnyPadroneCommand = AnyPadroneCommand>
 };
 type PadroneAPI<TCommand extends AnyPadroneCommand> = PadroneAPICommand<TCommand> & { [K in TCommand['~types']['commands'][number] as K['name']]: PadroneAPI<K> };
 type PadroneAPICommand<TCommand extends AnyPadroneCommand> = (args: GetArguments<'in', TCommand>) => GetResults<TCommand>;
-type NormalizeArguments<TArgs> = IsGeneric<TArgs> extends true ? void | EmptyRecord : TArgs;
-type GetArguments<TDir extends 'in' | 'out', TCommand extends AnyPadroneCommand> = TDir extends 'in' ? NormalizeArguments<TCommand['~types']['argsInput']> : NormalizeArguments<TCommand['~types']['argsOutput']>;
-type GetResults<TCommand extends AnyPadroneCommand> = ReturnType<NonNullable<TCommand['action']>>;
-type GetArgsMeta<TArgs extends PadroneSchema> = PadroneArgsSchemaMeta<NonNullable<StandardSchemaV1.InferInput<TArgs>>>;
-/** Base context shared across all plugin phases within a single execution. */
-type PluginBaseContext = {
-  /** The resolved command for this execution. In the parse phase, this is the root program. */command: AnyPadroneCommand; /** Mutable state bag shared across phases for this execution. Plugins can store cross-phase data here. */
-  state: Record<string, unknown>;
-};
-/** Context for the parse phase. */
-type PluginParseContext = PluginBaseContext & {
-  /** The raw CLI input string (undefined when invoked without input). */input: string | undefined;
-};
-/** Result returned by the parse phase's `next()`. */
-type PluginParseResult = {
-  command: AnyPadroneCommand;
-  rawArgs: Record<string, unknown>;
-  positionalArgs: string[];
-};
-/** Context for the validate phase. */
-type PluginValidateContext = PluginBaseContext & {
-  /** Raw named arguments extracted by the parser. Mutable — modify before `next()` to inject/override values. */rawArgs: Record<string, unknown>; /** Positional argument strings extracted by the parser. */
-  positionalArgs: string[];
-};
-/** Result returned by the validate phase's `next()`. */
-type PluginValidateResult<TArgs = unknown> = {
-  args: TArgs;
-  argsResult: StandardSchemaV1.Result<TArgs>;
-};
-/** Context for the execute phase. */
-type PluginExecuteContext<TArgs = unknown> = PluginBaseContext & {
-  /** Validated arguments that will be passed to the action. Mutable — modify before `next()` to override. */args: TArgs;
-};
-/** Result returned by the execute phase's `next()`. */
-type PluginExecuteResult<TResult = unknown> = {
-  result: TResult;
-};
-/** Context for the start phase. Runs before parsing, wraps the entire pipeline. */
-type PluginStartContext = PluginBaseContext & {
-  /** The raw CLI input string (undefined when invoked without input). */input: string | undefined;
-};
-/** Context for the error phase. Called when the pipeline throws. */
-type PluginErrorContext = PluginBaseContext & {
-  /** The error that was thrown. */error: unknown;
+//#endregion
+//#region src/types/builder.d.ts
+/**
+ * Helper type to set aliases on a command type.
+ * Uses intersection to override just the aliases while preserving all other type information.
+ */
+type WithAliases<TCommand extends AnyPadroneCommand, TAliases extends string[]> = Omit<TCommand, 'aliases' | '~types'> & {
+  aliases?: TAliases;
+  '~types': Omit<TCommand['~types'], 'aliases'> & {
+    aliases: TAliases;
+  };
 };
-/** Result returned by the error phase's `next()`. */
-type PluginErrorResult<TResult = unknown> = {
-  /** The error (possibly transformed). Set to `undefined` to suppress the error. */error?: unknown; /** A replacement result when suppressing the error. */
-  result?: TResult;
+/**
+ * Resolves aliases for a command override: if new aliases are provided (non-empty), use them;
+ * otherwise, preserve the existing command's aliases.
+ */
+type ResolvedAliases<TCommands extends [...AnyPadroneCommand[]], TNameNested extends string, TAliases extends string[]> = TAliases extends [] ? FindDirectChild<TCommands, TNameNested> extends infer E extends AnyPadroneCommand ? E['~types']['aliases'] : [] : TAliases;
+/**
+ * When TContext is `unknown` (no `.context()` called), context param is optional.
+ * Otherwise it is required.
+ */
+type ContextParam<TContext> = unknown extends TContext ? {
+  context?: TContext;
+} : {
+  context: TContext;
 };
-/** Context for the shutdown phase. Always runs after the pipeline (success or failure). */
-type PluginShutdownContext<TResult = unknown> = PluginBaseContext & {
-  /** The error, if the pipeline failed (after error phase processing). */error?: unknown; /** The pipeline result, if it succeeded. */
-  result?: TResult;
+/** Options for the `mount()` method. */
+type MountOptions<TContext, TNewContext> = {
+  context: (ctx: TContext) => TNewContext;
 };
 /**
- * A phase handler function for the plugin middleware chain.
- *
- * - `TCtx` — the context object available to the handler.
- * - `TNextResult` — the typed result returned by `next()`, giving the handler type-safe access to downstream output.
- * - `TReturn` — the type the handler itself returns. Defaults to `TNextResult` but can be wider,
- *   allowing plugins to transform or replace the result (e.g., error-recovery plugins returning a different type).
+ * Resolves the initial builder type for a `.command()` call.
+ * If TNameNested already exists in TCommands, the builder starts pre-populated with that command's types.
+ * Otherwise, a fresh builder with default types is used.
  */
-type PluginPhaseHandler<TCtx, TNextResult, TReturn = TNextResult> = (ctx: TCtx, next: () => TNextResult | Promise<TNextResult>) => TReturn | Promise<TReturn>;
+type InitialCommandBuilder<TProgramName extends string, TNameNested extends string, TParentPath extends string, TParentArgs extends PadroneSchema, TCommands extends [...AnyPadroneCommand[]], TParentContext> = [FindDirectChild<TCommands, TNameNested>] extends [never] ? PadroneBuilder<TProgramName, TNameNested, TParentPath, PadroneSchema<void>, void, [], TParentArgs, false, TParentContext> : FindDirectChild<TCommands, TNameNested> extends infer E extends AnyPadroneCommand ? PadroneBuilder<TProgramName, TNameNested, TParentPath, E['~types']['argsSchema'], E['~types']['result'], E['~types']['commands'], TParentArgs, E['~types']['async'], E['~types']['context'], E['~types']['contextProvided']> : PadroneBuilder<TProgramName, TNameNested, TParentPath, PadroneSchema<void>, void, [], TParentArgs, false, TParentContext>;
+type AnyPadroneBuilder = InitialCommandBuilder<string, string, string, any, [...AnyPadroneCommand[]], any>;
 /**
- * A Padrone plugin that can intercept the parse, validate, and execute phases of command execution.
- * Plugins are registered at the program or subcommand level with `.use()`.
- *
- * Type parameters:
- * - `TArgs` — the validated arguments type (output of the args schema). Provides typed `ctx.args` in the execute phase
- *   and typed `args` in the validate result from `next()`.
- * - `TResult` — the command's return type. Provides typed `result` in execute/error/shutdown phases.
- *
- * When registered inline on a builder, these are inferred from the command's types automatically.
- * For reusable plugins that work with any command, use `PadronePlugin<any, any>`.
- *
- * Each phase handler receives a context and a `next()` function (onion/middleware pattern):
- * - Call `next()` to proceed to the next plugin or the core operation.
- * - Return without calling `next()` to short-circuit.
- * - Wrap `next()` in try/catch for error handling.
- * - Modify context fields before `next()` to alter inputs.
- * - Transform the return value of `next()` to alter outputs.
+ * Like InitialCommandBuilder but uses `any` for args in the fresh case.
+ * Used as the default for TBuilder when no builderFn is provided.
  */
-type PadronePlugin<TArgs = unknown, TResult = unknown> = {
-  /** Display name for this plugin. Used for identification in logs and debugging. */name: string;
-  /**
-   * Optional unique identifier for deduplication. When multiple plugins share the same `id`,
-   * only the last one registered is kept. Useful for allowing downstream code to override
-   * a plugin without accumulating duplicates.
-   */
-  id?: string;
-  /**
-   * Ordering hint. Lower values run as outer layers (earlier before `next()`, later after).
-   * Plugins with the same order preserve registration order. Defaults to `0`.
-   */
-  order?: number;
-  /**
-   * Runs before the pipeline (parse → validate → execute). `next()` proceeds to the pipeline.
-   * Root plugins only. Use for startup tasks like telemetry, update checks, or global config loading.
-   */
-  start?: PluginPhaseHandler<PluginStartContext, unknown>; /** Intercepts command routing and raw argument extraction. */
-  parse?: PluginPhaseHandler<PluginParseContext, PluginParseResult>; /** Intercepts argument preprocessing, interactive prompting, and schema validation. */
-  validate?: PluginPhaseHandler<PluginValidateContext, PluginValidateResult<TArgs>, PluginValidateResult>; /** Intercepts handler execution. */
-  execute?: PluginPhaseHandler<PluginExecuteContext<TArgs>, PluginExecuteResult<TResult>, PluginExecuteResult>;
-  /**
-   * Called when the pipeline throws an error. `next()` passes to the next error handler
-   * (innermost returns `{ error }` unchanged). Return `{ result }` without `error` to suppress.
-   */
-  error?: PluginPhaseHandler<PluginErrorContext, PluginErrorResult<TResult>, PluginErrorResult>;
-  /**
-   * Always runs after the pipeline completes (success or failure). `next()` calls the next shutdown handler.
-   * Use for cleanup: closing connections, flushing logs, etc.
-   */
-  shutdown?: PluginPhaseHandler<PluginShutdownContext<TResult>, void>;
+type DefaultCommandBuilder<TProgramName extends string, TNameNested extends string, TParentPath extends string, TParentArgs extends PadroneSchema, TCommands extends [...AnyPadroneCommand[]], TParentContext> = [FindDirectChild<TCommands, TNameNested>] extends [never] ? PadroneBuilder<TProgramName, TNameNested, TParentPath, any, void, [], TParentArgs, false, TParentContext> : FindDirectChild<TCommands, TNameNested> extends infer E extends AnyPadroneCommand ? PadroneBuilder<TProgramName, TNameNested, TParentPath, E['~types']['argsSchema'], E['~types']['result'], E['~types']['commands'], TParentArgs, E['~types']['async'], E['~types']['context'], E['~types']['contextProvided']> : PadroneBuilder<TProgramName, TNameNested, TParentPath, any, void, [], TParentArgs, false, TParentContext>;
+/**
+ * Conditional type that returns either PadroneBuilder or PadroneProgram based on TReturn.
+ * Used to avoid repetition in PadroneBuilderMethods return types.
+ */
+type BuilderOrProgram<TReturn extends 'builder' | 'program', TProgramName extends string, TName extends string, TParentName extends string, TArgs extends PadroneSchema, TRes, TCommands extends [...AnyPadroneCommand[]], TParentArgs extends PadroneSchema, TAsync extends boolean, TContext, TContextProvided = unknown> = TReturn extends 'builder' ? PadroneBuilder<TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TAsync, TContext, TContextProvided> : PadroneProgram<TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TAsync, TContext, TContextProvided>;
+/**
+ * Base builder methods shared between PadroneBuilder and PadroneProgram.
+ * These methods are used for defining command structure (arguments, action, subcommands).
+ */
+type PadroneBuilderMethods<TProgramName extends string, TName extends string, TParentName extends string, TArgs extends PadroneSchema, TRes, TCommands extends [...AnyPadroneCommand[]], TParentArgs extends PadroneSchema, TAsync extends boolean, TContext, TContextProvided, /** The return type for builder methods - either PadroneBuilder or PadroneProgram */TReturn extends 'builder' | 'program'> = {
+  /** Apply a build-time extension that transforms this builder/program. @category Builder */extend: <TResult extends CommandTypesBase>(extension: PadroneExtension<BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TAsync, TContext, TContextProvided>, TResult>) => TResult; /** Register a runtime interceptor for lifecycle phases (parse, validate, execute, etc.). @category Builder */
+  intercept: {
+    /** Context-providing interceptor — extends context type. Rejects if required context is not satisfied. */<TInterceptor extends PadroneContextInterceptor<any, StandardSchemaV1.InferOutput<TArgs>, TRes, any>>(interceptor: TInterceptor): InterceptorRequiresCheck<TInterceptor, TContext & TContextProvided> extends true ? BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TAsync, TContext, TContextProvided & ExtractInterceptorContext<TInterceptor>> : InterceptorRequiresError; /** Plain interceptor — no context change. Rejects if required context is not satisfied. */
+    <TInterceptor extends PadroneInterceptorFn<StandardSchemaV1.InferOutput<TArgs>, TRes, any>>(interceptor: TInterceptor): InterceptorRequiresCheck<TInterceptor, TContext & TContextProvided> extends true ? BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TAsync, TContext, TContextProvided> : InterceptorRequiresError; /** Register an interceptor with static metadata and a factory function. Context is strongly typed. */
+    (meta: InterceptorMeta, factory: InterceptorFactory<StandardSchemaV1.InferOutput<TArgs>, TRes, TContext & TContextProvided>): BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TAsync, TContext, TContextProvided>;
+  }; /** Set command metadata like title, description, version, hidden, deprecated, etc. @category Builder */
+  configure: (config: PadroneCommandConfig) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TAsync, TContext, TContextProvided>; /** Override the runtime adapter (process, IO, environment). @category Builder */
+  runtime: (runtime: PadroneRuntime) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TAsync, TContext, TContextProvided>; /** Mark this command as async, forcing all return types to be `Promise`-wrapped. @category Builder */
+  async: () => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, true, TContext, TContextProvided>;
+  /**
+   * Declare or transform the user-defined context type for this command.
+   *
+   * - Without a callback: narrows the context type (type-only, no runtime transform).
+   * - With a callback: transforms the parent/current context into a new type. Chainable — multiple calls compose.
+   *
+   * Interceptor-provided context (`TContextProvided`) is preserved across `.context()` calls.
+   * @category Builder
+   */
+  context: {
+    <TNewContext>(): BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TAsync, TNewContext, TContextProvided>;
+    <TNewContext>(transform: (ctx: TContext) => TNewContext): BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TAsync, TNewContext, TContextProvided>;
+  }; /** Define the argument/option schema for this command. Accepts a Standard Schema or a function that extends the parent schema. @category Builder */
+  arguments: <TNewArgs extends PadroneSchema = PadroneSchema<void>, TMeta extends GetArgsMeta<TNewArgs> = GetArgsMeta<TNewArgs>>(schema?: TNewArgs | ((parentSchema: TParentArgs) => TNewArgs), meta?: TMeta) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TNewArgs, TRes, TCommands, TParentArgs, OrAsyncMeta<OrAsync<TAsync, TNewArgs>, TMeta>, TContext, TContextProvided>; /** Set the handler function that runs when this command is executed. @category Builder */
+  action: <TNewRes>(handler?: (args: StandardSchemaV1.InferOutput<TArgs>, ctx: PadroneActionContext<TContext & TContextProvided>, base: (args: StandardSchemaV1.InferOutput<TArgs>, ctx: PadroneActionContext<TContext & TContextProvided>) => TRes) => TNewRes) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TNewRes, TCommands, TParentArgs, TAsync, TContext, TContextProvided>; /** Wrap an external CLI tool, delegating execution to a shell command. @category Builder */
+  wrap: <TWrapArgs extends PadroneSchema = TArgs>(config: WrapConfig<TArgs, TWrapArgs>) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, Promise<WrapResult>, TCommands, TParentArgs, TAsync, TContext, TContextProvided>; /** Add or override a subcommand. Pass a builder function to define its schema, action, and nested commands. @category Builder */
+  command: <TNameNested extends string, TAliases extends string[] = [], TBuilder extends CommandTypesBase = DefaultCommandBuilder<TProgramName, TNameNested, FullCommandName<TName, TParentName>, TArgs, TCommands, TContext & TContextProvided>>(name: TNameNested | readonly [TNameNested, ...TAliases], builderFn?: (builder: InitialCommandBuilder<TProgramName, TNameNested, FullCommandName<TName, TParentName>, TArgs, TCommands, TContext & TContextProvided>) => TBuilder) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands extends [] ? [WithAliases<TBuilder['~types']['command'], TAliases>] : AnyPadroneCommand[] extends TCommands ? [WithAliases<TBuilder['~types']['command'], TAliases>] : ReplaceOrAppendCommand<TCommands, TNameNested, WithAliases<TBuilder['~types']['command'], ResolvedAliases<TCommands, TNameNested, TAliases>>>, TParentArgs, TAsync, TContext, TContextProvided>; /** Mount an existing program as a subcommand, optionally transforming the context. @category Builder */
+  mount: {
+    <TNameNested extends string, TAliases extends string[] = [], TProgram extends CommandTypesBase = CommandTypesBase>(name: TNameNested | readonly [TNameNested, ...TAliases], program: TProgram): BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands extends [] ? [WithAliases<PadroneCommand<TNameNested, FullCommandName<TName, TParentName>, TProgram['~types']['command']['~types']['argsSchema'], TProgram['~types']['command']['~types']['result'], RepathCommands<TProgram['~types']['command']['~types']['commands'], FullCommandName<TNameNested, FullCommandName<TName, TParentName>>>, [], TProgram['~types']['command']['~types']['async'], TContext & TContextProvided>, TAliases>] : AnyPadroneCommand[] extends TCommands ? [WithAliases<PadroneCommand<TNameNested, FullCommandName<TName, TParentName>, TProgram['~types']['command']['~types']['argsSchema'], TProgram['~types']['command']['~types']['result'], RepathCommands<TProgram['~types']['command']['~types']['commands'], FullCommandName<TNameNested, FullCommandName<TName, TParentName>>>, [], TProgram['~types']['command']['~types']['async'], TContext & TContextProvided>, TAliases>] : ReplaceOrAppendCommand<TCommands, TNameNested, WithAliases<PadroneCommand<TNameNested, FullCommandName<TName, TParentName>, TProgram['~types']['command']['~types']['argsSchema'], TProgram['~types']['command']['~types']['result'], RepathCommands<TProgram['~types']['command']['~types']['commands'], FullCommandName<TNameNested, FullCommandName<TName, TParentName>>>, [], TProgram['~types']['command']['~types']['async'], TContext & TContextProvided>, ResolvedAliases<TCommands, TNameNested, TAliases>>>, TParentArgs, TAsync, TContext, TContextProvided>;
+    <TNameNested extends string, TAliases extends string[] = [], TProgram extends CommandTypesBase = CommandTypesBase, TNewContext = unknown>(name: TNameNested | readonly [TNameNested, ...TAliases], program: TProgram, options: MountOptions<TContext & TContextProvided, TNewContext>): BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands extends [] ? [WithAliases<PadroneCommand<TNameNested, FullCommandName<TName, TParentName>, TProgram['~types']['command']['~types']['argsSchema'], TProgram['~types']['command']['~types']['result'], RepathCommands<TProgram['~types']['command']['~types']['commands'], FullCommandName<TNameNested, FullCommandName<TName, TParentName>>>, [], TProgram['~types']['command']['~types']['async'], TNewContext>, TAliases>] : AnyPadroneCommand[] extends TCommands ? [WithAliases<PadroneCommand<TNameNested, FullCommandName<TName, TParentName>, TProgram['~types']['command']['~types']['argsSchema'], TProgram['~types']['command']['~types']['result'], RepathCommands<TProgram['~types']['command']['~types']['commands'], FullCommandName<TNameNested, FullCommandName<TName, TParentName>>>, [], TProgram['~types']['command']['~types']['async'], TNewContext>, TAliases>] : ReplaceOrAppendCommand<TCommands, TNameNested, WithAliases<PadroneCommand<TNameNested, FullCommandName<TName, TParentName>, TProgram['~types']['command']['~types']['argsSchema'], TProgram['~types']['command']['~types']['result'], RepathCommands<TProgram['~types']['command']['~types']['commands'], FullCommandName<TNameNested, FullCommandName<TName, TParentName>>>, [], TProgram['~types']['command']['~types']['async'], TNewContext>, ResolvedAliases<TCommands, TNameNested, TAliases>>>, TParentArgs, TAsync, TContext, TContextProvided>;
+  }; /** @deprecated Internal use only */
+  '~types': {
+    programName: TProgramName;
+    name: TName;
+    parentName: TParentName;
+    path: FullCommandName<TName, TParentName>;
+    aliases: [];
+    argsSchema: TArgs;
+    result: TRes;
+    commands: TCommands;
+    async: TAsync;
+    context: TContext;
+    contextProvided: TContextProvided;
+    command: PadroneCommand<TName, TParentName, TArgs, TRes, TCommands, [], TAsync, TContext, TContextProvided>;
+  };
 };
+type PadroneBuilder<TProgramName extends string = '', TName extends string = string, TParentName extends string = '', TArgs extends PadroneSchema = PadroneSchema<DefaultArgs>, TRes = void, TCommands extends [...AnyPadroneCommand[]] = [], TParentArgs extends PadroneSchema = PadroneSchema<void>, TAsync extends boolean = false, TContext = unknown, TContextProvided = unknown> = PadroneBuilderMethods<TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TAsync, TContext, TContextProvided, 'builder'>;
+type PadroneProgram<TProgramName extends string = '', TName extends string = string, TParentName extends string = '', TArgs extends PadroneSchema = PadroneSchema<DefaultArgs>, TRes = void, TCommands extends [...AnyPadroneCommand[]] = [], TParentArgs extends PadroneSchema = PadroneSchema<void>, TAsync extends boolean = false, TContext = unknown, TContextProvided = unknown> = PadroneBuilderMethods<TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TAsync, TContext, TContextProvided, 'program'> & {
+  /** Execute a command by name with pre-validated args (skips parsing and validation). @category Execution */run: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], true, true>>(name: TCommand | SafeString, args: NoInfer<GetArguments<'in', PickCommandByName<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>>>, prefs?: ContextParam<TContext>) => PadroneCommandResult<PickCommandByName<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>>; /** Parse and execute a string input through the full interceptor pipeline. @category Execution */
+  eval: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], true, true>>(input: TCommand | SafeString, prefs?: PadroneEvalPreferences & ContextParam<TContext>) => MaybePromiseCommandResult<PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>, PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>['~types']['async']>; /** Parse and execute from `process.argv` through the full interceptor pipeline. @category Execution */
+  cli: (prefs?: PadroneCliPreferences & ContextParam<TContext>) => MaybePromiseCommandResult<FlattenCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>, TAsync>; /** Parse and validate input without executing the action. @category Execution */
+  parse: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], true, false>>(input?: TCommand | SafeString) => MaybePromise<PadroneParseResult<PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>>, PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>['~types']['async']>; /** Serialize args back into a CLI string. @category Utility */
+  stringify: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], false, true>>(command?: TCommand | SafeString, args?: GetArguments<'out', PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>>) => string; /** Look up a command definition by name. @category Utility */
+  find: <const TFind extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], false, true>>(command: TFind | SafeString) => PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TFind> | undefined; /** Get a structured API representation of all commands. @category Utility */
+  api: () => PadroneAPI<PadroneCommand<'', '', TArgs, TRes, TCommands>>; /** Start an interactive REPL session. @category Execution */
+  repl: (options?: PadroneReplPreferences<PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>) => AsyncIterable<PadroneCommandResult<FlattenCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>> & {
+    drain: () => Promise<PadroneDrainResult<PadroneCommandResult<FlattenCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>[]>>;
+  }; /** Export as an AI SDK tool. @category Utility */
+  tool: () => Tool<{
+    command: string;
+  }>; /** Generate help text for a command. @category Utility */
+  help: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], false, true>>(command?: TCommand, prefs?: HelpPreferences) => string; /** Generate shell completion script. @category Utility */
+  completion: (shell?: 'bash' | 'zsh' | 'fish' | 'powershell') => Promise<string>; /** Start a Model Context Protocol server. @category Server */
+  mcp: (prefs?: PadroneMcpPreferences) => Promise<void>; /** Start a REST HTTP server with OpenAPI docs. @category Server */
+  serve: (prefs?: PadroneServePreferences) => Promise<void>; /** Read-only metadata about the program (name, version, description, commands, etc.). @category Utility */
+  info: PadroneProgramMeta<TProgramName>;
+};
+type AnyPadroneProgram = PadroneProgram<string, string, string, any, any, [...AnyPadroneCommand[]]>;
+/**
+ * A build-time extension that transforms a builder/program.
+ * Extensions can add commands, arguments, interceptors, configure settings, etc.
+ *
+ * Use with `.extend(extension)`:
+ * ```ts
+ * const withAuth = (b) => b.arguments(authSchema).command('login', ...)
+ * program.extend(withAuth)
+ * ```
+ */
+type PadroneExtension<TIn extends CommandTypesBase = CommandTypesBase, TOut extends CommandTypesBase = TIn> = (builder: TIn) => TOut;
+type DefaultArgs = Record<string, unknown> | void;
 //#endregion
-export { Drained as A, REPL_SIGINT as B, PluginShutdownContext as C, WrapConfig as D, PluginValidateResult as E, PadroneProgressIndicator as F, PadroneProgressOptions as I, PadroneRuntime as L, PossibleCommands as M, InteractiveMode as N, WrapResult as O, InteractivePromptConfig as P, PadroneSpinnerConfig as R, PluginParseResult as S, PluginValidateContext as T, PadroneMcpPreferences as V, PluginErrorContext as _, PadroneActionContext as a, PluginExecuteResult as b, PadroneCommandResult as c, PadronePlugin as d, PadroneProgram as f, PluginBaseContext as g, PadroneSchema as h, AsyncPadroneSchema as i, PickCommandByName as j, UpdateCheckConfig as k, PadroneDrainResult as l, PadroneProgressPrefs as m, AnyPadroneCommand as n, PadroneBuilder as o, PadroneProgressMessage as p, AnyPadroneProgram as r, PadroneCommand as s, AnyPadroneBuilder as t, PadroneParseResult as u, PluginErrorResult as v, PluginStartContext as w, PluginParseContext as x, PluginExecuteContext as y, PadroneSpinnerPreset as z };
-//# sourceMappingURL=types-Ch8Mk6Qb.d.mts.map
+export { PadroneProgressOptions as $, InterceptorStartContext as A, WithInterceptor as B, InterceptorExecuteResult as C, InterceptorParseResult as D, InterceptorParseContext as E, PadroneInterceptorFn as F, PadroneServePreferences as G, PadroneSchema as H, Drained as I, InteractivePromptConfig as J, PadroneMcpPreferences as K, PickCommandByName as L, InterceptorValidateResult as M, PadroneContextInterceptor as N, InterceptorPhases as O, PadroneInterceptor as P, PadroneProgressIndicator as Q, PossibleCommands as R, InterceptorExecuteContext as S, InterceptorMeta as T, WrapConfig as U, AsyncPadroneSchema as V, WrapResult as W, PadroneBarChar as X, PadroneBarAnimation as Y, PadroneBarConfig as Z, ExtractInterceptorRequires as _, PadroneProgram as a, PadroneSpinnerPreset as at, InterceptorErrorContext as b, PadroneParseResult as c, CommandTypesBase as d, PadroneProgressShow as et, GetArgsMeta as f, ExtractInterceptorContext as g, PadroneProgramMeta as h, PadroneExtension as i, PadroneSpinnerConfig as it, InterceptorValidateContext as j, InterceptorShutdownContext as k, PadroneReplPreferences as l, PadroneCommand as m, AnyPadroneProgram as n, PadroneRuntime as nt, PadroneCommandResult as o, REPL_SIGINT as ot, PadroneActionContext as p, InteractiveMode as q, PadroneBuilder as r, PadroneSignal as rt, PadroneDrainResult as s, AnyPadroneBuilder as t, PadroneProgressUpdate as tt, AnyPadroneCommand as u, InterceptorBaseContext as v, InterceptorFactory as w, InterceptorErrorResult as x, InterceptorDefBuilder as y, WithCommand as z };
+//# sourceMappingURL=index-BaU3X6dY.d.mts.map