padrone 1.4.0 → 1.6.0

package/dist/index-BaU3X6dY.d.mts

@@ -0,0 +1,1178 @@
+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/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>;
+interface PadroneFieldMeta {
+  description?: string;
+  /** Single-character short flags (stackable: `-abc` = `-a -b -c`). Used with single dash. */
+  flags?: readonly SingleChar[] | SingleChar;
+  /** Multi-character alternative long names. Used with double dash (e.g. `--dry-run` for `--dryRun`). */
+  alias?: readonly string[] | string;
+  deprecated?: boolean | string;
+  hidden?: boolean;
+  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;
+/**
+ * Meta configuration for arguments, including positional arguments.
+ * The `positional` array defines which arguments are positional and their order.
+ * Use '...name' prefix to indicate variadic (rest) arguments, matching JS/TS rest syntax.
+ *
+ * @example
+ * ```ts
+ * .arguments(schema, {
+ *   positional: ['source', '...files', 'dest'],  // '...files' is variadic
+ * })
+ * ```
+ */
+/**
+ * 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;
+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?: readonly PositionalArgs<TObj>[];
+  /**
+   * Per-argument metadata.
+   */
+  fields?: { [K in keyof TObj]?: PadroneFieldMeta };
+  /**
+   * Automatically generate kebab-case aliases for camelCase option names.
+   * For example, `dryRun` automatically gets `--dry-run` as an alias.
+   * Defaults to `true`. Set to `false` to disable.
+   *
+   * @default true
+   * @example
+   * ```ts
+   * // Auto-aliases enabled (default): --dry-run → dryRun
+   * .arguments(z.object({ dryRun: z.boolean() }))
+   *
+   * // Disable auto-aliases
+   * .arguments(z.object({ dryRun: z.boolean() }), { autoAlias: false })
+   * ```
+   */
+  autoAlias?: boolean;
+  /**
+   * 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.
+   *
+   * 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
+   * // Read all stdin as text into 'data' field
+   * .arguments(z.object({ data: z.string() }), { stdin: 'data' })
+   *
+   * // Read stdin lines into 'lines' field (inferred from array schema)
+   * .arguments(z.object({ lines: z.string().array() }), { stdin: 'lines' })
+   * ```
+   */
+  stdin?: StdinConfig<TObj>;
+  /**
+   * Fields to interactively prompt for when their values are missing after CLI/env/config resolution.
+   * - `true`: prompt for all required fields that are missing.
+   * - `string[]`: prompt for these specific fields if missing.
+   *
+   * Interactive prompting only occurs in `cli()` when the runtime has `interactive: true`.
+   * Setting this makes `parse()` and `cli()` return Promises.
+   *
+   * @example
+   * ```ts
+   * .arguments(schema, {
+   *   interactive: true,                        // prompt all missing required fields
+   *   interactive: ['name', 'template'],         // prompt only these fields
+   * })
+   * ```
+   */
+  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.
+   * - `true`: offer all optional fields that are missing.
+   * - `string[]`: offer these specific fields.
+   *
+   * @example
+   * ```ts
+   * .arguments(schema, {
+   *   interactive: ['name'],
+   *   optionalInteractive: ['typescript', 'eslint', 'prettier'],
+   * })
+   * ```
+   */
+  optionalInteractive?: true | readonly (keyof TObj & string)[];
+}
+//#endregion
+//#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;
+};
+/**
+ * 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 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. */
+  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;
+};
+/** 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.
+ * - `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 | boolean | {
+  frames?: string[];
+  interval?: number;
+  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; /** 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;
+};
+/**
+ * Controls interactive prompting capability and default behavior at the runtime level.
+ * - `'supported'` — capable; caller decides.
+ * - `'unsupported'` — hard veto; nothing can override.
+ * - `'forced'` — capable and forces prompts by default.
+ * - `'disabled'` — capable but suppresses prompts by default.
+ */
+type InteractiveMode = 'supported' | 'unsupported' | 'forced' | 'disabled';
+/**
+ * Configuration passed to the runtime's `prompt` function for interactive field prompting.
+ * The prompt type and choices are auto-detected from the field's JSON schema.
+ */
+type InteractivePromptConfig = {
+  /** The field name being prompted. */name: string; /** Human-readable message/label for the prompt, derived from the field's description or name. */
+  message: string; /** The prompt type, auto-detected from the JSON schema. */
+  type: 'input' | 'confirm' | 'select' | 'multiselect' | 'password'; /** Available choices for select/multiselect prompts. */
+  choices?: {
+    label: string;
+    value: unknown;
+  }[]; /** Default value from the schema. */
+  default?: unknown;
+};
+/**
+ * Defines the execution context for a Padrone program.
+ * Abstracts all environment-dependent I/O so the CLI framework
+ * can run outside of a terminal (e.g., web UIs, chat interfaces, testing).
+ *
+ * All fields are optional — unspecified fields fall back to the Node.js/Bun defaults.
+ */
+type PadroneRuntime = {
+  /** Write normal output (replaces console.log). Receives the raw value — runtime handles formatting. */output?: (...args: unknown[]) => void; /** Write error output (replaces console.error). */
+  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'; /** Color theme for ANSI/console help output. A theme name or partial color config. */
+  theme?: ColorTheme | ColorConfig;
+  /**
+   * Standard input abstraction. Provides methods to read piped data from stdin.
+   * When not provided, defaults to reading from `process.stdin`.
+   *
+   * Used by commands that declare a `stdin` field in their arguments meta.
+   * The framework reads stdin automatically during the validate phase and
+   * injects the data into the specified argument field.
+   */
+  stdin?: {
+    /** Whether stdin is a TTY (interactive terminal) vs a pipe/file. */isTTY?: boolean; /** Read all of stdin as a string. */
+    text: () => Promise<string>; /** Async iterable of lines for streaming. */
+    lines: () => AsyncIterable<string>;
+  };
+  /**
+   * Controls interactive prompting capability and default behavior.
+   * - `'supported'` — runtime can handle prompts; caller (flag/pref) decides whether to prompt. This is the default when `prompt` is provided.
+   * - `'unsupported'` — runtime cannot handle prompts; hard veto that nothing can override.
+   * - `'forced'` — runtime supports prompts and forces them by default (prompts even for provided values).
+   * - `'disabled'` — runtime supports prompts but suppresses them by default.
+   *
+   * `'unsupported'` is the only immutable state. For the others, the `--interactive`/`-i` flag
+   * and `cli()` preferences can override the default behavior.
+   */
+  interactive?: InteractiveMode;
+  /**
+   * Prompt the user for input. Called during `cli()` for fields marked as interactive.
+   * When `interactive` is `true` and this is not provided, defaults to an Enquirer-based terminal prompt.
+   */
+  prompt?: (config: InteractivePromptConfig) => Promise<unknown>;
+  /**
+   * Read a line of input from the user. Used by `repl()` for custom runtimes
+   * (web UIs, chat interfaces, testing).
+   * Returns the input string, `null` on EOF (e.g. Ctrl+D, closed connection),
+   * or `REPL_SIGINT` when the user presses Ctrl+C.
+   *
+   * When not provided, `repl()` uses a built-in Node.js readline session
+   * 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' | '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/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: '/' */
+  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/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;
+type IsNever<T> = [T] extends [never] ? true : false;
+type IsGeneric<T> = IsAny<T> extends true ? true : IsUnknown<T> extends true ? true : IsNever<T> extends true ? true : false;
+/**
+ * Detects whether a schema has been branded as async via the `'~async'` property.
+ * Standard Schema V1's `validate()` always types its return as `Result | Promise<Result>`
+ * regardless of whether the schema is actually async, so we rely on an explicit brand instead.
+ *
+ * Use `asyncSchema(schema)` to brand a schema, or check for the `{ '~async': true }` property.
+ */
+type IsAsyncSchema<T> = IsAny<T> extends true ? false : T extends {
+  '~async': true;
+} ? true : false;
+/**
+ * Computes the new TAsync flag when a schema is added to a builder.
+ * Once TAsync is `true`, it stays `true`. Otherwise, checks if the new schema is branded async.
+ */
+type OrAsync<TExisting extends boolean, TSchema> = TExisting extends true ? true : IsAsyncSchema<TSchema> extends true ? true : false;
+/**
+ * Detects whether argument meta contains interactive or optionalInteractive configuration.
+ * When either is `true` or a `string[]`, the command requires async execution for prompting.
+ */
+type HasInteractive<TMeta> = TMeta extends {
+  interactive: true | readonly string[];
+} ? true : TMeta extends {
+  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 & 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> : 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];
+type AnyPartExtends<U, T> = [U] extends [never] ? false : U extends any ? (U extends T ? true : never) : never extends true ? true : false;
+type FullCommandName<TName extends string, TParentName extends string = ''> = TParentName extends '' ? TName : `${TParentName} ${TName}`;
+/**
+ * Generate full alias paths by combining parent path with each alias.
+ */
+type FullAliasPaths<TAliases extends string[], TParentName extends string = ''> = TAliases extends [infer First extends string, ...infer Rest extends string[]] ? FullCommandName<First, TParentName> | FullAliasPaths<Rest, TParentName> : never;
+/**
+ * Get all paths for a command including its primary path and all alias paths.
+ */
+type GetCommandPathsAndAliases<TCommand extends AnyPadroneCommand> = TCommand['~types']['path'] extends infer Path extends string ? TCommand['~types']['aliases'] extends infer Aliases extends string[] ? TCommand['~types']['parentName'] extends infer ParentName extends string ? Path | FullAliasPaths<Aliases, ParentName> : Path : Path : never;
+/**
+ * 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> = 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> = 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 : 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.
+ */
+type GetCommandPathsOrAliases<TCommands extends AnyPadroneCommand[]> = GetCommandPathsAndAliases<FlattenCommands<TCommands>>;
+/**
+ * Find all the commands that are prefixed with a command name or alias.
+ * This is needed to avoid matching other commands when followed by a space and another word.
+ * For example, let's say `level1` and `level1 level2` are commands.
+ * Then `level1 ${string}` would also match `level1 level2`,
+ * and it would cause `level1 level2` to not show up in the autocomplete.
+ * By excluding those cases, we can ensure autocomplete works correctly.
+ */
+type PrefixedCommands<TCommands extends AnyPadroneCommand[]> = GetCommandPathsOrAliases<TCommands> extends infer CommandNames ? CommandNames extends string ? AnyPartExtends<GetCommandPathsOrAliases<TCommands>, `${CommandNames} ${string}`> extends true ? never : `${CommandNames} ${string}` : never : never;
+/**
+ * The possible commands are the commands that can be parsed by the program.
+ * This includes the string that are exact matches to a command name or alias, and strings that are prefixed with a command name or alias.
+ */
+type PossibleCommands<TCommands extends AnyPadroneCommand[], TWithPrefixed extends boolean = false, TWithObjects extends boolean = false, TWithFallback extends boolean = true> = GetCommandPathsOrAliases<TCommands> | (TWithPrefixed extends true ? PrefixedCommands<TCommands> : never) | (TWithObjects extends true ? FlattenCommands<TCommands> : never) | (TWithFallback extends true ? SafeString : never);
+type CommandIsUnknownable<TCommand> = IsGeneric<TCommand> extends true ? true : string extends TCommand ? true : SafeString extends TCommand ? true : false;
+/**
+ * Match a string to a command by the possible commands.
+ * This is done by recursively splitting the string by the last space, and then checking if the prefix is a valid command name or alias.
+ * This is needed to avoid matching the top-level command when there are nested commands.
+ */
+/**
+ * Recursively re-paths a command's children under a new parent path.
+ * 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']['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/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>;
+/**
+ * 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 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;
+  /**
+   * 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.
+   */
+  id?: string;
+  /**
+   * Ordering hint. Lower values run as outer layers (earlier before `next()`, later after).
+   * Interceptors with the same order preserve registration order. Defaults to `0`.
+   */
+  order?: number;
+  /**
+   * 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`.
+   */
+  disabled?: boolean;
+  /**
+   * When `false`, the interceptor applies only to the command it was registered on
+   * and is not inherited by subcommands. Defaults to `true`.
+   */
+  inherit?: boolean;
+};
+/**
+ * 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 InterceptorPhases<TArgs = unknown, TResult = unknown, TContext = unknown> = {
+  /**
+   * 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.
+   */
+  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>;
+  /**
+   * 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?: InterceptorPhaseHandler<InterceptorErrorContext<TContext>, InterceptorErrorResult<TResult>, InterceptorErrorResult>;
+  /**
+   * Always runs after the pipeline completes (success or failure). `next()` calls the next shutdown handler.
+   * Use for cleanup: closing connections, flushing logs, etc.
+   */
+  shutdown?: InterceptorPhaseHandler<InterceptorShutdownContext<TResult, TContext>, void>;
+};
+/**
+ * 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 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>;
+  /**
+   * 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.
+   */
+  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/command.d.ts
+type UnknownRecord = Record<string, unknown>;
+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<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;
+  /**
+   * 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').
+   */
+  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';
+};
+/**
+ * Configuration for a command.
+ */
+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;
+};
+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;
+  description?: 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; /** 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); /** Usage examples shown in help output. Each entry is a command-line invocation string. */
+  examples?: string[];
+  argsSchema?: TArgs;
+  meta?: GetArgsMeta<TArgs>;
+  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; /** 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': {
+    name: TName;
+    parentName: TParentName;
+    path: FullCommandName<TName, TParentName>;
+    aliases: TAliases;
+    argsSchema: TArgs;
+    argsInput: StandardSchemaV1.InferInput<TArgs>;
+    argsOutput: StandardSchemaV1.InferOutput<TArgs>;
+    result: TRes;
+    commands: TCommands;
+    async: TAsync;
+    context: TContext;
+    contextProvided: TContextProvided;
+  };
+};
+type AnyPadroneCommand = PadroneCommand<string, any, any, any, [...AnyPadroneCommand[]], string[], any, any, any>;
+/**
+ * Base type for extracting command information from builder or program.
+ * Both PadroneBuilder and PadroneProgram share this structure.
+ */
+type CommandTypesBase = {
+  '~types': {
+    command: 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.
+ */
+/** A single spacing value: blank line (`true`), separator string, or an array of these for multiple lines. */
+type PadroneReplSpacing = boolean | string | (boolean | string)[];
+type PadroneReplPreferences<TScope extends string = string> = {
+  /** The prompt string displayed before each input, or a function returning it. Defaults to `"<programName>> "`. */prompt?: string | (() => string);
+  /**
+   * A greeting message displayed when the REPL starts.
+   * When not provided, defaults to `"Welcome to <name> v<version>"` (or just `"Welcome to <name>"` if no version).
+   * Set to `false` to suppress the default greeting entirely.
+   */
+  greeting?: string | false;
+  /**
+   * A hint message displayed below the greeting in dimmed text.
+   * When not provided, defaults to `'Type ".help" for more information, ".exit" to quit.'`.
+   * Set to `false` to suppress the hint.
+   */
+  hint?: string | false; /** Initial history entries (most recent last). Arrow keys navigate history in the terminal. */
+  history?: string[]; /** Set to `false` to disable tab completion. Defaults to `true`. */
+  completion?: boolean;
+  /**
+   * Add spacing/separators around each command's output.
+   * A spacing value can be:
+   * - `true` — blank line
+   * - A string — separator line (single char like `'─'` repeats to terminal width, multi-char prints as-is)
+   * - An array of the above — multiple lines in order (e.g. `[true, '─']` for blank line then separator)
+   *
+   * Shorthand applies to both before and after. Use `{ before?, after? }` for independent control.
+   */
+  spacing?: PadroneReplSpacing | {
+    before?: PadroneReplSpacing;
+    after?: PadroneReplSpacing;
+  }; /** Prefix each line of command output/error with this string (e.g. `'│ '`, `'  '`, `'▎ '`). */
+  outputPrefix?: string;
+  /**
+   * Start the REPL scoped to a command subtree. The scope path is a space-separated command path
+   * (e.g. `'db'` or `'db migrate'`). Commands are resolved relative to the scoped command.
+   * Users can change scope at runtime with `.scope <subcommand>` and `.scope ..`/`..`.
+   */
+  scope?: TScope;
+};
+/**
+ * Options that can be passed to `eval()` to control execution behavior.
+ */
+type PadroneEvalPreferences = {
+  /**
+   * Controls interactive prompting for this execution.
+   * Overrides the runtime's `interactive` setting, but is itself overridden by `--interactive` / `-i` flags.
+   *
+   * - `undefined`: inherit from runtime (default).
+   * - `true`: force prompting for all configured interactive fields, even if values are already provided.
+   * - `false`: suppress all interactive prompts.
+   */
+  interactive?: 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 = 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.
+ */
+type PadroneDrainResult<TResult> = {
+  value: Drained<TResult>;
+  error?: never;
+} | {
+  error: unknown;
+  value?: never;
+};
+/**
+ * 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; /** 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; /** 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>>>;
+};
+/**
+ * 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;
+  args?: GetArguments<'out', TCommand>;
+  argsResult?: StandardSchemaV1.Result<GetArguments<'out', TCommand>>;
+};
+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>;
+//#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;
+  };
+};
+/**
+ * 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;
+};
+/** Options for the `mount()` method. */
+type MountOptions<TContext, TNewContext> = {
+  context: (ctx: TContext) => TNewContext;
+};
+/**
+ * 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[]], 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>;
+/**
+ * Like InitialCommandBuilder but uses `any` for args 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[]], 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 { 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