padrone 1.5.0 → 1.7.0

package/src/core/default-runtime.ts

@@ -0,0 +1,239 @@
+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.
+ * Lazily imported to avoid loading Enquirer when not needed.
+ */
+async function defaultTerminalPrompt(config: InteractivePromptConfig): Promise<unknown> {
+  const Enquirer = (await import('enquirer')).default;
+
+  const question: Record<string, unknown> = {
+    type: config.type,
+    name: config.name,
+    message: config.message,
+  };
+
+  if (config.default !== undefined) {
+    question.initial = config.default;
+  }
+
+  if (config.choices) {
+    question.choices = config.choices.map((c) => ({
+      name: String(c.value),
+      message: c.label,
+    }));
+  }
+
+  const response = (await Enquirer.prompt(question as any)) as Record<string, unknown>;
+  return response[config.name];
+}
+
+export function createTerminalReplSession(config: ReplSessionConfig) {
+  // History accumulates across per-call interfaces, giving us
+  // up/down arrow navigation without a persistent stdin listener
+  // that would conflict with Enquirer or other stdin consumers.
+  let history: string[] = config.history ? [...config.history] : [];
+  let currentCompleter = config.completer;
+
+  return {
+    /** Update the tab completer (e.g. when REPL scope changes). Takes effect on the next question. */
+    set completer(fn: ((line: string) => [string[], string]) | undefined) {
+      currentCompleter = fn;
+    },
+    async question(prompt: string): Promise<string | typeof REPL_SIGINT | null> {
+      const { createInterface } = await import('node:readline');
+      const opts: Record<string, unknown> = {
+        input: process.stdin,
+        output: process.stdout,
+        terminal: true,
+        history: [...history],
+        historySize: Math.max(history.length, 1000),
+      };
+      if (currentCompleter) {
+        opts.completer = currentCompleter;
+      }
+      const rl = createInterface(opts as any);
+
+      return new Promise((resolve) => {
+        let resolved = false;
+        const settle = (value: string | typeof REPL_SIGINT | null) => {
+          if (resolved) return;
+          resolved = true;
+          rl.close();
+          resolve(value);
+        };
+
+        rl.question(prompt, (answer) => {
+          // Grab updated history (includes the new entry) before closing.
+          if (Array.isArray((rl as any).history)) history = [...(rl as any).history];
+          settle(answer);
+        });
+        // Ctrl+C: cancel current line, print newline, resolve SIGINT sentinel.
+        rl.once('SIGINT', () => {
+          process.stdout.write('\n');
+          settle(REPL_SIGINT);
+        });
+        // EOF (Ctrl+D) fires close without the question callback.
+        rl.once('close', () => {
+          // Write newline so zsh doesn't show '%' (partial-line indicator).
+          process.stdout.write('\n');
+          settle(null);
+        });
+      });
+    },
+    close() {
+      // No persistent interface to clean up.
+    },
+  };
+}
+
+/**
+ * Auto-detect interactive mode when not explicitly set.
+ * Returns 'disabled' in CI environments or non-TTY contexts, 'supported' otherwise.
+ */
+function detectInteractiveMode(): InteractiveMode {
+  if (typeof process === 'undefined') return 'disabled';
+  if (process.env.CI || process.env.CONTINUOUS_INTEGRATION) return 'disabled';
+  if (!process.stdout?.isTTY) return 'disabled';
+  return 'supported';
+}
+
+/**
+ * Creates a default stdin reader from `process.stdin`.
+ * Only created when a command actually declares a `stdin` meta field.
+ */
+function createDefaultStdin(): NonNullable<PadroneRuntime['stdin']> {
+  return {
+    get isTTY() {
+      // process.stdin.isTTY is `true` when interactive terminal, `undefined` when piped/redirected.
+      // Node.js never sets it to `false` — it's either `true` or absent.
+      if (typeof process === 'undefined') return true;
+      return process.stdin?.isTTY === true;
+    },
+    async text() {
+      if (typeof process === 'undefined') return '';
+      return readStreamAsText(process.stdin);
+    },
+    async *lines() {
+      if (typeof process === 'undefined') return;
+      const { createInterface } = await import('node:readline');
+      const rl = createInterface({ input: process.stdin });
+      try {
+        for await (const line of rl) {
+          yield line;
+        }
+      } finally {
+        rl.close();
+      }
+    },
+  };
+}
+
+/**
+ * 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),
+    error: (text) => console.error(text),
+    argv: () => (typeof process !== 'undefined' ? process.argv.slice(2) : []),
+    env: () => (typeof process !== 'undefined' ? (process.env as Record<string, string | undefined>) : {}),
+    format: 'auto',
+    prompt: defaultTerminalPrompt,
+    interactive: detectInteractiveMode(),
+    onSignal: defaultOnSignal,
+    terminal: getTerminalInfo(),
+    exit: defaultExit,
+  };
+}
+
+/**
+ * Returns the stdin abstraction: custom runtime stdin > default process.stdin.
+ * Returns `undefined` when no custom stdin is provided and process.stdin is not piped.
+ */
+export function resolveStdin(partial?: PadroneRuntime): NonNullable<PadroneRuntime['stdin']> | undefined {
+  if (partial?.stdin) return partial.stdin;
+  const defaultStdin = createDefaultStdin();
+  // Only use default stdin if it's actually piped (isTTY === false).
+  // This avoids accidentally blocking on stdin in tests/CI.
+  if (defaultStdin.isTTY) return undefined;
+  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;
+  return {
+    output: partial.output ?? defaults.output,
+    error: partial.error ?? defaults.error,
+    argv: partial.argv ?? defaults.argv,
+    env: partial.env ?? defaults.env,
+    format: partial.format ?? defaults.format,
+    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;
+}