padrone 1.4.0 → 1.5.0

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

@@ -1,4 +1,4 @@
-import { n as HelpFormat, t as HelpDetail } from "./formatter-ClUK5hcQ.mjs";
+import { a as ColorConfig, n as HelpFormat, o as ColorTheme, t as HelpDetail } from "./formatter-DtHzbP22.mjs";
 import { StandardJSONSchemaV1, StandardSchemaV1 } from "@standard-schema/spec";
 import { Tool } from "ai";
 
@@ -9,12 +9,14 @@ type SingleChar = Letter | Uppercase<Letter>;
 interface PadroneFieldMeta {
   description?: string;
   /** Single-character short flags (stackable: `-abc` = `-a -b -c`). Used with single dash. */
-  flags?: SingleChar[] | SingleChar;
+  flags?: readonly SingleChar[] | SingleChar;
   /** Multi-character alternative long names. Used with double dash (e.g. `--dry-run` for `--dryRun`). */
-  alias?: string[] | string;
+  alias?: readonly string[] | string;
   deprecated?: boolean | string;
   hidden?: boolean;
-  examples?: unknown[];
+  examples?: readonly unknown[];
+  /** Group name for organizing this option under a labeled section in help output. */
+  group?: string;
 }
 type PositionalArgs<TObj> = TObj extends Record<string, any> ? { [K in keyof TObj]: NonNullable<TObj[K]> extends Array<any> ? `...${K & string}` | (K & string) : K & string }[keyof TObj] : string;
 /**
@@ -31,23 +33,18 @@ type PositionalArgs<TObj> = TObj extends Record<string, any> ? { [K in keyof TOb
  */
 /**
  * Configuration for reading from stdin and mapping it to an argument field.
+ * Simply specify the field name — the read mode is inferred from the schema:
+ * - `string` field → reads all stdin as text
+ * - `string[]` field → reads stdin line-by-line
  */
-type StdinConfig<TObj = Record<string, any>> = (keyof TObj & string) | {
-  /** The argument field to populate with stdin data. */field: keyof TObj & string;
-  /**
-   * How to consume stdin:
-   * - `'text'` (default): read all stdin as a single string.
-   * - `'lines'`: read stdin as an array of lines (string[]).
-   */
-  as?: 'text' | 'lines';
-};
+type StdinConfig<TObj = Record<string, any>> = keyof TObj & string;
 interface PadroneArgsSchemaMeta<TObj = Record<string, any>> {
   /**
    * Array of argument names that should be treated as positional arguments.
    * Order in array determines position. Use '...name' prefix for variadic args.
    * @example ['source', '...files', 'dest'] - 'files' captures multiple values
    */
-  positional?: PositionalArgs<TObj>[];
+  positional?: readonly PositionalArgs<TObj>[];
   /**
    * Per-argument metadata.
    */
@@ -72,21 +69,19 @@ interface PadroneArgsSchemaMeta<TObj = Record<string, any>> {
    * Read from stdin and inject the data into the specified argument field.
    * Only reads when stdin is piped (not a TTY) and the field wasn't already provided via CLI flags.
    *
-   * - `string`: shorthand for `{ field: name, as: 'text' }` — read all stdin as a string.
-   * - `{ field, as }`: explicit form. `as: 'text'` reads all stdin as a string,
-   *   `as: 'lines'` reads stdin as an array of line strings.
+   * The read mode is inferred from the schema type of the target field:
+   * - `string` field → reads all stdin as a single string
+   * - `string[]` field → reads stdin line-by-line into an array
    *
    * Precedence: CLI flags > stdin > env vars > config file > schema defaults.
    *
    * @example
    * ```ts
-   * // Shorthand: read all stdin as text into 'data' field
+   * // Read all stdin as text into 'data' field
    * .arguments(z.object({ data: z.string() }), { stdin: 'data' })
    *
-   * // Explicit: read stdin lines into 'lines' field
-   * .arguments(z.object({ lines: z.string().array() }), {
-   *   stdin: { field: 'lines', as: 'lines' },
-   * })
+   * // Read stdin lines into 'lines' field (inferred from array schema)
+   * .arguments(z.object({ lines: z.string().array() }), { stdin: 'lines' })
    * ```
    */
   stdin?: StdinConfig<TObj>;
@@ -106,7 +101,7 @@ interface PadroneArgsSchemaMeta<TObj = Record<string, any>> {
    * })
    * ```
    */
-  interactive?: true | (keyof TObj & string)[];
+  interactive?: true | readonly (keyof TObj & string)[];
   /**
    * Optional fields offered after required interactive prompts.
    * Users are shown a multi-select to choose which of these fields to configure.
@@ -121,16 +116,70 @@ interface PadroneArgsSchemaMeta<TObj = Record<string, any>> {
    * })
    * ```
    */
-  optionalInteractive?: true | (keyof TObj & string)[];
+  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;
 };
 //#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. */
