padrone 1.0.0 → 1.2.0

package/src/create.ts

@@ -1,51 +1,74 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { Schema } from 'ai';
-import { generateCompletionOutput, type ShellType } from './completion.ts';
+import { coerceArgs, detectUnknownArgs, extractSchemaMetadata, parsePositionalConfig, parseStdinConfig, preprocessArgs } from './args.ts';
+import {
+  commandSymbol,
+  findCommandByName,
+  getCommandRuntime,
+  hasInteractiveConfig,
+  isAsyncBranded,
+  mergeCommands,
+  noop,
+  outputValue,
+  repathCommandTree,
+  runPluginChain,
+  suggestSimilar,
+  thenMaybe,
+  warnIfUnexpectedAsync,
+  wrapWithLifecycle,
+} from './command-utils.ts';
+import type { ShellType } from './completion.ts';
+import { ConfigError, RoutingError, ValidationError } from './errors.ts';
 import { generateHelp } from './help.ts';
-import { extractSchemaMetadata, parsePositionalConfig, preprocessOptions } from './options.ts';
+import { promptInteractiveFields } from './interactive.ts';
 import { getNestedValue, parseCliInputToParts, setNestedValue } from './parse.ts';
-import type { AnyPadroneCommand, AnyPadroneProgram, PadroneAPI, PadroneCommand, PadroneProgram } from './types.ts';
-import { findConfigFile, getVersion, loadConfigFile } from './utils.ts';
-
-const commandSymbol = Symbol('padrone_command');
-
-const noop = <TRes>() => undefined as TRes;
+import { createReplIterator } from './repl-loop.ts';
+import { resolveStdin } from './runtime.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>(
-  existingCommand: AnyPadroneCommand,
+  inputCommand: AnyPadroneCommand,
 ): TBuilder & { [commandSymbol]: AnyPadroneCommand } {
-  function findCommandByName(name: string, commands?: AnyPadroneCommand[]): AnyPadroneCommand | undefined {
-    if (!commands) return undefined;
-
-    const foundByName = commands.find((cmd) => cmd.name === name);
-    if (foundByName) return foundByName;
-
-    // Check for aliases
-    const foundByAlias = commands.find((cmd) => cmd.aliases?.includes(name));
-    if (foundByAlias) return foundByAlias;
-
-    for (const cmd of commands) {
-      if (cmd.commands && name.startsWith(`${cmd.name} `)) {
-        const subCommandName = name.slice(cmd.name.length + 1);
-        const subCommand = findCommandByName(subCommandName, cmd.commands);
-        if (subCommand) return subCommand;
-      }
-      // Check aliases for nested commands
-      if (cmd.commands && cmd.aliases) {
-        for (const alias of cmd.aliases) {
-          if (name.startsWith(`${alias} `)) {
-            const subCommandName = name.slice(alias.length + 1);
-            const subCommand = findCommandByName(subCommandName, cmd.commands);
-            if (subCommand) return subCommand;
-          }
+  // 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)),
         }
-      }
-    }
-    return undefined;
-  }
+      : 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 => ({
+    runtime: getCommandRuntime(cmd),
+    command: cmd,
+    program: builder as any,
+  });
 
   const find: AnyPadroneProgram['find'] = (command) => {
     if (typeof command !== 'string') return findCommandByName(command.path, existingCommand.commands) as any;
@@ -53,11 +76,18 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
   };
 
   /**
-   * Parses CLI input to find the command and extract raw options without validation.
+   * Parses CLI input to find the command and extract raw arguments without validation.
    */
   const parseCommand = (input: string | undefined) => {
-    input ??= typeof process !== 'undefined' ? (process.argv.slice(2).join(' ') as any) : undefined;
-    if (!input) return { command: existingCommand, rawOptions: {} as Record<string, unknown>, args: [] as string[] };
+    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);
 
@@ -65,6 +95,7 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
     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();
@@ -76,26 +107,36 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
       if (found) {
         curCommand = found;
       } else {
-        args.unshift(...terms.slice(i));
+        unmatchedTerms = terms.slice(i);
+        args.unshift(...unmatchedTerms);
         break;
       }
     }
 
