padrone 1.3.0 → 1.5.0

package/src/mcp.ts

@@ -0,0 +1,390 @@
+import { buildInputSchema, collectEndpoints, serializeArgsToFlags } from './command-utils.ts';
+import { generateHelp } from './help.ts';
+import type { AnyPadroneCommand, AnyPadroneProgram } from './types.ts';
+
+export type PadroneMcpPreferences = {
+  /** Server name. Defaults to the program name. */
+  name?: string;
+  /** Server version. Defaults to the program version. */
+  version?: string;
+  /**
+   * Transport mode.
+   * - `'http'` — Start a Streamable HTTP server (default). Responds with `application/json` or `text/event-stream` based on the client's `Accept` header. Use `port` and `host` to configure.
+   * - `'stdio'` — Communicate over stdin/stdout with newline-delimited JSON.
+   */
+  transport?: 'http' | 'stdio';
+  /** HTTP port. Defaults to `3000`. Only used with `transport: 'http'`. */
+  port?: number;
+  /** HTTP host. Defaults to `'127.0.0.1'`. Only used with `transport: 'http'`. */
+  host?: string;
+  /** Base path for the MCP endpoint. Defaults to `'/mcp'`. Only used with `transport: 'http'`. */
+  basePath?: string;
+  /** CORS allowed origin. Defaults to `'*'`. Set to a specific origin or `false` to disable CORS headers. Only used with HTTP transports. */
+  cors?: string | false;
+};
+
+const PROTOCOL_VERSION = '2025-11-25';
+
+type JsonRpcRequest = {
+  jsonrpc: '2.0';
+  id?: string | number;
+  method: string;
+  params?: Record<string, unknown>;
+};
+
+type JsonRpcResponse = {
+  jsonrpc: '2.0';
+  id: string | number | null;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+};
+
+/** Convert an endpoint dot-path to a valid MCP tool name. Spec allows: [A-Za-z0-9_\-\.] */
+function toToolName(path: string): string {
+  return path.replace(/\s+/g, '.');
+}
+
+/** Convert a tool name back to a command path (dot → space). */
+function toCommandPath(toolName: string): string {
+  return toolName.replace(/\./g, ' ');
+}
+
+/** Build MCP tool annotations from a command's metadata. */
+function buildAnnotations(cmd: AnyPadroneCommand) {
+  if (cmd.mutation == null) return undefined;
+  return {
+    destructiveHint: cmd.mutation || undefined,
+    readOnlyHint: cmd.mutation === false || undefined,
+  };
+}
+
+/** Build an MCP tool definition from a command. */
+function buildToolDefinition(name: string, cmd: AnyPadroneCommand) {
+  return {
+    name: toToolName(name),
+    title: cmd.title ?? undefined,
+    description: cmd.description || cmd.title || `Run the "${name}" command`,
+    inputSchema: buildInputSchema(cmd),
+    annotations: buildAnnotations(cmd),
+  };
+}
+
+/** Create the MCP request handler. Returns an async function that processes a JSON-RPC request and returns a response (or undefined for notifications). */
+export function createMcpHandler(
+  existingCommand: AnyPadroneCommand,
+  evalCommand: AnyPadroneProgram['eval'],
+  prefs?: PadroneMcpPreferences,
+) {
+  const serverName = prefs?.name ?? existingCommand.name;
+  const serverVersion = prefs?.version ?? existingCommand.version ?? '0.0.0';
+
+  const rootTools = collectEndpoints(existingCommand.commands, '');
+  if (existingCommand.action || existingCommand.argsSchema) {
+    rootTools.unshift({ name: '', command: existingCommand });
+  }
+
+  const toolMap = new Map(rootTools.map((t) => [toToolName(t.name), t]));
+
+  const helpToolName = 'help';
+  const helpToolDef = {
+    name: helpToolName,
+    title: 'Help',
+    description: `Show help for the "${serverName}" program or a specific command`,
+    inputSchema: {
+      type: 'object' as const,
+      properties: { command: { type: 'string', description: 'Command name to get help for (omit for program help)' } },
+      additionalProperties: false,
+    },
+  };
+
+  return async function handleRequest(req: JsonRpcRequest): Promise<JsonRpcResponse | undefined> {
+    const { id, method, params } = req;
+
+    switch (method) {
+      case 'initialize':
+        return {
+          jsonrpc: '2.0',
+          id: id ?? null,
+          result: {
+            protocolVersion: PROTOCOL_VERSION,
+            capabilities: { tools: {} },
+            serverInfo: { name: serverName, version: serverVersion },
+          },
+        };
+
+      case 'notifications/initialized':
+      case 'notifications/cancelled':
+        return undefined;
+
+      case 'ping':
+        return { jsonrpc: '2.0', id: id ?? null, result: {} };
+
+      case 'tools/list': {
+        const tools = [...rootTools.map((t) => buildToolDefinition(t.name, t.command)), helpToolDef];
+        return { jsonrpc: '2.0', id: id ?? null, result: { tools } };
+      }
+
+      case 'tools/call': {
+        const toolName = params?.name as string;
+        const args = (params?.arguments ?? {}) as Record<string, unknown>;
+
+        // Built-in help tool
+        if (toolName === helpToolName) {
+          const cmdName = args.command as string | undefined;
+          const targetCmd = cmdName ? rootTools.find((t) => t.name === cmdName || toToolName(t.name) === cmdName)?.command : undefined;
+          const helpText = generateHelp(existingCommand, targetCmd ?? existingCommand, { format: 'text', detail: 'full' });
+          return {
+            jsonrpc: '2.0',
+            id: id ?? null,
+            result: { content: [{ type: 'text', text: helpText }], isError: false },
+          };
+        }
+
+        const tool = toolMap.get(toolName);
+        if (!tool) {
+          return {
+            jsonrpc: '2.0',
+            id: id ?? null,
+            error: { code: -32602, message: `Unknown tool: ${toolName}` },
+          };
+        }
+
+        // Build command string: convert tool name back to command path + serialize args as flags
+        const commandPath = toCommandPath(tool.name);
+        const argParts = serializeArgsToFlags(args);
+        const input = [commandPath, ...argParts].filter(Boolean).join(' ') || undefined;
+
+        try {
+          const output: string[] = [];
+          const errors: string[] = [];
+          const result = await evalCommand(input as any, {
+            autoOutput: false,
+            runtime: {
+              output: (...outArgs: unknown[]) => output.push(outArgs.map(String).join(' ')),
+              error: (text: string) => errors.push(text),
+              interactive: 'unsupported',
+              format: 'text',
+            },
+          });
+
+          const content: { type: string; text: string }[] = [];
+
+          if (result.error) {
+            const errorMsg = result.error instanceof Error ? result.error.message : String(result.error);
+            if (errors.length) content.push({ type: 'text', text: errors.join('\n') });
+            content.push({ type: 'text', text: errorMsg });
+            return { jsonrpc: '2.0', id: id ?? null, result: { content, isError: true } };
+          }
+
+          if (result.argsResult?.issues) {
+            const issueMessages = result.argsResult.issues.map((i: any) => `${i.path?.join('.') || 'root'}: ${i.message}`).join('\n');
+            content.push({ type: 'text', text: `Validation error:\n${issueMessages}` });
+            return { jsonrpc: '2.0', id: id ?? null, result: { content, isError: true } };
+          }
+
+          if (output.length) content.push({ type: 'text', text: output.join('\n') });
+          if (result.result !== undefined && result.result !== null) {
+            const resultText = typeof result.result === 'string' ? result.result : JSON.stringify(result.result, null, 2);
+            content.push({ type: 'text', text: resultText });
+          }
+          if (content.length === 0) content.push({ type: 'text', text: 'Done.' });
+          return { jsonrpc: '2.0', id: id ?? null, result: { content, isError: false } };
+        } catch (err) {
+          const errorMsg = err instanceof Error ? err.message : String(err);
+          return {
+            jsonrpc: '2.0',
+            id: id ?? null,
+            result: { content: [{ type: 'text', text: errorMsg }], isError: true },
+          };
+        }
+      }
+
+      default: {
+        if (id !== undefined) {
+          return { jsonrpc: '2.0', id, error: { code: -32601, message: `Method not found: ${method}` } };
+        }
+        return undefined;
+      }
+    }
+  };
+}
+
+/** stdio transport: newline-delimited JSON per 2025-11-25 spec. */
+async function startStdioTransport(handleRequest: (req: JsonRpcRequest) => Promise<JsonRpcResponse | undefined>): Promise<void> {
+  const { stdin, stdout } = await import('node:process');
+  const { createInterface } = await import('node:readline');
+
+  function send(msg: JsonRpcResponse) {
+    stdout.write(`${JSON.stringify(msg)}\n`);
+  }
+
+  const rl = createInterface({ input: stdin, crlfDelay: Infinity });
+
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+    try {
+      const req = JSON.parse(line) as JsonRpcRequest;
+      const res = await handleRequest(req);
+      if (res) send(res);
+    } catch {
+      // Ignore malformed JSON
+    }
+  }
+}
+
+/** Streamable HTTP transport per 2025-11-25 spec. Responds with JSON or SSE based on client's Accept header. */
+async function startHttpTransport(
+  handleRequest: (req: JsonRpcRequest) => Promise<JsonRpcResponse | undefined>,
+  prefs: PadroneMcpPreferences,
+  log: (msg: string) => void,
+): Promise<void> {
+  const http = await import('node:http');
+  const crypto = await import('node:crypto');
+
+  const port = prefs.port ?? 3000;
+  const host = prefs.host ?? '127.0.0.1';
+  const endpoint = prefs.basePath ?? '/mcp';
+
+  // Session management
+  let sessionId: string | undefined;
+  let negotiatedVersion: string | undefined;
+
+  const corsOrigin = prefs.cors !== false ? (prefs.cors ?? '*') : undefined;
+
+  const server = http.createServer(async (req, res) => {
+    // CORS headers
+    if (corsOrigin) {
+      res.setHeader('Access-Control-Allow-Origin', corsOrigin);
+      res.setHeader('Access-Control-Allow-Methods', 'POST, GET, DELETE, OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type, MCP-Session-Id, MCP-Protocol-Version');
+      res.setHeader('Access-Control-Expose-Headers', 'MCP-Session-Id');
+    }
+
+    if (req.method === 'OPTIONS') {
+      res.writeHead(corsOrigin ? 204 : 405);
+      res.end();
+      return;
+    }
+
+    if (req.url !== endpoint) {
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ error: 'Not found' }));
+      return;
+    }
+
+    // DELETE: terminate session
+    if (req.method === 'DELETE') {
+      const reqSessionId = req.headers['mcp-session-id'] as string | undefined;
+      if (sessionId && reqSessionId === sessionId) {
+        sessionId = undefined;
+        negotiatedVersion = undefined;
+        res.writeHead(200);
+        res.end();
+      } else {
+        res.writeHead(404);
+        res.end();
+      }
+      return;
+    }
+
+    // GET: SSE stream (not implemented — return 405)
+    if (req.method === 'GET') {
+      res.writeHead(405, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32601, message: 'SSE stream not supported' } }));
+      return;
+    }
+
+    if (req.method !== 'POST') {
+      res.writeHead(405);
+      res.end();
+      return;
+    }
+
+    // Validate session ID on non-initialize requests
+    const reqSessionId = req.headers['mcp-session-id'] as string | undefined;
+    if (sessionId && reqSessionId && reqSessionId !== sessionId) {
+      res.writeHead(404, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Invalid session' } }));
+      return;
+    }
+
+    // Validate MCP-Protocol-Version header on post-init requests
+    const reqProtocolVersion = req.headers['mcp-protocol-version'] as string | undefined;
+    if (negotiatedVersion && reqProtocolVersion && reqProtocolVersion !== negotiatedVersion) {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32600, message: 'Protocol version mismatch' } }));
+      return;
+    }
+
+    // Read request body
+    const chunks: Buffer[] = [];
+    for await (const chunk of req) {
+      chunks.push(chunk);
+    }
+    const body = Buffer.concat(chunks).toString('utf-8');
+
+    let rpcRequest: JsonRpcRequest;
+    try {
+      rpcRequest = JSON.parse(body);
+    } catch {
+      res.writeHead(400, { 'Content-Type': 'application/json' });
+      res.end(JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } }));
+      return;
+    }
+
+    const response = await handleRequest(rpcRequest);
+
+    // On initialize response: create session and set header
+    if (rpcRequest.method === 'initialize' && response?.result) {
+      sessionId = crypto.randomUUID();
+      negotiatedVersion = PROTOCOL_VERSION;
+      res.setHeader('MCP-Session-Id', sessionId);
+    }
+
+    if (response) {
+      const accept = req.headers.accept ?? '';
+      if (accept.includes('text/event-stream')) {
+        res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', Connection: 'keep-alive' });
+        res.write(`event: message\ndata: ${JSON.stringify(response)}\n\n`);
+        res.end();
+      } else {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify(response));
+      }
+    } else {
+      // Notification or response from client — no body
+      res.writeHead(202);
+      res.end();
+    }
+  });
+
+  return new Promise<void>((resolve, reject) => {
+    server.listen(port, host, () => {
+      log(`MCP server listening on http://${host}:${port}${endpoint}`);
+    });
+    server.on('error', reject);
+    const onSignal = () => {
+      server.close(() => resolve());
+    };
+    process.on('SIGINT', onSignal);
+    process.on('SIGTERM', onSignal);
+  });
+}
+
+export async function startMcpServer(
+  _program: AnyPadroneProgram,
+  existingCommand: AnyPadroneCommand,
+  evalCommand: AnyPadroneProgram['eval'],
+  prefs?: PadroneMcpPreferences,
+): Promise<void> {
+  const handleRequest = createMcpHandler(existingCommand, evalCommand, prefs);
+  const transport = prefs?.transport ?? 'http';
+
+  if (transport === 'stdio') {
+    return startStdioTransport(handleRequest);
+  }
+
+  const { getCommandRuntime } = await import('./command-utils.ts');
+  const runtime = getCommandRuntime(existingCommand);
+  return startHttpTransport(handleRequest, prefs ?? {}, (msg) => runtime.error(msg));
+}