+  succeed: (message?: string | null, options?: {
+    indicator?: string;
+  }) => void; /** Mark as failed and stop. Pass `null` to stop without rendering a final message. */
+  fail: (message?: string | null, options?: {
+    indicator?: string;
+  }) => void; /** Stop without success/fail status. */
+  stop: () => void; /** Temporarily hide the indicator so other output can be written cleanly. */
+  pause: () => void; /** Redraw the indicator after a `pause()`. */
+  resume: () => void;
+};
+/** 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).
+ */
+type PadroneSpinnerConfig = PadroneSpinnerPreset | {
+  frames?: string[];
+  interval?: number;
+} | false;
+/**
+ * Options passed to the runtime's `progress` factory.
+ */
+type PadroneProgressOptions = {
+  spinner?: PadroneSpinnerConfig; /** Character/string shown before the success message. Defaults to `'✔'`. */
+  successIndicator?: string; /** Character/string shown before the error message. Defaults to `'✖'`. */
+  errorIndicator?: string;
+};
 /**
  * Controls interactive prompting capability and default behavior at the runtime level.
  * - `'supported'` — capable; caller decides.
@@ -165,7 +214,8 @@ type PadroneRuntime = {
   error?: (text: string) => void; /** Return the raw CLI arguments (replaces process.argv.slice(2)). */
   argv?: () => string[]; /** Return environment variables (replaces process.env). */
   env?: () => Record<string, string | undefined>; /** Default help output format. */
-  format?: HelpFormat | 'auto'; /** Load and parse a config file by path. Return undefined if not found or unparsable. */
+  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;
   /**
@@ -197,6 +247,12 @@ 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).
@@ -212,7 +268,7 @@ type PadroneRuntime = {
  * 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'>> & Pick<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin'>;
+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.
@@ -224,6 +280,22 @@ type ResolvedPadroneRuntime = Required<Omit<PadroneRuntime, 'prompt' | 'interact
  */
 declare const REPL_SIGINT: unique symbol;
 //#endregion
+//#region src/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: '/' */
+  basePath?: string; /** CORS allowed origin. Default: '*'. Set to `false` to disable CORS headers. */
+  cors?: string | false; /** Control built-in utility endpoints. All enabled by default. */
+  builtins?: {
+    /** GET /_health — returns 200 OK. */health?: boolean; /** GET /_help and GET /_help/:command — returns help text. */
+    help?: boolean; /** GET /_schema and GET /_schema/:command — returns JSON Schema. */
+    schema?: boolean; /** GET /_docs — Scalar OpenAPI docs viewer. */
+    docs?: boolean;
+  }; /** Hook to run before each request. Return a Response to short-circuit. */
+  onRequest?: (req: Request) => Response | void | Promise<Response | void>; /** Transform errors into responses. */
+  onError?: (error: unknown, req: Request) => Response;
+};
+//#endregion
 //#region src/type-utils.d.ts
 type SafeString = string & {};
 type IsUnknown<T> = unknown extends T ? true : false;
@@ -250,23 +322,39 @@ type OrAsync<TExisting extends boolean, TSchema> = TExisting extends true ? true
  * When either is `true` or a `string[]`, the command requires async execution for prompting.
  */
 type HasInteractive<TMeta> = TMeta extends {
-  interactive: true | string[];
+  interactive: true | readonly string[];
 } ? true : TMeta extends {
-  optionalInteractive: true | string[];
+  optionalInteractive: true | readonly string[];
 } ? true : false;
 /**
  * Combines schema-level async detection with meta-level interactive detection.
  * Returns `true` if the existing async flag is set, the schema is branded async, or the meta has interactive fields.
  */
 type OrAsyncMeta<TExisting extends boolean, TMeta> = TExisting extends true ? true : HasInteractive<TMeta> extends true ? true : false;
+/**
+ * Unwraps a result type by resolving Promises and collecting iterables into arrays.
+ * - `AsyncIterable<U>` → `U[]`
+ * - `Iterable<U>` (excluding strings) → `U[]`
+ * - `Promise<U>` → `Drained<U>` (recursively unwraps)
+ * - `T` → `T`
+ */
+type Drained<T> = T extends Promise<infer U> ? Drained<U> : T extends AsyncIterable<infer U> ? U[] : T extends string ? T : T extends Iterable<infer U> ? U[] : T;
+/**
+ * A sync value augmented with Promise-like methods (.then, .catch, .finally).
+ * Unlike a real Promise, properties of T are accessible synchronously.
+ */
+type Thenable<T> = T & PromiseLike<T> & {
+  catch: Promise<T>['catch'];
+  finally: Promise<T>['finally'];
+};
 /**
  * Conditionally wraps a type in Promise based on the TAsync flag.
  * - `true` → `Promise<T>`
- * - `false` → `T & PromiseLike<T>` (thenable: supports `.then()` and `await`)
+ * - `false` → `T & Thenable<T>` (thenable: supports `.then()`, `.catch()`, `.finally()`, and `await`)
  * - `boolean` (union of true|false) → `Promise<T>` (safe default when async-ness is uncertain)
  * - `any` → `T` (for generic/any typed commands like AnyPadroneCommand)
  */
