padrone 1.1.0 → 1.2.0

package/src/shell-utils.ts

@@ -0,0 +1,83 @@
+export type ShellType = 'bash' | 'zsh' | 'fish' | 'powershell';
+
+/**
+ * Detects the current shell from environment variables and process info.
+ * @returns The detected shell type, or undefined if unknown
+ */
+export function detectShell(): ShellType | undefined {
+  if (typeof process === 'undefined') return undefined;
+
+  // Method 1: Check SHELL environment variable (most common)
+  const shellEnv = process.env.SHELL || '';
+  if (shellEnv.includes('zsh')) return 'zsh';
+  if (shellEnv.includes('bash')) return 'bash';
+  if (shellEnv.includes('fish')) return 'fish';
+
+  // Method 2: Check Windows-specific shells
+  if (process.env.PSModulePath || process.env.POWERSHELL_DISTRIBUTION_CHANNEL) {
+    return 'powershell';
+  }
+
+  // Method 3: Check parent process on Unix-like systems
+  try {
+    const ppid = process.ppid;
+    if (ppid) {
+      const { execSync } = require('node:child_process') as typeof import('node:child_process');
+      const processName = execSync(`ps -p ${ppid} -o comm=`, {
+        encoding: 'utf-8',
+        stdio: ['pipe', 'pipe', 'ignore'],
+      }).trim();
+
+      if (processName.includes('zsh')) return 'zsh';
+      if (processName.includes('bash')) return 'bash';
+      if (processName.includes('fish')) return 'fish';
+    }
+  } catch {
+    // Ignore errors (e.g., ps not available)
+  }
+
+  return undefined;
+}
+
+export function getRcFile(shell: ShellType, home?: string): string | null {
+  const { homedir } = require('node:os') as typeof import('node:os');
+  const { join } = require('node:path') as typeof import('node:path');
+  const h = home ?? homedir();
+  switch (shell) {
+    case 'bash':
+      return join(h, '.bashrc');
+    case 'zsh':
+      return join(h, '.zshrc');
+    case 'fish':
+      return join(h, '.config', 'fish', 'config.fish');
+    case 'powershell':
+      return process.env.PROFILE || join(h, 'Documents', 'PowerShell', 'Microsoft.PowerShell_profile.ps1');
+    default:
+      return null;
+  }
+}
+
+export function escapeRegExp(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Writes a snippet to a shell config file using begin/end markers for idempotency.
+ * If a block with the same begin marker exists, it is replaced. Otherwise the snippet is appended.
+ */
+export function writeToRcFile(rcFile: string, snippet: string, beginMarker: string, endMarker: string): { file: string; updated: boolean } {
+  const { existsSync, mkdirSync, readFileSync, writeFileSync } = require('node:fs') as typeof import('node:fs');
+  const { dirname } = require('node:path') as typeof import('node:path');
+  const existing = existsSync(rcFile) ? readFileSync(rcFile, 'utf-8') : '';
+
+  if (existing.includes(beginMarker)) {
+    const pattern = new RegExp(`${escapeRegExp(beginMarker)}[\\s\\S]*?${escapeRegExp(endMarker)}`);
+    writeFileSync(rcFile, existing.replace(pattern, snippet));
+    return { file: rcFile, updated: true };
+  }
+
+  mkdirSync(dirname(rcFile), { recursive: true });
+  const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+  writeFileSync(rcFile, `${existing}${separator}\n${snippet}\n`);
+  return { file: rcFile, updated: false };
+}

package/src/test.ts

@@ -0,0 +1,285 @@
+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);
+
+      try {
+        const evalResult = await testProgram.eval(runInput ?? input ?? '', { autoOutput: false });
+        return toTestResult(evalResult, stdout, stderr);
+      } catch (err) {
+        stderr.push(err instanceof Error ? err.message : String(err));
+        return {
+          command: undefined as unknown as AnyPadroneCommand,
+          args: undefined,
+          result: undefined,
+          issues: undefined,
+          stdout,
+          stderr,
+          error: err,
+        };
+      }
+    },
+
+    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,
+    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;
+  };
+}

package/src/type-helpers.ts

@@ -2,22 +2,22 @@ import type { PickCommandByName, PossibleCommands } from './type-utils.ts';
 import type { AnyPadroneCommand, AnyPadroneProgram, PadroneCommand, PadroneSchema } from './types.ts';
 
 /**
- * Extracts the input type of the options schema from a command.
+ * Extracts the input type of the arguments schema from a command.
  * @example
  * ```ts
- * type Options = InferOptionsInput<typeof myCommand>;
+ * type Args = InferArgsInput<typeof myCommand>;
  * ```
  */
-export type InferOptionsInput<T extends AnyPadroneCommand> = T['~types']['optionsInput'];
+export type InferArgsInput<T extends AnyPadroneCommand> = T['~types']['argsInput'];
 
 /**
- * Extracts the output type of the options schema from a command.
+ * Extracts the output type of the arguments schema from a command.
  * @example
  * ```ts
- * type Options = InferOptionsOutput<typeof myCommand>;
+ * type Args = InferArgsOutput<typeof myCommand>;
  * ```
  */
