padrone 1.1.0 → 1.2.0

package/src/repl-loop.ts

@@ -0,0 +1,317 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import { buildReplCompleter, findCommandByName, getCommandRuntime } from './command-utils.ts';
+import { createTerminalReplSession, REPL_SIGINT, type ReplSessionConfig } from './runtime.ts';
+import type { AnyPadroneCommand, PadroneEvalPreferences, PadroneReplPreferences } from './types.ts';
+import { getVersion } from './utils.ts';
+
+export type ReplDeps = {
+  existingCommand: AnyPadroneCommand;
+  evalCommand: (input: string, prefs?: PadroneEvalPreferences) => any;
+  replActiveRef: { value: boolean };
+};
+
+/**
+ * Creates a REPL async iterable for running commands interactively.
+ */
+export function createReplIterator(deps: ReplDeps, options?: PadroneReplPreferences): AsyncIterable<any> {
+  const { existingCommand, evalCommand, replActiveRef } = deps;
+
+  if (replActiveRef.value) {
+    const runtime = getCommandRuntime(existingCommand);
+    runtime.error('REPL is already running. Nested REPL sessions are not supported.');
+    return (async function* () {})() as any;
+  }
+
+  const runtime = getCommandRuntime(existingCommand);
+
+  const programName = existingCommand.name || 'padrone';
+  const useAnsi =
+    runtime.format === 'ansi' ||
+    (runtime.format === 'auto' && typeof process !== 'undefined' && !process.env.NO_COLOR && !process.env.CI && process.stdout?.isTTY);
+
+  // Track command history for .history built-in
+  const commandHistory: string[] = [];
+
+  // Resolve the initial scope command from options.scope (command path like 'db' or 'db migrate')
+  const resolveScope = (scope: string): AnyPadroneCommand[] => {
+    const parts = scope.split(/\s+/);
+    const stack: AnyPadroneCommand[] = [];
+    let current = existingCommand;
+    for (const part of parts) {
+      const found = findCommandByName(part, current.commands);
+      if (!found) break;
+      stack.push(found);
+      current = found;
+    }
+    return stack;
+  };
+
+  async function* replIterator() {
+    replActiveRef.value = true;
+    const showGreeting = options?.greeting !== false;
+    const showHint = options?.hint !== false;
+
+    // Empty line before greeting/hint block
+    if (showGreeting || showHint) runtime.output('');
+
+    // Greeting: default shows program title (or name) + version, like "Welcome to My App v1.0.0"
+    if (showGreeting) {
+      if (options?.greeting) {
+        runtime.output(options.greeting);
+      } else {
+        const displayName = existingCommand.title || programName;
+        const version = existingCommand.version ? getVersion(existingCommand.version) : undefined;
+        const greeting = version ? `Welcome to ${displayName} v${version}` : `Welcome to ${displayName}`;
+        runtime.output(greeting);
+      }
+    }
+
+    // Hint: dimmed text below greeting
+    if (showHint) {
+      const hintText =
+        (typeof options?.hint === 'string' ? options.hint : undefined) ?? 'Type ".help" for more information, ".exit" to quit.';
+      runtime.output(useAnsi ? `\x1b[2m${hintText}\x1b[0m` : hintText);
+    }
+
+    // Empty line after greeting/hint block
+    if (showGreeting || showHint) runtime.output('');
+
+    // Scope stack for nested/contextual REPLs.
+    // `cd <subcommand>` pushes, `cd ..`/`..` pops. The scope path is prepended to all eval input.
+    const scopeStack: AnyPadroneCommand[] = options?.scope ? resolveScope(options.scope) : [];
+
+    const getScopeCommand = () => (scopeStack.length ? scopeStack[scopeStack.length - 1]! : existingCommand);
+    const getScopePath = () => scopeStack.map((c) => c.name).join(' ');
+
+    const buildPrompt = () => {
+      if (options?.prompt) return typeof options.prompt === 'function' ? options.prompt() : options.prompt;
+      const scopePath = getScopePath();
+      const label = scopePath ? `${programName}/${scopePath.replace(/ /g, '/')}` : programName;
+      return useAnsi ? `\x1b[1m${label}\x1b[0m ❯ ` : `${label} ❯ `;
+    };
+
+    // Build completer scoped to the current command
+    const buildScopedCompleter = () => {
+      const scopeCmd = getScopeCommand();
+      const inScope = scopeStack.length > 0;
+      return buildReplCompleter(scopeCmd, { inScope });
+    };
+
+    // Build session config with completer
+    const sessionConfig: ReplSessionConfig = { history: options?.history };
+    if (options?.completion !== false) {
+      sessionConfig.completer = buildScopedCompleter();
+    }
+
+    // If the runtime provides a custom readLine, use it (stateless, no history/completion).
+    // Otherwise, create a persistent terminal session with history + tab completion.
+    const session = runtime.readLine ? undefined : createTerminalReplSession(sessionConfig);
+    const questionFn = session ? (prompt: string) => session.question(prompt) : runtime.readLine!;
+
+    // Update the session's completer when scope changes
+    const updateCompleter = () => {
+      if (options?.completion === false) return;
+      const completer = buildScopedCompleter();
+      if (session) session.completer = completer;
+      sessionConfig.completer = completer;
+    };
+
+    // Track last SIGINT time for double Ctrl+C to exit
+    let lastSigintTime = 0;
+
+    try {
+      while (true) {
+        const promptStr = buildPrompt();
+        const input = await questionFn(promptStr);
+
+        // EOF (Ctrl+D, closed connection)
+        if (input === null) break;
+
+        // Handle Ctrl+C (SIGINT sentinel from terminal session)
+        if (input === REPL_SIGINT) {
+          const now = Date.now();
+          if (now - lastSigintTime < 2000) break; // Double Ctrl+C within 2s → exit
+          lastSigintTime = now;
+          runtime.output('(press Ctrl+C again to exit, or Ctrl+D)');
+          continue;
+        }
+
+        const trimmed = input.trim();
+        if (!trimmed) continue;
+
+        // Reset SIGINT timer on any real input
+        lastSigintTime = 0;
+
+        // Track command history for .history
+        commandHistory.push(trimmed);
+
+        // Dot-prefixed built-in REPL commands
+        if (trimmed === '.exit' || trimmed === '.quit') break;
+        if (trimmed === '.clear') {
+          runtime.output('\x1B[2J\x1B[H');
+          continue;
+        }
+        if (trimmed === '.help') {
+          const lines = [
+            'REPL Commands:',
+            '  .                 Execute the current scoped command',
+            '  .help             Print this help message',
+            '  .exit             Exit the REPL',
+            '  .clear            Clear the screen',
+            '  .history          Show command history',
+            '  .scope <cmd>      Scope into a subcommand',
+            '  .scope ..         Go up one scope level',
+          ];
+          lines.push(
+            '',
+            'Keybindings:',
+            '  Ctrl+C       Cancel current line (press twice to exit)',
+            '  Ctrl+D       Exit the REPL',
+            '  Up/Down      Navigate history',
+            '  Tab          Auto-complete',
+            '',
+            'Type "help" to see available commands.',
+          );
+          runtime.output(lines.join('\n'));
+          continue;
+        }
+        if (trimmed === '.history') {
+          // Show all previous entries (excluding the .history command itself)
+          const entries = commandHistory.slice(0, -1);
+          if (entries.length === 0) {
+            runtime.output('No history.');
+          } else {
+            runtime.output(entries.map((entry, i) => `${i + 1}  ${entry}`).join('\n'));
+          }
+          continue;
+        }
+
+        // `.scope <subcommand>` — scope the REPL to a command subtree
+        // `.scope ..` or `..` — go up one scope level
+        if (trimmed.startsWith('.scope ') || trimmed === '.scope') {
+          const target = trimmed.slice(6).trim();
+          if (target === '..' || target === '') {
+            if (scopeStack.length > 0) {
+              scopeStack.pop();
+              updateCompleter();
+            }
+          } else {
+            const scopeCmd = getScopeCommand();
+            const found = findCommandByName(target, scopeCmd.commands);
+            if (found) {
+              if (found.commands?.length) {
+                scopeStack.push(found);
+                updateCompleter();
+              } else {
+                runtime.error(`"${target}" has no subcommands to scope into.`);
+              }
+            } else {
+              runtime.error(`Unknown command: ${target}`);
+            }
+          }
+          continue;
+        }
+
+        // `..` shorthand for `.scope ..`
+        if (trimmed === '..') {
+          if (scopeStack.length > 0) {
+            scopeStack.pop();
+            updateCompleter();
+          }
+          continue;
+        }
+
+        // `.` (bare dot) — execute the current command (scoped or root)
+        let evalInput = trimmed;
+        if (trimmed === '.') {
+          evalInput = '';
+        }
+
+        const prefix = options?.outputPrefix;
+        const prefixLines = prefix
+          ? (text: string) =>
+              text
+                .split('\n')
+                .map((l) => prefix + l)
+                .join('\n')
+          : undefined;
+
+        // Temporarily patch runtime on all commands so handler output gets prefixed.
+        // Commands store parent refs from build time, so we patch each command directly.
+        const savedRuntimes: { cmd: AnyPadroneCommand; runtime: typeof existingCommand.runtime }[] = [];
+        if (prefixLines) {
+          const prefixedRuntime = {
+            ...existingCommand.runtime,
+            output: (...args: unknown[]) => {
+              const first = args[0];
+              runtime.output(typeof first === 'string' ? prefixLines(first) : first, ...args.slice(1));
+            },
+            error: (text: string) => runtime.error(prefixLines(text)),
+          };
+          const patchAll = (cmd: AnyPadroneCommand) => {
+            savedRuntimes.push({ cmd, runtime: cmd.runtime });
+            cmd.runtime = prefixedRuntime;
+            cmd.commands?.forEach(patchAll);
+          };
+          patchAll(existingCommand);
+        }
+
+        // Resolve before/after spacing from the shorthand or object form
+        const sp = options?.spacing;
+        const isSpacingObject = typeof sp === 'object' && sp !== null && !Array.isArray(sp);
+        const spacingBefore = isSpacingObject ? sp.before : sp;
+        const spacingAfter = isSpacingObject ? sp.after : sp;
+
+        const emitSpacingLine = (value: boolean | string) => {
+          if (typeof value === 'string') {
+            const sep =
+              value.length === 1
+                ? value.repeat(typeof process !== 'undefined' && process.stdout?.columns ? process.stdout.columns : 80)
+                : value;
+            runtime.output(sep);
+          } else if (value) {
+            runtime.output('');
+          }
+        };
+        const emitSpacing = (value: typeof spacingBefore) => {
+          if (!value) return;
+          if (Array.isArray(value)) {
+            for (const line of value) emitSpacingLine(line);
+          } else {
+            emitSpacingLine(value);
+          }
+        };
+
+        emitSpacing(spacingBefore);
+
+        // Prepend scope path so evalCommand resolves relative to root
+        const scopePath = getScopePath();
+        const scopedInput = scopePath ? (evalInput ? `${scopePath} ${evalInput}` : scopePath) : evalInput;
+
+        try {
+          const replEvalPrefs: PadroneEvalPreferences | undefined = options?.autoOutput === false ? { autoOutput: false } : undefined;
+          const result = await evalCommand(scopedInput, replEvalPrefs);
+          if (result.argsResult?.issues) {
+            const issueMessages = result.argsResult.issues
+              .map((i: StandardSchemaV1.Issue) => `  - ${i.path?.join('.') || 'root'}: ${i.message}`)
+              .join('\n');
+            const msg = `Validation error:\n${issueMessages}`;
+            runtime.error(prefixLines ? prefixLines(msg) : msg);
+          }
+          yield result as any;
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          runtime.error(prefixLines ? prefixLines(msg) : msg);
+        } finally {
+          for (const { cmd, runtime: saved } of savedRuntimes) cmd.runtime = saved;
+          emitSpacing(spacingAfter);
+        }
+      }
+    } finally {
+      replActiveRef.value = false;
+      session?.close();
+    }
+  }
+
+  return replIterator() as any;
+}

package/src/runtime.ts

@@ -0,0 +1,304 @@
+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'>;
+
+/**
+ * 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];
+}
+
+/**
+ * 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
+  // 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 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.
+ */
+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 '';
+      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');
+    },
+    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();
+      }
+    },
+  };
+}
+
+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',
+    loadConfigFile,
+    findFile: findConfigFile,
+    prompt: defaultTerminalPrompt,
+    interactive: detectInteractiveMode(),
+  };
+}
+
+/**
+ * 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.
+ */
+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;
+}
+
+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,
+    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,
+  };
+}