-    if (!curCommand) return { command: existingCommand, rawOptions: {} as Record<string, unknown>, args };
+    // 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 option metadata from the nested options object in meta
-    const optionsMeta = curCommand.meta?.options;
-    const schemaMetadata = curCommand.options ? extractSchemaMetadata(curCommand.options, optionsMeta) : { aliases: {} };
+    // Extract argument metadata from the nested arguments object in meta
+    const argsMeta = curCommand.meta?.fields;
+    const schemaMetadata = curCommand.argsSchema ? extractSchemaMetadata(curCommand.argsSchema, argsMeta) : { aliases: {} };
     const { aliases } = schemaMetadata;
 
-    // Get array options from schema (arrays are always variadic)
-    const arrayOptions = new Set<string>();
-    if (curCommand.options) {
+    // Get array arguments from schema (arrays are always variadic)
+    const arrayArguments = new Set<string>();
+    if (curCommand.argsSchema) {
       try {
-        const jsonSchema = curCommand.options['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+        const jsonSchema = curCommand.argsSchema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) 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') arrayOptions.add(key);
+            if (prop?.type === 'array') arrayArguments.add(key);
           }
         }
       } catch {
@@ -103,27 +144,27 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
       }
     }
 
-    const opts = parts.filter((p) => p.type === 'option' || p.type === 'alias');
-    const rawOptions: Record<string, unknown> = {};
+    const argParts = parts.filter((p) => p.type === 'named' || p.type === 'alias');
+    const rawArgs: Record<string, unknown> = {};
 
-    for (const opt of opts) {
+    for (const arg of argParts) {
       // For aliases, resolve to the full key name (aliases map single char to full key name)
-      // opt.key is now a string[] - for aliases it's always single element like ['v']
-      const key: string[] = opt.type === 'alias' && opt.key.length === 1 && aliases[opt.key[0]!] ? [aliases[opt.key[0]!]!] : opt.key;
+      // arg.key is now a string[] - for aliases it's always single element like ['v']
+      const key: string[] = arg.type === 'alias' && arg.key.length === 1 && aliases[arg.key[0]!] ? [aliases[arg.key[0]!]!] : arg.key;
 
       const rootKey = key[0]!;
 
-      // Handle negated boolean options (--no-verbose)
-      if (opt.type === 'option' && opt.negated) {
-        setNestedValue(rawOptions, key, false);
+      // Handle negated boolean arguments (--no-verbose)
+      if (arg.type === 'named' && arg.negated) {
+        setNestedValue(rawArgs, key, false);
         continue;
       }
 
-      const value = opt.value ?? true;
+      const value = arg.value ?? true;
 
-      // Handle array options - accumulate values into arrays (arrays are always variadic)
-      if (arrayOptions.has(rootKey)) {
-        const existing = getNestedValue(rawOptions, key);
+      // 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)) {
@@ -133,129 +174,259 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
             }
           } else {
             if (Array.isArray(value)) {
-              setNestedValue(rawOptions, key, [existing, ...value]);
+              setNestedValue(rawArgs, key, [existing, ...value]);
             } else {
-              setNestedValue(rawOptions, key, [existing, value]);
+              setNestedValue(rawArgs, key, [existing, value]);
             }
           }
         } else {
-          setNestedValue(rawOptions, key, Array.isArray(value) ? value : [value]);
+          setNestedValue(rawArgs, key, Array.isArray(value) ? value : [value]);
         }
       } else {
-        setNestedValue(rawOptions, key, value);
+        setNestedValue(rawArgs, key, value);
       }
     }
 
-    return { command: curCommand, rawOptions, args };
+    return { command: curCommand, rawArgs, args, unmatchedTerms };
   };
 
   /**
-   * Validates raw options against the command's schema and applies preprocessing.
+   * Preprocesses raw arguments: applies env/config values and maps positional arguments.
+   * Also performs auto-coercion (string→number/boolean) and unknown arg detection.
    */