-export type InferOptionsOutput<T extends AnyPadroneCommand> = T['~types']['optionsOutput'];
+export type InferArgsOutput<T extends AnyPadroneCommand> = T['~types']['argsOutput'];
 
 /**
  * Extracts the input type of the config schema from a command.
@@ -26,17 +26,17 @@ export type InferOptionsOutput<T extends AnyPadroneCommand> = T['~types']['optio
  * type Config = InferConfigInput<typeof myCommand>;
  * ```
  */
-export type InferConfigInput<T extends AnyPadroneCommand> = T['config'] extends PadroneSchema<infer I, any> ? I : never;
+export type InferConfigInput<T extends AnyPadroneCommand> = T['configSchema'] extends PadroneSchema<infer I, any> ? I : never;
 
 /**
  * Extracts the output type of the config schema from a command.
- * This is the type after transformation, which should match the options shape.
+ * This is the type after transformation, which should match the arguments shape.
  * @example
  * ```ts
  * type ConfigOutput = InferConfigOutput<typeof myCommand>;
  * ```
  */
-export type InferConfigOutput<T extends AnyPadroneCommand> = T['config'] extends PadroneSchema<any, infer O> ? O : never;
+export type InferConfigOutput<T extends AnyPadroneCommand> = T['configSchema'] extends PadroneSchema<any, infer O> ? O : never;
 
 /**
  * Extracts the input type of the env schema from a command.
@@ -50,7 +50,7 @@ export type InferEnvInput<T extends AnyPadroneCommand> = T['envSchema'] extends
 
 /**
  * Extracts the output type of the env schema from a command.
- * This is the type after transformation, which should match the options shape.
+ * This is the type after transformation, which should match the arguments shape.
  * @example
  * ```ts
  * type EnvOutput = InferEnvOutput<typeof myCommand>;

package/src/type-utils.ts

@@ -1,4 +1,4 @@
-import type { AnyPadroneCommand } from './types.ts';
+import type { AnyPadroneCommand, PadroneCommand } from './types.ts';
 
 /**
  * Use this type instead of `any` when you intend to fix it later
@@ -13,6 +13,54 @@ type IsNever<T> = [T] extends [never] ? true : false;
 
 export type IsGeneric<T> = IsAny<T> extends true ? true : IsUnknown<T> extends true ? true : IsNever<T> extends true ? true : false;
 
+/**
+ * Detects whether a schema has been branded as async via the `'~async'` property.
+ * Standard Schema V1's `validate()` always types its return as `Result | Promise<Result>`
+ * regardless of whether the schema is actually async, so we rely on an explicit brand instead.
+ *
+ * Use `asyncSchema(schema)` to brand a schema, or check for the `{ '~async': true }` property.
+ */
+export type IsAsyncSchema<T> = IsAny<T> extends true ? false : T extends { '~async': true } ? true : false;
+
+/**
+ * Computes the new TAsync flag when a schema is added to a builder.
+ * Once TAsync is `true`, it stays `true`. Otherwise, checks if the new schema is branded async.
+ */
+export type OrAsync<TExisting extends boolean, TSchema> = TExisting extends true
+  ? true
+  : IsAsyncSchema<TSchema> extends true
+    ? true
+    : false;
+
+/**
+ * Detects whether argument meta contains interactive or optionalInteractive configuration.
+ * When either is `true` or a `string[]`, the command requires async execution for prompting.
+ */
+export type HasInteractive<TMeta> = TMeta extends { interactive: true | string[] }
+  ? true
+  : TMeta extends { optionalInteractive: true | string[] }
+    ? true
+    : false;
+
+/**
+ * Combines schema-level async detection with meta-level interactive detection.
+ * Returns `true` if the existing async flag is set, the schema is branded async, or the meta has interactive fields.
+ */
+export type OrAsyncMeta<TExisting extends boolean, TMeta> = TExisting extends true
+  ? true
+  : HasInteractive<TMeta> extends true
+    ? true
+    : false;
+
+/**
+ * Conditionally wraps a type in Promise based on the TAsync flag.
+ * - `true` → `Promise<T>`
+ * - `false` → `T`
+ * - `boolean` (union of true|false) → `Promise<T>` (safe default when async-ness is uncertain)
+ * - `any` → `T` (for generic/any typed commands like AnyPadroneCommand)
+ */
+export type MaybePromise<T, TAsync> = IsAny<TAsync> extends true ? T : true extends TAsync ? Promise<T> : T;
+
 type SplitString<TName extends string, TSplitBy extends string = ' '> = TName extends `${infer FirstPart}${TSplitBy}${infer RestParts}`
   ? [FirstPart, ...SplitString<RestParts, TSplitBy>]
   : [TName];
