padrone 1.4.0 → 1.6.0

package/src/{runtime.ts → core/default-runtime.ts}

@@ -1,104 +1,13 @@
-import type { HelpFormat } from './formatter.ts';
-import { findConfigFile, loadConfigFile } from './utils.ts';
-
-/**
- * Controls interactive prompting capability and default behavior at the runtime level.
- * - `'supported'` — capable; caller decides.
- * - `'unsupported'` — hard veto; nothing can override.
- * - `'forced'` — capable and forces prompts by default.
- * - `'disabled'` — capable but suppresses prompts by default.
- */
-export type InteractiveMode = 'supported' | 'unsupported' | 'forced' | 'disabled';
-
-/**
- * Configuration passed to the runtime's `prompt` function for interactive field prompting.
- * The prompt type and choices are auto-detected from the field's JSON schema.
- */
-export type InteractivePromptConfig = {
-  /** The field name being prompted. */
-  name: string;
-  /** Human-readable message/label for the prompt, derived from the field's description or name. */
-  message: string;
-  /** The prompt type, auto-detected from the JSON schema. */
-  type: 'input' | 'confirm' | 'select' | 'multiselect' | 'password';
-  /** Available choices for select/multiselect prompts. */
-  choices?: { label: string; value: unknown }[];
-  /** Default value from the schema. */
-  default?: unknown;
-};
-
-/**
- * Defines the execution context for a Padrone program.
- * Abstracts all environment-dependent I/O so the CLI framework
- * can run outside of a terminal (e.g., web UIs, chat interfaces, testing).
- *
- * All fields are optional — unspecified fields fall back to the Node.js/Bun defaults.
- */
-export type PadroneRuntime = {
-  /** Write normal output (replaces console.log). Receives the raw value — runtime handles formatting. */
-  output?: (...args: unknown[]) => void;
-  /** Write error output (replaces console.error). */
-  error?: (text: string) => void;
-  /** Return the raw CLI arguments (replaces process.argv.slice(2)). */
-  argv?: () => string[];
-  /** Return environment variables (replaces process.env). */
-  env?: () => Record<string, string | undefined>;
-  /** Default help output format. */
-  format?: HelpFormat | 'auto';
-  /** 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. */
-  findFile?: (names: string[]) => string | undefined;
-  /**
-   * Standard input abstraction. Provides methods to read piped data from stdin.
-   * When not provided, defaults to reading from `process.stdin`.
-   *
-   * Used by commands that declare a `stdin` field in their arguments meta.
-   * The framework reads stdin automatically during the validate phase and
-   * injects the data into the specified argument field.
-   */
-  stdin?: {
-    /** Whether stdin is a TTY (interactive terminal) vs a pipe/file. */
-    isTTY?: boolean;
-    /** Read all of stdin as a string. */
-    text: () => Promise<string>;
-    /** Async iterable of lines for streaming. */
-    lines: () => AsyncIterable<string>;
-  };
-  /**
-   * Controls interactive prompting capability and default behavior.
-   * - `'supported'` — runtime can handle prompts; caller (flag/pref) decides whether to prompt. This is the default when `prompt` is provided.
-   * - `'unsupported'` — runtime cannot handle prompts; hard veto that nothing can override.
-   * - `'forced'` — runtime supports prompts and forces them by default (prompts even for provided values).
-   * - `'disabled'` — runtime supports prompts but suppresses them by default.
-   *
-   * `'unsupported'` is the only immutable state. For the others, the `--interactive`/`-i` flag
-   * and `cli()` preferences can override the default behavior.
-   */
-  interactive?: InteractiveMode;
-  /**
-   * Prompt the user for input. Called during `cli()` for fields marked as interactive.
-   * When `interactive` is `true` and this is not provided, defaults to an Enquirer-based terminal prompt.
-   */
-  prompt?: (config: InteractivePromptConfig) => Promise<unknown>;
-  /**
-   * Read a line of input from the user. Used by `repl()` for custom runtimes
-   * (web UIs, chat interfaces, testing).
-   * Returns the input string, `null` on EOF (e.g. Ctrl+D, closed connection),
-   * or `REPL_SIGINT` when the user presses Ctrl+C.
-   *
-   * When not provided, `repl()` uses a built-in Node.js readline session
-   * with command history (up/down arrows) and tab completion.
-   */
-  readLine?: (prompt: string) => Promise<string | typeof REPL_SIGINT | null>;
-};
-
-/**
- * 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'>;
+import { readStreamAsText } from '../util/stream.ts';
+import type {
+  InteractiveMode,
+  InteractivePromptConfig,
+  PadroneRuntime,
+  PadroneSignal,
+  ReplSessionConfig,
+  ResolvedPadroneRuntime,
+} from './runtime.ts';
+import { REPL_SIGINT } from './runtime.ts';
 
 /**
  * Default terminal prompt implementation powered by Enquirer.
@@ -128,25 +37,6 @@ async function defaultTerminalPrompt(config: InteractivePromptConfig): Promise<u
   return response[config.name];
 }
 
-/**
- * Internal session config for the REPL's persistent readline interface.
- */
-export type ReplSessionConfig = {
-  completer?: (line: string) => [string[], string];
-  history?: string[];
-};
-
-/**
- * Creates a persistent Node.js readline session for the REPL.
- * Enables up/down arrow history navigation and tab completion.
- * Used internally by `repl()` when no custom `readLine` is provided.
- */
-/**
- * Sentinel value returned by the terminal REPL session when Ctrl+C is pressed.
- * Distinguished from empty string (user pressed enter) and null (EOF/Ctrl+D).
- */
-export const REPL_SIGINT = Symbol('REPL_SIGINT');
-
 export function createTerminalReplSession(config: ReplSessionConfig) {
   // History accumulates across per-call interfaces, giving us
   // up/down arrow navigation without a persistent stdin listener
@@ -217,9 +107,6 @@ function detectInteractiveMode(): InteractiveMode {
   return 'supported';
 }
 
-/**
- * Creates the default Node.js/Bun runtime.
- */
 /**
  * Creates a default stdin reader from `process.stdin`.
  * Only created when a command actually declares a `stdin` meta field.
@@ -234,11 +121,7 @@ function createDefaultStdin(): NonNullable<PadroneRuntime['stdin']> {
     },
     async text() {
       if (typeof process === 'undefined') return '';
-      const chunks: Buffer[] = [];
-      for await (const chunk of process.stdin) {
-        chunks.push(typeof chunk === 'string' ? Buffer.from(chunk) : chunk);
-      }
-      return Buffer.concat(chunks).toString('utf-8');
+      return readStreamAsText(process.stdin);
     },
     async *lines() {
       if (typeof process === 'undefined') return;
@@ -255,6 +138,46 @@ function createDefaultStdin(): NonNullable<PadroneRuntime['stdin']> {
   };
 }
 
+/**
+ * Default signal listener that wires to `process.on(signal)`.
+ * Returns an unsubscribe function that removes all listeners.
+ */
+function defaultOnSignal(callback: (signal: PadroneSignal) => void): () => void {
+  if (typeof process === 'undefined') return () => {};
+  const signals: PadroneSignal[] = ['SIGINT', 'SIGTERM', 'SIGHUP'];
+  const handlers = new Map<PadroneSignal, () => void>();
+  for (const sig of signals) {
+    const handler = () => callback(sig);
+    handlers.set(sig, handler);
+    process.on(sig, handler);
+  }
+  return () => {
+    for (const [sig, handler] of handlers) {
+      process.removeListener(sig, handler);
+    }
+  };
+}
+
+/**
+ * Creates the default Node.js/Bun runtime.
+ */
+function defaultExit(code: number): never {
+  if (typeof process !== 'undefined') process.exit(code);
+  throw new Error(`Exit with code ${code}`);
+}
+
+function getTerminalInfo(): PadroneRuntime['terminal'] {
+  if (typeof process === 'undefined') return undefined;
+  return {
+    get columns() {
+      return process.stdout?.columns;
+    },
+    get isTTY() {
+      return process.stdout?.isTTY === true;
+    },
+  };
+}
+
 export function createDefaultRuntime(): ResolvedPadroneRuntime {
   return {
     output: (...args) => console.log(...args),
@@ -262,16 +185,14 @@ export function createDefaultRuntime(): ResolvedPadroneRuntime {
     argv: () => (typeof process !== 'undefined' ? process.argv.slice(2) : []),
     env: () => (typeof process !== 'undefined' ? (process.env as Record<string, string | undefined>) : {}),
     format: 'auto',
-    loadConfigFile,
-    findFile: findConfigFile,
     prompt: defaultTerminalPrompt,
     interactive: detectInteractiveMode(),
+    onSignal: defaultOnSignal,
+    terminal: getTerminalInfo(),
+    exit: defaultExit,
   };
 }
 
-/**
- * Merges a partial runtime with the default runtime.
- */
 /**
  * Returns the stdin abstraction: custom runtime stdin > default process.stdin.
  * Returns `undefined` when no custom stdin is provided and process.stdin is not piped.
@@ -285,6 +206,18 @@ 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();
+}
+
+/**
+ * Merges a partial runtime with the default runtime.
+ */
 export function resolveRuntime(partial?: PadroneRuntime): ResolvedPadroneRuntime {
   const defaults = createDefaultRuntime();
   if (!partial) return defaults;
@@ -294,11 +227,13 @@ export function resolveRuntime(partial?: PadroneRuntime): ResolvedPadroneRuntime
     argv: partial.argv ?? defaults.argv,
     env: partial.env ?? defaults.env,
     format: partial.format ?? defaults.format,
-    loadConfigFile: partial.loadConfigFile ?? defaults.loadConfigFile,
-    findFile: partial.findFile ?? defaults.findFile,
     interactive: partial.interactive ?? defaults.interactive,
     prompt: partial.prompt ?? defaults.prompt,
     readLine: partial.readLine ?? defaults.readLine,
     stdin: partial.stdin,
+    theme: partial.theme,
+    onSignal: partial.onSignal ?? defaults.onSignal,
+    terminal: partial.terminal ?? defaults.terminal,
+    exit: partial.exit ?? defaults.exit,
   };
 }

package/src/{errors.ts → core/errors.ts}

@@ -7,6 +7,8 @@
  * and to present formatted, actionable error messages.
  */
 
+import type { PadroneSignal } from './runtime.ts';
+
 export type PadroneErrorOptions = {
   /** Process exit code. Defaults to 1. */
   exitCode?: number;
@@ -129,3 +131,23 @@ export class ActionError extends PadroneError {
     this.name = 'ActionError';
   }
 }
+
+/**
+ * Thrown when command execution is interrupted by a process signal (SIGINT, SIGTERM, SIGHUP).
+ * Carries the signal name and the conventional exit code (128 + signal number).
+ */
+export class SignalError extends PadroneError {
+  readonly signal: PadroneSignal;
+
+  constructor(signal: PadroneSignal, options?: { cause?: unknown }) {
+    super(`Process interrupted by ${signal}`, { exitCode: signalExitCode(signal), cause: options?.cause });
+    this.name = 'SignalError';
+    this.signal = signal;
+  }
+}
+
+/** Maps a signal name to its conventional exit code (128 + signal number). */
+export function signalExitCode(signal: PadroneSignal): number {
+  const codes: Record<string, number> = { SIGINT: 130, SIGTERM: 143, SIGHUP: 129 };
+  return codes[signal] ?? 1;
+}

package/src/core/exec.ts

@@ -0,0 +1,259 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type {
+  AnyPadroneCommand,
+  AnyPadroneProgram,
+  InterceptorExecuteContext,
+  InterceptorExecuteResult,
+  InterceptorParseContext,
+  InterceptorParseResult,
+  InterceptorValidateContext,
+  InterceptorValidateResult,
+  PadroneActionContext,
+  PadroneEvalPreferences,
+  RegisteredInterceptor,
+  ResolvedInterceptor,
+} from '../types/index.ts';
+import { getCommandRuntime } from './commands.ts';
+import { RoutingError, SignalError, ValidationError } from './errors.ts';
+import { resolveRegisteredInterceptors, runInterceptorChain, wrapWithLifecycle } from './interceptors.ts';
+import { errorResult, noop, thenMaybe, warnIfUnexpectedAsync, withDrain } from './results.ts';
+import { buildCommandArgs, formatIssueMessages, validateCommandArgs } from './validate.ts';
+
+export type ExecContext = {
+  rootCommand: AnyPadroneCommand;
+  builder: AnyPadroneProgram;
+  parseCommandFn: (input: string | undefined) => {
+    command: AnyPadroneCommand;
+    rawArgs: Record<string, unknown>;
+    args: string[];
+    unmatchedTerms: string[];
+  };
+  collectInterceptorsFn: (cmd: AnyPadroneCommand) => RegisteredInterceptor[];
+};
+
+/**
+ * Collects registered interceptors from the command's parent chain (root → ... → target).
+ * Root/program interceptors come first (outermost), target command's interceptors last (innermost).
+ */
+export function collectInterceptors(cmd: AnyPadroneCommand, rootCommand: AnyPadroneCommand): RegisteredInterceptor[] {
+  const chain: RegisteredInterceptor[][] = [];
+  let current: AnyPadroneCommand | undefined = cmd;
+  while (current) {
+    const isTarget = current === cmd;
+    if (!current.parent) {
+      if (rootCommand.interceptors?.length) {
+        const isRootTarget = cmd === rootCommand || !cmd.parent;
+        chain.unshift(isRootTarget ? rootCommand.interceptors : rootCommand.interceptors.filter((i) => i.meta.inherit !== false));
+      }
+    } else {
+      if (current.interceptors?.length) {
+        chain.unshift(isTarget ? current.interceptors : current.interceptors.filter((i) => i.meta.inherit !== false));
+      }
+    }
+    current = current.parent;
+  }
+  return chain.flat();
+}
+
+/** Wraps an error into a result, preserving any signal info from the pipeline. */
+export function errorResultWithSignal(err: unknown) {
+  const result = errorResult(err);
+  if (err instanceof SignalError) {
+    (result as any).signal = err.signal;
+    (result as any).exitCode = err.exitCode;
+  }
+  return result;
+}
+
+/** Resolve context by walking the command parent chain and applying transforms from root to target. */
+function resolveContext(command: AnyPadroneCommand, initialContext: unknown): unknown {
+  const chain: AnyPadroneCommand[] = [];
+  let current: AnyPadroneCommand | undefined = command;
+  while (current) {
+    chain.unshift(current);
+    current = current.parent;
+  }
+  let resolved = initialContext;
+  for (const cmd of chain) {
+    if (cmd.contextTransform) resolved = cmd.contextTransform(resolved);
+  }
+  return resolved;
+}
+
+/** Validate parse result — reject unmatched terms when the command doesn't accept positional args. */
+function validateParseResult(
+  parseResult: { command: AnyPadroneCommand; rawArgs: Record<string, unknown>; args: string[]; unmatchedTerms: string[] },
+  rootCommand: AnyPadroneCommand,
+): InterceptorParseResult {
+  const { command, rawArgs, args, unmatchedTerms } = parseResult;
+
+  if (unmatchedTerms.length > 0) {
+    const hasPositionalConfig = command.meta?.positional && command.meta.positional.length > 0;
+    if (!hasPositionalConfig) {
+      const isRootCommand = command === rootCommand;
+      const commandDisplayName = command.name || command.aliases?.[0] || command.path || '(default)';
+      const errorMsg = isRootCommand
+        ? `Unknown command: ${unmatchedTerms[0]}`
+        : `Unexpected arguments for '${commandDisplayName}': ${unmatchedTerms.join(' ')}`;
+
+      throw new RoutingError(errorMsg, { command: command.path || command.name });
+    }
+  }
+
+  return { command, rawArgs, positionalArgs: args };
+}
+
+/** Handle validation issues based on error mode: throw (hard) or return result with issues (soft). */
+function handleValidationIssues(argsResult: StandardSchemaV1.FailureResult, command: AnyPadroneCommand, errorMode: 'soft' | 'hard') {
+  if (errorMode === 'hard') {
+    const issueMessages = formatIssueMessages(argsResult.issues);
+    throw new ValidationError(`Validation error:\n${issueMessages}`, argsResult.issues as any, {
+      command: command.path || command.name,
+    });
+  }
+
+  return withDrain({
+    command: command as any,
+    args: undefined,
+    argsResult,
+    result: 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)
+ */
+export function execCommand(
+  resolvedInput: string | undefined,
+  ctx: ExecContext,
+  evalOptions?: PadroneEvalPreferences,
+  errorMode: 'soft' | 'hard' = 'soft',
+  caller: PadroneActionContext['caller'] = 'eval',
+) {
+  const { rootCommand, parseCommandFn, collectInterceptorsFn } = ctx;
+  const baseRuntime = getCommandRuntime(rootCommand);
+  const runtime = evalOptions?.runtime
+    ? Object.assign({}, baseRuntime, Object.fromEntries(Object.entries(evalOptions.runtime).filter(([, v]) => v !== undefined)))
+    : baseRuntime;
+
+  // Inert signal — the signal extension overrides this via next({ signal }) in the start phase.
+  const inertSignal = new AbortController().signal;
+
+  // Pipeline state accumulated as phases complete — propagated to error/shutdown contexts.
+  const pipelineState: { rawArgs?: Record<string, unknown>; positionalArgs?: string[]; args?: unknown } = {};
+
+  const initialContext = evalOptions?.context;
+
+  // Factory resolution cache — ensures each factory is called at most once per execution,
+  // so root interceptor closures are shared when they appear in both root and command chains.
+  const factoryCache = new Map<RegisteredInterceptor, ResolvedInterceptor>();
+  const rootRegistered = rootCommand.interceptors ?? [];
+  const rootInterceptors = resolveRegisteredInterceptors(rootRegistered, factoryCache);
+
+  const runPipeline = (signal: AbortSignal, pipelineContext: unknown) => {
+    // ── Phase 1: Parse ──────────────────────────────────────────────────
+    const parseCtx: InterceptorParseContext = {
+      input: resolvedInput,
+      command: rootCommand,
+      signal,
+      context: pipelineContext,
+      runtime,
+      program: ctx.builder,
+      caller,
+    };
+
+    const coreParse = (parseCtx: InterceptorParseContext): InterceptorParseResult =>
+      validateParseResult(parseCommandFn(parseCtx.input), rootCommand);
+
+    const parsedOrPromise = runInterceptorChain('parse', rootInterceptors, parseCtx, coreParse);
+
+    // ── Phases 2 & 3 chained after parse ────────────────────────────────
+    const continueAfterParse = (parsed: InterceptorParseResult) => {
+      const { command } = parsed;
+      pipelineState.rawArgs = parsed.rawArgs;
+      pipelineState.positionalArgs = parsed.positionalArgs;
+      const commandInterceptors = resolveRegisteredInterceptors(collectInterceptorsFn(command), factoryCache);
+      const context = resolveContext(command, pipelineContext);
+
+      // ── Phase 2: Validate ───────────────────────────────────────────
+      const validateCtx: InterceptorValidateContext = {
+        ...parseCtx,
+        command,
+        rawArgs: parsed.rawArgs,
+        positionalArgs: parsed.positionalArgs,
+        context,
+        evalInteractive: evalOptions?.interactive,
+      };
+
+      const coreValidate = (validateCtx: InterceptorValidateContext): InterceptorValidateResult | Promise<InterceptorValidateResult> => {
+        const preprocessedArgs = buildCommandArgs(validateCtx.command, validateCtx.rawArgs, validateCtx.positionalArgs);
+        const validated = validateCommandArgs(validateCtx.command, preprocessedArgs);
+        return thenMaybe(validated, (v) => v as InterceptorValidateResult);
+      };
+
+      const validatedOrPromise = runInterceptorChain('validate', commandInterceptors, validateCtx, coreValidate);
+
+      // ── Phase 3: Execute (or handle validation errors) ──────────────
+      const continueAfterValidate = (v: InterceptorValidateResult) => {
+        pipelineState.args = v.args;
+        if (v.argsResult?.issues) return handleValidationIssues(v.argsResult as StandardSchemaV1.FailureResult, command, errorMode);
+
+        const executeCtx: InterceptorExecuteContext = {
+          ...validateCtx,
+          args: v.args,
+        };
+
+        const coreExecute = (executeCtx: InterceptorExecuteContext): InterceptorExecuteResult => {
+          const handler = command.action ?? noop;
+          const effectiveRuntime = executeCtx.runtime;
+          const actionCtx: PadroneActionContext = {
+            runtime: effectiveRuntime,
+            command: executeCtx.command,
+            program: ctx.builder as any,
+            signal: executeCtx.signal,
+            context: executeCtx.context,
+            caller,
+          };
+          const result = handler(executeCtx.args as any, actionCtx);
+          return { result };
+        };
+
+        const executedOrPromise = runInterceptorChain('execute', commandInterceptors, executeCtx, coreExecute);
+
+        return thenMaybe(executedOrPromise, (e) => {
+          const finalize = (result: unknown) =>
+            withDrain({
+              command: command as any,
+              args: v.args,
+              argsResult: v.argsResult,
+              result,
+            });
+
+          if (e.result instanceof Promise) return e.result.then(finalize);
+          return finalize(e.result);
+        });
+      };
+
+      return thenMaybe(warnIfUnexpectedAsync(validatedOrPromise, command), continueAfterValidate) as any;
+    };
+
+    return thenMaybe(parsedOrPromise, continueAfterParse) as any;
+  };
+
+  return wrapWithLifecycle(
+    rootInterceptors,
+    rootCommand,
+    resolvedInput,
+    runPipeline,
+    (result) => withDrain({ command: rootCommand, args: undefined, argsResult: undefined, result }),
+    inertSignal,
+    initialContext,
+    runtime,
+    ctx.builder,
+    caller,
+    pipelineState,
+  ) as any;
+}