padrone 1.4.0 → 1.5.0

package/src/stream.ts

@@ -0,0 +1,75 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { PadroneSchema } from './types.ts';
+
+export interface AsyncStreamMeta {
+  [x: string]: unknown;
+  readonly asyncStream: number;
+  readonly itemSchema?: StandardSchemaV1;
+}
+
+let asyncStreamIdCounter = 1;
+export const asyncStreamRegistry = new Map<number, AsyncStreamMeta>();
+
+/**
+ * Returns metadata to mark a schema field as an async stream via `.meta()`.
+ *
+ * When used with `stdin`, padrone pipes stdin data as an `AsyncIterable` instead of
+ * buffering it. Each line is validated against the item schema (if provided) as it arrives.
+ *
+ * @param itemSchema - Optional item schema for per-item validation.
+ *   Non-string schemas cause each stdin line to be `JSON.parse`'d before validation.
+ *
+ * @example
+ * ```ts
+ * import { asyncStream } from 'padrone';
+ *
+ * // String lines
+ * z.object({ lines: z.custom<AsyncIterable<string>>().meta(asyncStream()) })
+ *
+ * // Typed items — each line JSON.parse'd and validated
+ * z.object({ records: z.custom<AsyncIterable<{ name: string }>>().meta(asyncStream(recordSchema)) })
+ * ```
+ */
+export function asyncStream<T = string>(itemSchema?: PadroneSchema<T>): AsyncStreamMeta {
+  const id = asyncStreamIdCounter++;
+  const meta: AsyncStreamMeta = itemSchema ? { asyncStream: id, itemSchema } : { asyncStream: id };
+  asyncStreamRegistry.set(id, meta);
+  return meta;
+}
+
+/** Stdin interface matching PadroneRuntime.stdin */
+interface StdinSource {
+  isTTY?: boolean;
+  text(): Promise<string>;
+  lines(): AsyncIterable<string>;
+}
+
+/**
+ * Creates an `AsyncIterable` from a stdin source, optionally validating each item.
+ * When no stdin is available (TTY / undefined), yields nothing.
+ *
+ * - No item schema: yields raw string lines
+ * - With item schema: `JSON.parse`s each line, validates, then yields
+ */
+export function createStdinStream(stdin: StdinSource | undefined, itemSchema?: StandardSchemaV1): AsyncIterable<unknown> {
+  if (!stdin) return emptyAsyncIterable;
+
+  if (!itemSchema) return stdin.lines();
+
+  return {
+    async *[Symbol.asyncIterator]() {
+      for await (const line of stdin.lines()) {
+        const result = itemSchema['~standard'].validate(line);
+        const resolved = result instanceof Promise ? await result : result;
+        if ('issues' in resolved && resolved.issues) {
+          throw new Error(`Stream item validation failed: ${resolved.issues.map((i) => i.message).join(', ')}`);
+        }
+        yield (resolved as { value: unknown }).value;
+      }
+    },
+  };
+}
+
+const emptyAsyncIterable: AsyncIterable<never> = {
+  async *[Symbol.asyncIterator]() {},
+};

package/src/test.ts