@@ -62,6 +110,44 @@ type GetCommandPathsAndAliases<TCommand extends AnyPadroneCommand> = TCommand['~
     : Path
   : never;
 
+/**
+ * Find a direct child command in a tuple by name.
+ * Unlike PickCommandByName, this does NOT flatten — it only checks direct children by their `name` field.
+ */
+export type FindDirectChild<TCommands extends AnyPadroneCommand[], TName extends string> = TCommands extends [
+  infer First extends AnyPadroneCommand,
+  ...infer Rest extends AnyPadroneCommand[],
+]
+  ? First['~types']['name'] extends TName
+    ? First
+    : FindDirectChild<Rest, TName>
+  : never;
+
+/**
+ * Replace a command in a tuple by name, or append if not found.
+ * Used by `.command()` override semantics: re-registering a name replaces that entry.
+ */
+export type ReplaceOrAppendCommand<TCommands extends [...AnyPadroneCommand[]], TName extends string, TNew extends AnyPadroneCommand> =
+  HasDirectChild<TCommands, TName> extends true ? ReplaceInTuple<TCommands, TName, TNew> : [...TCommands, TNew];
+
+type HasDirectChild<TCommands extends AnyPadroneCommand[], TName extends string> = TCommands extends [
+  infer First extends AnyPadroneCommand,
+  ...infer Rest extends AnyPadroneCommand[],
+]
+  ? First['~types']['name'] extends TName
+    ? true
+    : HasDirectChild<Rest, TName>
+  : false;
+
+type ReplaceInTuple<TCommands extends AnyPadroneCommand[], TName extends string, TNew extends AnyPadroneCommand> = TCommands extends [
+  infer First extends AnyPadroneCommand,
+  ...infer Rest extends AnyPadroneCommand[],
+]
+  ? First['~types']['name'] extends TName
+    ? [TNew, ...Rest]
+    : [First, ...ReplaceInTuple<Rest, TName, TNew>]
+  : [];
+
 export type PickCommandByName<
   TCommands extends AnyPadroneCommand[],
   TName extends string | AnyPadroneCommand,
@@ -130,19 +216,43 @@ type CommandIsUnknownable<TCommand> =
  * This is done by recursively splitting the string by the last space, and then checking if the prefix is a valid command name or alias.
  * This is needed to avoid matching the top-level command when there are nested commands.
  */
+/**
+ * Recursively re-paths a command's children under a new parent path.
+ * Used by `mount()` to update all nested command paths when a program is mounted as a subcommand.
+ */
+export type RepathCommands<TCommands extends [...AnyPadroneCommand[]], TNewParentPath extends string> = TCommands extends [
+  infer First extends AnyPadroneCommand,
+  ...infer Rest extends AnyPadroneCommand[],
+]
+  ? [RepathCommand<First, TNewParentPath>, ...RepathCommands<Rest, TNewParentPath>]
+  : [];
+
+type RepathCommand<TCommand extends AnyPadroneCommand, TNewParentName extends string> = PadroneCommand<
+  TCommand['~types']['name'],
+  TNewParentName,
+  TCommand['~types']['argsSchema'],
+  TCommand['~types']['result'],
+  RepathCommands<TCommand['~types']['commands'], FullCommandName<TCommand['~types']['name'], TNewParentName>>,
+  TCommand['~types']['aliases'],
+  TCommand['~types']['configSchema'],
+  TCommand['~types']['envSchema'],
+  TCommand['~types']['async']
+>;
+
 export type PickCommandByPossibleCommands<
   TCommands extends AnyPadroneCommand[],
   TCommand extends PossibleCommands<TCommands, true, true> | SafeString,
-> = CommandIsUnknownable<TCommand> extends true
-  ? FlattenCommands<TCommands>
-  : TCommand extends AnyPadroneCommand
-    ? TCommand
-    : TCommand extends string
-      ? TCommand extends GetCommandPathsOrAliases<TCommands>
-        ? PickCommandByName<TCommands, TCommand>
-        : SplitLastSpace<TCommand> extends [infer Prefix extends string, infer Rest]
-          ? IsNever<Rest> extends true
-            ? PickCommandByName<TCommands, Prefix>
-            : PickCommandByPossibleCommands<TCommands, Prefix>
-          : never
-      : never;
+> =
+  CommandIsUnknownable<TCommand> extends true
+    ? FlattenCommands<TCommands>
+    : TCommand extends AnyPadroneCommand
+      ? TCommand
+      : TCommand extends string
+        ? TCommand extends GetCommandPathsOrAliases<TCommands>
+          ? PickCommandByName<TCommands, TCommand>
+          : SplitLastSpace<TCommand> extends [infer Prefix extends string, infer Rest]
+            ? IsNever<Rest> extends true
+              ? PickCommandByName<TCommands, Prefix>
+              : PickCommandByPossibleCommands<TCommands, Prefix>
+            : never
+        : never;