padrone 1.4.0 → 1.5.0

package/src/create.ts

@@ -1,21 +1,42 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
 import type { Schema } from 'ai';
-import { coerceArgs, detectUnknownArgs, extractSchemaMetadata, parsePositionalConfig, parseStdinConfig, preprocessArgs } from './args.ts';
+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';
@@ -24,7 +45,8 @@ import { generateHelp } from './help.ts';
 import { promptInteractiveFields } from './interactive.ts';
 import { getNestedValue, parseCliInputToParts, setNestedValue } from './parse.ts';
 import { createReplIterator } from './repl-loop.ts';
-import { resolveStdin } from './runtime.ts';
+import { type PadroneProgressIndicator, resolveStdin, resolveStdinAlways } from './runtime.ts';
+import { createStdinStream } from './stream.ts';
 import type {
   AnyPadroneCommand,
   AnyPadroneProgram,
@@ -65,11 +87,14 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
       : 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 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;
@@ -136,7 +161,7 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
     const arrayArguments = new Set<string>();
     if (curCommand.argsSchema) {
       try {
-        const jsonSchema = curCommand.argsSchema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+        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);
@@ -352,16 +377,24 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
           const stdinConfig = command.meta?.stdin;
           if (!stdinConfig) return {};
 
-          const { field, as } = parseStdinConfig(stdinConfig);
+          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 (as === 'lines') {
+          if (isArrayField(command.argsSchema, field)) {
             return (async () => {
               const lines: string[] = [];
               for await (const line of stdin.lines()) {
@@ -499,10 +532,13 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
   const checkBuiltinCommands = (
     input: string | undefined,
   ):
-    | { type: 'help'; command?: AnyPadroneCommand; detail?: DetailLevel; format?: FormatLevel }
+    | { 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;
 
@@ -516,18 +552,21 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
     // 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>
+    // 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') && typeof arg.value === 'string') {
-          if (arg.value === 'minimal' || arg.value === 'standard' || arg.value === 'full') {
+        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') && typeof arg.value === 'string') {
-          if (arg.value === 'minimal' || arg.value === 'standard' || arg.value === '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;
@@ -553,6 +592,9 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
     };
     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'))),
@@ -573,7 +615,7 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
       // 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 };
+      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)
@@ -590,7 +632,7 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
           break;
         }
       }
-      return { type: 'help', command: targetCommand, detail, format };
+      return { type: 'help', command: targetCommand, detail, format, all: hasAllFlag || undefined };
     }
 
     // Check for 'version' command (only if user hasn't defined one)
@@ -607,13 +649,21 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
       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 };
+      return { type: 'help', command: targetCommand, detail, format, all: hasAllFlag || undefined };
     }
 
     // Handle version flag (only for root command, i.e., no subcommand terms)
@@ -621,6 +671,32 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
       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) {
@@ -651,6 +727,35 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
     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:
@@ -659,38 +764,51 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
    */
   const execCommand = (resolvedInput: string | undefined, evalOptions?: PadroneEvalPreferences, errorMode: 'soft' | 'hard' = 'soft') => {
     const baseRuntime = getCommandRuntime(existingCommand);
-    const runtime = evalOptions?.runtime
+    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 {
+        return withDrain({
           command: existingCommand,
           args: undefined,
           result: helpText,
-        } as any;
+        }) as any;
       }
 
       if (builtin.type === 'version') {
         const version = getVersion(existingCommand.version);
         runtime.output(version);
-        return {
+        return withDrain({
           command: existingCommand,
           args: undefined,
           result: version,
-        } as any;
+        }) as any;
       }
 
       if (builtin.type === 'completion') {
+        resolveAllCommands(existingCommand);
         return import('./completion.ts').then(({ detectShell, generateCompletionOutput, setupCompletions }) => {
           if (builtin.setup) {
             const shell = builtin.shell ?? detectShell();
@@ -700,19 +818,57 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
             const result = setupCompletions(existingCommand.name, shell);
             const message = `${result.updated ? 'Updated' : 'Added'} ${existingCommand.name} completions in ${result.file}`;
             runtime.output(message);
-            return {
+            return withDrain({
               command: existingCommand,
               args: undefined,
               result: message,
-            };
+            });
           }
           const completionScript = generateCompletionOutput(existingCommand, builtin.shell);
           runtime.output(completionScript);
-          return {
+          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;
       }
     }
@@ -732,7 +888,8 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
         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 });
+          resolveAllCommands(existingCommand);
+          const helpText = generateHelp(existingCommand, command, { format: runtime.format, theme: runtime.theme });
           runtime.output(helpText);
           return {
             command: command,
@@ -785,7 +942,11 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
                   runtime.output(`\nAvailable commands: ${cmdList}`);
                 }
               } else {
-                const helpText = generateHelp(existingCommand, isRootCommand ? existingCommand : command, { format: runtime.format });
+                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 });
@@ -817,6 +978,40 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
           } 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,