package/src/repl-loop.ts

@@ -13,7 +13,7 @@ export type ReplDeps = {
 /**
  * Creates a REPL async iterable for running commands interactively.
  */
-export function createReplIterator(deps: ReplDeps, options?: PadroneReplPreferences): AsyncIterable<any> {
+export function createReplIterator(deps: ReplDeps, options?: PadroneReplPreferences): AsyncIterable<any> & { drain: () => Promise<any> } {
   const { existingCommand, evalCommand, replActiveRef } = deps;
 
   if (replActiveRef.value) {
@@ -291,7 +291,10 @@ export function createReplIterator(deps: ReplDeps, options?: PadroneReplPreferen
         try {
           const replEvalPrefs: PadroneEvalPreferences | undefined = options?.autoOutput === false ? { autoOutput: false } : undefined;
           const result = await evalCommand(scopedInput, replEvalPrefs);
-          if (result.argsResult?.issues) {
+          if (result.error) {
+            const msg = result.error instanceof Error ? result.error.message : String(result.error);
+            runtime.error(prefixLines ? prefixLines(msg) : msg);
+          } else if (result.argsResult?.issues) {
             const issueMessages = result.argsResult.issues
               .map((i: StandardSchemaV1.Issue) => `  - ${i.path?.join('.') || 'root'}: ${i.message}`)
               .join('\n');
@@ -313,5 +316,15 @@ export function createReplIterator(deps: ReplDeps, options?: PadroneReplPreferen
     }
   }
 
-  return replIterator() as any;
+  const iterable = replIterator();
+  (iterable as any).drain = async () => {
+    try {
+      const results: any[] = [];
+      for await (const result of iterable) results.push(result);
+      return { value: results };
+    } catch (err) {
+      return { error: err };
+    }
+  };
+  return iterable as any;
 }

package/src/runtime.ts

@@ -1,6 +1,48 @@
+import type { ColorConfig, ColorTheme } from './colorizer.ts';
 import type { HelpFormat } from './formatter.ts';
 import { findConfigFile, loadConfigFile } from './utils.ts';
 
+/**
+ * A progress indicator instance (spinner, progress bar, etc).
+ * Created by the runtime's `progress` factory and used to show loading state during command execution.
+ */
+export type PadroneProgressIndicator = {
+  /** Update the displayed message. */
+  update: (message: string) => void;
+  /** Mark as succeeded and stop. Pass `null` to stop without rendering a final message. */
+  succeed: (message?: string | null, options?: { indicator?: string }) => void;
+  /** Mark as failed and stop. Pass `null` to stop without rendering a final message. */
+  fail: (message?: string | null, options?: { indicator?: string }) => void;
+  /** Stop without success/fail status. */
+  stop: () => void;
+  /** Temporarily hide the indicator so other output can be written cleanly. */
+  pause: () => void;
+  /** Redraw the indicator after a `pause()`. */
+  resume: () => void;
+};
+
+/** Built-in spinner presets. */
+export type PadroneSpinnerPreset = 'dots' | 'line' | 'arc' | 'bounce';
+
+/**
+ * Spinner configuration for progress indicators.
+ * - A preset name (e.g., `'dots'`) to use built-in frames.
+ * - An object with custom `frames` and/or `interval`.
+ * - `false` to disable the spinner animation (static text only).
+ */
+export type PadroneSpinnerConfig = PadroneSpinnerPreset | { frames?: string[]; interval?: number } | false;
+
+/**
+ * Options passed to the runtime's `progress` factory.
+ */
+export type PadroneProgressOptions = {
+  spinner?: PadroneSpinnerConfig;
+  /** Character/string shown before the success message. Defaults to `'✔'`. */
+  successIndicator?: string;
+  /** Character/string shown before the error message. Defaults to `'✖'`. */
+  errorIndicator?: string;
+};
+
 /**
  * Controls interactive prompting capability and default behavior at the runtime level.
  * - `'supported'` — capable; caller decides.
@@ -45,6 +87,8 @@ export type PadroneRuntime = {
   env?: () => Record<string, string | undefined>;
   /** Default help output format. */
   format?: HelpFormat | 'auto';
+  /** Color theme for ANSI/console help output. A theme name or partial color config. */
+  theme?: ColorTheme | ColorConfig;
   /** Load and parse a config file by path. Return undefined if not found or unparsable. */
   loadConfigFile?: (path: string) => Record<string, unknown> | undefined;
   /** Find the first existing file from a list of candidate names. */
@@ -81,6 +125,12 @@ export type PadroneRuntime = {
    * When `interactive` is `true` and this is not provided, defaults to an Enquirer-based terminal prompt.
    */
   prompt?: (config: InteractivePromptConfig) => Promise<unknown>;
+  /**
+   * Create a progress indicator (spinner, progress bar, etc).
+   * Used by commands that set `progress` in their config, or manually via `ctx.progress()` in actions.
+   * When not provided, auto-progress is silently skipped and `ctx.progress()` returns a no-op indicator.
+   */
+  progress?: (message: string, options?: PadroneProgressOptions) => PadroneProgressIndicator;
   /**
    * Read a line of input from the user. Used by `repl()` for custom runtimes
    * (web UIs, chat interfaces, testing).
@@ -97,8 +147,10 @@ export type PadroneRuntime = {
  * Internal resolved runtime where all fields are guaranteed to be present.
  * The `prompt`, `interactive`, and `readLine` fields remain optional since not all runtimes provide them.
  */
-export type ResolvedPadroneRuntime = Required<Omit<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin'>> &
-  Pick<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin'>;
+export type ResolvedPadroneRuntime = Required<
+  Omit<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin' | 'progress' | 'theme'>
+> &
+  Pick<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin' | 'progress' | 'theme'>;
 
 /**
  * Default terminal prompt implementation powered by Enquirer.
@@ -255,6 +307,135 @@ function createDefaultStdin(): NonNullable<PadroneRuntime['stdin']> {
   };
 }
 
+const spinnerPresets: Record<PadroneSpinnerPreset, string[]> = {
+  dots: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
+  line: ['-', '\\', '|', '/'],
+  arc: ['◜', '◠', '◝', '◞', '◡', '◟'],
+  bounce: ['⠁', '⠂', '⠄', '⡀', '⢀', '⠠', '⠐', '⠈'],
+};
+
+function resolveSpinnerConfig(config?: PadroneSpinnerConfig): { frames: string[]; interval: number; disabled: boolean } {
+  if (config === false) return { frames: [], interval: 80, disabled: true };
+  if (typeof config === 'string') return { frames: spinnerPresets[config], interval: 80, disabled: false };
+  if (typeof config === 'object') {
+    return {
+      frames: config.frames ?? spinnerPresets.dots,
+      interval: config.interval ?? 80,
+      disabled: false,
+    };
+  }
+  return { frames: spinnerPresets.dots, interval: 80, disabled: false };
+}
+
+/**
+ * Creates a built-in terminal spinner. Returns a no-op indicator in non-TTY/CI environments.
+ */
+function createTerminalSpinner(message: string, options?: PadroneProgressOptions): PadroneProgressIndicator {
+  const { frames, interval, disabled: spinnerDisabled } = resolveSpinnerConfig(options?.spinner);
+  const successIcon = options?.successIndicator ?? '✔';
+  const errorIcon = options?.errorIndicator ?? '✖';
+
+  const formatFinal = (icon: string, msg: string) => (icon ? `${icon} ${msg}\n` : `${msg}\n`);
+
+  if (typeof process === 'undefined' || !process.stderr?.isTTY) {
+    // Non-TTY: just log start/end, no animation
+    return {
+      update() {},
+      succeed(msg, opts) {
+        if (msg === null) return;
+        const icon = opts?.indicator ?? successIcon;
+        if (msg || message) process?.stderr?.write?.(formatFinal(icon, msg || message));
+      },
+      fail(msg, opts) {
+        if (msg === null) return;
+        const icon = opts?.indicator ?? errorIcon;
+        if (msg || message) process?.stderr?.write?.(formatFinal(icon, msg || message));
+      },
+      stop() {},
+      pause() {},
+      resume() {},
+    };
+  }
+
+  // If spinner is disabled and there's no message, nothing to render
+  if (spinnerDisabled && !message) {
+    return { update() {}, succeed() {}, fail() {}, stop() {}, pause() {}, resume() {} };
+  }
+
+  let frame = 0;
+  let text = message;
+  let stopped = false;
+  let paused = false;
+
+  const writeStderr = process.stderr.write.bind(process.stderr);
+  const writeStdout = process.stdout.write.bind(process.stdout);
+  const clearLine = () => writeStderr('\x1b[2K\r');
+
+  const render = () => {
+    if (paused || stopped) return;
+    if (spinnerDisabled) {
+      // Static text only, no spinner frames
+      if (text) writeStderr(`\x1b[2K\r${text}`);
+    } else {
+      const prefix = frames[frame] ?? '';
+      writeStderr(`\x1b[2K\r${text ? `${prefix} ${text}` : prefix}`);
+    }
+  };
+
+  const timer = spinnerDisabled
+    ? undefined
+    : setInterval(() => {
+        frame = (frame + 1) % frames.length;
+        render();
+      }, interval);
+
+  render();
+
+  const clear = () => {
+    if (stopped) return;
+    stopped = true;
+    paused = false;
+    if (timer) clearInterval(timer);
+    clearLine();
+  };
+
+  return {
+    update(msg) {
+      if (stopped) return;
+      text = msg;
+      render();
+    },
+    succeed(msg, opts) {
+      clear();
+      if (msg === null) return;
+      const finalMsg = msg ?? text;
+      const icon = opts?.indicator ?? successIcon;
+      if (finalMsg) writeStderr(formatFinal(icon, finalMsg));
+    },
+    fail(msg, opts) {
+      clear();
+      if (msg === null) return;
+      const finalMsg = msg ?? text;
+      const icon = opts?.indicator ?? errorIcon;
+      if (finalMsg) writeStderr(formatFinal(icon, finalMsg));
+    },
+    stop() {
+      clear();
+    },
+    pause() {
+      if (stopped || paused) return;
+      paused = true;
+      clearLine();
+      writeStdout('\x1b[2K\r');
+    },
+    resume() {
+      if (stopped || !paused) return;
+      paused = false;
+      render();
+    },
+  };
+}
+
 export function createDefaultRuntime(): ResolvedPadroneRuntime {
   return {
     output: (...args) => console.log(...args),
@@ -266,6 +447,7 @@ export function createDefaultRuntime(): ResolvedPadroneRuntime {
     findFile: findConfigFile,
     prompt: defaultTerminalPrompt,
     interactive: detectInteractiveMode(),
+    progress: createTerminalSpinner,
   };
 }
 
@@ -285,6 +467,15 @@ export function resolveStdin(partial?: PadroneRuntime): NonNullable<PadroneRunti
   return defaultStdin;
 }
 
+/**
+ * Like `resolveStdin`, but always returns a stdin source even when it's a TTY.
+ * Used for async streams which support interactive (non-piped) input.
+ */
+export function resolveStdinAlways(partial?: PadroneRuntime): NonNullable<PadroneRuntime['stdin']> {
+  if (partial?.stdin) return partial.stdin;
+  return createDefaultStdin();
+}
+
 export function resolveRuntime(partial?: PadroneRuntime): ResolvedPadroneRuntime {
   const defaults = createDefaultRuntime();
   if (!partial) return defaults;
@@ -299,6 +490,8 @@ export function resolveRuntime(partial?: PadroneRuntime): ResolvedPadroneRuntime
     interactive: partial.interactive ?? defaults.interactive,
     prompt: partial.prompt ?? defaults.prompt,
     readLine: partial.readLine ?? defaults.readLine,
+    progress: partial.progress ?? defaults.progress,
     stdin: partial.stdin,
+    theme: partial.theme,
   };
 }