padrone 1.5.0 → 1.7.0

package/src/feature/test.ts

@@ -0,0 +1,262 @@
+import type { InteractivePromptConfig, PadroneRuntime } from '../core/runtime.ts';
+import type { AnyPadroneCommand, PadroneCommandResult } from '../types/index.ts';
+
+/**
+ * Result from a single command execution in test mode.
+ * Extends the standard PadroneCommandResult with captured I/O.
+ */
+export type TestCliResult = {
+  /** The matched command. */
+  command: AnyPadroneCommand;
+  /** Validated arguments (undefined if validation failed). */
+  args: unknown;
+  /** Action handler return value (undefined if validation failed or no action). */
+  result: unknown;
+  /** Validation issues, if any. */
+  issues: { message: string; path?: PropertyKey[] }[] | undefined;
+  /** All values passed to `runtime.output()`. */
+  stdout: unknown[];
+  /** All strings passed to `runtime.error()`. */
+  stderr: string[];
+  /** The thrown error, if the command threw (routing error, action error, etc.). */
+  error?: unknown;
+};
+
+/**
+ * Result from a REPL test session.
+ */
+export type TestReplResult = {
+  /** One entry per successfully executed command (validation errors are captured in stderr, not here). */
+  results: Omit<TestCliResult, 'stdout' | 'stderr'>[];
+  /** All output from the entire REPL session. */
+  stdout: unknown[];
+  /** All errors from the entire REPL session. */
+  stderr: string[];
+};
+
+/**
+ * Fluent builder for setting up CLI test scenarios.
+ */
+export type TestCliBuilder = {
+  /** Set the CLI input string (e.g. `'deploy --env production'`). */
+  args(input: string): TestCliBuilder;
+  /** Set environment variables visible to the command. */
+  env(vars: Record<string, string | undefined>): TestCliBuilder;
+  /** Provide mock answers for interactive prompts. Keys are field names. */
+  prompt(answers: Record<string, unknown>): TestCliBuilder;
+  /** Provide mock stdin data (simulates piped input). */
+  stdin(data: string): TestCliBuilder;
+  /**
+   * Execute a single command via `eval()` and return the result with captured I/O.
+   * @param input - Optional CLI input string. Overrides `.args()` if provided.
+   */
+  run(input?: string): Promise<TestCliResult>;
+  /**
+   * Run a REPL session with the given sequence of inputs.
+   * Each string in the array is fed as one line of input.
+   * The session ends after all inputs are consumed (EOF).
+   */
+  repl(inputs: string[]): Promise<TestReplResult>;
+};
+
+/**
+ * Creates a fluent test builder for a Padrone program.
+ * Captures all I/O and provides a clean interface for assertions.
+ *
+ * Works with any test framework (bun:test, vitest, jest, node:test, etc.).
+ *
+ * @example
+ * ```ts
+ * import { testCli } from 'padrone/test'
+ *
+ * const result = await testCli(myProgram)
+ *   .args('deploy --env production')
+ *   .env({ API_KEY: 'xxx' })
+ *   .run()
+ *
+ * expect(result.result).toBe('Deployed')
+ * expect(result.stdout).toContain('Deploying...')
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Shorthand: pass input directly to run()
+ * const result = await testCli(myProgram).run('deploy --env production')
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Test interactive prompts
+ * const result = await testCli(myProgram)
+ *   .args('init')
+ *   .prompt({ name: 'myapp', template: 'react' })
+ *   .run()
+ *
+ * expect(result.args).toEqual({ name: 'myapp', template: 'react' })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Test REPL sessions
+ * const { results } = await testCli(myProgram)
+ *   .repl(['greet World', 'add --a=2 --b=3'])
+ *
+ * expect(results[0].result).toBe('Hello, World!')
+ * expect(results[1].result).toBe(5)
+ * ```
+ */
+/**
+ * Any program-like object that has `eval`, `runtime`, and `repl` methods.
+ * Avoids strict variance issues with `AnyPadroneProgram`.
+ */
+type TestableProgram = {
+  eval: (input: string, prefs?: Record<string, unknown>) => any;
+  runtime: (runtime: PadroneRuntime) => TestableProgram;
+  repl: (options?: { greeting?: false; hint?: false }) => AsyncIterable<any>;
+};
+
+export function testCli(program: TestableProgram): TestCliBuilder {
+  let input: string | undefined;
+  let envVars: Record<string, string | undefined> | undefined;
+  let promptAnswers: Record<string, unknown> | undefined;
+  let stdinData: string | undefined;
+
+  const builder: TestCliBuilder = {
+    args(args: string) {
+      input = args;
+      return builder;
+    },
+    env(vars) {
+      envVars = vars;
+      return builder;
+    },
+    prompt(answers) {
+      promptAnswers = answers;
+      return builder;
+    },
+    stdin(data: string) {
+      stdinData = data;
+      return builder;
+    },
+
+    async run(runInput?: string) {
+      const stdout: unknown[] = [];
+      const stderr: string[] = [];
+
+      const runtime = buildRuntime(stdout, stderr, { envVars, promptAnswers, stdinData });
+      const testProgram = program.runtime(runtime);
+
+      const evalResult = await testProgram.eval(runInput ?? input ?? '', {});
+      if (evalResult.error) {
+        stderr.push(evalResult.error instanceof Error ? evalResult.error.message : String(evalResult.error));
+      }
+      return toTestResult(evalResult, stdout, stderr);
+    },
+
+    async repl(inputs: string[]) {
+      const stdout: unknown[] = [];
+      const stderr: string[] = [];
+
+      const runtime = buildRuntime(stdout, stderr, {
+        envVars,
+        promptAnswers,
+        readLine: createMockReadLine(inputs),
+      });
+
+      const testProgram = program.runtime(runtime);
+      const results: Omit<TestCliResult, 'stdout' | 'stderr'>[] = [];
+
+      for await (const r of testProgram.repl({ greeting: false, hint: false })) {
+        results.push({
+          command: r.command!,
+          args: r.args,
+          result: r.result,
+          issues: r.argsResult?.issues as TestCliResult['issues'],
+        });
+      }
+
+      return { results, stdout, stderr };
+    },
+  };
+
+  return builder;
+}
+
+function toTestResult(evalResult: PadroneCommandResult, stdout: unknown[], stderr: string[]): TestCliResult {
+  return {
+    command: evalResult.command!,
+    args: evalResult.args,
+    result: evalResult.result,
+    error: evalResult.error,
+    issues: evalResult.argsResult?.issues as TestCliResult['issues'],
+    stdout,
+    stderr,
+  };
+}
+
+function buildRuntime(
+  stdout: unknown[],
+  stderr: string[],
+  opts: {
+    envVars?: Record<string, string | undefined>;
+    promptAnswers?: Record<string, unknown>;
+    readLine?: (prompt: string) => Promise<string | null>;
+    stdinData?: string;
+  },
+): PadroneRuntime {
+  const runtime: PadroneRuntime = {
+    output: (...args: unknown[]) => stdout.push(...args),
+    error: (text: string) => stderr.push(text),
+  };
+
+  if (opts.envVars) {
+    runtime.env = () => opts.envVars!;
+  }
+
+  if (opts.promptAnswers) {
+    runtime.interactive = 'supported';
+    runtime.prompt = async (config: InteractivePromptConfig) => opts.promptAnswers![config.name];
+  }
+
+  if (opts.readLine) {
+    runtime.readLine = opts.readLine;
+  }
+
+  if (opts.stdinData !== undefined) {
+    runtime.stdin = {
+      isTTY: false,
+      async text() {
+        return opts.stdinData!;
+      },
+      async *lines() {
+        const lines = opts.stdinData!.split('\n');
+        // Remove trailing empty line from final newline (matches readline behavior)
+        if (lines.length > 0 && lines[lines.length - 1] === '') lines.pop();
+        for (const line of lines) {
+          yield line;
+        }
+      },
+    };
+  } else {
+    // No stdin data: simulate a TTY (no piped input) to avoid reading from process.stdin
+    runtime.stdin = {
+      isTTY: true,
+      async text() {
+        return '';
+      },
+      async *lines() {
+        // no lines
+      },
+    };
+  }
+
+  return runtime;
+}
+
+function createMockReadLine(inputs: string[]): (prompt: string) => Promise<string | null> {
+  let index = 0;
+  return async (_prompt: string): Promise<string | null> => {
+    if (index >= inputs.length) return null;
+    return inputs[index++] ?? null;
+  };
+}

