padrone 1.5.0 → 1.7.0

package/src/test.ts

@@ -1,276 +1,2 @@
-import type { InteractivePromptConfig, PadroneRuntime } from './runtime.ts';
-import type { AnyPadroneCommand, PadroneCommandResult } from './types.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 config files. Keys are file paths, values are parsed config objects. */
-  config(files: Record<string, 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?: { autoOutput?: boolean }) => 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 configFiles: Record<string, 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;
-    },
-    config(files) {
-      configFiles = files;
-      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, configFiles, stdinData });
-      const testProgram = program.runtime(runtime);
-
-      const evalResult = await testProgram.eval(runInput ?? input ?? '', { autoOutput: false });
-      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,
-        configFiles,
-        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>;
-    configFiles?: Record<string, 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.configFiles) {
-    runtime.loadConfigFile = (path: string) => opts.configFiles![path];
-    runtime.findFile = (names: string[]) => names.find((n) => n in opts.configFiles!);
-  }
-
-  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;
-  };
-}
+export type { TestCliBuilder, TestCliResult, TestReplResult } from './feature/test.ts';
+export { testCli } from './feature/test.ts';

package/src/types/args-meta.ts

@@ -0,0 +1,151 @@
+type Letter =
+  | 'a'
+  | 'b'
+  | 'c'
+  | 'd'
+  | 'e'
+  | 'f'
+  | 'g'
+  | 'h'
+  | 'i'
+  | 'j'
+  | 'k'
+  | 'l'
+  | 'm'
+  | 'n'
+  | 'o'
+  | 'p'
+  | 'q'
+  | 'r'
+  | 's'
+  | 't'
+  | 'u'
+  | 'v'
+  | 'w'
+  | 'x'
+  | 'y'
+  | 'z';
+
+/** A single letter character, valid as a short CLI flag (e.g. `'v'`, `'n'`, `'V'`). */
+export type SingleChar = Letter | Uppercase<Letter>;
+
+export interface PadroneFieldMeta {
+  description?: string;
+  /** Single-character short flags (stackable: `-abc` = `-a -b -c`). Used with single dash. */
+  flags?: readonly SingleChar[] | SingleChar;
+  /** Multi-character alternative long names. Used with double dash (e.g. `--dry-run` for `--dryRun`). */
+  alias?: readonly string[] | string;
+  deprecated?: boolean | string;
+  hidden?: boolean;
+  examples?: readonly unknown[];
+  /** Group name for organizing this option under a labeled section in help output. */
+  group?: string;
+}
+
+type PositionalArgs<TObj> =
+  TObj extends Record<string, any>
+    ? {
+        [K in keyof TObj]: NonNullable<TObj[K]> extends Array<any> ? `...${K & string}` | (K & string) : K & string;
+      }[keyof TObj]
+    : string;
+
+/**
+ * Meta configuration for arguments, including positional arguments.
+ * The `positional` array defines which arguments are positional and their order.
+ * Use '...name' prefix to indicate variadic (rest) arguments, matching JS/TS rest syntax.
+ *
+ * @example
+ * ```ts
+ * .arguments(schema, {
+ *   positional: ['source', '...files', 'dest'],  // '...files' is variadic
+ * })
+ * ```
+ */
+/**
+ * Configuration for reading from stdin and mapping it to an argument field.
+ * Simply specify the field name — the read mode is inferred from the schema:
+ * - `string` field → reads all stdin as text
+ * - `string[]` field → reads stdin line-by-line
+ */
+export type StdinConfig<TObj = Record<string, any>> = keyof TObj & string;
+
+export interface PadroneArgsSchemaMeta<TObj = Record<string, any>> {
+  /**
+   * Array of argument names that should be treated as positional arguments.
+   * Order in array determines position. Use '...name' prefix for variadic args.
+   * @example ['source', '...files', 'dest'] - 'files' captures multiple values
+   */
+  positional?: readonly PositionalArgs<TObj>[];
+  /**
+   * Per-argument metadata.
+   */
+  fields?: { [K in keyof TObj]?: PadroneFieldMeta };
+  /**
+   * Automatically generate kebab-case aliases for camelCase option names.
+   * For example, `dryRun` automatically gets `--dry-run` as an alias.
+   * Defaults to `true`. Set to `false` to disable.
+   *
+   * @default true
+   * @example
+   * ```ts
+   * // Auto-aliases enabled (default): --dry-run → dryRun
+   * .arguments(z.object({ dryRun: z.boolean() }))
+   *
+   * // Disable auto-aliases
+   * .arguments(z.object({ dryRun: z.boolean() }), { autoAlias: false })
+   * ```
+   */
+  autoAlias?: boolean;
+  /**
+   * Read from stdin and inject the data into the specified argument field.
+   * Only reads when stdin is piped (not a TTY) and the field wasn't already provided via CLI flags.
+   *
+   * The read mode is inferred from the schema type of the target field:
+   * - `string` field → reads all stdin as a single string
+   * - `string[]` field → reads stdin line-by-line into an array
+   *
+   * Precedence: CLI flags > stdin > env vars > config file > schema defaults.
+   *
+   * @example
+   * ```ts
+   * // Read all stdin as text into 'data' field
+   * .arguments(z.object({ data: z.string() }), { stdin: 'data' })
+   *
+   * // Read stdin lines into 'lines' field (inferred from array schema)
+   * .arguments(z.object({ lines: z.string().array() }), { stdin: 'lines' })
+   * ```
+   */
+  stdin?: StdinConfig<TObj>;
+  /**
+   * Fields to interactively prompt for when their values are missing after CLI/env/config resolution.
+   * - `true`: prompt for all required fields that are missing.
+   * - `string[]`: prompt for these specific fields if missing.
+   *
+   * Interactive prompting only occurs in `cli()` when the runtime has `interactive: true`.
+   * Setting this makes `parse()` and `cli()` return Promises.
+   *
+   * @example
+   * ```ts
+   * .arguments(schema, {
+   *   interactive: true,                        // prompt all missing required fields
+   *   interactive: ['name', 'template'],         // prompt only these fields
+   * })
+   * ```
+   */
+  interactive?: true | readonly (keyof TObj & string)[];
+  /**
+   * Optional fields offered after required interactive prompts.
+   * Users are shown a multi-select to choose which of these fields to configure.
+   * - `true`: offer all optional fields that are missing.
+   * - `string[]`: offer these specific fields.
+   *
+   * @example
+   * ```ts
+   * .arguments(schema, {
+   *   interactive: ['name'],
+   *   optionalInteractive: ['typescript', 'eslint', 'prettier'],
+   * })
+   * ```
+   */
+  optionalInteractive?: true | readonly (keyof TObj & string)[];
+}