{"version":3,"file":"runtime.mjs","names":[],"sources":["../../src/core/runtime.ts"],"sourcesContent":["import type { ColorConfig, ColorTheme } from '../output/colorizer.ts';\nimport type { HelpFormat } from '../output/formatter.ts';\n\n/** Process signals that Padrone can handle for graceful shutdown. */\nexport type PadroneSignal = 'SIGINT' | 'SIGTERM' | 'SIGHUP';\n\n/** Value accepted by `PadroneProgress.update()`. */\nexport type PadroneProgressUpdate = string | number | { message?: string; progress?: number; indeterminate?: boolean; time?: boolean };\n\n/**\n * A progress indicator instance (spinner, progress bar, etc).\n * Created by the runtime's `progress` factory and used to show loading state during command execution.\n */\nexport type PadroneProgress = {\n  /**\n   * Update the indicator.\n   * - `string` — update the displayed message.\n   * - `number` — set progress ratio (0–1). Values outside this range are clamped.\n   * - `{ message?, progress?, indeterminate? }` — update message, progress, or both.\n   *\n   * Set `indeterminate: true` to force the bar into indeterminate mode (shows animation, no percentage).\n   * This makes the bar visible even in `show: 'auto'` mode without providing a number.\n   * Omitting `progress` (or passing a string) leaves the bar in its current state.\n   * Setting `progress` when bar mode is not enabled is a no-op for the bar portion.\n   *\n   * Set `time: true` to start the elapsed timer on demand (useful when `time` was not set in options).\n   * Set `time: false` to hide the elapsed timer.\n   */\n  update: (value: PadroneProgressUpdate) => void;\n  /** Mark as succeeded and stop. Pass `null` to stop without rendering a final message. */\n  succeed: (message?: string | null, options?: { indicator?: string }) => void;\n  /** Mark as failed and stop. Pass `null` to stop without rendering a final message. */\n  fail: (message?: string | null, options?: { indicator?: string }) => void;\n  /** Control ETA (estimated time remaining) display at runtime. */\n  eta: {\n    /** Enable ETA tracking. Starts collecting samples from subsequent `update()` calls. */\n    start: () => void;\n    /** Disable ETA display. */\n    stop: () => void;\n    /** Clear collected samples and restart estimation. Useful between operation phases. */\n    reset: () => void;\n  };\n  /** Stop without success/fail status. */\n  stop: () => void;\n  /** Temporarily hide the indicator so other output can be written cleanly. */\n  pause: () => void;\n  /** Redraw the indicator after a `pause()`. */\n  resume: () => void;\n};\n\n/** Controls when a progress element (spinner or bar) is visible. */\nexport type PadroneProgressShow = 'auto' | 'always' | 'never';\n\n/** Built-in spinner presets. */\nexport type PadroneSpinnerPreset = 'dots' | 'line' | 'arc' | 'bounce';\n\n/**\n * Spinner configuration for progress indicators.\n * - A preset name (e.g., `'dots'`) to use built-in frames.\n * - `true` — default spinner with `show: 'always'` (visible even alongside a bar).\n * - An object with custom `frames`, `interval`, and/or `show`.\n * - `false` to disable the spinner (`show: 'never'`).\n *\n * Default `show` is `'auto'`: visible when the bar is not shown.\n */\nexport type PadroneSpinnerConfig = PadroneSpinnerPreset | boolean | { frames?: string[]; interval?: number; show?: PadroneProgressShow };\n\n/**\n * Options passed to the runtime's `progress` factory.\n */\n/** Common fill/empty character pairs for progress bars. */\nexport type PadroneBarChar = '█' | '░' | '▓' | '▒' | '─' | '━' | '■' | '□' | '#' | '-' | '=' | '·' | '▰' | '▱' | (string & {});\n\n/**\n * Built-in indeterminate bar animation presets.\n * - `'bounce'` — a filled segment slides back and forth (default).\n * - `'slide'` — a filled segment slides left-to-right and wraps around.\n * - `'pulse'` — the entire bar fades in and out using gradient characters (`░▒▓█▓▒░`).\n */\nexport type PadroneBarAnimation = 'bounce' | 'slide' | 'pulse';\n\n/**\n * Progress bar configuration.\n */\nexport type PadroneBarConfig = {\n  /** Total width of the bar in characters. Defaults to `20`. */\n  width?: number;\n  /** Character used for the filled portion of the bar. Defaults to `'█'`. */\n  filled?: PadroneBarChar;\n  /** Character used for the empty portion of the bar. Defaults to `'░'`. */\n  empty?: PadroneBarChar;\n  /** Indeterminate animation style. Defaults to `'bounce'`. */\n  animation?: PadroneBarAnimation;\n  /**\n   * When the bar is visible. Defaults to `'always'` when bar is enabled, `'auto'` when bar is not explicitly configured.\n   * - `'always'` — bar is always shown (indeterminate until a number is provided).\n   * - `'auto'` — bar is shown only after `update()` is called with a number.\n   * - `'never'` — bar is never shown.\n   */\n  show?: PadroneProgressShow;\n};\n\nexport type PadroneProgressOptions = {\n  spinner?: PadroneSpinnerConfig;\n  /** Enable a progress bar. `true` for defaults (`show: 'always'`), or a `PadroneBarConfig` object. `false` to disable entirely. When omitted, bar defaults to `show: 'auto'` (appears when a number is provided). */\n  bar?: boolean | PadroneBarConfig;\n  /** Show elapsed time since the indicator started. Defaults to `false`. */\n  time?: boolean;\n  /** Show estimated time remaining based on progress rate. Requires numeric `update()` calls. Defaults to `false`. */\n  eta?: boolean;\n  /** Character/string shown before the success message. Defaults to `'✔'`. */\n  successIndicator?: string;\n  /** Character/string shown before the error message. Defaults to `'✖'`. */\n  errorIndicator?: string;\n};\n\n/**\n * Controls interactive prompting capability and default behavior at the runtime level.\n * - `'supported'` — capable; caller decides.\n * - `'unsupported'` — hard veto; nothing can override.\n * - `'forced'` — capable and forces prompts by default.\n * - `'disabled'` — capable but suppresses prompts by default.\n */\nexport type InteractiveMode = 'supported' | 'unsupported' | 'forced' | 'disabled';\n\n/**\n * Configuration passed to the runtime's `prompt` function for interactive field prompting.\n * The prompt type and choices are auto-detected from the field's JSON schema.\n */\nexport type InteractivePromptConfig = {\n  /** The field name being prompted. */\n  name: string;\n  /** Human-readable message/label for the prompt, derived from the field's description or name. */\n  message: string;\n  /** The prompt type, auto-detected from the JSON schema. */\n  type: 'input' | 'confirm' | 'select' | 'multiselect' | 'password';\n  /** Available choices for select/multiselect prompts. */\n  choices?: { label: string; value: unknown }[];\n  /** Default value from the schema. */\n  default?: unknown;\n};\n\n/**\n * Defines the execution context for a Padrone program.\n * Abstracts all environment-dependent I/O so the CLI framework\n * can run outside of a terminal (e.g., web UIs, chat interfaces, testing).\n *\n * All fields are optional — unspecified fields fall back to the Node.js/Bun defaults.\n */\nexport type PadroneRuntime = {\n  /** Write normal output (replaces console.log). Receives the raw value — runtime handles formatting. */\n  output?: (...args: unknown[]) => void;\n  /** Write error output (replaces console.error). */\n  error?: (text: string) => void;\n  /** Return the raw CLI arguments (replaces process.argv.slice(2)). */\n  argv?: () => string[];\n  /** Return environment variables (replaces process.env). */\n  env?: () => Record<string, string | undefined>;\n  /** Default help output format. */\n  format?: HelpFormat | 'auto';\n  /** Color theme for ANSI/console help output. A theme name or partial color config. */\n  theme?: ColorTheme | ColorConfig;\n  /**\n   * Standard input abstraction. Provides methods to read piped data from stdin.\n   * When not provided, defaults to reading from `process.stdin`.\n   *\n   * Used by commands that declare a `stdin` field in their arguments meta.\n   * The framework reads stdin automatically during the validate phase and\n   * injects the data into the specified argument field.\n   */\n  stdin?: {\n    /** Whether stdin is a TTY (interactive terminal) vs a pipe/file. */\n    isTTY?: boolean;\n    /** Read all of stdin as a string. */\n    text: () => Promise<string>;\n    /** Async iterable of lines for streaming. */\n    lines: () => AsyncIterable<string>;\n  };\n  /**\n   * Controls interactive prompting capability and default behavior.\n   * - `'supported'` — runtime can handle prompts; caller (flag/pref) decides whether to prompt. This is the default when `prompt` is provided.\n   * - `'unsupported'` — runtime cannot handle prompts; hard veto that nothing can override.\n   * - `'forced'` — runtime supports prompts and forces them by default (prompts even for provided values).\n   * - `'disabled'` — runtime supports prompts but suppresses them by default.\n   *\n   * `'unsupported'` is the only immutable state. For the others, the `--interactive`/`-i` flag\n   * and `cli()` preferences can override the default behavior.\n   */\n  interactive?: InteractiveMode;\n  /**\n   * Prompt the user for input. Called during `cli()` for fields marked as interactive.\n   * When `interactive` is `true` and this is not provided, defaults to an Enquirer-based terminal prompt.\n   */\n  prompt?: (config: InteractivePromptConfig) => Promise<unknown>;\n  /**\n   * Read a line of input from the user. Used by `repl()` for custom runtimes\n   * (web UIs, chat interfaces, testing).\n   * Returns the input string, `null` on EOF (e.g. Ctrl+D, closed connection),\n   * or `REPL_SIGINT` when the user presses Ctrl+C.\n   *\n   * When not provided, `repl()` uses a built-in Node.js readline session\n   * with command history (up/down arrows) and tab completion.\n   */\n  readLine?: (prompt: string) => Promise<string | typeof REPL_SIGINT | null>;\n\n  /**\n   * Register a callback for process signals. Returns an unsubscribe function.\n   * The default runtime wires this to `process.on('SIGINT' | 'SIGTERM' | 'SIGHUP')`.\n   * Non-Node runtimes (web UIs, tests) can map their own cancellation semantics.\n   *\n   * When not provided, signal handling is disabled for this runtime.\n   */\n  onSignal?: (callback: (signal: PadroneSignal) => void) => () => void;\n\n  /**\n   * Terminal/output capabilities. Used for ANSI detection, text wrapping, and TTY checks.\n   * The default runtime auto-detects from `process.stdout`. Non-terminal runtimes\n   * (web UIs, tests) should provide explicit values.\n   */\n  terminal?: {\n    /** Number of columns in the terminal. Used for text wrapping. */\n    columns?: number;\n    /** Whether stdout is a TTY. Affects ANSI color output and interactive features. */\n    isTTY?: boolean;\n  };\n\n  /**\n   * Force-exit the process. The default runtime wires this to `process.exit()`.\n   * Non-Node runtimes can throw an error or no-op.\n   */\n  exit?: (code: number) => never;\n};\n\n/**\n * Internal resolved runtime where all fields are guaranteed to be present.\n * The `prompt`, `interactive`, and `readLine` fields remain optional since not all runtimes provide them.\n */\nexport type ResolvedPadroneRuntime = Required<\n  Omit<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin' | 'theme' | 'onSignal' | 'terminal' | 'exit'>\n> &\n  Pick<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin' | 'theme' | 'onSignal' | 'terminal' | 'exit'>;\n\n/**\n * Sentinel value returned by the terminal REPL session when Ctrl+C is pressed.\n * Distinguished from empty string (user pressed enter) and null (EOF/Ctrl+D).\n */\nexport const REPL_SIGINT = Symbol('REPL_SIGINT');\n\n/**\n * Internal session config for the REPL's persistent readline interface.\n */\nexport type ReplSessionConfig = {\n  completer?: (line: string) => [string[], string];\n  history?: string[];\n};\n"],"mappings":";;;;;AAsPA,MAAa,cAAc,OAAO,aAAa"}