package/src/{update-check.ts → feature/update-check.ts}

@@ -1,4 +1,4 @@
-import type { ResolvedPadroneRuntime } from './runtime.ts';
+import type { ResolvedPadroneRuntime } from '../core/runtime.ts';
 
 /**
  * Configuration for the update check feature.
@@ -92,9 +92,9 @@ export function isNewerVersion(current: string, latest: string): boolean {
 /**
  * Reads the update check cache file.
  */
-function readCache(cachePath: string): CacheData | undefined {
+async function readCache(cachePath: string): Promise<CacheData | undefined> {
   try {
-    const { existsSync, readFileSync } = require('node:fs') as typeof import('node:fs');
+    const { existsSync, readFileSync } = await import('node:fs');
     if (!existsSync(cachePath)) return undefined;
     const data = JSON.parse(readFileSync(cachePath, 'utf-8'));
     if (typeof data.lastCheck === 'number' && typeof data.latestVersion === 'string') {
@@ -109,10 +109,10 @@ function readCache(cachePath: string): CacheData | undefined {
 /**
  * Writes the update check cache file.
  */
-function writeCache(cachePath: string, data: CacheData): void {
+async function writeCache(cachePath: string, data: CacheData): Promise<void> {
   try {
-    const { existsSync, mkdirSync, writeFileSync } = require('node:fs') as typeof import('node:fs');
-    const { dirname } = require('node:path') as typeof import('node:path');
+    const { existsSync, mkdirSync, writeFileSync } = await import('node:fs');
+    const { dirname } = await import('node:path');
     const dir = dirname(cachePath);
     if (!existsSync(dir)) {
       mkdirSync(dir, { recursive: true });
@@ -126,9 +126,9 @@ function writeCache(cachePath: string, data: CacheData): void {
 /**
  * Resolves the cache path, expanding `~` to the home directory.
  */
-function resolveCachePath(cachePath: string): string {
-  const { homedir } = require('node:os') as typeof import('node:os');
-  const { resolve } = require('node:path') as typeof import('node:path');
+async function resolveCachePath(cachePath: string): Promise<string> {
+  const { homedir } = await import('node:os');
+  const { resolve } = await import('node:path');
   if (cachePath.startsWith('~')) {
     return cachePath.replace('~', homedir());
   }
@@ -173,28 +173,28 @@ export function formatUpdateMessage(currentVersion: string, latestVersion: strin
  * This is designed to be non-blocking: the check starts immediately but the
  * result is only consumed after command execution completes.
  */
-export function createUpdateChecker(
+export async function createUpdateChecker(
   programName: string,
   currentVersion: string,
   config: UpdateCheckConfig,
   runtime: ResolvedPadroneRuntime,
-): () => void {
+): Promise<() => void> {
   const packageName = config.packageName ?? programName;
   const registry = config.registry ?? 'npm';
   const intervalMs = parseInterval(config.interval ?? '1d');
   const disableEnvVar = config.disableEnvVar ?? `${programName.toUpperCase().replace(/-/g, '_')}_NO_UPDATE_CHECK`;
 
   const defaultCachePath = `~/.config/${programName}-update-check.json`;
-  const cachePath = resolveCachePath(config.cache ?? defaultCachePath);
+  const cachePath = await resolveCachePath(config.cache ?? defaultCachePath);
 
   // Check if disabled
   const env = runtime.env();
   if (env.CI || env.CONTINUOUS_INTEGRATION) return noop;
   if (env[disableEnvVar]) return noop;
-  if (typeof process !== 'undefined' && !process.stdout?.isTTY) return noop;
+  if (runtime.terminal && !runtime.terminal.isTTY) return noop;
 
   // Check cache — if we checked recently, use cached result
-  const cached = readCache(cachePath);
+  const cached = await readCache(cachePath);
   if (cached && Date.now() - cached.lastCheck < intervalMs) {
     // Use cached version for display
     if (isNewerVersion(currentVersion, cached.latestVersion)) {
@@ -206,9 +206,9 @@ export function createUpdateChecker(
   }
 
   // Start background fetch
-  const fetchPromise = fetchLatestVersion(packageName, registry).then((latestVersion) => {
+  const fetchPromise = fetchLatestVersion(packageName, registry).then(async (latestVersion) => {
     if (latestVersion) {
-      writeCache(cachePath, { lastCheck: Date.now(), latestVersion });
+      await writeCache(cachePath, { lastCheck: Date.now(), latestVersion });
       if (isNewerVersion(currentVersion, latestVersion)) {
         return latestVersion;
       }

package/src/{wrap.ts → feature/wrap.ts}

@@ -1,6 +1,7 @@
 import type { StandardSchemaV1 } from '@standard-schema/spec';
-import { ValidationError } from './errors.ts';
-import type { PadroneSchema } from './types.ts';
+import { ValidationError } from '../core/errors.ts';
+import type { PadroneSchema } from '../types/index.ts';
+import { concatBytes } from '../util/stream.ts';
 
 /**
  * Configuration for wrapping an external CLI tool.
@@ -160,21 +161,22 @@ export function createWrapHandler<TCommandArgs extends PadroneSchema, TWrapArgs
         stdio: inheritStdio ? 'inherit' : ['ignore', 'pipe', 'pipe'],
       });
 
-      const stdoutChunks: Buffer[] = [];
-      const stderrChunks: Buffer[] = [];
+      const stdoutChunks: Uint8Array[] = [];
+      const stderrChunks: Uint8Array[] = [];
 
       if (!inheritStdio) {
-        proc.stdout!.on('data', (chunk: Buffer) => stdoutChunks.push(chunk));
-        proc.stderr!.on('data', (chunk: Buffer) => stderrChunks.push(chunk));
+        proc.stdout!.on('data', (chunk: Uint8Array) => stdoutChunks.push(chunk));
+        proc.stderr!.on('data', (chunk: Uint8Array) => stderrChunks.push(chunk));
       }
 
+      const decoder = new TextDecoder();
       proc.on('error', reject);
       proc.on('close', (code) => {
         const exitCode = code ?? 1;
         resolve({
           exitCode,
-          stdout: inheritStdio ? undefined : Buffer.concat(stdoutChunks).toString(),
-          stderr: inheritStdio ? undefined : Buffer.concat(stderrChunks).toString(),
+          stdout: inheritStdio ? undefined : decoder.decode(concatBytes(stdoutChunks)),
+          stderr: inheritStdio ? undefined : decoder.decode(concatBytes(stderrChunks)),
           success: exitCode === 0,
         });
       });

package/src/index.ts

@@ -1,51 +1,136 @@
-export type { AnsiStyle, ColorConfig, ColorTheme } from './colorizer.ts';
-export { colorThemes } from './colorizer.ts';
-export { asyncSchema, buildReplCompleter, createPadrone } from './create.ts';
-export type { PadroneErrorOptions } from './errors.ts';
-export { ActionError, ConfigError, PadroneError, RoutingError, ValidationError } from './errors.ts';
-export type { HelpInfo } from './formatter.ts';
-export type { PadroneMcpPreferences } from './mcp.ts';
+export { buildReplCompleter } from './core/commands.ts';
+export type { PadroneOptions } from './core/create.ts';
+export { createPadrone, defineCommand } from './core/create.ts';
+export type { PadroneErrorOptions } from './core/errors.ts';
+export { ActionError, ConfigError, PadroneError, RoutingError, SignalError, ValidationError } from './core/errors.ts';
+export { defineInterceptor } from './core/interceptors.ts';
+export { asyncSchema } from './core/results.ts';
 export type {
   InteractiveMode,
   InteractivePromptConfig,
+  PadroneBarAnimation,
+  PadroneBarChar,
+  PadroneBarConfig,
   PadroneProgressIndicator,
   PadroneProgressOptions,
+  PadroneProgressShow,
+  PadroneProgressUpdate,
   PadroneRuntime,
+  PadroneSignal,
   PadroneSpinnerConfig,
   PadroneSpinnerPreset,
-} from './runtime.ts';
-export { REPL_SIGINT } from './runtime.ts';
-export type { AsyncStreamMeta } from './stream.ts';
-export { asyncStream } from './stream.ts';
-export type { InferArgsInput, InferArgsOutput, InferCommand } from './type-helpers.ts';
-export type { Drained } from './type-utils.ts';
+} from './core/runtime.ts';
+export { REPL_SIGINT } from './core/runtime.ts';
+export type {
+  HelpCommand,
+  InkOptions,
+  OtelSpan,
+  OtelTracer,
+  OtelTracerProvider,
+  PadroneLogger,
+  PadroneLoggerConfig,
+  PadroneLogLevel,
+  PadroneProgressConfig,
+  PadroneProgressDefaults,
+  PadroneProgressMessage,
+  PadroneProgressMessages,
+  PadroneProgressRenderer,
+  PadroneTracer,
+  PadroneTracingConfig,
+  VersionCommand,
+  WithCompletion,
+  WithHelp,
+  WithLogger,
+  WithMan,
+  WithMcp,
+  WithProgress,
+  WithRepl,
+  WithServe,
+  WithTracing,
+  WithVersion,
+} from './extension/index.ts';
+export {
+  createTerminalProgress,
+  isReactElement,
+  padroneAutoOutput,
+  padroneColor,
+  padroneCompletion,
+  padroneConfig,
+  padroneEnv,
+  padroneHelp,
+  padroneInk,
+  padroneInteractive,
+  padroneLogger,
+  padroneMan,
+  padroneMcp,
+  padroneProgress,
+  padroneRepl,
+  padroneServe,
+  padroneSignalHandling,
+  padroneStdin,
+  padroneSuggestions,
+  padroneTiming,
+  padroneTracing,
+  padroneUpdateCheck,
+  padroneVersion,
+} from './extension/index.ts';
+export type { PadroneMcpPreferences } from './feature/mcp.ts';
+export type { UpdateCheckConfig } from './feature/update-check.ts';
+export type { WrapConfig, WrapResult } from './feature/wrap.ts';
+export type { AnsiStyle, ColorConfig, ColorTheme } from './output/colorizer.ts';
+export { colorThemes } from './output/colorizer.ts';
+export type { HelpInfo } from './output/formatter.ts';
+export type { PadroneOutputIndicator } from './output/output-indicator.ts';
+export type { KeyValueOptions, ListItem, ListOptions, TableOptions, TreeNode, TreeOptions } from './output/primitives.ts';
+export type { OutputContext, OutputFormat } from './output/styling.ts';
 export type {
   AnyPadroneBuilder,
   AnyPadroneCommand,
   AnyPadroneProgram,
   AsyncPadroneSchema,
+  CommandTypesBase,
+  DefineCommand,
+  ExtractInterceptorContext,
+  ExtractInterceptorRequires,
+  GetArgsMeta,
+  InterceptorBaseContext,
+  InterceptorDefBuilder,
+  InterceptorErrorContext,
+  InterceptorErrorResult,
+  InterceptorExecuteContext,
+  InterceptorExecuteResult,
+  InterceptorFactory,
+  InterceptorMeta,
+  InterceptorParseContext,
+  InterceptorParseResult,
+  InterceptorPhases,
+  InterceptorShutdownContext,
+  InterceptorStartContext,
+  InterceptorValidateContext,
+  InterceptorValidateResult,
   PadroneActionContext,
   PadroneBuilder,
   PadroneCommand,
   PadroneCommandResult,
+  PadroneContextInterceptor,
   PadroneDrainResult,
+  PadroneExtension,
+  PadroneInterceptor,
+  PadroneInterceptorFn,
   PadroneParseResult,
-  PadronePlugin,
   PadroneProgram,
-  PadroneProgressMessage,
-  PadroneProgressPrefs as PadroneProgressConfig,
+  PadroneProgramMeta,
   PadroneSchema,
-  PluginBaseContext,
-  PluginErrorContext,
-  PluginErrorResult,
-  PluginExecuteContext,
-  PluginExecuteResult,
-  PluginParseContext,
-  PluginParseResult,
-  PluginShutdownContext,
-  PluginStartContext,
-  PluginValidateContext,
-  PluginValidateResult,
-} from './types.ts';
-export type { UpdateCheckConfig } from './update-check.ts';
-export type { WrapConfig, WrapResult } from './wrap.ts';
+} from './types/index.ts';
+export type { AsyncStreamMeta } from './util/stream.ts';
+export { asyncStream } from './util/stream.ts';
+export type {
+  InferArgsInput,
+  InferArgsOutput,
+  InferCommand,
+  InferContext,
+  InferContextProvided,
+  InferInterceptorContext,
+  InferInterceptorRequires,
+} from './util/type-helpers.ts';
+export type { Drained } from './util/type-utils.ts';