@@ -839,6 +1034,10 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
             }
           }
 
+          // 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;
@@ -928,17 +1127,24 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
             const stdinConfig = command.meta?.stdin;
             if (!stdinConfig) return {};
 
-            const { field, as } = parseStdinConfig(stdinConfig);
+            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 (as === 'lines') {
+            if (isArrayField(command.argsSchema, field)) {
               return (async () => {
                 const lines: string[] = [];
                 for await (const line of stdin.lines()) {
@@ -1057,7 +1263,7 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
               knownOptions = [];
               if (command.argsSchema) {
                 try {
-                  const js = command.argsSchema['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+                  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 */
@@ -1082,7 +1288,8 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
               .join('\n');
 
             if (errorMode === 'hard') {
-              const helpText = generateHelp(existingCommand, command, { format: runtime.format });
+              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, {
@@ -1096,12 +1303,18 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
             }
 
             // Soft mode: return result with issues, skip the action
-            return {
+            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 = {
@@ -1112,7 +1325,11 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
 
           const coreExecute = (): PluginExecuteResult => {
             const handler = command.action ?? noop;
-            const ctx = evalOptions?.runtime ? { ...createActionContext(command), runtime } : createActionContext(command);
+            const ctx: PadroneActionContext = {
+              ...createActionContext(command),
+              runtime,
+              progress: (state._progress as PadroneProgressIndicator) ?? createLazyIndicator(runtime, state),
+            };
             const result = handler(executeCtx.args as any, ctx);
             return { result };
           };
@@ -1120,21 +1337,62 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
           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,
-            };
+            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(e.result, runtime.output);
-              if (outputOrPromise instanceof Promise) {
-                return outputOrPromise.then(() => commandResult);
+              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 commandResult;
+            return finalize(e.result);
           });
         };
 
@@ -1144,16 +1402,24 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
       return thenMaybe(parsedOrPromise, continueAfterParse) as any;
     };
 
-    return wrapWithLifecycle(rootPlugins, existingCommand, state, resolvedInput, runPipeline, (result) => ({
-      command: existingCommand,
-      args: undefined,
-      argsResult: undefined,
-      result,
-    })) 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) => {
-    return makeThenable(execCommand(input as string, evalOptions, 'soft'));
+    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;
+    }
   };
 
   /**
@@ -1166,8 +1432,8 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
    * `.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[][] = [];
+  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
@@ -1183,94 +1449,143 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
   };
 
   // Forward declaration — assigned by the repl method in the return object, used by cli() for --repl.
-  let replFn: (options?: PadroneReplPreferences) => AsyncIterable<any>;
+  const replFn = (options?: PadroneReplPreferences) => {
+    return createReplIterator({ existingCommand, evalCommand, replActiveRef }, options);
+  };
   const replActiveRef = { value: false };
 
   const cli: AnyPadroneProgram['cli'] = (cliOptions) => {
-    const runtime = getCommandRuntime(existingCommand);
-    const resolvedInput = (runtime.argv().join(' ') || undefined) as string | undefined;
+    try {
+      const runtime = getCommandRuntime(existingCommand);
+      const resolvedInput = (runtime.argv().join(' ') || undefined) as string | undefined;
 
-    // Check for --repl flag before normal execution
-    if (cliOptions?.repl !== false) {
+      // Check for --repl flag and mcp command before normal execution
       const builtin = checkBuiltinCommands(resolvedInput);
-      if (builtin?.type === 'repl') {
+
+      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 () => {
-          for await (const _ of replFn(replPrefs)) {
-            // Results are handled by command actions
-          }
-          return { command: existingCommand, args: undefined, result: undefined } as any;
+          const { value } = await repl.drain();
+          return withDrain({ command: existingCommand, args: undefined, result: value }) as any;
         };
-        return drainRepl() as any;
+        return withPromiseDrain(drainRepl()) 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),
-        );
+      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;
       }
-    }
 
-    const result = execCommand(resolvedInput, cliOptions, 'hard');
+      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;
+      }
 
-    // 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;
+      // 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?.());
       }
-      // For sync results, schedule notification for next tick (non-blocking)
-      updateCheckPromise.then((show) => show?.());
-    }
 
-    return makeThenable(result);
+      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) => {
-    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 });
+    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 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 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 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,
-    });
+      const toResult = (e: PluginExecuteResult) =>
+        withDrain({
+          command: commandObj as any,
+          args: args as any,
+          result: e.result,
+        });
 
-    if (executedOrPromise instanceof Promise) {
-      return executedOrPromise.then(toResult) as any;
+      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;
     }
-    return toResult(executedOrPromise);
   };
 
   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}`;
@@ -1299,7 +1614,8 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
       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;
+        if (parsed.command.needsApproval != null) return !!parsed.command.needsApproval;
+        return !!parsed.command.mutation;
       },
       execute: async (input) => {
         const output: string[] = [];
@@ -1345,6 +1661,10 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
       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({
@@ -1364,6 +1684,9 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
       // 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 }
         : ({
@@ -1374,21 +1697,33 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
             '~types': {} as any,
           } satisfies PadroneCommand);
 
-      const builder = createPadroneBuilder(initialCommand);
+      // 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 commandObj =
-        ((builderFn?.(builder as any) as unknown as typeof builder)?.[commandSymbol] as AnyPadroneCommand) ?? initialCommand;
+        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];
 
-      // Merge subcommands when overriding: existing subcommands that aren't replaced are kept
-      const mergedCommandObj = existingSubcommand ? mergeCommands(existingSubcommand, commandObj) : commandObj;
+        return createPadroneBuilder({ ...existingCommand, commands: updatedCommands }) as any;
+      }
 
-      // Replace existing command or append new one
+      // 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), mergedCommandObj, ...commands.slice(existingIndex + 1)]
-          : [...commands, mergedCommandObj];
+          ? [...commands.slice(0, existingIndex), initialCommand, ...commands.slice(existingIndex + 1)]
+          : [...commands, initialCommand];
 
       return createPadroneBuilder({ ...existingCommand, commands: updatedCommands }) as any;
     },
@@ -1419,7 +1754,7 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
       return createPadroneBuilder({ ...existingCommand, commands: updatedCommands }) as any;
     },
 
-    use(plugin: PadronePlugin) {
+    use(plugin: PadronePlugin<any, any>) {
       return createPadroneBuilder({
         ...existingCommand,
         plugins: [...(existingCommand.plugins ?? []), plugin],
@@ -1438,11 +1773,10 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
     cli,
     tool,
 
-    repl: (replFn = (options?: PadroneReplPreferences) => {
-      return createReplIterator({ existingCommand, evalCommand, replActiveRef }, options);
-    }),
+    repl: replFn,
 
     api() {
+      resolveAllCommands(existingCommand);
       function buildApi(command: AnyPadroneCommand) {
         const runCommand = ((args) => run(command, args).result) as PadroneAPI<AnyPadroneCommand>;
         if (!command.commands) return runCommand;
@@ -1454,6 +1788,7 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
     },
 
     help(command, prefs) {
+      resolveAllCommands(existingCommand);
       const commandObj = !command
         ? existingCommand
         : typeof command === 'string'
@@ -1461,14 +1796,31 @@ export function createPadroneBuilder<TBuilder extends PadroneProgram = PadronePr
           : (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 });
+      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,