-  const validateOptions = (
+  const buildCommandArgs = (
     command: AnyPadroneCommand,
-    rawOptions: Record<string, unknown>,
+    rawArgs: Record<string, unknown>,
     args: string[],
-    parseOptions?: { envData?: Record<string, unknown>; configData?: Record<string, unknown> },
-  ) => {
-    // Apply preprocessing (env and config bindings)
-    const preprocessedOptions = preprocessOptions(rawOptions, {
+    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, {
       aliases: {}, // Already resolved aliases in parseCommand
-      envData: parseOptions?.envData,
-      configData: parseOptions?.configData,
+      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 options
+    // Map positional arguments to their named arguments
     if (positionalConfig.length > 0) {
       let argIndex = 0;
-      for (const { name, variadic } of positionalConfig) {
+      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(positionalConfig.indexOf({ name, variadic }) + 1);
+          const remainingPositionals = positionalConfig.slice(i + 1);
           const nonVariadicAfter = remainingPositionals.filter((p) => !p.variadic).length;
           const variadicEnd = args.length - nonVariadicAfter;
-          preprocessedOptions[name] = args.slice(argIndex, variadicEnd);
+          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 {
-          preprocessedOptions[name] = args[argIndex];
+          preprocessedArgs[name] = args[argIndex];
           argIndex++;
         }
       }
     }
 
-    const optionsParsed = command.options ? command.options['~standard'].validate(preprocessedOptions) : { value: preprocessedOptions };
+    // Auto-coerce CLI string values to match schema types (string→number, string→boolean)
+    if (command.argsSchema) {
+      preprocessedArgs = coerceArgs(preprocessedArgs, command.argsSchema);
+    }
+
+    return preprocessedArgs;
+  };
 
-    if (optionsParsed instanceof Promise) {
-      throw new Error('Async validation is not supported. Schema validate() must return a synchronous result.');
+  /**
+   * 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 { aliases } = extractSchemaMetadata(command.argsSchema, argsMeta);
+
+    return detectUnknownArgs(preprocessedArgs, command.argsSchema, 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 };
     }
 
-    // Return undefined for options when there's no schema and no meaningful options
-    const hasOptions = command.options || Object.keys(preprocessedOptions).length > 0;
+    const argsParsed = command.argsSchema ? command.argsSchema['~standard'].validate(preprocessedArgs) : { value: preprocessedArgs };
 
-    return {
-      options: optionsParsed.issues ? undefined : hasOptions ? (optionsParsed.value as any) : undefined,
-      optionsResult: optionsParsed as any,
-    };
+    // 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);
   };
 
-  const parse: AnyPadroneProgram['parse'] = (input, parseOptions) => {
-    const { command, rawOptions, args } = parseCommand(input);
+  /**
+   * 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);
+  };
 
-    // 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 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 };
     };
-    const envSchema = resolveEnvSchema(command);
-
-    // Validate env vars against schema if provided
-    let envData: Record<string, unknown> | undefined = parseOptions?.envData;
-    if (envSchema && !envData) {
-      const rawEnv = parseOptions?.env ?? (typeof process !== 'undefined' ? process.env : {});
-      const envValidated = envSchema['~standard'].validate(rawEnv);
-      if (envValidated instanceof Promise) {
-        throw new Error('Async validation is not supported. Env schema validate() must return a synchronous result.');
-      }
-      // For env vars, we don't throw on validation errors - just use the transformed value if valid
-      if (!envValidated.issues) {
-        envData = envValidated.value as unknown as Record<string, unknown>;
-      }
-    }
 
-    const { options, optionsResult } = validateOptions(command, rawOptions, args, {
-      envData,
-      configData: parseOptions?.configData,
-    });
+    // Parse phase: root plugins only
+    const rootPlugins = existingCommand.plugins ?? [];
+    const parsedOrPromise = runPluginChain('parse', rootPlugins, parseCtx, coreParse);
 
-    return {
-      command: command as any,
-      options,
-      optionsResult,
+    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, as } = 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 stdin = resolveStdin(runtime as any);
+          if (!stdin) return {};
+
+          if (as === 'lines') {
+            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 thenMaybe(parsedOrPromise, continueAfterParse) as any;
   };
 
-  const stringify: AnyPadroneProgram['stringify'] = (command = '' as any, options) => {
+  const stringify: AnyPadroneProgram['stringify'] = (command = '' as any, args) => {
     const commandObj = typeof command === 'string' ? findCommandByName(command, existingCommand.commands) : (command as AnyPadroneCommand);
-    if (!commandObj) throw new Error(`Command "${command ?? ''}" not found`);
+    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 options are positional
+    // 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 (options && typeof options === 'object') {
+    if (args && typeof args === 'object') {
       for (const { name, variadic } of positionalConfig) {
-        const value = (options as Record<string, unknown>)[name];
+        const value = (args as Record<string, unknown>)[name];
         if (value === undefined) continue;
 
         if (variadic && Array.isArray(value)) {
@@ -279,7 +450,7 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
           if (value) parts.push(`--${key}`);
           else parts.push(`--no-${key}`);
         } else if (Array.isArray(value)) {
-          // Handle variadic options - output each value separately
+          // Handle variadic arguments - output each value separately
           for (const v of value) {
             const vStr = String(v);
             if (vStr.includes(' ')) parts.push(`--${key}="${vStr}"`);
@@ -298,8 +469,8 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
         }
       };
 
-      // Output remaining options (non-positional)
-      for (const [key, value] of Object.entries(options)) {
+      // Output remaining arguments (non-positional)
+      for (const [key, value] of Object.entries(args)) {
         if (value === undefined || positionalNames.has(key)) continue;
         stringifyValue(key, value);
       }
@@ -320,31 +491,32 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
   ):
     | { type: 'help'; command?: AnyPadroneCommand; detail?: DetailLevel; format?: FormatLevel }
     | { type: 'version' }
-    | { type: 'completion'; shell?: ShellType }
+    | { type: 'completion'; shell?: ShellType; setup?: boolean }
+    | { type: 'repl'; scope?: string }
     | null => {
     if (!input) return null;
 
     const parts = parseCliInputToParts(input);
     const terms = parts.filter((p) => p.type === 'term').map((p) => p.value);
-    const opts = parts.filter((p) => p.type === 'option' || p.type === 'alias');
+    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 = opts.some((p) => (p.type === 'option' && keyIs(p.key, 'help')) || (p.type === 'alias' && keyIs(p.key, 'h')));
+    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>
     const getDetailLevel = (): DetailLevel | undefined => {
-      for (const opt of opts) {
-        if (opt.type === 'option' && keyIs(opt.key, 'detail') && typeof opt.value === 'string') {
-          if (opt.value === 'minimal' || opt.value === 'standard' || opt.value === 'full') {
-            return opt.value;
+      for (const arg of args) {
+        if (arg.type === 'named' && keyIs(arg.key, 'detail') && typeof arg.value === 'string') {
+          if (arg.value === 'minimal' || arg.value === 'standard' || arg.value === 'full') {
+            return arg.value;
           }
         }
-        if (opt.type === 'alias' && keyIs(opt.key, 'd') && typeof opt.value === 'string') {
-          if (opt.value === 'minimal' || opt.value === 'standard' || opt.value === 'full') {
-            return opt.value;
+        if (arg.type === 'alias' && keyIs(arg.key, 'd') && typeof arg.value === 'string') {
+          if (arg.value === 'minimal' || arg.value === 'standard' || arg.value === 'full') {
+            return arg.value;
           }
         }
       }
@@ -355,15 +527,15 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
     // Extract format from --format=<value> or -f <value>
     const getFormat = (): FormatLevel | undefined => {
       const validFormats: FormatLevel[] = ['text', 'ansi', 'console', 'markdown', 'html', 'json', 'auto'];
-      for (const opt of opts) {
-        if (opt.type === 'option' && keyIs(opt.key, 'format') && typeof opt.value === 'string') {
-          if (validFormats.includes(opt.value as FormatLevel)) {
-            return opt.value as FormatLevel;
+      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 (opt.type === 'alias' && keyIs(opt.key, 'f') && typeof opt.value === 'string') {
-          if (validFormats.includes(opt.value as FormatLevel)) {
-            return opt.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;
           }
         }
       }
@@ -372,8 +544,8 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
     const format = getFormat();
 
     // Check for --version, -v, -V flags
-    const hasVersionFlag = opts.some(
-      (p) => (p.type === 'option' && keyIs(p.key, 'version')) || (p.type === 'alias' && (keyIs(p.key, 'v') || keyIs(p.key, 'V'))),
+    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
@@ -386,12 +558,30 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
     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 };
     }
+    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 };
+    }
 
     // Check for 'version' command (only if user hasn't defined one)
     if (!userVersionCommand && normalizedTerms[0] === 'version') {
@@ -403,7 +593,8 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
       const shellArg = normalizedTerms[1] as ShellType | undefined;
       const validShells: ShellType[] = ['bash', 'zsh', 'fish', 'powershell'];
       const shell = shellArg && validShells.includes(shellArg) ? shellArg : undefined;
-      return { type: 'completion', shell };
+      const setup = args.some((p) => p.type === 'named' && keyIs(p.key, 'setup'));
+      return { type: 'completion', shell, setup };
     }
 
     // Handle help flag - find the command being requested
@@ -420,6 +611,13 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
       return { type: 'version' };
     }
 
+    // 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;
   };
 
@@ -430,171 +628,642 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
     if (!input) return undefined;
 
     const parts = parseCliInputToParts(input);
-    const opts = parts.filter((p) => p.type === 'option' || p.type === 'alias');
+    const args = parts.filter((p) => p.type === 'named' || p.type === 'alias');
 
-    for (const opt of opts) {
-      if (opt.type === 'option' && opt.key.length === 1 && opt.key[0] === 'config' && typeof opt.value === 'string') {
-        return opt.value;
+    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 (opt.type === 'alias' && opt.key.length === 1 && opt.key[0] === 'c' && typeof opt.value === 'string') {
-        return opt.value;
+      if (arg.type === 'alias' && arg.key.length === 1 && arg.key[0] === 'c' && typeof arg.value === 'string') {
+        return arg.value;
       }
     }
     return undefined;
   };
 
-  const cli: AnyPadroneProgram['cli'] = (input, cliOptions) => {
-    // Resolve input from process.argv if not provided
-    const resolvedInput = input ?? (typeof process !== 'undefined' ? (process.argv.slice(2).join(' ') as any) : 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);
+    const runtime = evalOptions?.runtime
+      ? Object.assign({}, baseRuntime, Object.fromEntries(Object.entries(evalOptions.runtime).filter(([, v]) => v !== undefined)))
+      : baseRuntime;
 
-    // Check for built-in help/version/completion commands and flags
+    // Check for built-in help/version/completion commands and flags (bypass plugins)
     const builtin = checkBuiltinCommands(resolvedInput);
 
     if (builtin) {
       if (builtin.type === 'help') {
         const helpText = generateHelp(existingCommand, builtin.command ?? existingCommand, {
           detail: builtin.detail,
-          format: builtin.format,
+          format: builtin.format ?? runtime.format,
         });
-        console.log(helpText);
+        runtime.output(helpText);
         return {
           command: existingCommand,
           args: undefined,
-          options: undefined,
           result: helpText,
         } as any;
       }
 
       if (builtin.type === 'version') {
         const version = getVersion(existingCommand.version);
-        console.log(version);
+        runtime.output(version);
         return {
           command: existingCommand,
-          options: undefined,
+          args: undefined,
           result: version,
         } as any;
       }
 
       if (builtin.type === 'completion') {
-        const completionScript = generateCompletionOutput(existingCommand, builtin.shell);
-        console.log(completionScript);
-        return {
-          command: existingCommand,
-          options: undefined,
-          result: completionScript,
-        } as any;
+        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 {
+              command: existingCommand,
+              args: undefined,
+              result: message,
+            };
+          }
+          const completionScript = generateCompletionOutput(existingCommand, builtin.shell);
+          runtime.output(completionScript);
+          return {
+            command: existingCommand,
+            args: undefined,
+            result: completionScript,
+          };
+        }) as any;
       }
     }
 
-    // Parse the command first (without validating options)
-    const { command, rawOptions, args } = parseCommand(resolvedInput);
+    // 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) {
+          const helpText = generateHelp(existingCommand, command, { format: runtime.format });
+          runtime.output(helpText);
+          return {
+            command: command,
+            rawArgs: { '~help': helpText } as Record<string, unknown>,
+            positionalArgs: [],
+          };
+        }
 
-    // Extract config file path from --config or -c flag
-    const configPath = extractConfigPath(resolvedInput);
+        // 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);
+                }
+              }
+            }
 
-    // Resolve config files: command's own configFiles > inherited from parent/root
-    // undefined = inherit, empty array = no config files (explicit opt-out)
-    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);
+            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 {
+                const helpText = generateHelp(existingCommand, isRootCommand ? existingCommand : command, { format: runtime.format });
+                runtime.error(helpText);
+              }
+              throw new RoutingError(errorMsg, { suggestions, command: command.path || command.name });
+            }
 
-    // Resolve config schema: command's own config > inherited from parent/root
-    const resolveConfigSchema = (cmd: AnyPadroneCommand): AnyPadroneCommand['config'] => {
-      if (cmd.config !== undefined) return cmd.config;
-      if (cmd.parent) return resolveConfigSchema(cmd.parent);
-      return undefined;
-    };
-    const configSchema = resolveConfigSchema(command);
+            // Soft mode: throw too — this is a routing error, not a validation issue
+            throw new RoutingError(errorMsg, { suggestions, command: command.path || command.name });
+          }
+        }
 
-    // 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;
+        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;
+        }
+
+        // ── 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;
+            }
+          }
+
+          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, as } = parseStdinConfig(stdinConfig);
+
+            // Skip if the field was already provided via CLI flags (highest precedence)
+            if (field in validateCtx.rawArgs && validateCtx.rawArgs[field] !== undefined) return {};
+
+            // 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 (as === 'lines') {
+              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({ target: 'draft-2020-12' }) 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') {
+              const helpText = generateHelp(existingCommand, command, { format: runtime.format });
+              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 {
+              command: command as any,
+              args: undefined,
+              argsResult: v.argsResult,
+              result: undefined,
+            };
+          }
+
+          const executeCtx: PluginExecuteContext = {
+            command,
+            args: v.args,
+            state,
+          };
+
+          const coreExecute = (): PluginExecuteResult => {
+            const handler = command.action ?? noop;
+            const ctx = evalOptions?.runtime ? { ...createActionContext(command), runtime } : createActionContext(command);
+            const result = handler(executeCtx.args as any, ctx);
+            return { result };
+          };
+
+          const executedOrPromise = runPluginChain('execute', commandPlugins, executeCtx, coreExecute);
+
+          return thenMaybe(executedOrPromise, (e) => {
+            const commandResult = {
+              command: command as any,
+              args: v.args,
+              argsResult: v.argsResult,
+              result: e.result,
+            };
+
+            if (command.autoOutput ?? evalOptions?.autoOutput ?? true) {
+              const outputOrPromise = outputValue(e.result, runtime.output);
+              if (outputOrPromise instanceof Promise) {
+                return outputOrPromise.then(() => commandResult);
+              }
+            }
+
+            return commandResult;
+          });
+        };
+
+        return warnIfUnexpectedAsync(thenMaybe(validatedOrPromise, continueAfterValidate), command) as any;
+      };
+
+      return thenMaybe(parsedOrPromise, continueAfterParse) as any;
     };
-    const envSchema = resolveEnvSchema(command);
-
-    // Determine config data: explicit --config flag > auto-discovered config > provided configData
-    let configData = cliOptions?.configData;
-    if (configPath) {
-      // Explicit config path takes precedence
-      configData = loadConfigFile(configPath);
-    } else if (effectiveConfigFiles?.length) {
-      // Search for config files if configFiles is configured (inherited or own)
-      const foundConfigPath = findConfigFile(effectiveConfigFiles);
-      if (foundConfigPath) {
-        configData = loadConfigFile(foundConfigPath) ?? configData;
+
+    return wrapWithLifecycle(rootPlugins, existingCommand, state, resolvedInput, runPipeline, (result) => ({
+      command: existingCommand,
+      args: undefined,
+      argsResult: undefined,
+      result,
+    })) as any;
+  };
+
+  const evalCommand: AnyPadroneProgram['eval'] = (input, evalOptions) => {
+    return execCommand(input as string, evalOptions, 'soft');
+  };
+
+  /**
+   * 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[] => {
+    const chain: PadronePlugin[][] = [];
+    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();
+  };
 
-    // Validate config data against schema if provided
-    if (configData && configSchema) {
-      const configValidated = configSchema['~standard'].validate(configData);
-      if (configValidated instanceof Promise) {
-        throw new Error('Async validation is not supported. Config schema validate() must return a synchronous result.');
-      }
-      if (configValidated.issues) {
-        const issueMessages = configValidated.issues.map((i) => `  - ${i.path?.join('.') || 'root'}: ${i.message}`).join('\n');
-        throw new Error(`Invalid config file:\n${issueMessages}`);
+  // Forward declaration — assigned by the repl method in the return object, used by cli() for --repl.
+  let replFn: (options?: PadroneReplPreferences) => AsyncIterable<any>;
+  const replActiveRef = { value: false };
+
+  const cli: AnyPadroneProgram['cli'] = (cliOptions) => {
+    const runtime = getCommandRuntime(existingCommand);
+    const resolvedInput = (runtime.argv().join(' ') || undefined) as string | undefined;
+
+    // Check for --repl flag before normal execution
+    if (cliOptions?.repl !== false) {
+      const builtin = checkBuiltinCommands(resolvedInput);
+      if (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 drainRepl = async () => {
+          for await (const _ of replFn(replPrefs)) {
+            // Results are handled by command actions
+          }
+          return { command: existingCommand, args: undefined, result: undefined } as any;
+        };
+        return drainRepl() as any;
       }
-      configData = configValidated.value as unknown as Record<string, unknown>;
     }
 
-    // Validate env vars against schema if provided
-    let envData: Record<string, unknown> | undefined = cliOptions?.envData;
-    if (envSchema) {
-      const rawEnv = cliOptions?.env ?? (typeof process !== 'undefined' ? process.env : {});
-      const envValidated = envSchema['~standard'].validate(rawEnv);
-      if (envValidated instanceof Promise) {
-        throw new Error('Async validation is not supported. Env schema validate() must return a synchronous result.');
-      }
-      // For env vars, we don't throw on validation errors - just use the transformed value if valid
-      // This is because the schema may use .optional() or .default() for missing env vars
-      if (!envValidated.issues) {
-        envData = envValidated.value as unknown as Record<string, unknown>;
+    // 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),
+        );
       }
     }
 
-    // Validate options with env and config data
-    const { options, optionsResult } = validateOptions(command, rawOptions, args, {
-      envData,
-      configData,
-    });
+    const result = execCommand(resolvedInput, cliOptions, 'hard');
 
-    const res = run(command, options) as any;
-    return {
-      ...res,
-      optionsResult,
-    };
+    // Show update notification after command output
+    if (updateCheckPromise) {
+      if (result instanceof Promise) {
+        return result.then(async (r) => {
+          const showUpdateNotification = await updateCheckPromise;
+          showUpdateNotification?.();
+          return r;
+        }) as any;
+      }
+      // For sync results, schedule notification for next tick (non-blocking)
+      updateCheckPromise.then((show) => show?.());
+    }
+
+    return result;
   };
 
-  const run: AnyPadroneProgram['run'] = (command, options) => {
+  const run: AnyPadroneProgram['run'] = (command, args) => {
     const commandObj = typeof command === 'string' ? findCommandByName(command, existingCommand.commands) : (command as AnyPadroneCommand);
-    if (!commandObj) throw new Error(`Command "${command ?? ''}" not found`);
-    if (!commandObj.handler) throw new Error(`Command "${commandObj.path}" has no handler`);
+    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 result = commandObj.handler(options as any);
+    const state: Record<string, unknown> = {};
+    const executeCtx: PluginExecuteContext = { command: commandObj, args, state };
 
-    return {
-      command: commandObj as any,
-      options: options as any,
-      result,
+    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) => ({
+      command: commandObj as any,
+      args: args as any,
+      result: e.result,
+    });
+
+    if (executedOrPromise instanceof Promise) {
+      return executedOrPromise.then(toResult) as any;
+    }
+    return toResult(executedOrPromise);
   };
 
   const tool: AnyPadroneProgram['tool'] = () => {
-    const helpText = generateHelp(existingCommand, undefined, { format: 'text', detail: 'full' });
-
-    const description = `\n
-This is a CLI tool created with Padrone. You can run any of the defined commands described in the help text below. If you need assistance, refer to the documentation or use the help command.
+    const helpText = generateHelp(existingCommand, undefined, { format: 'text' });
 
-<help_output>
-${helpText}
-</help_output>
-`;
+    const description = `Run a command. Pass the full command string including arguments. Use "help <command>" for detailed usage.\n\n${helpText}`;
 
     return {
       type: 'function',
@@ -602,7 +1271,7 @@ ${helpText}
       strict: true,
       title: existingCommand.description,
       description,
-      inputExamples: [{ input: { command: '<command> [args...] [options...]' } }],
+      inputExamples: [{ input: { command: '<command> [positionals...] [arguments...]' } }],
       inputSchema: {
         [Symbol.for('vercel.ai.schema') as keyof Schema & symbol]: true,
         jsonSchema: {
@@ -617,67 +1286,155 @@ ${helpText}
           return { success: false, error: new Error('Expected an object with command property as string.') };
         },
       } satisfies Schema<{ command: string }> as Schema<{ command: string }>,
-      needsApproval: (input) => {
-        const { command, options } = parse(input.command);
-        if (typeof command.needsApproval === 'function') return command.needsApproval(options);
-        return !!command.needsApproval;
+      needsApproval: async (input) => {
+        const parsed = await parse(input.command);
+        if (typeof parsed.command.needsApproval === 'function') return parsed.command.needsApproval(parsed.args);
+        return !!parsed.command.needsApproval;
       },
-      execute: (input) => {
-        return cli(input.command).result;
+      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') };
       },
     };
   };
 
-  return {
+  const builder = {
     configure(config) {
       return createPadroneBuilder({ ...existingCommand, ...config }) as any;
     },
-    options(options, meta) {
-      // If options is a function, call it with parent's options as base
-      const resolvedOptions = typeof options === 'function' ? options(existingCommand.options as any) : options;
-      return createPadroneBuilder({ ...existingCommand, options: resolvedOptions, meta }) 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.options) : (schema ?? existingCommand.options);
-      return createPadroneBuilder({ ...existingCommand, configFiles, config: resolvedConfig as any }) as any;
+      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.options) : schema;
-      return createPadroneBuilder({ ...existingCommand, envSchema: resolvedEnv as any }) as any;
+      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;
     },
     action(handler = noop) {
-      return createPadroneBuilder({ ...existingCommand, handler }) as any;
+      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;
 
-      const initialCommand = {
-        name,
-        path: existingCommand.path ? `${existingCommand.path} ${name}` : name,
-        aliases,
-        parent: existingCommand,
-        '~types': {} as any,
-      } satisfies PadroneCommand;
+      // Check if a command with this name already exists (override case)
+      const existingSubcommand = existingCommand.commands?.find((c) => c.name === name) as AnyPadroneCommand | undefined;
+
+      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);
+
       const builder = createPadroneBuilder(initialCommand);
 
       const commandObj =
         ((builderFn?.(builder as any) as unknown as typeof builder)?.[commandSymbol] as AnyPadroneCommand) ?? initialCommand;
-      return createPadroneBuilder({ ...existingCommand, commands: [...(existingCommand.commands || []), commandObj] }) as any;
+
+      // Merge subcommands when overriding: existing subcommands that aren't replaced are kept
+      const mergedCommandObj = existingSubcommand ? mergeCommands(existingSubcommand, commandObj) : commandObj;
+
+      // Replace existing command or append new one
+      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;
+    },
+
+    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) {
+      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 = (options?: PadroneReplPreferences) => {
+      return createReplIterator({ existingCommand, evalCommand, replActiveRef }, options);
+    }),
+
     api() {
       function buildApi(command: AnyPadroneCommand) {
-        const runCommand = ((options) => run(command, options).result) as PadroneAPI<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;
@@ -686,17 +1443,19 @@ ${helpText}
       return buildApi(existingCommand);
     },
 
-    help(command, options) {
+    help(command, prefs) {
       const commandObj = !command
         ? existingCommand
         : typeof command === 'string'
           ? findCommandByName(command, existingCommand.commands)
           : (command as AnyPadroneCommand);
-      if (!commandObj) throw new Error(`Command "${command ?? ''}" not found`);
-      return generateHelp(existingCommand, commandObj, options);
+      if (!commandObj) throw new RoutingError(`Command "${command ?? ''}" not found`);
+      const runtime = getCommandRuntime(existingCommand);
+      return generateHelp(existingCommand, commandObj, { ...prefs, format: prefs?.format ?? runtime.format });
     },
 
-    completion(shell) {
+    async completion(shell) {
+      const { generateCompletionOutput } = await import('./completion.ts');
       return generateCompletionOutput(existingCommand, shell as ShellType | undefined);
     },
 
@@ -704,4 +1463,5 @@ ${helpText}
 
     [commandSymbol]: existingCommand,
   } satisfies AnyPadroneProgram & { [commandSymbol]: AnyPadroneCommand } as any;
+  return builder as TBuilder & { [commandSymbol]: AnyPadroneCommand };
 }