padrone 1.5.0 → 1.7.0

package/src/create.ts

@@ -1,1829 +0,0 @@
-import type { StandardSchemaV1 } from '@standard-schema/spec';
-import type { Schema } from 'ai';
-import {
-  coerceArgs,
-  detectUnknownArgs,
-  extractSchemaMetadata,
-  isArrayField,
-  isAsyncStreamField,
-  JSON_SCHEMA_OPTS,
-  parsePositionalConfig,
-  parseStdinConfig,
-  preprocessArgs,
-} from './args.ts';
-import { type ColorConfig, type ColorTheme, colorThemes } from './colorizer.ts';
-import {
-  commandSymbol,
-  createLazyIndicator,
-  createProgress,
-  errorResult,
-  findCommandByName,
-  getCommandRuntime,
-  hasInteractiveConfig,
-  isAsyncBranded,
-  lazyResolver,
-  makeThenable,
-  mergeCommands,
-  noop,
-  noopIndicator,
-  outputValue,
-  repathCommandTree,
-  resolveAllCommands,
-  resolveCommand,
-  resolveProgressMessage,
-  runPluginChain,
-  suggestSimilar,
-  thenMaybe,
-  warnIfUnexpectedAsync,
-  withDrain,
-  withPromiseDrain,
-  wrapWithLifecycle,
-} from './command-utils.ts';
-import type { ShellType } from './completion.ts';
-import { ConfigError, RoutingError, ValidationError } from './errors.ts';
-import { generateHelp } from './help.ts';
-import { promptInteractiveFields } from './interactive.ts';
-import { getNestedValue, parseCliInputToParts, setNestedValue } from './parse.ts';
-import { createReplIterator } from './repl-loop.ts';
-import { type PadroneProgressIndicator, resolveStdin, resolveStdinAlways } from './runtime.ts';
-import { createStdinStream } from './stream.ts';
-import type {
-  AnyPadroneCommand,
-  AnyPadroneProgram,
-  PadroneActionContext,
-  PadroneAPI,
-  PadroneCommand,
-  PadroneEvalPreferences,
-  PadronePlugin,
-  PadroneProgram,
-  PadroneReplPreferences,
-  PluginExecuteContext,
-  PluginExecuteResult,
-  PluginParseContext,
-  PluginParseResult,
-  PluginValidateContext,
-  PluginValidateResult,
-} from './types.ts';
-import { getVersion } from './utils.ts';
-import { createWrapHandler } from './wrap.ts';
-
-export { asyncSchema, buildReplCompleter } from './command-utils.ts';
-
-export function createPadrone<TProgramName extends string>(name: TProgramName): PadroneProgram<TProgramName, '', ''> {
-  return createPadroneBuilder({ name, path: '', commands: [] } as any) as unknown as PadroneProgram<TProgramName, '', ''>;
-}
-
-export function createPadroneBuilder<TBuilder extends PadroneProgram = PadroneProgram>(
-  inputCommand: AnyPadroneCommand,
-): TBuilder & { [commandSymbol]: AnyPadroneCommand } {
-  // Re-parent direct subcommands so getCommandRuntime walks to the current root,
-  // not a stale parent from before .runtime()/.configure()/etc.
-  const existingCommand =
-    inputCommand.commands?.length && inputCommand.commands.some((c) => c.parent && c.parent !== inputCommand)
-      ? {
-          ...inputCommand,
-          commands: inputCommand.commands.map((c) => (c.parent && c.parent !== inputCommand ? { ...c, parent: inputCommand } : c)),
-        }
-      : inputCommand;
-
-  /** Creates the action context passed to command handlers. References `builder` which is defined later but only called at runtime. */
-  const createActionContext = (cmd: AnyPadroneCommand): PadroneActionContext => {
-    return {
-      runtime: getCommandRuntime(cmd),
-      command: cmd,
-      program: builder as any,
-      progress: noopIndicator,
-    };
-  };
-
-  const find: AnyPadroneProgram['find'] = (command) => {
-    if (typeof command !== 'string') return findCommandByName(command.path, existingCommand.commands) as any;
-    return findCommandByName(command, existingCommand.commands) as any;
-  };
-
-  /**
-   * Parses CLI input to find the command and extract raw arguments without validation.
-   */
-  const parseCommand = (input: string | undefined) => {
-    input ??= getCommandRuntime(existingCommand).argv().join(' ') || undefined;
-    if (!input) {
-      // No input: check for default '' command
-      const defaultCommand = findCommandByName('', existingCommand.commands);
-      if (defaultCommand) {
-        return { command: defaultCommand, rawArgs: {} as Record<string, unknown>, args: [] as string[], unmatchedTerms: [] as string[] };
-      }
-      return { command: existingCommand, rawArgs: {} as Record<string, unknown>, args: [] as string[], unmatchedTerms: [] as string[] };
-    }
-
-    const parts = parseCliInputToParts(input);
-
-    const terms = parts.filter((p) => p.type === 'term').map((p) => p.value);
-    const args = parts.filter((p) => p.type === 'arg').map((p) => p.value);
-
-    let curCommand: AnyPadroneCommand | undefined = existingCommand;
-    let unmatchedTerms: string[] = [];
-
-    // If the first term is the program name, skip it
-    if (terms[0] === existingCommand.name) terms.shift();
-
-    for (let i = 0; i < terms.length; i++) {
-      const term = terms[i] || '';
-      const found = findCommandByName(term, curCommand.commands);
-
-      if (found) {
-        curCommand = found;
-      } else {
-        unmatchedTerms = terms.slice(i);
-        args.unshift(...unmatchedTerms);
-        break;
-      }
-    }
-
-    // If no unmatched terms remain, check for a default '' subcommand.
-    // This handles both the root level (no input) and nested commands (e.g., "advanced" with a '' subcommand).
-    if (unmatchedTerms.length === 0 && curCommand.commands?.length) {
-      const defaultCommand = findCommandByName('', curCommand.commands);
-      if (defaultCommand) {
-        curCommand = defaultCommand;
-      }
-    }
-
-    if (!curCommand) return { command: existingCommand, rawArgs: {} as Record<string, unknown>, args, unmatchedTerms };
-
-    // Extract argument metadata from the nested arguments object in meta
-    const argsMeta = curCommand.meta?.fields;
-    const schemaMetadata = curCommand.argsSchema
-      ? extractSchemaMetadata(curCommand.argsSchema, argsMeta, curCommand.meta?.autoAlias)
-      : { flags: {}, aliases: {} };
-    const { flags, aliases } = schemaMetadata;
-
-    // Get array arguments from schema (arrays are always variadic)
-    const arrayArguments = new Set<string>();
-    if (curCommand.argsSchema) {
-      try {
-        const jsonSchema = curCommand.argsSchema['~standard'].jsonSchema.input(JSON_SCHEMA_OPTS) as Record<string, any>;
-        if (jsonSchema.type === 'object' && jsonSchema.properties) {
-          for (const [key, prop] of Object.entries(jsonSchema.properties as Record<string, any>)) {
-            if (prop?.type === 'array') arrayArguments.add(key);
-          }
-        }
-      } catch {
-        // Ignore schema parsing errors
-      }
-    }
-
-    const argParts = parts.filter((p) => p.type === 'named' || p.type === 'alias');
-    const rawArgs: Record<string, unknown> = {};
-
-    for (const arg of argParts) {
-      // Resolve flags (single-char, from alias parts: -v) and aliases (multi-char, from named parts: --dry-run)
-      let key: string[];
-      if (arg.type === 'alias' && arg.key.length === 1 && flags[arg.key[0]!]) {
-        key = [flags[arg.key[0]!]!];
-      } else if (arg.type === 'named' && arg.key.length === 1 && aliases[arg.key[0]!]) {
-        key = [aliases[arg.key[0]!]!];
-      } else {
-        key = arg.key;
-      }
-
-      const rootKey = key[0]!;
-
-      // Handle negated boolean arguments (--no-verbose)
-      if (arg.type === 'named' && arg.negated) {
-        setNestedValue(rawArgs, key, false);
-        continue;
-      }
-
-      const value = arg.value ?? true;
-
-      // Handle array arguments - accumulate values into arrays (arrays are always variadic)
-      if (arrayArguments.has(rootKey)) {
-        const existing = getNestedValue(rawArgs, key);
-        if (existing !== undefined) {
-          if (Array.isArray(existing)) {
-            if (Array.isArray(value)) {
-              existing.push(...value);
-            } else {
-              existing.push(value);
-            }
-          } else {
-            if (Array.isArray(value)) {
-              setNestedValue(rawArgs, key, [existing, ...value]);
-            } else {
-              setNestedValue(rawArgs, key, [existing, value]);
-            }
-          }
-        } else {
-          setNestedValue(rawArgs, key, Array.isArray(value) ? value : [value]);
-        }
-      } else {
-        setNestedValue(rawArgs, key, value);
-      }
-    }
-
-    return { command: curCommand, rawArgs, args, unmatchedTerms };
-  };
-
-  /**
-   * Preprocesses raw arguments: applies env/config values and maps positional arguments.
-   * Also performs auto-coercion (string→number/boolean) and unknown arg detection.
-   */
-  const buildCommandArgs = (
-    command: AnyPadroneCommand,
-    rawArgs: Record<string, unknown>,
-    args: string[],
-    context?: { stdinData?: Record<string, unknown>; envData?: Record<string, unknown>; configData?: Record<string, unknown> },
-  ): Record<string, unknown> => {
-    // Apply preprocessing (stdin, env, and config bindings)
-    let preprocessedArgs = preprocessArgs(rawArgs, {
-      flags: {}, // Already resolved in parseCommand
-      aliases: {}, // Already resolved in parseCommand
-      stdinData: context?.stdinData,
-      envData: context?.envData,
-      configData: context?.configData,
-    });
-
-    // Parse positional configuration
-    const positionalConfig = command.meta?.positional ? parsePositionalConfig(command.meta.positional) : [];
-
-    // Map positional arguments to their named arguments
-    if (positionalConfig.length > 0) {
-      let argIndex = 0;
-      for (let i = 0; i < positionalConfig.length; i++) {
-        const { name, variadic } = positionalConfig[i]!;
-        if (argIndex >= args.length) break;
-
-        if (variadic) {
-          // Collect remaining args (but leave room for non-variadic args after)
-          const remainingPositionals = positionalConfig.slice(i + 1);
-          const nonVariadicAfter = remainingPositionals.filter((p) => !p.variadic).length;
-          const variadicEnd = args.length - nonVariadicAfter;
-          preprocessedArgs[name] = args.slice(argIndex, variadicEnd);
-          argIndex = variadicEnd;
-        } else if (i === positionalConfig.length - 1 && args.length > argIndex + 1) {
-          // Last non-variadic positional: join all remaining tokens (e.g. `-- Hello world` → "Hello world")
-          preprocessedArgs[name] = args.slice(argIndex).join(' ');
-          argIndex = args.length;
-        } else {
-          preprocessedArgs[name] = args[argIndex];
-          argIndex++;
-        }
-      }
-    }
-
-    // Auto-coerce CLI string values to match schema types (string→number, string→boolean)
-    if (command.argsSchema) {
-      preprocessedArgs = coerceArgs(preprocessedArgs, command.argsSchema);
-    }
-
-    return preprocessedArgs;
-  };
-
-  /**
-   * Detects unknown options in args that aren't defined in the schema.
-   * Returns unknown key info with suggestions, or empty array if schema is loose.
-   */
-  const checkUnknownArgs = (
-    command: AnyPadroneCommand,
-    preprocessedArgs: Record<string, unknown>,
-  ): { key: string; suggestion: string }[] => {
-    if (!command.argsSchema) return [];
-
-    const argsMeta = command.meta?.fields;
-    const { flags, aliases } = extractSchemaMetadata(command.argsSchema, argsMeta, command.meta?.autoAlias);
-
-    return detectUnknownArgs(preprocessedArgs, command.argsSchema, flags, aliases, suggestSimilar);
-  };
-
-  /**
-   * Validates preprocessed arguments against the command's schema.
-   * First checks for unknown args (strict by default), then runs schema validation.
-   * Returns sync or async result depending on the schema's validate method.
-   */
-  const validateCommandArgs = (command: AnyPadroneCommand, preprocessedArgs: Record<string, unknown>) => {
-    // Check for unknown args before schema validation (strict by default)
-    const unknownArgs = checkUnknownArgs(command, preprocessedArgs);
-    if (unknownArgs.length > 0) {
-      const issues: StandardSchemaV1.Issue[] = unknownArgs.map(({ key, suggestion }) => ({
-        path: [key],
-        message: suggestion ? `Unknown option: "${key}". ${suggestion}` : `Unknown option: "${key}"`,
-      }));
-      return { args: undefined, argsResult: { issues } as any };
-    }
-
-    const argsParsed = command.argsSchema ? command.argsSchema['~standard'].validate(preprocessedArgs) : { value: preprocessedArgs };
-
-    // Return undefined for args when there's no schema and no meaningful args
-    const hasArgs = command.argsSchema || Object.keys(preprocessedArgs).length > 0;
-
-    const buildResult = (parsed: StandardSchemaV1.Result<unknown>) => ({
-      args: parsed.issues ? undefined : hasArgs ? (parsed.value as any) : undefined,
-      argsResult: parsed as any,
-    });
-
-    return thenMaybe(argsParsed, buildResult);
-  };
-
-  /**
-   * Preprocesses and validates raw arguments against the command's schema.
-   * Returns sync or async result depending on the schema's validate method.
-   */
-  const validateArgs = (
-    command: AnyPadroneCommand,
-    rawArgs: Record<string, unknown>,
-    args: string[],
-    context?: { stdinData?: Record<string, unknown>; envData?: Record<string, unknown>; configData?: Record<string, unknown> },
-  ) => {
-    const preprocessedArgs = buildCommandArgs(command, rawArgs, args, context);
-    return validateCommandArgs(command, preprocessedArgs);
-  };
-
-  const parse: AnyPadroneProgram['parse'] = (input) => {
-    const state: Record<string, unknown> = {};
-
-    // Parse phase (with plugins)
-    const parseCtx: PluginParseContext = { input: input as string | undefined, command: existingCommand, state };
-    const coreParse = (): PluginParseResult => {
-      const { command, rawArgs, args } = parseCommand(parseCtx.input);
-      return { command, rawArgs, positionalArgs: args };
-    };
-
-    // Parse phase: root plugins only
-    const rootPlugins = existingCommand.plugins ?? [];
-    const parsedOrPromise = runPluginChain('parse', rootPlugins, parseCtx, coreParse);
-
-    const continueAfterParse = (parsed: PluginParseResult) => {
-      const { command } = parsed;
-
-      // Validate phase: collected from parent chain
-      const commandPlugins = collectPlugins(command);
-      const validateCtx: PluginValidateContext = {
-        command,
-        rawArgs: parsed.rawArgs,
-        positionalArgs: parsed.positionalArgs,
-        state,
-      };
-
-      const coreValidate = (): PluginValidateResult | Promise<PluginValidateResult> => {
-        // Resolve env schema: command's own envSchema > inherited from parent/root
-        const resolveEnvSchema = (cmd: AnyPadroneCommand): AnyPadroneCommand['envSchema'] => {
-          if (cmd.envSchema !== undefined) return cmd.envSchema;
-          if (cmd.parent) return resolveEnvSchema(cmd.parent);
-          return undefined;
-        };
-        const envSchema = resolveEnvSchema(command);
-
-        const readStdinForParse = (): Record<string, unknown> | Promise<Record<string, unknown>> => {
-          const stdinConfig = command.meta?.stdin;
-          if (!stdinConfig) return {};
-
-          const field = parseStdinConfig(stdinConfig);
-
-          // Skip if the field was already provided via CLI flags
-          if (field in validateCtx.rawArgs && validateCtx.rawArgs[field] !== undefined) return {};
-
-          const runtime = getCommandRuntime(existingCommand);
-
-          const streamInfo = isAsyncStreamField(command.argsSchema, field);
-          if (streamInfo) {
-            // Async stream: always resolve stdin (even on TTY) for interactive use
-            const stdinForStream = resolveStdinAlways(runtime as any);
-            return { [field]: createStdinStream(stdinForStream, streamInfo.itemSchema) };
-          }
-
-          const stdin = resolveStdin(runtime as any);
-          if (!stdin) return {};
-
-          if (isArrayField(command.argsSchema, field)) {
-            return (async () => {
-              const lines: string[] = [];
-              for await (const line of stdin.lines()) {
-                lines.push(line);
-              }
-              return { [field]: lines };
-            })();
-          }
-          return stdin.text().then((text) => (text ? { [field]: text } : {}));
-        };
-
-        const finalize = (
-          envData: Record<string, unknown> | undefined,
-          stdinData: Record<string, unknown> | undefined,
-        ): PluginValidateResult | Promise<PluginValidateResult> => {
-          const validated = validateArgs(command, validateCtx.rawArgs, validateCtx.positionalArgs, { stdinData, envData });
-          return thenMaybe(validated, (v) => v as PluginValidateResult);
-        };
-
-        let envData: Record<string, unknown> | undefined;
-        const afterEnv = (envResult: Record<string, unknown> | undefined) => {
-          const stdinDataOrPromise = readStdinForParse();
-          return thenMaybe(stdinDataOrPromise, (stdinData) => {
-            const hasStdinData = Object.keys(stdinData).length > 0;
-            return finalize(envResult, hasStdinData ? stdinData : undefined);
-          });
-        };
-
-        if (envSchema) {
-          const runtime = getCommandRuntime(existingCommand);
-          const rawEnv = runtime.env();
-          const envValidated = envSchema['~standard'].validate(rawEnv);
-
-          return thenMaybe(envValidated, (result) => {
-            if (!result.issues) {
-              envData = result.value as unknown as Record<string, unknown>;
-            }
-            return afterEnv(envData);
-          });
-        }
-
-        return afterEnv(envData);
-      };
-
-      const validatedOrPromise = runPluginChain('validate', commandPlugins, validateCtx, coreValidate);
-
-      return warnIfUnexpectedAsync(
-        thenMaybe(validatedOrPromise, (v) => ({
-          command: command as any,
-          args: v.args,
-          argsResult: v.argsResult,
-        })),
-        command,
-      );
-    };
-
-    return makeThenable(thenMaybe(parsedOrPromise, continueAfterParse)) as any;
-  };
-
-  const stringify: AnyPadroneProgram['stringify'] = (command = '' as any, args) => {
-    const commandObj = typeof command === 'string' ? findCommandByName(command, existingCommand.commands) : (command as AnyPadroneCommand);
-    if (!commandObj) throw new RoutingError(`Command "${command ?? ''}" not found`);
-
-    const parts: string[] = [];
-
-    if (commandObj.path) parts.push(commandObj.path);
-
-    // Get positional config to determine which args are positional
-    const positionalConfig = commandObj.meta?.positional ? parsePositionalConfig(commandObj.meta.positional) : [];
-    const positionalNames = new Set(positionalConfig.map((p) => p.name));
-
-    // Output positional arguments first in order
-    if (args && typeof args === 'object') {
-      for (const { name, variadic } of positionalConfig) {
-        const value = (args as Record<string, unknown>)[name];
-        if (value === undefined) continue;
-
-        if (variadic && Array.isArray(value)) {
-          for (const v of value) {
-            const vStr = String(v);
-            if (vStr.includes(' ')) parts.push(`"${vStr}"`);
-            else parts.push(vStr);
-          }
-        } else {
-          const argStr = String(value);
-          if (argStr.includes(' ')) parts.push(`"${argStr}"`);
-          else parts.push(argStr);
-        }
-      }
-
-      // Helper to stringify a value with a given key prefix
-      const stringifyValue = (key: string, value: unknown) => {
-        if (value === undefined) return;
-
-        if (typeof value === 'boolean') {
-          if (value) parts.push(`--${key}`);
-          else parts.push(`--no-${key}`);
-        } else if (Array.isArray(value)) {
-          // Handle variadic arguments - output each value separately
-          for (const v of value) {
-            const vStr = String(v);
-            if (vStr.includes(' ')) parts.push(`--${key}="${vStr}"`);
-            else parts.push(`--${key}=${vStr}`);
-          }
-        } else if (typeof value === 'object' && value !== null) {
-          // Handle nested objects - convert to dot notation
-          for (const [nestedKey, nestedValue] of Object.entries(value)) {
-            stringifyValue(`${key}.${nestedKey}`, nestedValue);
-          }
-        } else if (typeof value === 'string') {
-          if (value.includes(' ')) parts.push(`--${key}="${value}"`);
-          else parts.push(`--${key}=${value}`);
-        } else {
-          parts.push(`--${key}=${value}`);
-        }
-      };
-
-      // Output remaining arguments (non-positional)
-      for (const [key, value] of Object.entries(args)) {
-        if (value === undefined || positionalNames.has(key)) continue;
-        stringifyValue(key, value);
-      }
-    }
-
-    return parts.join(' ');
-  };
-
-  type DetailLevel = 'minimal' | 'standard' | 'full';
-  type FormatLevel = 'text' | 'ansi' | 'console' | 'markdown' | 'html' | 'json' | 'auto';
-
-  /**
-   * Check if help, version, or completion flags/commands are present in the input.
-   * Returns the appropriate action to take, or null if normal execution should proceed.
-   */
-  const checkBuiltinCommands = (
-    input: string | undefined,
-  ):
-    | { type: 'help'; command?: AnyPadroneCommand; detail?: DetailLevel; format?: FormatLevel; all?: boolean }
-    | { type: 'version' }
-    | { type: 'completion'; shell?: ShellType; setup?: boolean }
-    | { type: 'man'; setup?: boolean; remove?: boolean }
-    | { type: 'repl'; scope?: string }
-    | { type: 'mcp'; transport?: 'http' | 'stdio'; port?: number; host?: string; basePath?: string }
-    | { type: 'serve'; port?: number; host?: string; basePath?: string }
-    | null => {
-    if (!input) return null;
-
-    const parts = parseCliInputToParts(input);
-    const terms = parts.filter((p) => p.type === 'term').map((p) => p.value);
-    const args = parts.filter((p) => p.type === 'named' || p.type === 'alias');
-
-    // Helper to check if a key array matches a single key string
-    const keyIs = (key: string[], name: string) => key.length === 1 && key[0] === name;
-
-    // Check for --help, -h flags (these take precedence over commands)
-    const hasHelpFlag = args.some((p) => (p.type === 'named' && keyIs(p.key, 'help')) || (p.type === 'alias' && keyIs(p.key, 'h')));
-
-    // Extract detail level from --detail[=<level>] or -d [<level>]
-    // Bare --detail (no value) defaults to 'full'
-    const getDetailLevel = (): DetailLevel | undefined => {
-      for (const arg of args) {
-        if (arg.type === 'named' && keyIs(arg.key, 'detail')) {
-          if (typeof arg.value === 'string' && (arg.value === 'minimal' || arg.value === 'standard' || arg.value === 'full')) {
-            return arg.value;
-          }
-          return 'full';
-        }
-        if (arg.type === 'alias' && keyIs(arg.key, 'd')) {
-          if (typeof arg.value === 'string' && (arg.value === 'minimal' || arg.value === 'standard' || arg.value === 'full')) {
-            return arg.value;
-          }
-          return 'full';
-        }
-      }
-      return undefined;
-    };
-    const detail = getDetailLevel();
-
-    // Extract format from --format=<value> or -f <value>
-    const getFormat = (): FormatLevel | undefined => {
-      const validFormats: FormatLevel[] = ['text', 'ansi', 'console', 'markdown', 'html', 'json', 'auto'];
-      for (const arg of args) {
-        if (arg.type === 'named' && keyIs(arg.key, 'format') && typeof arg.value === 'string') {
-          if (validFormats.includes(arg.value as FormatLevel)) {
-            return arg.value as FormatLevel;
-          }
-        }
-        if (arg.type === 'alias' && keyIs(arg.key, 'f') && typeof arg.value === 'string') {
-          if (validFormats.includes(arg.value as FormatLevel)) {
-            return arg.value as FormatLevel;
-          }
-        }
-      }
-      return undefined;
-    };
-    const format = getFormat();
-
-    // Check for --all flag (show all built-in help)
-    const hasAllFlag = args.some((p) => p.type === 'named' && keyIs(p.key, 'all'));
-
-    // Check for --version, -v, -V flags
-    const hasVersionFlag = args.some(
-      (p) => (p.type === 'named' && keyIs(p.key, 'version')) || (p.type === 'alias' && (keyIs(p.key, 'v') || keyIs(p.key, 'V'))),
-    );
-
-    // If the first term is the program name, skip it
-    const normalizedTerms = [...terms];
-    if (normalizedTerms[0] === existingCommand.name) normalizedTerms.shift();
-
-    // Check if user has defined 'help', 'version', or 'completion' commands (they take precedence)
-    const userHelpCommand = findCommandByName('help', existingCommand.commands);
-    const userVersionCommand = findCommandByName('version', existingCommand.commands);
-    const userCompletionCommand = findCommandByName('completion', existingCommand.commands);
-
-    // Check for 'help' command (only if user hasn't defined one)
-    // Supports both 'help <command>' and '<command> help' forms
-    if (!userHelpCommand && normalizedTerms[0] === 'help') {
-      // help <command> - get help for specific command
-      const commandName = normalizedTerms.slice(1).join(' ');
-      const targetCommand = commandName ? findCommandByName(commandName, existingCommand.commands) : undefined;
-      return { type: 'help', command: targetCommand, detail, format, all: hasAllFlag || undefined };
-    }
-    if (!userHelpCommand && normalizedTerms.length > 0 && normalizedTerms[normalizedTerms.length - 1] === 'help') {
-      // <command> help - get help for specific command (trailing form)
-      const commandTerms = normalizedTerms.slice(0, -1);
-      // Walk the command tree to find the deepest matching command
-      let targetCommand: AnyPadroneCommand | undefined;
-      let current = existingCommand;
-      for (const term of commandTerms) {
-        const found = findCommandByName(term, current.commands);
-        if (found) {
-          targetCommand = found;
-          current = found;
-        } else {
-          break;
-        }
-      }
-      return { type: 'help', command: targetCommand, detail, format, all: hasAllFlag || undefined };
-    }
-
-    // Check for 'version' command (only if user hasn't defined one)
-    if (!userVersionCommand && normalizedTerms[0] === 'version') {
-      return { type: 'version' };
-    }
-
-    // Check for 'completion' command (only if user hasn't defined one)
-    if (!userCompletionCommand && normalizedTerms[0] === 'completion') {
-      const shellArg = normalizedTerms[1] as ShellType | undefined;
-      const validShells: ShellType[] = ['bash', 'zsh', 'fish', 'powershell'];
-      const shell = shellArg && validShells.includes(shellArg) ? shellArg : undefined;
-      const setup = args.some((p) => p.type === 'named' && keyIs(p.key, 'setup'));
-      return { type: 'completion', shell, setup };
-    }
-
-    // Check for 'man' command (only if user hasn't defined one)
-    const userManCommand = findCommandByName('man', existingCommand.commands);
-    if (!userManCommand && normalizedTerms[0] === 'man') {
-      const setup = args.some((p) => p.type === 'named' && keyIs(p.key, 'setup'));
-      const remove = args.some((p) => p.type === 'named' && keyIs(p.key, 'remove'));
-      return { type: 'man', setup, remove };
-    }
-
-    // Handle help flag - find the command being requested
-    if (hasHelpFlag) {
-      // Filter out help-related terms and flags to find the target command
-      const commandTerms = normalizedTerms.filter((t) => t !== 'help');
-      const commandName = commandTerms.join(' ');
-      const targetCommand = commandName ? findCommandByName(commandName, existingCommand.commands) : undefined;
-      return { type: 'help', command: targetCommand, detail, format, all: hasAllFlag || undefined };
-    }
-
-    // Handle version flag (only for root command, i.e., no subcommand terms)
-    if (hasVersionFlag && normalizedTerms.length === 0) {
-      return { type: 'version' };
-    }
-
-    // Check for 'mcp' command (only if user hasn't defined one)
-    const userMcpCommand = findCommandByName('mcp', existingCommand.commands);
-    if (!userMcpCommand && normalizedTerms[0] === 'mcp') {
-      const transportArg = normalizedTerms[1];
-      const transport = transportArg === 'stdio' || transportArg === 'http' ? transportArg : undefined;
-      const portArg = args.find((p) => p.type === 'named' && keyIs(p.key, 'port'));
-      const port = typeof portArg?.value === 'string' ? parseInt(portArg.value, 10) : undefined;
-      const hostArg = args.find((p) => p.type === 'named' && keyIs(p.key, 'host'));
-      const host = typeof hostArg?.value === 'string' ? hostArg.value : undefined;
-      const basePathArg = args.find((p) => p.type === 'named' && keyIs(p.key, 'base-path'));
-      const mcpBasePath = typeof basePathArg?.value === 'string' ? basePathArg.value : undefined;
-      return { type: 'mcp', transport, port: port && !Number.isNaN(port) ? port : undefined, host, basePath: mcpBasePath };
-    }
-
-    // Check for 'serve' command (only if user hasn't defined one)
-    const userServeCommand = findCommandByName('serve', existingCommand.commands);
-    if (!userServeCommand && normalizedTerms[0] === 'serve') {
-      const portArg = args.find((p) => p.type === 'named' && keyIs(p.key, 'port'));
-      const port = typeof portArg?.value === 'string' ? parseInt(portArg.value, 10) : undefined;
-      const hostArg = args.find((p) => p.type === 'named' && keyIs(p.key, 'host'));
-      const host = typeof hostArg?.value === 'string' ? hostArg.value : undefined;
-      const basePathArg = args.find((p) => p.type === 'named' && keyIs(p.key, 'base-path'));
-      const basePath = typeof basePathArg?.value === 'string' ? basePathArg.value : undefined;
-      return { type: 'serve', port: port && !Number.isNaN(port) ? port : undefined, host, basePath };
-    }
-
-    // Check for --repl flag
-    const hasReplFlag = args.some((p) => p.type === 'named' && keyIs(p.key, 'repl'));
-    if (hasReplFlag) {
-      const scope = normalizedTerms.length > 0 ? normalizedTerms.join(' ') : undefined;
-      return { type: 'repl', scope };
-    }
-
-    return null;
-  };
-
-  /**
-   * Extract the config file path from --config=<path> or -c <path> flags.
-   */
-  const extractConfigPath = (input: string | undefined): string | undefined => {
-    if (!input) return undefined;
-
-    const parts = parseCliInputToParts(input);
-    const args = parts.filter((p) => p.type === 'named' || p.type === 'alias');
-
-    for (const arg of args) {
-      if (arg.type === 'named' && arg.key.length === 1 && arg.key[0] === 'config' && typeof arg.value === 'string') {
-        return arg.value;
-      }
-      if (arg.type === 'alias' && arg.key.length === 1 && arg.key[0] === 'c' && typeof arg.value === 'string') {
-        return arg.value;
-      }
-    }
-    return undefined;
-  };
-
-  /**
-   * Extract --color flag from input.
-   * - `--color` or `--color=true` → use default theme
-   * - `--color=false` or `--no-color` → disable colors (text format)
-   * - `--color=<theme>` → use the named theme
-   * Returns `undefined` if no --color flag is present.
-   */
-  const extractColorFlag = (input: string | undefined): { theme?: ColorTheme | ColorConfig; disableColor?: boolean } | undefined => {
-    if (!input) return undefined;
-
-    const parts = parseCliInputToParts(input);
-    const args = parts.filter((p) => p.type === 'named');
-    const keyIs = (key: string[], name: string) => key.length === 1 && key[0] === name;
-
-    for (const arg of args) {
-      if (arg.type === 'named' && keyIs(arg.key, 'no-color')) {
-        return { disableColor: true };
-      }
-      if (arg.type === 'named' && keyIs(arg.key, 'color')) {
-        if (arg.negated) return { disableColor: true };
-        if (arg.value === undefined || arg.value === 'true') return { theme: 'default' };
-        if (arg.value === 'false') return { disableColor: true };
-        if (typeof arg.value === 'string' && arg.value in colorThemes) return { theme: arg.value as ColorTheme };
-        return undefined;
-      }
-    }
-    return undefined;
-  };
-
-  /**
-   * Core execution logic shared by eval() and cli().
-   * errorMode controls validation error behavior:
-   * - 'soft': return result with issues (eval behavior)
-   * - 'hard': print error + help and throw (cli-without-input behavior)
-   */
-  const execCommand = (resolvedInput: string | undefined, evalOptions?: PadroneEvalPreferences, errorMode: 'soft' | 'hard' = 'soft') => {
-    const baseRuntime = getCommandRuntime(existingCommand);
-    let runtime = evalOptions?.runtime
-      ? Object.assign({}, baseRuntime, Object.fromEntries(Object.entries(evalOptions.runtime).filter(([, v]) => v !== undefined)))
-      : baseRuntime;
-
-    // Apply --color / --no-color flag to runtime
-    const colorFlag = extractColorFlag(resolvedInput);
-    if (colorFlag) {
-      runtime = {
-        ...runtime,
-        ...(colorFlag.disableColor ? { format: 'text' as const, theme: undefined } : { theme: colorFlag.theme }),
-      };
-    }
-
-    // Check for built-in help/version/completion commands and flags (bypass plugins)
-    const builtin = checkBuiltinCommands(resolvedInput);
-
-    if (builtin) {
-      if (builtin.type === 'help') {
-        resolveAllCommands(existingCommand);
-        const helpText = generateHelp(existingCommand, builtin.command ?? existingCommand, {
-          detail: builtin.detail,
-          format: builtin.format ?? runtime.format,
-          theme: runtime.theme,
-          all: builtin.all,
-        });
-        runtime.output(helpText);
-        return withDrain({
-          command: existingCommand,
-          args: undefined,
-          result: helpText,
-        }) as any;
-      }
-
-      if (builtin.type === 'version') {
-        const version = getVersion(existingCommand.version);
-        runtime.output(version);
-        return withDrain({
-          command: existingCommand,
-          args: undefined,
-          result: version,
-        }) as any;
-      }
-
-      if (builtin.type === 'completion') {
-        resolveAllCommands(existingCommand);
-        return import('./completion.ts').then(({ detectShell, generateCompletionOutput, setupCompletions }) => {
-          if (builtin.setup) {
-            const shell = builtin.shell ?? detectShell();
-            if (!shell) {
-              throw new Error('Could not detect shell. Specify one: completion bash --setup');
-            }
-            const result = setupCompletions(existingCommand.name, shell);
-            const message = `${result.updated ? 'Updated' : 'Added'} ${existingCommand.name} completions in ${result.file}`;
-            runtime.output(message);
-            return withDrain({
-              command: existingCommand,
-              args: undefined,
-              result: message,
-            });
-          }
-          const completionScript = generateCompletionOutput(existingCommand, builtin.shell);
-          runtime.output(completionScript);
-          return withDrain({
-            command: existingCommand,
-            args: undefined,
-            result: completionScript,
-          });
-        }) as any;
-      }
-
-      if (builtin.type === 'man') {
-        resolveAllCommands(existingCommand);
-        return import('./docs/index.ts').then(({ setupManPages, removeManPages, generateDocs }) => {
-          if (builtin.setup) {
-            const result = setupManPages(existingCommand);
-            const message = `${result.updated ? 'Updated' : 'Installed'} ${result.written.length} man page(s) in ${result.dir}`;
-            runtime.output(message);
-            return withDrain({
-              command: existingCommand,
-              args: undefined,
-              result: message,
-            });
-          }
-          if (builtin.remove) {
-            const result = removeManPages(existingCommand);
-            const message =
-              result.removed.length > 0
-                ? `Removed ${result.removed.length} man page(s) from ${result.dir}`
-                : 'No man pages found to remove.';
-            runtime.output(message);
-            return withDrain({
-              command: existingCommand,
-              args: undefined,
-              result: message,
-            });
-          }
-          // Default: generate man page for the root command and print it
-          const result = generateDocs(existingCommand, { format: 'man' });
-          const manPage = result.pages[0]?.content ?? '';
-          runtime.output(manPage);
-          return withDrain({
-            command: existingCommand,
-            args: undefined,
-            result: manPage,
-          });
-        }) as any;
-      }
-    }
-
-    // Shared plugin state for this execution
-    const state: Record<string, unknown> = {};
-    const rootPlugins = existingCommand.plugins ?? [];
-
-    const runPipeline = () => {
-      // ── Phase 1: Parse ──────────────────────────────────────────────────
-      const parseCtx: PluginParseContext = { input: resolvedInput, command: existingCommand, state };
-
-      const coreParse = (): PluginParseResult => {
-        const { command, rawArgs, args, unmatchedTerms } = parseCommand(parseCtx.input);
-
-        // Default help: command with no action → show its help when there's nothing to execute.
-        const hasSubcommands = command.commands && command.commands.length > 0;
-        const hasSchema = command.argsSchema != null;
-        if (!command.action && (hasSubcommands || !hasSchema) && unmatchedTerms.length === 0) {
-          resolveAllCommands(existingCommand);
-          const helpText = generateHelp(existingCommand, command, { format: runtime.format, theme: runtime.theme });
-          runtime.output(helpText);
-          return {
-            command: command,
-            rawArgs: { '~help': helpText } as Record<string, unknown>,
-            positionalArgs: [],
-          };
-        }
-
-        // Reject unmatched terms when the matched command doesn't accept positional args
-        if (unmatchedTerms.length > 0) {
-          const hasPositionalConfig = command.meta?.positional && command.meta.positional.length > 0;
-          if (!hasPositionalConfig) {
-            const isRootCommand = command === existingCommand;
-            const commandDisplayName = command.name || command.aliases?.[0] || command.path || '(default)';
-
-            // Collect candidate names for fuzzy suggestion
-            const candidateNames: string[] = [];
-            if (isRootCommand && existingCommand.commands) {
-              for (const cmd of existingCommand.commands) {
-                if (!cmd.hidden) {
-                  candidateNames.push(cmd.name);
-                  if (cmd.aliases) candidateNames.push(...cmd.aliases);
-                }
-              }
-            } else if (command.commands) {
-              for (const cmd of command.commands) {
-                if (!cmd.hidden) {
-                  candidateNames.push(cmd.name);
-                  if (cmd.aliases) candidateNames.push(...cmd.aliases);
-                }
-              }
-            }
-
-            const suggestion = suggestSimilar(unmatchedTerms[0]!, candidateNames);
-            const suggestions = suggestion ? [suggestion] : [];
-            const baseMsg = isRootCommand
-              ? `Unknown command: ${unmatchedTerms[0]}`
-              : `Unexpected arguments for '${commandDisplayName}': ${unmatchedTerms.join(' ')}`;
-            const errorMsg = suggestions.length ? `${baseMsg}\n\n  ${suggestions[0]}` : baseMsg;
-
-            if (errorMode === 'hard') {
-              runtime.error(errorMsg);
-              // When we have a suggestion, show a compact single-line "Available commands" note
-              // instead of the full help text to avoid overwhelming the user
-              if (suggestions.length > 0) {
-                const targetCmd = isRootCommand ? existingCommand : command;
-                const visibleCommands = (targetCmd.commands ?? []).filter((c) => !c.hidden && c.name);
-                if (visibleCommands.length > 0) {
-                  const cmdList = visibleCommands.map((c) => c.name).join(', ');
-                  runtime.output(`\nAvailable commands: ${cmdList}`);
-                }
-              } else {
-                resolveAllCommands(existingCommand);
-                const helpText = generateHelp(existingCommand, isRootCommand ? existingCommand : command, {
-                  format: runtime.format,
-                  theme: runtime.theme,
-                });
-                runtime.error(helpText);
-              }
-              throw new RoutingError(errorMsg, { suggestions, command: command.path || command.name });
-            }
-
-            // Soft mode: throw too — this is a routing error, not a validation issue
-            throw new RoutingError(errorMsg, { suggestions, command: command.path || command.name });
-          }
-        }
-
-        return { command, rawArgs, positionalArgs: args };
-      };
-
-      // Parse phase: root plugins only
-      const parsedOrPromise = runPluginChain('parse', rootPlugins, parseCtx, coreParse);
-
-      // ── Phases 2 & 3 chained after parse ────────────────────────────────
-      const continueAfterParse = (parsed: PluginParseResult) => {
-        const { command } = parsed;
-        // Validate/execute: collected from parent chain
-        const commandPlugins = collectPlugins(command);
-
-        // Short-circuit: parse returned a help result
-        if (parsed.rawArgs['~help']) {
-          return {
-            command: command,
-            args: undefined,
-            result: parsed.rawArgs['~help'],
-          } as any;
-        }
-
-        // ── Auto-progress: start before validation ───────────────────────
-        const progressConfig = command.progress;
-        if (progressConfig && runtime.progress) {
-          const isObj = typeof progressConfig === 'object';
-          const defaultMsg = typeof progressConfig === 'string' ? progressConfig : `Running ${command.name}...`;
-          const progressMsg = isObj ? (progressConfig.progress ?? defaultMsg) : defaultMsg;
-          const validationMsg = isObj ? (progressConfig.validation ?? '') : '';
-          state._progressSuccess = isObj ? progressConfig.success : undefined;
-          state._progressError = isObj ? progressConfig.error : undefined;
-          state._progressMsg = progressMsg;
-          state._progressValidationMsg = validationMsg || undefined;
-          const spinnerConfig = isObj ? progressConfig.spinner : undefined;
-          const progressOptions = spinnerConfig !== undefined ? { spinner: spinnerConfig } : undefined;
-          const indicator = createProgress(runtime, validationMsg || progressMsg, progressOptions);
-          state._progress = indicator;
-
-          const originalOutput = runtime.output;
-          const originalError = runtime.error;
-          runtime.output = (...args: unknown[]) => {
-            indicator.pause();
-            originalOutput(...args);
-            indicator.resume();
-          };
-          runtime.error = (text: string) => {
-            indicator.pause();
-            originalError(text);
-            indicator.resume();
-          };
-          state._restoreOutput = () => {
-            runtime.output = originalOutput;
-            runtime.error = originalError;
-          };
-        }
-
-        // ── Phase 2: Validate ───────────────────────────────────────────
-        const validateCtx: PluginValidateContext = {
-          command,
-          rawArgs: parsed.rawArgs,
-          positionalArgs: parsed.positionalArgs,
-          state,
-        };
-
-        const coreValidate = (): PluginValidateResult | Promise<PluginValidateResult> => {
-          // Determine interactivity
-          let flagInteractive: boolean | undefined;
-          if (hasInteractiveConfig(command.meta)) {
-            if (validateCtx.rawArgs.interactive !== undefined) {
-              flagInteractive = validateCtx.rawArgs.interactive !== false && validateCtx.rawArgs.interactive !== 'false';
-              delete validateCtx.rawArgs.interactive;
-            }
-            if (validateCtx.rawArgs.i !== undefined) {
-              flagInteractive = validateCtx.rawArgs.i !== false && validateCtx.rawArgs.i !== 'false';
-              delete validateCtx.rawArgs.i;
-            }
-          }
-
-          // Strip --color / --no-color from rawArgs (handled globally)
-          delete validateCtx.rawArgs.color;
-          delete validateCtx.rawArgs['no-color'];
-
-          const runtimeDefault: boolean | undefined =
-            runtime.interactive === 'forced' ? true : runtime.interactive === 'disabled' ? false : undefined;
-          const effectiveInteractive: boolean | undefined = flagInteractive ?? evalOptions?.interactive ?? runtimeDefault;
-          // Suppress interactive prompts when the command reads stdin — prompts share stdin which is already consumed/closed.
-          const commandUsesStdin = !!command.meta?.stdin;
-          const stdinIsPiped =
-            commandUsesStdin && (runtime.stdin ? !runtime.stdin.isTTY : typeof process !== 'undefined' && process.stdin?.isTTY !== true);
-          const interactivitySuppressed =
-            runtime.interactive === 'unsupported' || effectiveInteractive === false || (stdinIsPiped && effectiveInteractive !== true);
-          const forceInteractive = !interactivitySuppressed && effectiveInteractive === true;
-
-          // Extract config file path from --config or -c flag
-          const configPath = extractConfigPath(parseCtx.input);
-
-          // Resolve config files: command's own configFiles > inherited from parent/root
-          const resolveConfigFiles = (cmd: AnyPadroneCommand): string[] | undefined => {
-            if (cmd.configFiles !== undefined) return cmd.configFiles;
-            if (cmd.parent) return resolveConfigFiles(cmd.parent);
-            return undefined;
-          };
-          const effectiveConfigFiles = resolveConfigFiles(command);
-
-          // Resolve config schema: command's own configSchema > inherited from parent/root
-          const resolveConfigSchema = (cmd: AnyPadroneCommand): AnyPadroneCommand['configSchema'] => {
-            if (cmd.configSchema !== undefined) return cmd.configSchema;
-            if (cmd.parent) return resolveConfigSchema(cmd.parent);
-            return undefined;
-          };
-          const configSchema = resolveConfigSchema(command);
-
-          // Resolve env schema: command's own envSchema > inherited from parent/root
-          const resolveEnvSchema = (cmd: AnyPadroneCommand): AnyPadroneCommand['envSchema'] => {
-            if (cmd.envSchema !== undefined) return cmd.envSchema;
-            if (cmd.parent) return resolveEnvSchema(cmd.parent);
-            return undefined;
-          };
-          const envSchema = resolveEnvSchema(command);
-
-          // Determine config data: explicit --config flag > auto-discovered config
-          let configData: Record<string, unknown> | undefined;
-          if (configPath) {
-            configData = runtime.loadConfigFile(configPath);
-          } else if (effectiveConfigFiles?.length) {
-            const foundConfigPath = runtime.findFile(effectiveConfigFiles);
-            if (foundConfigPath) {
-              configData = runtime.loadConfigFile(foundConfigPath) ?? configData;
-            }
-          }
-
-          // Step 1: Validate config data against schema if provided
-          const validateConfig = (): Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined> => {
-            if (configData && configSchema) {
-              const configValidated = configSchema['~standard'].validate(configData);
-              return thenMaybe(configValidated, (result) => {
-                if (result.issues) {
-                  const issueMessages = result.issues
-                    .map((i: StandardSchemaV1.Issue) => `  - ${i.path?.join('.') || 'root'}: ${i.message}`)
-                    .join('\n');
-                  throw new ConfigError(`Invalid config file:\n${issueMessages}`, {
-                    command: command.path || command.name,
-                  });
-                }
-                return result.value as unknown as Record<string, unknown>;
-              });
-            }
-            return configData;
-          };
-
-          // Step 2: Validate env vars
-          const validateEnv = (): Record<string, unknown> | undefined | Promise<Record<string, unknown> | undefined> => {
-            let envData: Record<string, unknown> | undefined;
-            if (envSchema) {
-              const rawEnv = runtime.env();
-              const envValidated = envSchema['~standard'].validate(rawEnv);
-              return thenMaybe(envValidated, (result) => {
-                if (!result.issues) {
-                  envData = result.value as unknown as Record<string, unknown>;
-                }
-                return envData;
-              });
-            }
-            return envData;
-          };
-
-          // Step 3: Read stdin if configured and not already provided via CLI
-          const readStdin = (): Record<string, unknown> | Promise<Record<string, unknown>> => {
-            const stdinConfig = command.meta?.stdin;
-            if (!stdinConfig) return {};
-
-            const field = parseStdinConfig(stdinConfig);
-
-            // Skip if the field was already provided via CLI flags (highest precedence)
-            if (field in validateCtx.rawArgs && validateCtx.rawArgs[field] !== undefined) return {};
-
-            const streamInfo = isAsyncStreamField(command.argsSchema, field);
-            if (streamInfo) {
-              // Async stream: always resolve stdin (even on TTY) for interactive use
-              const stdinForStream = resolveStdinAlways(runtime as any);
-              return { [field]: createStdinStream(stdinForStream, streamInfo.itemSchema) };
-            }
-
-            // Resolve stdin: use runtime's custom stdin, or default if piped.
-            // Returns undefined when stdin is a TTY or unavailable.
-            const stdin = resolveStdin(runtime as any);
-            if (!stdin) return {};
-
-            if (isArrayField(command.argsSchema, field)) {
-              return (async () => {
-                const lines: string[] = [];
-                for await (const line of stdin.lines()) {
-                  lines.push(line);
-                }
-                return { [field]: lines };
-              })();
-            }
-
-            // Default: read all as text
-            return stdin.text().then((text) => {
-              // Don't inject empty stdin
-              if (!text) return {};
-              return { [field]: text };
-            });
-          };
-
-          // Step 4: Preprocess, interactive prompt, and validate
-          const finalizeValidation = (
-            validatedConfigData: Record<string, unknown> | undefined,
-            envData: Record<string, unknown> | undefined,
-            stdinData: Record<string, unknown> | undefined,
-          ): PluginValidateResult | Promise<PluginValidateResult> => {
-            const preprocessedArgs = buildCommandArgs(command, validateCtx.rawArgs, validateCtx.positionalArgs, {
-              stdinData,
-              envData,
-              configData: validatedConfigData,
-            });
-
-            // Early validation: check provided args for errors before prompting.
-            // This catches unknown options and invalid values on explicitly-provided fields
-            // so the user isn't asked interactive questions for a doomed command.
-            const willPrompt = !interactivitySuppressed && runtime.prompt && hasInteractiveConfig(command.meta);
-            if (willPrompt) {
-              const unknowns = checkUnknownArgs(command, preprocessedArgs);
-              if (unknowns.length > 0) {
-                const issues: StandardSchemaV1.Issue[] = unknowns.map(({ key, suggestion }) => ({
-                  path: [key],
-                  message: suggestion ? `Unknown option: "${key}". ${suggestion}` : `Unknown option: "${key}"`,
-                }));
-                return { args: undefined, argsResult: { issues } as any };
-              }
-
-              // Run schema validation on what we have so far (before prompting fills missing fields).
-              // Only fail on issues for fields the user explicitly provided — skip issues for
-              // missing/undefined fields since those will be filled by interactive prompts.
-              if (command.argsSchema) {
-                const providedKeys = new Set(Object.keys(preprocessedArgs).filter((k) => preprocessedArgs[k] !== undefined));
-                const earlyCheck = command.argsSchema['~standard'].validate(preprocessedArgs);
-                const checkForProvidedFieldErrors = (result: StandardSchemaV1.Result<unknown>): PluginValidateResult | undefined => {
-                  if (!result.issues) return undefined;
-                  // Only keep issues whose path starts with a key the user actually provided
-                  const providedFieldIssues = result.issues.filter((issue) => {
-                    const rootKey = issue.path?.[0];
-                    return rootKey !== undefined && providedKeys.has(String(rootKey));
-                  });
-                  if (providedFieldIssues.length > 0) {
-                    return { args: undefined, argsResult: { issues: providedFieldIssues } as any };
-                  }
-                  return undefined;
-                };
-                const earlyResult = thenMaybe(earlyCheck, (result) => {
-                  const errors = checkForProvidedFieldErrors(result);
-                  if (errors) return errors;
-                  return undefined;
-                });
-                if (earlyResult instanceof Promise) {
-                  return earlyResult.then((err) => {
-                    if (err) return err;
-                    return continueWithPrompt(preprocessedArgs);
-                  });
-                }
-                if (earlyResult) return earlyResult;
-              }
-            }
-
-            return continueWithPrompt(preprocessedArgs);
-          };
-
-          const continueWithPrompt = (preprocessedArgs: Record<string, unknown>): PluginValidateResult | Promise<PluginValidateResult> => {
-            const willPrompt = !interactivitySuppressed && runtime.prompt && hasInteractiveConfig(command.meta);
-            const afterInteractive = willPrompt
-              ? promptInteractiveFields(preprocessedArgs, command, runtime, forceInteractive || undefined)
-              : preprocessedArgs;
-
-            return thenMaybe(afterInteractive, (filledArgs) => {
-              const validated = validateCommandArgs(command, filledArgs);
-              return thenMaybe(validated, (v) => v as PluginValidateResult);
-            });
-          };
-
-          // Chain: config → env → stdin → validate
-          const validatedConfig = validateConfig();
-          return thenMaybe(validatedConfig, (cfgData) => {
-            const validatedEnv = validateEnv();
-            return thenMaybe(validatedEnv, (envData) => {
-              const stdinDataOrPromise = readStdin();
-              return thenMaybe(stdinDataOrPromise, (stdinData) => {
-                const hasStdinData = Object.keys(stdinData).length > 0;
-                return finalizeValidation(cfgData, envData, hasStdinData ? stdinData : undefined);
-              });
-            });
-          });
-        };
-
-        const validatedOrPromise = runPluginChain('validate', commandPlugins, validateCtx, coreValidate);
-
-        // ── Phase 3: Execute (or handle validation errors) ──────────────
-        const continueAfterValidate = (v: PluginValidateResult) => {
-          // Handle validation failures
-          if (v.argsResult?.issues) {
-            // Collect known option names for fuzzy suggestion on unknown keys
-            let knownOptions: string[] | undefined;
-            const getKnownOptions = () => {
-              if (knownOptions) return knownOptions;
-              knownOptions = [];
-              if (command.argsSchema) {
-                try {
-                  const js = command.argsSchema['~standard'].jsonSchema.input(JSON_SCHEMA_OPTS) as Record<string, any>;
-                  if (js.type === 'object' && js.properties) knownOptions = Object.keys(js.properties);
-                } catch {
-                  /* ignore */
-                }
-              }
-              return knownOptions;
-            };
-
-            const issueMessages = v.argsResult.issues
-              .map((i: StandardSchemaV1.Issue) => {
-                const base = `  - ${i.path?.join('.') || 'root'}: ${i.message}`;
-                // Try to suggest for unrecognized key errors
-                const issueAny = i as any;
-                const unrecognizedKeys: string[] | undefined =
-                  issueAny.keys ?? i.message?.match(/[Uu]nrecognized key(?:s)?[^"]*"([^"]+)"/)?.slice(1);
-                if (unrecognizedKeys?.length) {
-                  const hints = unrecognizedKeys.map((k: string) => suggestSimilar(k, getKnownOptions())).filter(Boolean);
-                  if (hints.length) return `${base}\n    ${hints.join('\n    ')}`;
-                }
-                return base;
-              })
-              .join('\n');
-
-            if (errorMode === 'hard') {
-              resolveAllCommands(existingCommand);
-              const helpText = generateHelp(existingCommand, command, { format: runtime.format, theme: runtime.theme });
-              runtime.error(`Validation error:\n${issueMessages}`);
-              runtime.error(helpText);
-              throw new ValidationError(`Validation error:\n${issueMessages}`, v.argsResult.issues as any, {
-                suggestions: v.argsResult.issues.flatMap((i: any) => {
-                  const keys: string[] | undefined = i.keys ?? i.message?.match(/[Uu]nrecognized key(?:s)?[^"]*"([^"]+)"/)?.slice(1);
-                  if (!keys?.length) return [];
-                  return keys.map((k: string) => suggestSimilar(k, getKnownOptions())).filter(Boolean);
-                }),
-                command: command.path || command.name,
-              });
-            }
-
-            // Soft mode: return result with issues, skip the action
-            return withDrain({
-              command: command as any,
-              args: undefined,
-              argsResult: v.argsResult,
-              result: undefined,
-            });
-          }
-
-          // Update auto-progress message from validation to execute phase
-          const activeIndicator = state._progress as import('./runtime.ts').PadroneProgressIndicator | undefined;
-          if (activeIndicator && state._progressMsg && state._progressValidationMsg) {
-            activeIndicator.update(state._progressMsg as string);
-          }
-
-          const executeCtx: PluginExecuteContext = {
-            command,
-            args: v.args,
-            state,
-          };
-
-          const coreExecute = (): PluginExecuteResult => {
-            const handler = command.action ?? noop;
-            const ctx: PadroneActionContext = {
-              ...createActionContext(command),
-              runtime,
-              progress: (state._progress as PadroneProgressIndicator) ?? createLazyIndicator(runtime, state),
-            };
-            const result = handler(executeCtx.args as any, ctx);
-            return { result };
-          };
-
-          const executedOrPromise = runPluginChain('execute', commandPlugins, executeCtx, coreExecute);
-
-          return thenMaybe(executedOrPromise, (e) => {
-            const finalize = (result: unknown) => {
-              // Clean up progress before auto-output so the spinner clears first
-              const indicator = state._progress as import('./runtime.ts').PadroneProgressIndicator | undefined;
-              if (indicator) {
-                const hasProgressConfig = '_progressMsg' in state;
-                if (!hasProgressConfig) {
-                  // Lazy/manual indicator: just stop silently
-                  indicator.stop();
-                } else {
-                  const { message: successMsg, indicator: successIcon } = resolveProgressMessage(state._progressSuccess, result);
-                  indicator.succeed(successMsg, successIcon !== undefined ? { indicator: successIcon } : undefined);
-                }
-                (state._restoreOutput as (() => void) | undefined)?.();
-                state._progress = undefined;
-                state._restoreOutput = undefined;
-              }
-
-              const commandResult = withDrain({
-                command: command as any,
-                args: v.args,
-                argsResult: v.argsResult,
-                result,
-              });
-
-              if (command.autoOutput ?? evalOptions?.autoOutput ?? true) {
-                const outputOrPromise = outputValue(result, runtime.output);
-                if (outputOrPromise instanceof Promise) {
-                  return outputOrPromise.then(() => commandResult);
-                }
-              }
-
-              return commandResult;
-            };
-
-            // If the action returned a Promise, wait for it before finalizing
-            if (e.result instanceof Promise) {
-              return e.result.then(finalize, (err: unknown) => {
-                const indicator = state._progress as import('./runtime.ts').PadroneProgressIndicator | undefined;
-                if (indicator) {
-                  const hasProgressConfig = '_progressMsg' in state;
-                  if (!hasProgressConfig) {
-                    indicator.stop();
-                  } else {
-                    const fallback = err instanceof Error ? err.message : String(err);
-                    const { message: errorMsg, indicator: errorIcon } = resolveProgressMessage(state._progressError, err, fallback);
-                    indicator.fail(errorMsg, errorIcon !== undefined ? { indicator: errorIcon } : undefined);
-                  }
-                  (state._restoreOutput as (() => void) | undefined)?.();
-                  state._progress = undefined;
-                  state._restoreOutput = undefined;
-                }
-                throw err;
-              });
-            }
-
-            return finalize(e.result);
-          });
-        };
-
-        return thenMaybe(warnIfUnexpectedAsync(validatedOrPromise, command), continueAfterValidate) as any;
-      };
-
-      return thenMaybe(parsedOrPromise, continueAfterParse) as any;
-    };
-
-    return wrapWithLifecycle(rootPlugins, existingCommand, state, resolvedInput, runPipeline, (result) =>
-      withDrain({
-        command: existingCommand,
-        args: undefined,
-        argsResult: undefined,
-        result,
-      }),
-    ) as any;
-  };
-
-  const evalCommand: AnyPadroneProgram['eval'] = (input, evalOptions) => {
-    try {
-      const result = execCommand(input as string, evalOptions, 'soft');
-      if (result instanceof Promise) return withPromiseDrain(result.catch((err: unknown) => errorResult(err))) as any;
-      return makeThenable(result);
-    } catch (err) {
-      return makeThenable(errorResult(err)) as any;
-    }
-  };
-
-  /**
-   * Collects plugins from the command's parent chain (root → ... → target).
-   * Root/program plugins come first (outermost), target command's plugins last (innermost).
-   *
-   * The `programRoot` parameter provides the current program command, because
-   * subcommands' `.parent` references may be stale (builders are immutable — each
-   * method returns a new builder, so a subcommand's parent was captured before
-   * `.use()` was called on the program). We substitute `programRoot` for the
-   * top of the chain to ensure program-level plugins are always included.
-   */
-  const collectPlugins = (cmd: AnyPadroneCommand): PadronePlugin<any, any>[] => {
-    const chain: PadronePlugin<any, any>[][] = [];
-    let current: AnyPadroneCommand | undefined = cmd;
-    while (current) {
-      // If this is the root (no parent), use existingCommand's plugins instead
-      // to pick up plugins added after subcommands were defined.
-      if (!current.parent) {
-        if (existingCommand.plugins?.length) chain.unshift(existingCommand.plugins);
-      } else {
-        if (current.plugins?.length) chain.unshift(current.plugins);
-      }
-      current = current.parent;
-    }
-    return chain.flat();
-  };
-
-  // Forward declaration — assigned by the repl method in the return object, used by cli() for --repl.
-  const replFn = (options?: PadroneReplPreferences) => {
-    return createReplIterator({ existingCommand, evalCommand, replActiveRef }, options);
-  };
-  const replActiveRef = { value: false };
-
-  const cli: AnyPadroneProgram['cli'] = (cliOptions) => {
-    try {
-      const runtime = getCommandRuntime(existingCommand);
-      const resolvedInput = (runtime.argv().join(' ') || undefined) as string | undefined;
-
-      // Check for --repl flag and mcp command before normal execution
-      const builtin = checkBuiltinCommands(resolvedInput);
-
-      if (cliOptions?.repl !== false && builtin?.type === 'repl') {
-        const replPrefs: PadroneReplPreferences = {
-          ...(typeof cliOptions?.repl === 'object' ? cliOptions.repl : {}),
-          scope: builtin.scope,
-          autoOutput: (typeof cliOptions?.repl === 'object' ? cliOptions.repl.autoOutput : undefined) ?? cliOptions?.autoOutput,
-        };
-        const repl = replFn(replPrefs);
-        const drainRepl = async () => {
-          const { value } = await repl.drain();
-          return withDrain({ command: existingCommand, args: undefined, result: value }) as any;
-        };
-        return withPromiseDrain(drainRepl()) as any;
-      }
-
-      if (cliOptions?.mcp !== false && builtin?.type === 'mcp') {
-        const basePrefs = typeof cliOptions?.mcp === 'object' ? cliOptions.mcp : {};
-        const mcpPrefs = {
-          ...basePrefs,
-          transport: builtin.transport ?? basePrefs.transport,
-          port: builtin.port ?? basePrefs.port,
-          host: builtin.host ?? basePrefs.host,
-          basePath: builtin.basePath ?? basePrefs.basePath,
-        };
-        const startMcp = async () => {
-          const { startMcpServer } = await import('./mcp.ts');
-          await startMcpServer(builder as any, existingCommand, evalCommand, mcpPrefs);
-          return withDrain({ command: existingCommand, args: undefined, result: undefined }) as any;
-        };
-        return withPromiseDrain(startMcp()) as any;
-      }
-
-      if (cliOptions?.serve !== false && builtin?.type === 'serve') {
-        const basePrefs = typeof cliOptions?.serve === 'object' ? cliOptions.serve : {};
-        const servePrefs = {
-          ...basePrefs,
-          port: builtin.port ?? basePrefs.port,
-          host: builtin.host ?? basePrefs.host,
-          basePath: builtin.basePath ?? basePrefs.basePath,
-        };
-        const startServe = async () => {
-          const { startServeServer } = await import('./serve.ts');
-          await startServeServer(builder as any, existingCommand, evalCommand, servePrefs);
-          return withDrain({ command: existingCommand, args: undefined, result: undefined }) as any;
-        };
-        return withPromiseDrain(startServe()) as any;
-      }
-
-      // Start background update check (non-blocking)
-      let updateCheckPromise: Promise<(() => void) | undefined> | undefined;
-      if (existingCommand.updateCheck) {
-        // Respect --no-update-check flag
-        const hasNoUpdateCheckFlag =
-          resolvedInput &&
-          parseCliInputToParts(resolvedInput).some((p) => p.type === 'named' && p.key.length === 1 && p.key[0] === 'no-update-check');
-        if (!hasNoUpdateCheckFlag) {
-          const currentVersion = getVersion(existingCommand.version);
-          updateCheckPromise = import('./update-check.ts').then(({ createUpdateChecker }) =>
-            createUpdateChecker(existingCommand.name, currentVersion, existingCommand.updateCheck!, runtime),
-          );
-        }
-      }
-
-      const result = execCommand(resolvedInput, cliOptions, 'hard');
-
-      // Show update notification after command output
-      if (updateCheckPromise) {
-        if (result instanceof Promise) {
-          return withPromiseDrain(
-            result
-              .then(async (r) => {
-                const showUpdateNotification = await updateCheckPromise;
-                showUpdateNotification?.();
-                return r;
-              })
-              .catch((err: unknown) => errorResult(err)),
-          ) as any;
-        }
-        // For sync results, schedule notification for next tick (non-blocking)
-        updateCheckPromise.then((show) => show?.());
-      }
-
-      if (result instanceof Promise) return withPromiseDrain(result.catch((err: unknown) => errorResult(err))) as any;
-      return makeThenable(result);
-    } catch (err) {
-      return makeThenable(errorResult(err)) as any;
-    }
-  };
-
-  const run: AnyPadroneProgram['run'] = (command, args) => {
-    try {
-      const commandObj =
-        typeof command === 'string' ? findCommandByName(command, existingCommand.commands) : (command as AnyPadroneCommand);
-      if (!commandObj) throw new RoutingError(`Command "${command ?? ''}" not found`);
-      if (!commandObj.action) throw new RoutingError(`Command "${commandObj.path}" has no action`, { command: commandObj.path });
-
-      const state: Record<string, unknown> = {};
-      const executeCtx: PluginExecuteContext = { command: commandObj, args, state };
-
-      const coreExecute = (): PluginExecuteResult => {
-        const result = commandObj.action!(executeCtx.args as any, createActionContext(commandObj));
-        return { result };
-      };
-
-      const commandObjPlugins = collectPlugins(commandObj);
-      const executedOrPromise = runPluginChain('execute', commandObjPlugins, executeCtx, coreExecute);
-
-      const toResult = (e: PluginExecuteResult) =>
-        withDrain({
-          command: commandObj as any,
-          args: args as any,
-          result: e.result,
-        });
-
-      if (executedOrPromise instanceof Promise) {
-        return executedOrPromise.then(toResult).catch((err: unknown) => errorResult(err, { command: commandObj, args })) as any;
-      }
-      return toResult(executedOrPromise);
-    } catch (err) {
-      return errorResult(err) as any;
-    }
-  };
-
-  const tool: AnyPadroneProgram['tool'] = () => {
-    resolveAllCommands(existingCommand);
-    const helpText = generateHelp(existingCommand, undefined, { format: 'text' });
-
-    const description = `Run a command. Pass the full command string including arguments. Use "help <command>" for detailed usage.\n\n${helpText}`;
-
-    return {
-      type: 'function',
-      name: existingCommand.name,
-      strict: true,
-      title: existingCommand.description,
-      description,
-      inputExamples: [{ input: { command: '<command> [positionals...] [arguments...]' } }],
-      inputSchema: {
-        [Symbol.for('vercel.ai.schema') as keyof Schema & symbol]: true,
-        jsonSchema: {
-          type: 'object',
-          properties: { command: { type: 'string' } },
-          additionalProperties: false,
-        },
-        _type: undefined as unknown as { command: string },
-        validate: (value) => {
-          const command = (value as any)?.command;
-          if (typeof command === 'string') return { success: true, value: { command } };
-          return { success: false, error: new Error('Expected an object with command property as string.') };
-        },
-      } satisfies Schema<{ command: string }> as Schema<{ command: string }>,
-      needsApproval: async (input) => {
-        const parsed = await parse(input.command);
-        if (typeof parsed.command.needsApproval === 'function') return parsed.command.needsApproval(parsed.args);
-        if (parsed.command.needsApproval != null) return !!parsed.command.needsApproval;
-        return !!parsed.command.mutation;
-      },
-      execute: async (input) => {
-        const output: string[] = [];
-        const errors: string[] = [];
-        const result = await evalCommand(input.command, {
-          autoOutput: false,
-          runtime: {
-            output: (...args) => output.push(args.map(String).join(' ')),
-            error: (text) => errors.push(text),
-            interactive: 'unsupported',
-            format: 'text',
-          },
-        });
-        return { result: result.result, logs: output.join('\n'), error: errors.join('\n') };
-      },
-    };
-  };
-
-  const builder = {
-    configure(config) {
-      return createPadroneBuilder({ ...existingCommand, ...config }) as any;
-    },
-    runtime(runtimeConfig) {
-      return createPadroneBuilder({ ...existingCommand, runtime: { ...existingCommand.runtime, ...runtimeConfig } }) as any;
-    },
-    async() {
-      return createPadroneBuilder({ ...existingCommand, isAsync: true }) as any;
-    },
-    arguments(schema, meta) {
-      // If schema is a function, call it with parent's arguments as base
-      const resolvedArgs = typeof schema === 'function' ? schema(existingCommand.argsSchema as any) : schema;
-      const isAsync = existingCommand.isAsync || isAsyncBranded(resolvedArgs) || hasInteractiveConfig(meta);
-      return createPadroneBuilder({ ...existingCommand, argsSchema: resolvedArgs, meta, isAsync }) as any;
-    },
-    configFile(file, schema) {
-      const configFiles = file === undefined ? undefined : Array.isArray(file) ? file : [file];
-      const resolvedConfig = typeof schema === 'function' ? schema(existingCommand.argsSchema) : (schema ?? existingCommand.argsSchema);
-      const isAsync = existingCommand.isAsync || isAsyncBranded(resolvedConfig);
-      return createPadroneBuilder({ ...existingCommand, configFiles, configSchema: resolvedConfig as any, isAsync }) as any;
-    },
-    env(schema) {
-      const resolvedEnv = typeof schema === 'function' ? schema(existingCommand.argsSchema) : schema;
-      const isAsync = existingCommand.isAsync || isAsyncBranded(resolvedEnv);
-      return createPadroneBuilder({ ...existingCommand, envSchema: resolvedEnv as any, isAsync }) as any;
-    },
-    progress(config = true) {
-      const progress = typeof config === 'boolean' || typeof config === 'string' ? config : { ...config };
-      return createPadroneBuilder({ ...existingCommand, progress }) as any;
-    },
-    action(handler = noop) {
-      const baseHandler = existingCommand.action ?? noop;
-      return createPadroneBuilder({
-        ...existingCommand,
-        action: (args: any, ctx: any) => (handler as any)(args, ctx, baseHandler),
-      }) as any;
-    },
-    wrap(config) {
-      const handler = createWrapHandler(config, existingCommand.argsSchema as any, existingCommand.meta?.positional);
-      return createPadroneBuilder({ ...existingCommand, action: handler }) as any;
-    },
-    command(nameOrNames, builderFn) {
-      // Extract name and aliases from the input
-      const name = Array.isArray(nameOrNames) ? nameOrNames[0] : nameOrNames;
-      const aliases = Array.isArray(nameOrNames) && nameOrNames.length > 1 ? (nameOrNames.slice(1) as string[]) : undefined;
-
-      // Check if a command with this name already exists (override case)
-      const existingSubcommand = existingCommand.commands?.find((c) => c.name === name) as AnyPadroneCommand | undefined;
-
-      // For override case, resolve the existing lazy command first so the builder starts with full state
-      if (existingSubcommand) resolveCommand(existingSubcommand);
-
-      const initialCommand: AnyPadroneCommand = existingSubcommand
-        ? { ...existingSubcommand, aliases: aliases ?? existingSubcommand.aliases, parent: existingCommand }
-        : ({
-            name,
-            path: existingCommand.path ? `${existingCommand.path} ${name}` : name,
-            aliases,
-            parent: existingCommand,
-            '~types': {} as any,
-          } satisfies PadroneCommand);
-
-      // Lazy initialization: defer builderFn invocation until the command is actually needed
-      if (builderFn) {
-        const lazyCmd: AnyPadroneCommand = { ...initialCommand };
-        (lazyCmd as any)[lazyResolver] = (target: AnyPadroneCommand) => {
-          const builder = createPadroneBuilder(target);
-          const commandObj = ((builderFn(builder as any) as unknown as typeof builder)?.[commandSymbol] as AnyPadroneCommand) ?? target;
-          const mergedCommandObj = existingSubcommand ? mergeCommands(existingSubcommand, commandObj) : commandObj;
-          Object.assign(target, mergedCommandObj);
-        };
-
-        const commands = existingCommand.commands || [];
-        const existingIndex = commands.findIndex((c) => c.name === name);
-        const updatedCommands =
-          existingIndex >= 0
-            ? [...commands.slice(0, existingIndex), lazyCmd, ...commands.slice(existingIndex + 1)]
-            : [...commands, lazyCmd];
-
-        return createPadroneBuilder({ ...existingCommand, commands: updatedCommands }) as any;
-      }
-
-      // No builderFn: use the initial command as-is (no lazy resolution needed)
-      const commands = existingCommand.commands || [];
-      const existingIndex = commands.findIndex((c) => c.name === name);
-      const updatedCommands =
-        existingIndex >= 0
-          ? [...commands.slice(0, existingIndex), initialCommand, ...commands.slice(existingIndex + 1)]
-          : [...commands, initialCommand];
-
-      return createPadroneBuilder({ ...existingCommand, commands: updatedCommands }) as any;
-    },
-
-    mount(nameOrNames, program) {
-      const name = Array.isArray(nameOrNames) ? nameOrNames[0] : nameOrNames;
-      const aliases = Array.isArray(nameOrNames) && nameOrNames.length > 1 ? (nameOrNames.slice(1) as string[]) : undefined;
-
-      // Extract the underlying command from the program
-      const programCommand = (program as any)[commandSymbol] as AnyPadroneCommand | undefined;
-      if (!programCommand) throw new RoutingError('Cannot mount: not a valid Padrone program');
-
-      // Re-path the command tree under the new name
-      const remounted = repathCommandTree(programCommand, name, existingCommand.path || '', existingCommand);
-      remounted.aliases = aliases;
-
-      // Merge with existing command if one with the same name exists
-      const existingSubcommand = existingCommand.commands?.find((c) => c.name === name) as AnyPadroneCommand | undefined;
-      const mergedCommandObj = existingSubcommand ? mergeCommands(existingSubcommand, remounted) : remounted;
-
-      const commands = existingCommand.commands || [];
-      const existingIndex = commands.findIndex((c) => c.name === name);
-      const updatedCommands =
-        existingIndex >= 0
-          ? [...commands.slice(0, existingIndex), mergedCommandObj, ...commands.slice(existingIndex + 1)]
-          : [...commands, mergedCommandObj];
-
-      return createPadroneBuilder({ ...existingCommand, commands: updatedCommands }) as any;
-    },
-
-    use(plugin: PadronePlugin<any, any>) {
-      return createPadroneBuilder({
-        ...existingCommand,
-        plugins: [...(existingCommand.plugins ?? []), plugin],
-      }) as any;
-    },
-
-    updateCheck(config = {}) {
-      return createPadroneBuilder({ ...existingCommand, updateCheck: config }) as any;
-    },
-
-    run,
-    find,
-    parse,
-    stringify,
-    eval: evalCommand,
-    cli,
-    tool,
-
-    repl: replFn,
-
-    api() {
-      resolveAllCommands(existingCommand);
-      function buildApi(command: AnyPadroneCommand) {
-        const runCommand = ((args) => run(command, args).result) as PadroneAPI<AnyPadroneCommand>;
-        if (!command.commands) return runCommand;
-        for (const cmd of command.commands) runCommand[cmd.name] = buildApi(cmd);
-        return runCommand;
-      }
-
-      return buildApi(existingCommand);
-    },
-
-    help(command, prefs) {
-      resolveAllCommands(existingCommand);
-      const commandObj = !command
-        ? existingCommand
-        : typeof command === 'string'
-          ? findCommandByName(command, existingCommand.commands)
-          : (command as AnyPadroneCommand);
-      if (!commandObj) throw new RoutingError(`Command "${command ?? ''}" not found`);
-      const runtime = getCommandRuntime(existingCommand);
-      return generateHelp(existingCommand, commandObj, {
-        ...prefs,
-        format: prefs?.format ?? runtime.format,
-        theme: prefs?.theme ?? runtime.theme,
-      });
-    },
-
-    async completion(shell) {
-      resolveAllCommands(existingCommand);
-      const { generateCompletionOutput } = await import('./completion.ts');
-      return generateCompletionOutput(existingCommand, shell as ShellType | undefined);
-    },
-
-    async mcp(prefs) {
-      resolveAllCommands(existingCommand);
-      const { startMcpServer } = await import('./mcp.ts');
-      return startMcpServer(builder as any, existingCommand, evalCommand, prefs);
-    },
-
-    async serve(prefs) {
-      resolveAllCommands(existingCommand);
-      const { startServeServer } = await import('./serve.ts');
-      return startServeServer(builder as any, existingCommand, evalCommand, prefs);
-    },
-
-    '~types': {} as any,
-
-    [commandSymbol]: existingCommand,
-  } satisfies AnyPadroneProgram & { [commandSymbol]: AnyPadroneCommand } as any;
-  return builder as TBuilder & { [commandSymbol]: AnyPadroneCommand };
-}