@@ -153,21 +153,11 @@ export function testCli(program: TestableProgram): TestCliBuilder {
       const runtime = buildRuntime(stdout, stderr, { envVars, promptAnswers, configFiles, stdinData });
       const testProgram = program.runtime(runtime);
 
-      try {
-        const evalResult = await testProgram.eval(runInput ?? input ?? '', { autoOutput: false });
-        return toTestResult(evalResult, stdout, stderr);
-      } catch (err) {
-        stderr.push(err instanceof Error ? err.message : String(err));
-        return {
-          command: undefined as unknown as AnyPadroneCommand,
-          args: undefined,
-          result: undefined,
-          issues: undefined,
-          stdout,
-          stderr,
-          error: err,
-        };
+      const evalResult = await testProgram.eval(runInput ?? input ?? '', { autoOutput: false });
+      if (evalResult.error) {
+        stderr.push(evalResult.error instanceof Error ? evalResult.error.message : String(evalResult.error));
       }
+      return toTestResult(evalResult, stdout, stderr);
     },
 
     async repl(inputs: string[]) {
@@ -186,7 +176,7 @@ export function testCli(program: TestableProgram): TestCliBuilder {
 
       for await (const r of testProgram.repl({ greeting: false, hint: false })) {
         results.push({
-          command: r.command,
+          command: r.command!,
           args: r.args,
           result: r.result,
           issues: r.argsResult?.issues as TestCliResult['issues'],
@@ -202,9 +192,10 @@ export function testCli(program: TestableProgram): TestCliBuilder {
 
 function toTestResult(evalResult: PadroneCommandResult, stdout: unknown[], stderr: string[]): TestCliResult {
   return {
-    command: evalResult.command,
+    command: evalResult.command!,
     args: evalResult.args,
     result: evalResult.result,
+    error: evalResult.error,
     issues: evalResult.argsResult?.issues as TestCliResult['issues'],
     stdout,
     stderr,

package/src/type-utils.ts

@@ -36,9 +36,9 @@ export type OrAsync<TExisting extends boolean, TSchema> = TExisting extends true
  * Detects whether argument meta contains interactive or optionalInteractive configuration.
  * When either is `true` or a `string[]`, the command requires async execution for prompting.
  */
-export type HasInteractive<TMeta> = TMeta extends { interactive: true | string[] }
+export type HasInteractive<TMeta> = TMeta extends { interactive: true | readonly string[] }
   ? true
-  : TMeta extends { optionalInteractive: true | string[] }
+  : TMeta extends { optionalInteractive: true | readonly string[] }
     ? true
     : false;
 
@@ -52,14 +52,38 @@ export type OrAsyncMeta<TExisting extends boolean, TMeta> = TExisting extends tr
     ? 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`
+ */
+export 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.
+ */
+export type Thenable<T> = T & PromiseLike<T> & { catch: Promise<T>['catch']; finally: Promise<T>['finally'] };
+
 /**
  * Conditionally wraps a type in Promise based on the TAsync flag.
  * - `true` → `Promise<T>`
- * - `false` → `T & PromiseLike<T>` (thenable: supports `.then()` and `await`)
+ * - `false` → `T & Thenable<T>` (thenable: supports `.then()`, `.catch()`, `.finally()`, and `await`)
  * - `boolean` (union of true|false) → `Promise<T>` (safe default when async-ness is uncertain)
  * - `any` → `T` (for generic/any typed commands like AnyPadroneCommand)
  */
-export type MaybePromise<T, TAsync> = IsAny<TAsync> extends true ? T : true extends TAsync ? Promise<T> : T & PromiseLike<T>;
+export 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>]

package/src/types.ts

@@ -2,8 +2,11 @@ import type { StandardJSONSchemaV1, StandardSchemaV1 } from '@standard-schema/sp
 import type { Tool } from 'ai';
 import type { PadroneArgsSchemaMeta } from './args.ts';
 import type { HelpPreferences } from './help.ts';
-import type { PadroneRuntime, ResolvedPadroneRuntime } from './runtime.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,
@@ -36,6 +39,11 @@ export type PadroneActionContext = {
   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;
 };
 
 /**
@@ -178,8 +186,24 @@ export type PadroneCommand<
   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;
@@ -193,7 +217,7 @@ export type PadroneCommand<
   runtime?: PadroneRuntime;
 
   /** Plugins registered on this command. Collected from the parent chain at execution time. */
-  plugins?: PadronePlugin[];
+  plugins?: PadronePlugin<any, any>[];
 
   /** Update check configuration. Only used on the root program. */
   updateCheck?: UpdateCheckConfig;
@@ -233,6 +257,33 @@ type CommandTypesBase = {
 /**
  * Configuration for a command.
  */
+/**
+ * A progress message value: a plain string, `null` to suppress, or an object with a message and custom indicator icon.
+ */
+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;
@@ -244,12 +295,23 @@ export type PadroneCommandConfig = {
   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;
 };
 
 /**
@@ -325,7 +387,7 @@ export type PadroneBuilderMethods<
    * On subcommands, only validate and execute plugins apply (parse is handled by the root program).
    */
   use: (
-    plugin: PadronePlugin,
+    plugin: PadronePlugin<StandardSchemaV1.InferOutput<TArgs>, TRes>,
   ) => BuilderOrProgram<TReturn, TProgramName, TName, TParentName, TArgs, TRes, TCommands, TParentArgs, TConfig, TEnv, TAsync>;
 
   configure: (
@@ -463,6 +525,31 @@ export type PadroneBuilderMethods<
     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.
@@ -479,6 +566,8 @@ export type PadroneBuilderMethods<
    * 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
@@ -769,8 +858,8 @@ export type PadroneProgram<
   eval: <const TCommand extends PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], true, true>>(
     input: TCommand | SafeString,
     prefs?: PadroneEvalPreferences,
-  ) => MaybePromise<
-    PadroneCommandResult<PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>>,
+  ) => MaybePromiseCommandResult<
+    PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>,
     PickCommandByPossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>], TCommand>['~types']['async']
   >;
 
@@ -781,7 +870,7 @@ export type PadroneProgram<
    */
   cli: (
     prefs?: PadroneCliPreferences<PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>,
-  ) => MaybePromise<PadroneCommandResult<FlattenCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>, TAsync>;
+  ) => MaybePromiseCommandResult<FlattenCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>, TAsync>;
 
   /**
    * Parses CLI input (or the provided input string) into command and arguments without executing anything.
@@ -831,9 +920,11 @@ export type PadroneProgram<
    * - History persistence: save/load history across sessions (currently in-memory only)
    * - Middleware/hooks: onBeforeCommand, onAfterCommand, error interceptors (design alongside general middleware system)
    */
-  repl: (
-    options?: PadroneReplPreferences<PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>,
-  ) => AsyncIterable<PadroneCommandResult<FlattenCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>>;
+  repl: (options?: PadroneReplPreferences<PossibleCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>) => AsyncIterable<
+    PadroneCommandResult<FlattenCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>
+  > & {
+    drain: () => Promise<PadroneDrainResult<PadroneCommandResult<FlattenCommands<[PadroneCommand<'', '', TArgs, TRes, TCommands>]>>[]>>;
+  };
 
   /**
    * Returns a tool definition that can be passed to AI SDK.
@@ -863,6 +954,34 @@ export type PadroneProgram<
    * ```
    */
   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[]]>;
@@ -959,10 +1078,48 @@ export type PadroneEvalPreferences = {
 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;
 };
 
-export type PadroneCommandResult<TCommand extends AnyPadroneCommand = AnyPadroneCommand> = PadroneParseResult<TCommand> & {
-  result: GetResults<TCommand>;
+/**
+ * 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> = {
@@ -1020,20 +1177,20 @@ export type PluginValidateContext = PluginBaseContext & {
 };
 
 /** Result returned by the validate phase's `next()`. */
-export type PluginValidateResult = {
-  args: unknown;
-  argsResult: StandardSchemaV1.Result<unknown>;
+export type PluginValidateResult<TArgs = unknown> = {
+  args: TArgs;
+  argsResult: StandardSchemaV1.Result<TArgs>;
 };
 
 /** Context for the execute phase. */
-export type PluginExecuteContext = PluginBaseContext & {
+export type PluginExecuteContext<TArgs = unknown> = PluginBaseContext & {
   /** Validated arguments that will be passed to the action. Mutable — modify before `next()` to override. */
-  args: unknown;
+  args: TArgs;
 };
 
 /** Result returned by the execute phase's `next()`. */
-export type PluginExecuteResult = {
-  result: unknown;
+export type PluginExecuteResult<TResult = unknown> = {
+  result: TResult;
 };
 
 /** Context for the start phase. Runs before parsing, wraps the entire pipeline. */
@@ -1049,26 +1206,45 @@ export type PluginErrorContext = PluginBaseContext & {
 };
 
 /** Result returned by the error phase's `next()`. */
-export type PluginErrorResult = {
+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?: unknown;
+  result?: TResult;
 };
 
 /** Context for the shutdown phase. Always runs after the pipeline (success or failure). */
-export type PluginShutdownContext = PluginBaseContext & {
+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?: unknown;
+  result?: TResult;
 };
 
-type PluginPhaseHandler<TCtx, TResult> = (ctx: TCtx, next: () => TResult | Promise<TResult>) => TResult | Promise<TResult>;
+/**
+ * A phase handler function for the plugin middleware chain.
+ *
+ * - `TCtx` — the context object available to the handler.
+ * - `TNextResult` — the typed result returned by `next()`, giving the handler type-safe access to downstream output.
+ * - `TReturn` — the type the handler itself returns. Defaults to `TNextResult` but can be wider,
+ *   allowing plugins to transform or replace the result (e.g., error-recovery plugins returning a different type).
+ */
+type PluginPhaseHandler<TCtx, TNextResult, TReturn = TNextResult> = (
+  ctx: TCtx,
+  next: () => TNextResult | Promise<TNextResult>,
+) => TReturn | Promise<TReturn>;
 
 /**
  * A Padrone plugin that can intercept the parse, validate, and execute phases of command execution.
- * Plugins are registered at the program level with `.use()` and apply to all commands.
+ * Plugins are registered at the program or subcommand level with `.use()`.
+ *
+ * Type parameters:
+ * - `TArgs` — the validated arguments type (output of the args schema). Provides typed `ctx.args` in the execute phase
+ *   and typed `args` in the validate result from `next()`.
+ * - `TResult` — the command's return type. Provides typed `result` in execute/error/shutdown phases.
+ *
+ * When registered inline on a builder, these are inferred from the command's types automatically.
+ * For reusable plugins that work with any command, use `PadronePlugin<any, any>`.
  *
  * Each phase handler receives a context and a `next()` function (onion/middleware pattern):
  * - Call `next()` to proceed to the next plugin or the core operation.
@@ -1077,9 +1253,15 @@ type PluginPhaseHandler<TCtx, TResult> = (ctx: TCtx, next: () => TResult | Promi
  * - Modify context fields before `next()` to alter inputs.
  * - Transform the return value of `next()` to alter outputs.
  */
-export type PadronePlugin = {
-  /** Unique name for this plugin. Used for identification and future disable/override support. */
+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`.
@@ -1093,17 +1275,17 @@ export type PadronePlugin = {
   /** Intercepts command routing and raw argument extraction. */
   parse?: PluginPhaseHandler<PluginParseContext, PluginParseResult>;
   /** Intercepts argument preprocessing, interactive prompting, and schema validation. */
-  validate?: PluginPhaseHandler<PluginValidateContext, PluginValidateResult>;
+  validate?: PluginPhaseHandler<PluginValidateContext, PluginValidateResult<TArgs>, PluginValidateResult>;
   /** Intercepts handler execution. */
-  execute?: PluginPhaseHandler<PluginExecuteContext, PluginExecuteResult>;
+  execute?: PluginPhaseHandler<PluginExecuteContext<TArgs>, PluginExecuteResult<TResult>, PluginExecuteResult>;
   /**
    * Called when the pipeline throws an error. `next()` passes to the next error handler
    * (innermost returns `{ error }` unchanged). Return `{ result }` without `error` to suppress.
    */
-  error?: PluginPhaseHandler<PluginErrorContext, PluginErrorResult>;
+  error?: PluginPhaseHandler<PluginErrorContext, PluginErrorResult<TResult>, PluginErrorResult>;
   /**
    * Always runs after the pipeline completes (success or failure). `next()` calls the next shutdown handler.
    * Use for cleanup: closing connections, flushing logs, etc.
    */
-  shutdown?: PluginPhaseHandler<PluginShutdownContext, void>;
+  shutdown?: PluginPhaseHandler<PluginShutdownContext<TResult>, void>;
 };

package/src/wrap.ts

@@ -58,7 +58,7 @@ export type WrapResult = {
 /**
  * Converts parsed arguments to CLI arguments for an external command.
  */
-function argsToCliArgs(input: Record<string, unknown> | undefined, positional: string[] = []): string[] {
+function argsToCliArgs(input: Record<string, unknown> | undefined, positional: readonly string[] = []): string[] {
   const args: string[] = [];
 
   // Handle undefined or null input
@@ -122,7 +122,7 @@ function argsToCliArgs(input: Record<string, unknown> | undefined, positional: s
 export function createWrapHandler<TCommandArgs extends PadroneSchema, TWrapArgs extends PadroneSchema>(
   config: WrapConfig<TCommandArgs, TWrapArgs>,
   commandArguments: TCommandArgs,
-  commandPositional?: string[],
+  commandPositional?: readonly string[],
 ): (args: StandardSchemaV1.InferOutput<TCommandArgs>) => Promise<WrapResult> {
   return async (args: StandardSchemaV1.InferOutput<TCommandArgs>): Promise<WrapResult> => {
     const { command, args: fixedArgs = [], inheritStdio = true, positional = commandPositional, schema: wrapSchema } = config;
@@ -153,33 +153,31 @@ export function createWrapHandler<TCommandArgs extends PadroneSchema, TWrapArgs
     const allArgs = [...fixedArgs, ...regularArgs];
 
     // Execute the external command
-    const proc = Bun.spawn([command, ...allArgs], {
-      stdout: inheritStdio ? 'inherit' : 'pipe',
-      stderr: inheritStdio ? 'inherit' : 'pipe',
-      stdin: inheritStdio ? 'inherit' : 'ignore',
-    });
+    const { spawn } = await import('node:child_process');
 
-    const exitCode = await proc.exited;
+    return new Promise<WrapResult>((resolve, reject) => {
+      const proc = spawn(command, allArgs, {
+        stdio: inheritStdio ? 'inherit' : ['ignore', 'pipe', 'pipe'],
+      });
 
-    let stdout: string | undefined;
-    let stderr: string | undefined;
+      const stdoutChunks: Buffer[] = [];
+      const stderrChunks: Buffer[] = [];
 
-    if (!inheritStdio) {
-      if (proc.stdout) {
-        const stdoutBuffer = await new Response(proc.stdout).arrayBuffer();
-        stdout = new TextDecoder().decode(stdoutBuffer);
-      }
-      if (proc.stderr) {
-        const stderrBuffer = await new Response(proc.stderr).arrayBuffer();
-        stderr = new TextDecoder().decode(stderrBuffer);
+      if (!inheritStdio) {
+        proc.stdout!.on('data', (chunk: Buffer) => stdoutChunks.push(chunk));
+        proc.stderr!.on('data', (chunk: Buffer) => stderrChunks.push(chunk));
       }
-    }
 
-    return {
-      exitCode,
-      stdout,
-      stderr,
-      success: exitCode === 0,
-    };
+      proc.on('error', reject);
+      proc.on('close', (code) => {
+        const exitCode = code ?? 1;
+        resolve({
+          exitCode,
+          stdout: inheritStdio ? undefined : Buffer.concat(stdoutChunks).toString(),
+          stderr: inheritStdio ? undefined : Buffer.concat(stderrChunks).toString(),
+          success: exitCode === 0,
+        });
+      });
+    });
   };
 }