-type MaybePromise<T, TAsync> = IsAny<TAsync> extends true ? T : true extends TAsync ? Promise<T> : T & PromiseLike<T>;
+type MaybePromise<T, TAsync> = IsAny<TAsync> extends true ? T : true extends TAsync ? Promise<T> : Thenable<T>;
 type SplitString<TName extends string, TSplitBy extends string = ' '> = TName extends `${infer FirstPart}${TSplitBy}${infer RestParts}` ? [FirstPart, ...SplitString<RestParts, TSplitBy>] : [TName];
 type JoinString<TParts extends string[], TJoinBy extends string = ' '> = TParts extends [infer FirstPart extends string, ...infer RestParts extends string[]] ? RestParts extends [] ? FirstPart : `${FirstPart}${TJoinBy}${JoinString<RestParts, TJoinBy>}` : TParts extends [] ? '' : TParts[number];
 type SplitLastSpace<S extends string> = SplitString<S> extends [...infer Init extends string[], infer Last extends string] ? Init extends [] ? [S, never] : [JoinString<Init>, Last] : [S, never];
@@ -424,6 +512,11 @@ type PadroneActionContext = {
   /** 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.
+   */
+  progress: PadroneProgressIndicator;
 };
 /**
  * A schema that supports both validation (StandardSchemaV1) and JSON schema generation (StandardJSONSchemaV1).
@@ -478,9 +571,22 @@ type PadroneCommand<TName extends string = string, TParentName extends string =
   version?: string; /** Alternative names that can be used to invoke this command. Derived from the names passed to command(). */
   aliases?: TAliases;
   deprecated?: boolean | string;
-  hidden?: boolean;
+  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;
+  autoOutput?: 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;
@@ -489,7 +595,7 @@ type PadroneCommand<TName extends string = string, TParentName extends string =
   configFiles?: string[]; /** 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[]; /** Update check configuration. Only used on the root program. */
+  plugins?: PadronePlugin<any, any>[]; /** Update check configuration. Only used on the root program. */
   updateCheck?: UpdateCheckConfig;
   parent?: AnyPadroneCommand;
   commands?: TCommands; /** @deprecated Internal use only */
@@ -521,18 +627,50 @@ type CommandTypesBase = {
 /**
  * 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;
+  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;
+  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.
@@ -575,7 +713,7 @@ type PadroneBuilderMethods<TProgramName extends string, TName extends string, TP
    * 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) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
+  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.
@@ -657,6 +795,28 @@ type PadroneBuilderMethods<TProgramName extends string, TName extends string, TP
    * ```
    */
   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.
@@ -666,6 +826,8 @@ type PadroneBuilderMethods<TProgramName extends string, TName extends string, TP
    * 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
@@ -797,13 +959,13 @@ type PadroneProgram<TProgramName extends string = '', TName extends string = str
    * if (result.argsResult?.issues) { /* handle validation errors *\/ }
    * ```
    */
-  eval: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], true, true>>(input: TCommand | SafeString, prefs?: PadroneEvalPreferences) => MaybePromise<PadroneCommandResult<PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>>, PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>['~types']['async']>;
+  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>]>>) => MaybePromise<PadroneCommandResult<FlattenCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>, TAsync>;
+  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.
    */
@@ -838,7 +1000,9 @@ type PadroneProgram<TProgramName extends string = '', TName extends string = str
    * - 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>]>>>;
+  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.
    */
