padrone 1.1.0 → 1.3.0

package/dist/test.d.mts

@@ -0,0 +1,112 @@
+import { b as PadroneRuntime, n as AnyPadroneCommand } from "./types-BS7RP5Ls.mjs";
+
+//#region src/test.d.ts
+/**
+ * Result from a single command execution in test mode.
+ * Extends the standard PadroneCommandResult with captured I/O.
+ */
+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.
+ */
+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.
+ */
+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>;
+};
+declare function testCli(program: TestableProgram): TestCliBuilder;
+//#endregion
+export { TestCliBuilder, TestCliResult, TestReplResult, testCli };
+//# sourceMappingURL=test.d.mts.map

package/dist/test.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"test.d.mts","names":[],"sources":["../src/test.ts"],"mappings":";;;;AAOA;;;KAAY,aAAA;EAEV,2BAAA,OAAA,EAAS,iBAAA,EAET;EAAA,IAAA,WAIA;EAFA,MAAA,WAE2B;EAA3B,MAAA;IAAU,OAAA;IAAiB,IAAA,GAAO,WAAA;EAAA,iBAM7B;EAJL,MAAA,aAUU;EARV,MAAA;EAEA,KAAA;AAAA;;;;KAMU,cAAA;EAMJ,wGAJN,OAAA,EAAS,IAAA,CAAK,aAAA,0BAUJ;EARV,MAAA;EAEA,MAAA;AAAA;;;;KAMU,cAAA;EAQI,mEANd,IAAA,CAAK,KAAA,WAAgB,cAAA,EAQA;EANrB,GAAA,CAAI,IAAA,EAAM,MAAA,+BAAqC,cAAA,EAW1B;EATrB,MAAA,CAAO,OAAA,EAAS,MAAA,oBAA0B,cAAA,EAelB;EAbxB,MAAA,CAAO,KAAA,EAAO,MAAA,SAAe,MAAA,qBAA2B,cAAA,EAazB;EAX/B,KAAA,CAAM,IAAA,WAAe,cAAA;EARhB;;;;EAaL,GAAA,CAAI,KAAA,YAAiB,OAAA,CAAQ,aAAA;EAXkB;;;;;EAiB/C,IAAA,CAAK,MAAA,aAAmB,OAAA,CAAQ,cAAA;AAAA;;;;;;;;;;;;;;;;;AAChC;;;;;;;;;;;;;;;;;;;;;;;AA0DF;;;;;;;;;;;KANK,eAAA;EACH,IAAA,GAAO,KAAA,UAAe,KAAA;IAAU,UAAA;EAAA;EAChC,OAAA,GAAU,OAAA,EAAS,cAAA,KAAmB,eAAA;EACtC,IAAA,GAAO,OAAA;IAAY,QAAA;IAAkB,IAAA;EAAA,MAAmB,aAAA;AAAA;AAAA,iBAG1C,OAAA,CAAQ,OAAA,EAAS,eAAA,GAAkB,cAAA"}

package/dist/test.mjs

@@ -0,0 +1,138 @@
+//#region src/test.ts
+function testCli(program) {
+	let input;
+	let envVars;
+	let promptAnswers;
+	let configFiles;
+	let stdinData;
+	const builder = {
+		args(args) {
+			input = args;
+			return builder;
+		},
+		env(vars) {
+			envVars = vars;
+			return builder;
+		},
+		prompt(answers) {
+			promptAnswers = answers;
+			return builder;
+		},
+		config(files) {
+			configFiles = files;
+			return builder;
+		},
+		stdin(data) {
+			stdinData = data;
+			return builder;
+		},
+		async run(runInput) {
+			const stdout = [];
+			const stderr = [];
+			const runtime = buildRuntime(stdout, stderr, {
+				envVars,
+				promptAnswers,
+				configFiles,
+				stdinData
+			});
+			const testProgram = program.runtime(runtime);
+			try {
+				return toTestResult(await testProgram.eval(runInput ?? input ?? "", { autoOutput: false }), stdout, stderr);
+			} catch (err) {
+				stderr.push(err instanceof Error ? err.message : String(err));
+				return {
+					command: void 0,
+					args: void 0,
+					result: void 0,
+					issues: void 0,
+					stdout,
+					stderr,
+					error: err
+				};
+			}
+		},
+		async repl(inputs) {
+			const stdout = [];
+			const stderr = [];
+			const runtime = buildRuntime(stdout, stderr, {
+				envVars,
+				promptAnswers,
+				configFiles,
+				readLine: createMockReadLine(inputs)
+			});
+			const testProgram = program.runtime(runtime);
+			const results = [];
+			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
+			});
+			return {
+				results,
+				stdout,
+				stderr
+			};
+		}
+	};
+	return builder;
+}
+function toTestResult(evalResult, stdout, stderr) {
+	return {
+		command: evalResult.command,
+		args: evalResult.args,
+		result: evalResult.result,
+		issues: evalResult.argsResult?.issues,
+		stdout,
+		stderr
+	};
+}
+function buildRuntime(stdout, stderr, opts) {
+	const runtime = {
+		output: (...args) => stdout.push(...args),
+		error: (text) => stderr.push(text)
+	};
+	if (opts.envVars) runtime.env = () => opts.envVars;
+	if (opts.promptAnswers) {
+		runtime.interactive = "supported";
+		runtime.prompt = async (config) => opts.promptAnswers[config.name];
+	}
+	if (opts.configFiles) {
+		runtime.loadConfigFile = (path) => opts.configFiles[path];
+		runtime.findFile = (names) => names.find((n) => n in opts.configFiles);
+	}
+	if (opts.readLine) runtime.readLine = opts.readLine;
+	if (opts.stdinData !== void 0) runtime.stdin = {
+		isTTY: false,
+		async text() {
+			return opts.stdinData;
+		},
+		async *lines() {
+			const lines = opts.stdinData.split("\n");
+			if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+			for (const line of lines) yield line;
+		}
+	};
+	else runtime.stdin = {
+		isTTY: true,
+		async text() {
+			return "";
+		},
+		async *lines() {}
+	};
+	return runtime;
+}
+function createMockReadLine(inputs) {
+	let index = 0;
+	return async (_prompt) => {
+		if (index >= inputs.length) return null;
+		return inputs[index++] ?? null;
+	};
+}
+//#endregion
+export { testCli };
+
+//# sourceMappingURL=test.mjs.map

package/dist/test.mjs.map

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