padrone 1.5.0 → 1.7.0

package/src/types.ts

@@ -1,1291 +0,0 @@
-import type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/spec';
-import type { Tool } from 'ai';
-import type { PadroneArgsSchemaMeta } from './args.ts';
-import type { HelpPreferences } from './help.ts';
-import type { PadroneMcpPreferences } from './mcp.ts';
-import type { PadroneProgressIndicator, PadroneRuntime, PadroneSpinnerConfig, ResolvedPadroneRuntime } from './runtime.ts';
-import type { PadroneServePreferences } from './serve.ts';
-import type {
-  Drained,
-  FindDirectChild,
-  FlattenCommands,
-  FullCommandName,
-  IsGeneric,
-  MaybePromise,
-  OrAsync,
-  OrAsyncMeta,
-  PickCommandByName,
-  PickCommandByPossibleCommands,
-  PossibleCommands,
-  RepathCommands,
-  ReplaceOrAppendCommand,
-  SafeString,
-} from './type-utils.ts';
-import type { UpdateCheckConfig } from './update-check.ts';
-import type { WrapConfig, WrapResult } from './wrap.ts';
-
-type UnknownRecord = Record<string, unknown>;
-type EmptyRecord = Record<string, never>;
-type DefaultArgs = UnknownRecord | void;
-
-/**
- * Context object passed as the second argument to command action handlers.
- * Contains the resolved runtime, the executing command, and the program instance.
- */
-export 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).
- * This is the type required for command arguments in Padrone.
- */
-export 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) => { ... }));
- * ```
- */
-export type AsyncPadroneSchema<Input = unknown, Output = Input> = PadroneSchema<Input, Output> & { '~async': true };
-
-/**
- * Helper type to set aliases on a command type.
- * Uses intersection to override just the aliases while preserving all other type information.
- */
-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;
-
-/**
- * Resolves the initial builder type for a `.command()` call.
- * If TNameNested already exists in TCommands, the builder starts pre-populated with that command's types.
- * Otherwise, a fresh builder with default types is used.
- */
-type InitialCommandBuilder<
-  TProgramName extends string,
-  TNameNested extends string,
-  TParentPath extends string,
-  TParentArgs extends PadroneSchema,
-  TCommands extends [...AnyPadroneCommand[]],
-> = [FindDirectChild<TCommands, TNameNested>] extends [never]
-  ? PadroneBuilder<
-      TProgramName,
-      TNameNested,
-      TParentPath,
-      PadroneSchema<void>,
-      void,
-      [],
-      TParentArgs,
-      PadroneSchema<void>,
-      PadroneSchema<void>,
-      false
-    >
-  : FindDirectChild<TCommands, TNameNested> extends infer E extends AnyPadroneCommand
-    ? PadroneBuilder<
-        TProgramName,
-        TNameNested,
-        TParentPath,
-        E['~types']['argsSchema'],
-        E['~types']['result'],
-        E['~types']['commands'],
-        TParentArgs,
-        E['~types']['configSchema'],
-        E['~types']['envSchema'],
-        E['~types']['async']
-      >
-    : PadroneBuilder<
-        TProgramName,
-        TNameNested,
-        TParentPath,
-        PadroneSchema<void>,
-        void,
-        [],
-        TParentArgs,
-        PadroneSchema<void>,
-        PadroneSchema<void>,
-        false
-      >;
-
-export type AnyPadroneBuilder = InitialCommandBuilder<string, string, string, any, [...AnyPadroneCommand[]]>;
-
-/**
- * Like InitialCommandBuilder but uses `any` for args/config/env in the fresh case.
- * Used as the default for TBuilder when no builderFn is provided.
- */
-type DefaultCommandBuilder<
-  TProgramName extends string,
-  TNameNested extends string,
-  TParentPath extends string,
-  TParentArgs extends PadroneSchema,
-  TCommands extends [...AnyPadroneCommand[]],
-> = [FindDirectChild<TCommands, TNameNested>] extends [never]
-  ? PadroneBuilder<TProgramName, TNameNested, TParentPath, any, void, [], TParentArgs, any, any, false>
-  : FindDirectChild<TCommands, TNameNested> extends infer E extends AnyPadroneCommand
-    ? PadroneBuilder<
-        TProgramName,
-        TNameNested,
-        TParentPath,
-        E['~types']['argsSchema'],
-        E['~types']['result'],
-        E['~types']['commands'],
-        TParentArgs,
-        E['~types']['configSchema'],
-        E['~types']['envSchema'],
-        E['~types']['async']
-      >
-    : PadroneBuilder<TProgramName, TNameNested, TParentPath, any, void, [], TParentArgs, any, any, false>;
-
-export type PadroneCommand<
-  TName extends string = string,
-  TParentName extends string = '',
-  TArgs extends PadroneSchema = PadroneSchema<DefaultArgs>,
-  TRes = void,
-  TCommands extends [...AnyPadroneCommand[]] = [],
-  TAliases extends string[] = string[],
-  TConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = PadroneSchema<void>,
-  TEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = PadroneSchema<void>,
-  TAsync extends boolean = false,
-> = {
-  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);
-  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;
-  meta?: GetArgsMeta<TArgs>;
-  action?: (args: StandardSchemaV1.InferOutput<TArgs>, ctx: PadroneActionContext) => TRes;
-  /** List of possible config file names to search for. */
-  configFiles?: string[];
-  /** Runtime flag indicating this command uses async validation. Set by `.async()` or `asyncSchema()`. */
-  isAsync?: boolean;
-  /** Runtime configuration for I/O abstraction. */
-  runtime?: PadroneRuntime;
-
-  /** Plugins registered on this command. Collected from the parent chain at execution time. */
-  plugins?: PadronePlugin<any, any>[];
-
-  /** Update check configuration. Only used on the root program. */
-  updateCheck?: UpdateCheckConfig;
-
-  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;
-    configSchema: TConfig;
-    envSchema: TEnv;
-    async: TAsync;
-  };
-};
-
-export 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;
-  };
-};
-
-/**
- * Configuration for a command.
- */
-/**
- * A progress message value: a plain string, `null` to suppress, or an object with a message and custom indicator icon.
- */
-export 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.
- */
-export 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;
-};
-
-export type PadroneCommandConfig = {
-  /** A short title for the command, displayed in help. */
-  title?: string;
-  /** A longer description of what the command does. */
-  description?: string;
-  /** The version of the command. */
-  version?: string;
-  /** Whether the command is deprecated, or a message explaining the deprecation. */
-  deprecated?: boolean | string;
-  /** Whether the command should be hidden from help output. */
-  hidden?: boolean;
-  /** Group name for organizing this command under a labeled section in help output. */
-  group?: string;
-  /**
-   * Automatically write this command's return value to output in CLI/eval/REPL mode.
-   * Overrides the `autoOutput` setting in eval/cli preferences for this command.
-   * See `PadroneEvalPreferences.autoOutput` for serialization details.
-   */
-  autoOutput?: boolean;
-  /** Usage examples shown in help output. Each entry is a command-line invocation string. */
-  examples?: string[];
-  /**
-   * Whether this command performs a mutation (create, update, delete).
-   * - In `serve()`: mutation commands accept POST only; non-mutation commands accept GET and POST.
-   * - In `mcp()`: sets `annotations.destructiveHint` on the tool definition.
-   * - In `tool()`: defaults `needsApproval` to `true` when not explicitly set.
-   */
-  mutation?: boolean;
-};
-
-/**
- * Conditional type that returns either PadroneBuilder or PadroneProgram based on TReturn.
- * Used to avoid repetition in PadroneBuilderMethods return types.
- */
-type BuilderOrProgram<
-  TReturn extends 'builder' | 'program',
-  TProgramName extends string,
-  TName extends string,
-  TParentName extends string,
-  TArgs extends PadroneSchema,
-  TRes,
-  TCommands extends [...AnyPadroneCommand[]],
-  TParentArgs extends PadroneSchema,
-  TConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>>,
-  TEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>>,
-  TAsync extends boolean,
-> = TReturn extends 'builder'
-  ? PadroneBuilder<TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>
-  : PadroneProgram<TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
-
-/**
- * Base builder methods shared between PadroneBuilder and PadroneProgram.
- * These methods are used for defining command structure (arguments, config, env, action, subcommands).
- */
-export type PadroneBuilderMethods<
-  TProgramName extends string,
-  TName extends string,
-  TParentName extends string,
-  TArgs extends PadroneSchema,
-  TRes,
-  TCommands extends [...AnyPadroneCommand[]],
-  TParentArgs extends PadroneSchema,
-  TConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>>,
-  TEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>>,
-  TAsync extends boolean,
-  /** The return type for builder methods - either PadroneBuilder or PadroneProgram */
-  TReturn extends 'builder' | 'program',
-> = {
-  /**
-   * Enables automatic update checking against a package registry.
-   * When enabled, the program checks for a newer version in the background
-   * and displays a notification after command output if an update is available.
-   *
-   * - Non-blocking: check runs in background, never delays command execution.
-   * - Non-intrusive: shows a one-line notice after command output, not before.
-   * - Respects CI: disabled when `CI=true` or non-TTY.
-   * - Respects user preference: `--no-update-check` flag or env var.
-   * - Caches last check timestamp to avoid hitting the registry on every invocation.
-   *
-   * @example
-   * ```ts
-   * createPadrone('myapp')
-   *   .version('1.2.3')
-   *   .updateCheck({
-   *     registry: 'npm',         // or custom URL
-   *     interval: '1d',          // check at most once per day
-   *     cache: '~/.myapp-update' // where to store last check
-   *   })
-   * ```
-   */
-  updateCheck: (
-    config?: UpdateCheckConfig,
-  ) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
-
-  /**
-   * Registers a plugin that intercepts command execution phases (parse, validate, execute).
-   * Plugins are applied in order: first registered = outermost wrapper (runs first before `next()`).
-   * Use `plugin.order` for explicit ordering (lower = outermost).
-   *
-   * On the program, parse/validate/execute plugins all apply.
-   * On subcommands, only validate and execute plugins apply (parse is handled by the root program).
-   */
-  use: (
-    plugin: PadronePlugin<StandardSchemaV1.InferOutput<TArgs>, TRes>,
-  ) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
-
-  configure: (
-    config: PadroneCommandConfig,
-  ) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
-
-  /**
-   * Configures the runtime adapter for I/O abstraction.
-   * Allows the CLI framework to work outside of a terminal (e.g., web UIs, chat interfaces, testing).
-   * Unspecified fields fall back to the Node.js/Bun defaults.
-   *
-   * @example
-   * ```ts
-   * .runtime({
-   *   output: (text) => panel.append(text),
-   *   error: (text) => panel.appendError(text),
-   *   format: 'html',
-   * })
-   * ```
-   */
-  runtime: (
-    runtime: PadroneRuntime,
-  ) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
-
-  /**
-   * Explicitly marks this command as using async validation.
-   * When a command is async, `parse()` and `cli()` return Promises.
-   *
-   * This is an alternative to using `asyncSchema()` on individual schemas.
-   * Use this when your schema has async refinements but you don't want to
-   * (or can't) brand the schema itself.
-   *
-   * @example
-   * ```ts
-   * .arguments(z.object({ name: z.string() }).check(async (v) => { ... }))
-   * .async()
-   * .action((args) => { ... })
-   * ```
-   */
-  async: () => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, true>;
-
-  /**
-   * Defines the arguments schema for the command, including positional arguments.
-   * Can accept either a schema directly or a function that takes parent args schema as a base and returns a schema.
-   * Use the `positional` array in meta to specify which arguments are positional args.
-   * Use '...name' prefix for variadic (rest) arguments, matching JS/TS rest syntax.
-   *
-   * @example
-   * ```ts
-   * // Direct schema
-   * .arguments(z.object({
-   *   source: z.string(),
-   *   files: z.string().array(),
-   *   dest: z.string(),
-   *   recursive: z.boolean().default(false),
-   * }), {
-   *   positional: ['source', '...files', 'dest'],
-   * })
-   * ```
-   *
-   * @example
-   * ```ts
-   * // Function-based schema extending parent arguments
-   * .arguments((parentArgs) => {
-   *   return z.object({
-   *     ...parentArgs.shape,
-   *     verbose: z.boolean().default(false),
-   *   });
-   * })
-   * ```
-   */
-  arguments: <TNewArgs extends PadroneSchema = PadroneSchema<void>, TMeta extends GetArgsMeta<TNewArgs> = GetArgsMeta<TNewArgs>>(
-    schema?: TNewArgs | ((parentSchema: TParentArgs) => TNewArgs),
-    meta?: TMeta,
-  ) => BuilderOrProgram<
-    TReturn,
-    TProgramName,
-    TName,
-    TParentName,
-    TNewArgs,
-    TRes,
-    TCommands,
-    TParentArgs,
-    TConfig,
-    TEnv,
-    OrAsyncMeta<OrAsync<TAsync, TNewArgs>, TMeta>
-  >;
-
-  /**
-   * Configures config file path(s) and schema for parsing config files.
-   * @example
-   * ```ts
-   * .configFile('config.json', z.object({ port: z.number() }))
-   * ```
-   */
-  configFile: <TNewConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = TArgs>(
-    file: string | string[] | undefined,
-    schema?: TNewConfig | ((argsSchema: TArgs) => TNewConfig),
-  ) => BuilderOrProgram<
-    TReturn,
-    TProgramName,
-    TName,
-    TParentName,
-    TArgs,
-    TRes,
-    TCommands,
-    TParentArgs,
-    TNewConfig,
-    TEnv,
-    OrAsync<TAsync, TNewConfig>
-  >;
-
-  /**
-   * Configures environment variable schema for parsing env vars into arguments.
-   * The schema should transform environment variables (typically SCREAMING_SNAKE_CASE)
-   * into the argument names used by the command.
-   * @example
-   * ```ts
-   * .env(z.object({ MY_APP_PORT: z.coerce.number() }).transform(e => ({ port: e.MY_APP_PORT })))
-   * ```
-   */
-  env: <TNewEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = TArgs>(
-    schema: TNewEnv | ((argsSchema: TArgs) => TNewEnv),
-  ) => BuilderOrProgram<
-    TReturn,
-    TProgramName,
-    TName,
-    TParentName,
-    TArgs,
-    TRes,
-    TCommands,
-    TParentArgs,
-    TConfig,
-    TNewEnv,
-    OrAsync<TAsync, TNewEnv>
-  >;
-
-  /**
-   * Configures an auto-managed progress indicator for this command.
-   * The indicator starts before validation and is automatically stopped on success or failure.
-   *
-   * - `true` — generic message based on command name.
-   * - `string` — custom message for all states.
-   * - `PadroneProgressConfig` — full control: per-state messages, dynamic callbacks, spinner config.
-   *
-   * Requires a `progress` factory on the runtime — silently skipped if not available.
-   *
-   * @example
-   * ```ts
-   * .progress('Deploying...')
-   * .progress({
-   *   progress: 'Deploying...',
-   *   success: (result) => `Deployed ${result.version}`,
-   *   error: (err) => `Deploy failed: ${err.message}`,
-   *   spinner: 'line',
-   * })
-   * ```
-   */
-  progress: (
-    config?: boolean | string | PadroneProgressPrefs<Awaited<TRes>>,
-  ) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
-
-  /**
-   * Defines the handler function to be executed when the command is run.
-   * When overriding an existing command, the previous handler is passed as the third `base` parameter.
-   */
-  action: <TNewRes>(
-    handler?: (
-      args: StandardSchemaV1.InferOutput<TArgs>,
-      ctx: PadroneActionContext,
-      base: (args: StandardSchemaV1.InferOutput<TArgs>, ctx: PadroneActionContext) => TRes,
-    ) => TNewRes,
-  ) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TNewRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
-
-  /**
-   * Wraps an external CLI tool with optional schema transformation.
-   * The config can include a schema that transforms command arguments to external CLI arguments.
-   *
-   * @experimental This API is experimental and may change in future releases.
-   *
-   * @example
-   * ```ts
-   * // No transformation - pass arguments as-is
-   * .arguments(z.object({
-   *   message: z.string(),
-   * }))
-   * .wrap({
-   *   command: 'echo',
-   * })
-   * ```
-   *
-   * @example
-   * ```ts
-   * // With transformation schema
-   * .arguments(z.object({
-   *   message: z.string(),
-   *   all: z.boolean().optional(),
-   * }), {
-   *   positional: ['message'],
-   * })
-   * .wrap({
-   *   command: 'git',
-   *   args: ['commit'],
-   *   positional: ['m'],
-   *   schema: z.object({
-   *     message: z.string(),
-   *     all: z.boolean().optional(),
-   *   }).transform(args => ({
-   *     m: args.message,
-   *     a: args.all,
-   *   })),
-   * })
-   * ```
-   *
-   * @example
-   * ```ts
-   * // Using function-based schema for type inference
-   * .arguments(z.object({
-   *   image: z.string(),
-   *   detach: z.boolean().optional(),
-   * }))
-   * .wrap({
-   *   command: 'docker',
-   *   args: ['run'],
-   *   positional: ['image'],
-   *   schema: (schema) => schema.transform(args => ({
-   *     d: args.detach,
-   *     image: args.image,
-   *   })),
-   * })
-   * ```
-   */
-  wrap: <TWrapArgs extends PadroneSchema = TArgs>(
-    config: WrapConfig<TArgs, TWrapArgs>,
-  ) => BuilderOrProgram<
-    TReturn,
-    TProgramName,
-    TName,
-    TParentName,
-    TArgs,
-    Promise<WrapResult>,
-    TCommands,
-    TParentArgs,
-    TConfig,
-    TEnv,
-    TAsync
-  >;
-
-  /**
-   * Creates or extends a nested command within the current command.
-   * If a command with the same name already exists, it is extended:
-   * - Configuration is merged (new values override old).
-   * - The builder callback receives a builder pre-populated with the existing command's state.
-   * - `.action()` receives the previous handler as the third `base` parameter.
-   * - `.arguments()` callback receives the existing schema as its parameter.
-   * - Subcommands are recursively merged by name.
-   *
-   * @example
-   * ```ts
-   * // Fresh command
-   * .command('list', (c) => c.action(() => 'list'))
-   *
-   * // Override — extend an existing command
-   * .command('list', (c) => c.action((args, ctx, base) => {
-   *   const original = base(args, ctx);
-   *   return `modified: ${original}`;
-   * }))
-   *
-   * // Name with aliases
-   * .command(['list', 'ls', 'l'], (c) => c.action(() => 'list'))
-   * ```
-   */
-  command: <
-    TNameNested extends string,
-    TAliases extends string[] = [],
-    TBuilder extends CommandTypesBase = DefaultCommandBuilder<
-      TProgramName,
-      TNameNested,
-      FullCommandName<TName, TParentName>,
-      TArgs,
-      TCommands
-    >,
-  >(
-    name: TNameNested | readonly [TNameNested, ...TAliases],
-    builderFn?: (
-      builder: InitialCommandBuilder<TProgramName, TNameNested, FullCommandName<TName, TParentName>, TArgs, TCommands>,
-    ) => TBuilder,
-  ) => BuilderOrProgram<
-    TReturn,
-    TProgramName,
-    TName,
-    TParentName,
-    TArgs,
-    TRes,
-    TCommands extends []
-      ? [WithAliases<TBuilder['~types']['command'], TAliases>]
-      : AnyPadroneCommand[] extends TCommands
-        ? [WithAliases<TBuilder['~types']['command'], TAliases>]
-        : ReplaceOrAppendCommand<
-            TCommands,
-            TNameNested,
-            WithAliases<TBuilder['~types']['command'], ResolvedAliases<TCommands, TNameNested, TAliases>>
-          >,
-    TParentArgs,
-    TConfig,
-    TEnv,
-    TAsync
-  >;
-
-  /**
-   * Mounts an existing Padrone program as a subcommand.
-   * The program's root-level properties (name, path, parent) are replaced to fit the mount point.
-   * All subcommands are recursively re-pathed. Root-level `version` is dropped.
-   *
-   * @example
-   * ```ts
-   * const admin = createPadrone('admin')
-   *   .command('users', (c) => c.action(() => 'users'))
-   *   .command('roles', (c) => c.action(() => 'roles'));
-   *
-   * const app = createPadrone('app')
-   *   .mount('admin', admin)
-   *   // Now: app admin users, app admin roles
-   *
-   * // With aliases
-   * const app2 = createPadrone('app')
-   *   .mount(['admin', 'adm'], admin)
-   * ```
-   */
-  mount: <TNameNested extends string, TAliases extends string[] = [], TProgram extends CommandTypesBase = CommandTypesBase>(
-    name: TNameNested | readonly [TNameNested, ...TAliases],
-    program: TProgram,
-  ) => BuilderOrProgram<
-    TReturn,
-    TProgramName,
-    TName,
-    TParentName,
-    TArgs,
-    TRes,
-    TCommands extends []
-      ? [
-          WithAliases<
-            PadroneCommand<
-              TNameNested,
-              FullCommandName<TName, TParentName>,
-              TProgram['~types']['command']['~types']['argsSchema'],
-              TProgram['~types']['command']['~types']['result'],
-              RepathCommands<
-                TProgram['~types']['command']['~types']['commands'],
-                FullCommandName<TNameNested, FullCommandName<TName, TParentName>>
-              >,
-              [],
-              TProgram['~types']['command']['~types']['configSchema'],
-              TProgram['~types']['command']['~types']['envSchema'],
-              TProgram['~types']['command']['~types']['async']
-            >,
-            TAliases
-          >,
-        ]
-      : AnyPadroneCommand[] extends TCommands
-        ? [
-            WithAliases<
-              PadroneCommand<
-                TNameNested,
-                FullCommandName<TName, TParentName>,
-                TProgram['~types']['command']['~types']['argsSchema'],
-                TProgram['~types']['command']['~types']['result'],
-                RepathCommands<
-                  TProgram['~types']['command']['~types']['commands'],
-                  FullCommandName<TNameNested, FullCommandName<TName, TParentName>>
-                >,
-                [],
-                TProgram['~types']['command']['~types']['configSchema'],
-                TProgram['~types']['command']['~types']['envSchema'],
-                TProgram['~types']['command']['~types']['async']
-              >,
-              TAliases
-            >,
-          ]
-        : ReplaceOrAppendCommand<
-            TCommands,
-            TNameNested,
-            WithAliases<
-              PadroneCommand<
-                TNameNested,
-                FullCommandName<TName, TParentName>,
-                TProgram['~types']['command']['~types']['argsSchema'],
-                TProgram['~types']['command']['~types']['result'],
-                RepathCommands<
-                  TProgram['~types']['command']['~types']['commands'],
-                  FullCommandName<TNameNested, FullCommandName<TName, TParentName>>
-                >,
-                [],
-                TProgram['~types']['command']['~types']['configSchema'],
-                TProgram['~types']['command']['~types']['envSchema'],
-                TProgram['~types']['command']['~types']['async']
-              >,
-              ResolvedAliases<TCommands, TNameNested, TAliases>
-            >
-          >,
-    TParentArgs,
-    TConfig,
-    TEnv,
-    TAsync
-  >;
-
-  /** @deprecated Internal use only */
-  '~types': {
-    programName: TProgramName;
-    name: TName;
-    parentName: TParentName;
-    path: FullCommandName<TName, TParentName>;
-    aliases: [];
-    argsSchema: TArgs;
-    result: TRes;
-    commands: TCommands;
-    async: TAsync;
-    command: PadroneCommand<TName, TParentName, TArgs, TRes, TCommands, [], TConfig, TEnv, TAsync>;
-  };
-};
-
-export type PadroneBuilder<
-  TProgramName extends string = '',
-  TName extends string = string,
-  TParentName extends string = '',
-  TArgs extends PadroneSchema = PadroneSchema<DefaultArgs>,
-  TRes = void,
-  TCommands extends [...AnyPadroneCommand[]] = [],
-  TParentArgs extends PadroneSchema = PadroneSchema<void>,
-  TConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = PadroneSchema<void>,
-  TEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = PadroneSchema<void>,
-  TAsync extends boolean = false,
-> = PadroneBuilderMethods<TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync, 'builder'>;
-
-export type PadroneProgram<
-  TProgramName extends string = '',
-  TName extends string = string,
-  TParentName extends string = '',
-  TArgs extends PadroneSchema = PadroneSchema<DefaultArgs>,
-  TRes = void,
-  TCommands extends [...AnyPadroneCommand[]] = [],
-  TParentArgs extends PadroneSchema = PadroneSchema<void>,
-  TConfig extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = PadroneSchema<void>,
-  TEnv extends PadroneSchema<unknown, StandardSchemaV1.InferInput<TArgs>> = PadroneSchema<void>,
-  TAsync extends boolean = false,
-> = PadroneBuilderMethods<TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync, 'program'> & {
-  /**
-   * Runs a command programmatically by name with provided arguments (including positional args).
-   */
-  run: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], true, true>>(
-    name: TCommand | SafeString,
-    args: NoInfer<GetArguments<'in', PickCommandByName<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>>>,
-  ) => PadroneCommandResult<PickCommandByName<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>>;
-
-  /**
-   * Evaluates a command string: parses, validates, and executes.
-   * On validation errors, returns a result with issues instead of throwing.
-   * This is the method used by `repl()` internally, and the right choice for
-   * programmatic invocation, testing, chat interfaces, or any context where
-   * you have a command string and want a result — not a process exit.
-   *
-   * @example
-   * ```ts
-   * const result = await program.eval('greet --name Alice');
-   * if (result.argsResult?.issues) { /* handle validation errors *\/ }
-   * ```
-   */
-  eval: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], true, true>>(
-    input: TCommand | SafeString,
-    prefs?: PadroneEvalPreferences,
-  ) => MaybePromiseCommandResult<
-    PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>,
-    PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>['~types']['async']
-  >;
-
-  /**
-   * Runs the program as a CLI entry point, parsing `process.argv`.
-   * On validation errors, throws and prints help.
-   * For programmatic invocation with a command string, use `eval()` instead.
-   */
-  cli: (
-    prefs?: PadroneCliPreferences<PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>,
-  ) => MaybePromiseCommandResult<FlattenCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>, TAsync>;
-
-  /**
-   * Parses CLI input (or the provided input string) into command and arguments without executing anything.
-   */
-  parse: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], true, false>>(
-    input?: TCommand | SafeString,
-  ) => MaybePromise<
-    PadroneParseResult<PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>>,
-    PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>['~types']['async']
-  >;
-
-  /**
-   * Converts command and arguments back into a CLI string.
-   */
-  stringify: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], false, true>>(
-    command?: TCommand | SafeString,
-    args?: GetArguments<'out', PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>>,
-  ) => string;
-
-  /**
-   * Finds a command by name, returning `undefined` if not found.
-   */
-  find: <const TFind extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], false, true>>(
-    command: TFind | SafeString,
-  ) => PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TFind> | undefined;
-
-  /**
-   * Generates a type-safe API for invoking commands programmatically.
-   */
-  api: () => PadroneAPI<PadroneCommand<'', '', TArgs, TRes, TCommands>>;
-
-  /**
-   * Starts a REPL (Read-Eval-Print Loop) for running commands interactively.
-   * Returns an AsyncIterable that yields a `PadroneCommandResult` for each successfully executed command.
-   * Errors are printed via `runtime.error()` and the loop continues.
-   * The loop ends when the user sends EOF (Ctrl+D), types `.exit`/`.quit`,
-   * or presses Ctrl+C twice within 2 seconds.
-   *
-   * @example
-   * ```ts
-   * for await (const result of program.repl()) {
-   *   console.log(result.command.name, result.result);
-   * }
-   * ```
-   *
-   * TODO: REPL future enhancements:
-   * - History persistence: save/load history across sessions (currently in-memory only)
-   * - Middleware/hooks: onBeforeCommand, onAfterCommand, error interceptors (design alongside general middleware system)
-   */
-  repl: (options?: PadroneReplPreferences<PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>) => AsyncIterable<
-    PadroneCommandResult<FlattenCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>
-  > & {
-    drain: () => Promise<PadroneDrainResult<PadroneCommandResult<FlattenCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>[]>>;
-  };
-
-  /**
-   * Returns a tool definition that can be passed to AI SDK.
-   */
-  tool: () => Tool<{ command: string }>;
-
-  /**
-   * Returns the help information for the program or a specific command.
-   */
-  help: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], false, true>>(
-    command?: TCommand,
-    prefs?: HelpPreferences,
-  ) => string;
-
-  /**
-   * Generates and returns a shell completion script.
-   * If shell is not specified, automatically detects the current shell and provides instructions.
-   * @param shell - The shell type (bash, zsh, fish, powershell). If not provided, auto-detects.
-   * @returns The shell completion script as a string.
-   * @example
-   * ```ts
-   * // Get bash completion script
-   * const bashScript = program.completion('bash');
-   *
-   * // Auto-detect shell and get completion script with instructions
-   * const script = program.completion();
-   * ```
-   */
-  completion: (shell?: 'bash' | 'zsh' | 'fish' | 'powershell') => Promise<string>;
-
-  /**
-   * Starts a Model Context Protocol (MCP) server that exposes commands as tools for AI assistants.
-   * Communicates over stdio using JSON-RPC with Content-Length framing.
-   * Returns a Promise that resolves when the connection closes.
-   *
-   * @experimental This API is experimental and may change in future releases.
-   *
-   * @example
-   * ```ts
-   * await program.mcp();
-   * ```
-   */
-  mcp: (prefs?: PadroneMcpPreferences) => Promise<void>;
-
-  /**
-   * Starts a REST HTTP server that exposes commands as endpoints.
-   * Each command becomes a route: `users list` → `GET/POST /users/list`.
-   * Commands with `mutation: true` only accept POST.
-   *
-   * @experimental This API is experimental and may change in future releases.
-   *
-   * @example
-   * ```ts
-   * await program.serve({ port: 3000 });
-   * ```
-   */
-  serve: (prefs?: PadroneServePreferences) => Promise<void>;
-};
-
-export type AnyPadroneProgram = PadroneProgram<string, string, string, any, any, [...AnyPadroneCommand[]]>;
-
-/**
- * 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. */
-export type PadroneReplSpacing = boolean | string | (boolean | string)[];
-
-export 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;
-
-  /**
-   * Automatically write each command's return value to output.
-   * See `PadroneEvalPreferences.autoOutput` for details on how values are serialized.
-   * Defaults to `true`.
-   */
-  autoOutput?: boolean;
-};
-
-/**
- * Options that can be passed to `eval()` to control execution behavior.
- */
-export 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;
-
-  /**
-   * Automatically write the command's return value to output.
-   *
-   * - Values are passed directly to the runtime's `output` function (no stringification).
-   * - Promises are awaited before output.
-   * - Iterators and async iterators are consumed, outputting each yielded value as it arrives.
-   * - `undefined` and `null` results produce no output.
-   *
-   * Defaults to `true`. Set to `false` to disable.
-   */
-  autoOutput?: boolean;
-
-  /**
-   * Override the runtime for this execution.
-   * Partial — only the provided fields replace the command's resolved runtime.
-   * Useful for capturing output, injecting test doubles, or running in non-terminal contexts (e.g. AI tool calls).
-   */
-  runtime?: PadroneRuntime;
-};
-
-/**
- * Options that can be passed to `cli()` to control execution behavior.
- */
-export type PadroneCliPreferences<TScope extends string = string> = PadroneEvalPreferences & {
-  /** REPL preferences used when `--repl` flag is passed. Set to `false` to disable the `--repl` flag. */
-  repl?: PadroneReplPreferences<TScope> | false;
-  /** MCP server preferences used when `mcp` command is used. Set to `false` to disable. */
-  mcp?: PadroneMcpPreferences | false;
-  /** REST server preferences used when `serve` command is used. Set to `false` to disable. */
-  serve?: PadroneServePreferences | false;
-};
-
-/**
- * Result of `drain()` — a discriminated union that never throws.
- * On success, `value` holds the fully resolved/collected result; on failure, `error` holds the error.
- */
-export 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.
- */
-export 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>>>;
-};
-
-export type PadroneParseResult<TCommand extends AnyPadroneCommand = AnyPadroneCommand> = {
-  command: TCommand;
-  args?: GetArguments<'out', TCommand>;
-  argsResult?: StandardSchemaV1.Result<GetArguments<'out', TCommand>>;
-};
-
-export type PadroneAPI<TCommand extends AnyPadroneCommand> = PadroneAPICommand<TCommand> & {
-  [K in TCommand['~types']['commands'][number] as K['name']]: PadroneAPI<K>;
-};
-
-type PadroneAPICommand<TCommand extends AnyPadroneCommand> = (args: GetArguments<'in', TCommand>) => GetResults<TCommand>;
-
-type NormalizeArguments<TArgs> = IsGeneric<TArgs> extends true ? void | EmptyRecord : TArgs;
-type GetArguments<TDir extends 'in' | 'out', TCommand extends AnyPadroneCommand> = TDir extends 'in'
-  ? NormalizeArguments<TCommand['~types']['argsInput']>
-  : NormalizeArguments<TCommand['~types']['argsOutput']>;
-
-type GetResults<TCommand extends AnyPadroneCommand> = ReturnType<NonNullable<TCommand['action']>>;
-
-type GetArgsMeta<TArgs extends PadroneSchema> = PadroneArgsSchemaMeta<NonNullable<StandardSchemaV1.InferInput<TArgs>>>;
-
-// ---------------------------------------------------------------------------
-// Plugin system
-// ---------------------------------------------------------------------------
-
-/** Base context shared across all plugin phases within a single execution. */
-export type PluginBaseContext = {
-  /** The resolved command for this execution. In the parse phase, this is the root program. */
-  command: AnyPadroneCommand;
-  /** Mutable state bag shared across phases for this execution. Plugins can store cross-phase data here. */
-  state: Record<string, unknown>;
-};
-
-/** Context for the parse phase. */
-export type PluginParseContext = PluginBaseContext & {
-  /** The raw CLI input string (undefined when invoked without input). */
-  input: string | undefined;
-};
-
-/** Result returned by the parse phase's `next()`. */
-export type PluginParseResult = {
-  command: AnyPadroneCommand;
-  rawArgs: Record<string, unknown>;
-  positionalArgs: string[];
-};
-
-/** Context for the validate phase. */
-export type PluginValidateContext = PluginBaseContext & {
-  /** Raw named arguments extracted by the parser. Mutable — modify before `next()` to inject/override values. */
-  rawArgs: Record<string, unknown>;
-  /** Positional argument strings extracted by the parser. */
-  positionalArgs: string[];
-};
-
-/** Result returned by the validate phase's `next()`. */
-export type PluginValidateResult<TArgs = unknown> = {
-  args: TArgs;
-  argsResult: StandardSchemaV1.Result<TArgs>;
-};
-
-/** Context for the execute phase. */
-export 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()`. */
-export type PluginExecuteResult<TResult = unknown> = {
-  result: TResult;
-};
-
-/** Context for the start phase. Runs before parsing, wraps the entire pipeline. */
-export type PluginStartContext = PluginBaseContext & {
-  /** The raw CLI input string (undefined when invoked without input). */
-  input: string | undefined;
-};
-
-/** Context for the error phase. Called when the pipeline throws. */
-export type PluginErrorContext = PluginBaseContext & {
-  /** The error that was thrown. */
-  error: unknown;
-};
-
-/** Result returned by the error phase's `next()`. */
-export type PluginErrorResult<TResult = unknown> = {
-  /** The error (possibly transformed). Set to `undefined` to suppress the error. */
-  error?: unknown;
-  /** A replacement result when suppressing the error. */
-  result?: TResult;
-};
-
-/** Context for the shutdown phase. Always runs after the pipeline (success or failure). */
-export type PluginShutdownContext<TResult = unknown> = PluginBaseContext & {
-  /** The error, if the pipeline failed (after error phase processing). */
-  error?: unknown;
-  /** The pipeline result, if it succeeded. */
-  result?: TResult;
-};
-
-/**
- * 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 or subcommand level with `.use()`.
- *
- * Type parameters:
- * - `TArgs` — the validated arguments type (output of the args schema). Provides typed `ctx.args` in the execute phase
- *   and typed `args` in the validate result from `next()`.
- * - `TResult` — the command's return type. Provides typed `result` in execute/error/shutdown phases.
- *
- * When registered inline on a builder, these are inferred from the command's types automatically.
- * For reusable plugins that work with any command, use `PadronePlugin<any, any>`.
- *
- * Each phase handler receives a context and a `next()` function (onion/middleware pattern):
- * - Call `next()` to proceed to the next plugin or the core operation.
- * - Return without calling `next()` to short-circuit.
- * - Wrap `next()` in try/catch for error handling.
- * - Modify context fields before `next()` to alter inputs.
- * - Transform the return value of `next()` to alter outputs.
- */
-export type PadronePlugin<TArgs = unknown, TResult = unknown> = {
-  /** Display name for this plugin. Used for identification in logs and debugging. */
-  name: string;
-  /**
-   * Optional unique identifier for deduplication. When multiple plugins share the same `id`,
-   * only the last one registered is kept. Useful for allowing downstream code to override
-   * a plugin without accumulating duplicates.
-   */
-  id?: string;
-  /**
-   * Ordering hint. Lower values run as outer layers (earlier before `next()`, later after).
-   * Plugins with the same order preserve registration order. Defaults to `0`.
-   */
-  order?: number;
-  /**
-   * Runs before the pipeline (parse → validate → execute). `next()` proceeds to the pipeline.
-   * Root plugins only. Use for startup tasks like telemetry, update checks, or global config loading.
-   */
-  start?: PluginPhaseHandler<PluginStartContext, unknown>;
-  /** Intercepts command routing and raw argument extraction. */
-  parse?: PluginPhaseHandler<PluginParseContext, PluginParseResult>;
-  /** Intercepts argument preprocessing, interactive prompting, and schema validation. */
-  validate?: PluginPhaseHandler<PluginValidateContext, PluginValidateResult<TArgs>, PluginValidateResult>;
-  /** Intercepts handler execution. */
-  execute?: PluginPhaseHandler<PluginExecuteContext<TArgs>, PluginExecuteResult<TResult>, PluginExecuteResult>;
-  /**
-   * Called when the pipeline throws an error. `next()` passes to the next error handler
-   * (innermost returns `{ error }` unchanged). Return `{ result }` without `error` to suppress.
-   */
-  error?: PluginPhaseHandler<PluginErrorContext, PluginErrorResult<TResult>, PluginErrorResult>;
-  /**
-   * Always runs after the pipeline completes (success or failure). `next()` calls the next shutdown handler.
-   * Use for cleanup: closing connections, flushing logs, etc.
-   */
-  shutdown?: PluginPhaseHandler<PluginShutdownContext<TResult>, void>;
-};