@@ -864,6 +1028,32 @@ type PadroneProgram<TProgramName extends string = '', TName extends string = str
    * ```
    */
   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[]]>;
 /**
@@ -949,10 +1139,46 @@ type PadroneEvalPreferences = {
  * 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;
+  /** 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;
+};
+/**
+ * Result of `drain()` — a discriminated union that never throws.
+ * On success, `value` holds the fully resolved/collected result; on failure, `error` holds the error.
+ */
+type PadroneDrainResult<TResult> = {
+  value: Drained<TResult>;
+  error?: never;
+} | {
+  error: unknown;
+  value?: never;
 };
-type PadroneCommandResult<TCommand extends AnyPadroneCommand = AnyPadroneCommand> = PadroneParseResult<TCommand> & {
+/**
+ * Result returned by `eval()`, `cli()`, and `run()`. Never thrown — errors are captured in the `error` field.
+ * Discriminated union: check `error` to distinguish success from failure.
+ *
+ * On success: `command`, `args`, `argsResult`, `result` are populated; `error` is absent.
+ * On failure: `error` is populated; `command` may be present if routing succeeded.
+ */
+type PadroneCommandResult<TCommand extends AnyPadroneCommand = AnyPadroneCommand> = (PadroneParseResult<TCommand> & {
   result: GetResults<TCommand>;
+  error?: never; /** 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. */
+  drain: () => Promise<PadroneDrainResult<GetResults<TCommand>>>;
+};
+/**
+ * Like `MaybePromise<PadroneCommandResult<TCommand>, TAsync>` but ensures `drain()` is available
+ * at the outer level in all cases — both sync (Thenable) and async (Promise).
+ */
+type MaybePromiseCommandResult<TCommand extends AnyPadroneCommand, TAsync> = MaybePromise<PadroneCommandResult<TCommand>, TAsync> & {
+  drain: () => Promise<PadroneDrainResult<GetResults<TCommand>>>;
 };
 type PadroneParseResult<TCommand extends AnyPadroneCommand = AnyPadroneCommand> = {
   command: TCommand;
@@ -986,17 +1212,17 @@ type PluginValidateContext = PluginBaseContext & {
   positionalArgs: string[];
 };
 /** Result returned by the validate phase's `next()`. */
-type PluginValidateResult = {
-  args: unknown;
-  argsResult: StandardSchemaV1.Result<unknown>;
+type PluginValidateResult<TArgs = unknown> = {
+  args: TArgs;
+  argsResult: StandardSchemaV1.Result<TArgs>;
 };
 /** Context for the execute phase. */
-type PluginExecuteContext = PluginBaseContext & {
-  /** Validated arguments that will be passed to the action. Mutable — modify before `next()` to override. */args: unknown;
+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 = {
-  result: unknown;
+type PluginExecuteResult<TResult = unknown> = {
+  result: TResult;
 };
 /** Context for the start phase. Runs before parsing, wraps the entire pipeline. */
 type PluginStartContext = PluginBaseContext & {
@@ -1007,19 +1233,35 @@ type PluginErrorContext = PluginBaseContext & {
   /** The error that was thrown. */error: unknown;
 };
 /** Result returned by the error phase's `next()`. */
-type PluginErrorResult = {
+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?: unknown;
+  result?: TResult;
 };
 /** Context for the shutdown phase. Always runs after the pipeline (success or failure). */
-type PluginShutdownContext = PluginBaseContext & {
+type PluginShutdownContext<TResult = unknown> = PluginBaseContext & {
   /** The error, if the pipeline failed (after error phase processing). */error?: unknown; /** The pipeline result, if it succeeded. */
-  result?: unknown;
+  result?: TResult;
 };
-type PluginPhaseHandler<TCtx, TResult> = (ctx: TCtx, next: () => TResult | Promise<TResult>) => TResult | Promise<TResult>;
+/**
+ * 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).
+ */
+type PluginPhaseHandler<TCtx, TNextResult, TReturn = TNextResult> = (ctx: TCtx, next: () => TNextResult | Promise<TNextResult>) => TReturn | Promise<TReturn>;
 /**
  * A Padrone plugin that can intercept the parse, validate, and execute phases of command execution.
- * Plugins are registered at the program level with `.use()` and apply to all commands.
+ * 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.
@@ -1028,8 +1270,14 @@ type PluginPhaseHandler<TCtx, TResult> = (ctx: TCtx, next: () => TResult | Promi
  * - Modify context fields before `next()` to alter inputs.
  * - Transform the return value of `next()` to alter outputs.
  */
-type PadronePlugin = {
-  /** Unique name for this plugin. Used for identification and future disable/override support. */name: string;
+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`.
@@ -1041,19 +1289,19 @@ type PadronePlugin = {
    */
   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>; /** Intercepts handler execution. */
-  execute?: PluginPhaseHandler<PluginExecuteContext, PluginExecuteResult>;
+  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>;
+  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, void>;
+  shutdown?: PluginPhaseHandler<PluginShutdownContext<TResult>, void>;
 };
 //#endregion
-export { PossibleCommands as _, PadroneActionContext as a, PadroneRuntime as b, PadroneCommandResult as c, PadroneProgram as d, PadroneSchema as f, PickCommandByName as g, UpdateCheckConfig as h, AsyncPadroneSchema as i, PadroneParseResult as l, WrapResult as m, AnyPadroneCommand as n, PadroneBuilder as o, WrapConfig as p, AnyPadroneProgram as r, PadroneCommand as s, AnyPadroneBuilder as t, PadronePlugin as u, InteractiveMode as v, REPL_SIGINT as x, InteractivePromptConfig as y };
-//# sourceMappingURL=types-DjIdJN5G.d.mts.map
+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