padrone 1.8.2 → 2.0.0

package/dist/core/results.mjs

@@ -0,0 +1,150 @@
+import { getCommandRuntime } from "./commands.mjs";
+//#region src/core/results.ts
+/**
+* Brands a schema as async, signaling that its `validate()` may return a Promise.
+* When an async-branded schema is passed to `.arguments()`, `.configFile()`, or `.env()`,
+* the command's `parse()` and `cli()` will return Promises.
+*/
+function asyncSchema(schema) {
+	return Object.assign(schema, { "~async": true });
+}
+const noop = () => void 0;
+/**
+* Maps over a value that may or may not be a Promise.
+* If the value is a Promise, chains with `.then()`. Otherwise, calls the function synchronously.
+* This preserves sync behavior for sync schemas and async behavior for async schemas.
+*/
+function thenMaybe(value, fn) {
+	if (value instanceof Promise) return value.then(fn);
+	return fn(value);
+}
+/**
+* Makes a sync result object thenable by adding `.then()`, `.catch()`, and `.finally()` methods.
+* If the value is already a Promise, returns it as-is.
+* This allows users to write `await program.cli()` or `program.cli().then(...)` regardless of sync/async.
+*
+* The `.then()` resolves with a plain copy (without thenable methods) to avoid infinite
+* recursive unwrapping by the Promise resolution algorithm.
+*/
+function makeThenable(value) {
+	if (value instanceof Promise) return value;
+	if (value !== null && typeof value === "object" && !("then" in value)) {
+		const toPlain = () => {
+			const plain = { ...value };
+			delete plain.then;
+			delete plain.catch;
+			delete plain.finally;
+			return plain;
+		};
+		value.then = (onfulfilled, onrejected) => {
+			try {
+				const result = onfulfilled ? onfulfilled(toPlain()) : toPlain();
+				return Promise.resolve(result);
+			} catch (err) {
+				if (onrejected) return Promise.resolve(onrejected(err));
+				return Promise.reject(err);
+			}
+		};
+		value.catch = (onrejected) => value.then(void 0, onrejected);
+		value.finally = (onfinally) => value.then((v) => {
+			onfinally?.();
+			return v;
+		}, (err) => {
+			onfinally?.();
+			throw err;
+		});
+	}
+	return value;
+}
+/**
+* Wraps a Promise to include a `drain()` method at the top level.
+* This allows `await promise.drain()` without first awaiting the promise.
+* Since cli/eval never reject, this just delegates to the resolved result's `drain()`.
+*/
+function withPromiseDrain(promise) {
+	promise.drain = async () => {
+		return (await promise).drain();
+	};
+	return promise;
+}
+function isIterator(value) {
+	return typeof value === "object" && value !== null && Symbol.iterator in value && typeof value[Symbol.iterator] === "function";
+}
+function isAsyncIterator(value) {
+	return typeof value === "object" && value !== null && Symbol.asyncIterator in value && typeof value[Symbol.asyncIterator] === "function";
+}
+/**
+* Resolves a result value by unwrapping Promises and collecting iterables into arrays.
+* This is the runtime counterpart of the `Drained<T>` type.
+*/
+async function drainValue(value) {
+	if (value instanceof Promise) return drainValue(await value);
+	if (isAsyncIterator(value)) {
+		const items = [];
+		const iter = value[Symbol.asyncIterator]();
+		while (true) {
+			const { done, value: item } = await iter.next();
+			if (done) break;
+			items.push(item);
+		}
+		return items;
+	}
+	if (typeof value !== "string" && !Array.isArray(value) && isIterator(value)) {
+		const items = [];
+		const iter = value[Symbol.iterator]();
+		while (true) {
+			const { done, value: item } = iter.next();
+			if (done) break;
+			items.push(item);
+		}
+		return items;
+	}
+	return value;
+}
+/**
+* Attaches a `drain()` method to a command result object.
+* If the result has an `error` field, `drain()` returns `{ error }`.
+* Otherwise, resolves the result (unwrapping Promises, collecting iterables), catches errors,
+* and returns a discriminated union `{ value } | { error }` that never throws.
+*/
+function withDrain(obj) {
+	obj.drain = async () => {
+		if ("error" in obj && obj.error !== void 0) return { error: obj.error };
+		try {
+			return { value: await drainValue(obj.result) };
+		} catch (err) {
+			return { error: err };
+		}
+	};
+	return obj;
+}
+/**
+* Creates an error command result with a `drain()` that returns the error.
+*/
+function errorResult(error, partial) {
+	return withDrain({
+		error,
+		result: void 0,
+		command: partial?.command,
+		args: partial?.args,
+		argsResult: partial?.argsResult
+	});
+}
+function isAsyncBranded(schema) {
+	return !!schema && typeof schema === "object" && "~async" in schema && schema["~async"] === true;
+}
+function hasInteractiveConfig(meta) {
+	if (!meta || typeof meta !== "object") return false;
+	const m = meta;
+	return m.interactive === true || Array.isArray(m.interactive) || m.optionalInteractive === true || Array.isArray(m.optionalInteractive);
+}
+function warnIfUnexpectedAsync(value, command) {
+	const runtime = getCommandRuntime(command);
+	if (runtime.env().NODE_ENV === "production") return value;
+	if (value instanceof Promise && !command.isAsync) runtime.error(`[padrone] Command "${command.path || command.name}" returned a Promise from validation, but was not marked as async. Use \`.async()\` on the builder or \`asyncSchema()\` to brand your schema. Without this, TypeScript will infer a sync return type and the result will be a Promise at runtime.`);
+	return value;
+}
+//#endregion
+export { asyncSchema, drainValue, errorResult, hasInteractiveConfig, isAsyncBranded, isAsyncIterator, isIterator, makeThenable, noop, thenMaybe, warnIfUnexpectedAsync, withDrain, withPromiseDrain };
+
+//# sourceMappingURL=results.mjs.map

package/dist/core/results.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"results.mjs","names":[],"sources":["../../src/core/results.ts"],"sourcesContent":["import type { AnyPadroneCommand, PadroneSchema } from '../types/index.ts';\nimport type { Thenable } from '../util/type-utils.ts';\nimport { getCommandRuntime } from './commands.ts';\n\n/**\n * Brands a schema as async, signaling that its `validate()` may return a Promise.\n * When an async-branded schema is passed to `.arguments()`, `.configFile()`, or `.env()`,\n * the command's `parse()` and `cli()` will return Promises.\n */\nexport function asyncSchema<T extends PadroneSchema>(schema: T): T & { '~async': true } {\n  return Object.assign(schema, { '~async': true as const });\n}\n\nexport const noop = <TRes>() => undefined as TRes;\n\n/**\n * Maps over a value that may or may not be a Promise.\n * If the value is a Promise, chains with `.then()`. Otherwise, calls the function synchronously.\n * This preserves sync behavior for sync schemas and async behavior for async schemas.\n */\nexport function thenMaybe<T, U>(value: T | Promise<T>, fn: (v: T) => U | Promise<U>): U | Promise<U> {\n  if (value instanceof Promise) return value.then(fn);\n  return fn(value);\n}\n\n/**\n * Makes a sync result object thenable by adding `.then()`, `.catch()`, and `.finally()` methods.\n * If the value is already a Promise, returns it as-is.\n * This allows users to write `await program.cli()` or `program.cli().then(...)` regardless of sync/async.\n *\n * The `.then()` resolves with a plain copy (without thenable methods) to avoid infinite\n * recursive unwrapping by the Promise resolution algorithm.\n */\nexport function makeThenable<T>(value: T | Promise<T>): Thenable<T> {\n  if (value instanceof Promise) return value as any;\n  if (value !== null && typeof value === 'object' && !('then' in value)) {\n    const toPlain = () => {\n      const plain = { ...value } as any;\n      delete plain.then;\n      delete plain.catch;\n      delete plain.finally;\n      return plain as T;\n    };\n    // biome-ignore lint/suspicious/noThenProperty: intentional thenable shim for sync results\n    (value as any).then = (onfulfilled?: (v: T) => any, onrejected?: (reason: any) => any) => {\n      try {\n        const result = onfulfilled ? onfulfilled(toPlain()) : toPlain();\n        return Promise.resolve(result);\n      } catch (err) {\n        if (onrejected) return Promise.resolve(onrejected(err));\n        return Promise.reject(err);\n      }\n    };\n    (value as any).catch = (onrejected?: (reason: any) => any) => (value as any).then(undefined, onrejected);\n    (value as any).finally = (onfinally?: () => void) =>\n      (value as any).then(\n        (v: any) => {\n          onfinally?.();\n          return v;\n        },\n        (err: any) => {\n          onfinally?.();\n          throw err;\n        },\n      );\n  }\n  return value as any;\n}\n\n/**\n * Wraps a Promise to include a `drain()` method at the top level.\n * This allows `await promise.drain()` without first awaiting the promise.\n * Since cli/eval never reject, this just delegates to the resolved result's `drain()`.\n */\nexport function withPromiseDrain<T extends Promise<any>>(promise: T): T & { drain: () => Promise<any> } {\n  (promise as any).drain = async () => {\n    const resolved = await promise;\n    return resolved.drain();\n  };\n  return promise as any;\n}\n\nexport function isIterator(value: unknown): value is Iterator<unknown> {\n  return typeof value === 'object' && value !== null && Symbol.iterator in value && typeof (value as any)[Symbol.iterator] === 'function';\n}\n\nexport function isAsyncIterator(value: unknown): value is AsyncIterator<unknown> {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    Symbol.asyncIterator in value &&\n    typeof (value as any)[Symbol.asyncIterator] === 'function'\n  );\n}\n\n/**\n * Writes a command's return value to output, handling promises, iterators, and async iterators.\n * Values are passed directly to the output function without stringification —\n * runtimes like Node/Bun already format objects via console.log.\n * Returns void or a Promise depending on whether async consumption is needed.\n */\nexport function outputValue(value: unknown, output: (...args: unknown[]) => void): void | Promise<void> {\n  if (value == null) return;\n\n  // Async iterator — consume and output each yielded value\n  if (isAsyncIterator(value)) {\n    return (async () => {\n      const iter = (value as any)[Symbol.asyncIterator]();\n      while (true) {\n        const { done, value: item } = await iter.next();\n        if (done) break;\n        if (item != null) output(item);\n      }\n    })();\n  }\n\n  // Sync iterator (but not a plain string/array which also have Symbol.iterator)\n  if (typeof value !== 'string' && !Array.isArray(value) && isIterator(value)) {\n    const iter = (value as any)[Symbol.iterator]();\n    while (true) {\n      const { done, value: item } = iter.next();\n      if (done) break;\n      if (item != null) output(item);\n    }\n    return;\n  }\n\n  // Promise — await then output\n  if (value instanceof Promise) {\n    return value.then((resolved) => outputValue(resolved, output));\n  }\n\n  // Pass value directly — runtime handles formatting\n  output(value);\n}\n\n/**\n * Resolves a result value by unwrapping Promises and collecting iterables into arrays.\n * This is the runtime counterpart of the `Drained<T>` type.\n */\nexport async function drainValue(value: unknown): Promise<unknown> {\n  // Unwrap promises first\n  if (value instanceof Promise) {\n    return drainValue(await value);\n  }\n\n  // Async iterator — collect into array\n  if (isAsyncIterator(value)) {\n    const items: unknown[] = [];\n    const iter = (value as any)[Symbol.asyncIterator]();\n    while (true) {\n      const { done, value: item } = await iter.next();\n      if (done) break;\n      items.push(item);\n    }\n    return items;\n  }\n\n  // Sync iterator (but not string/array)\n  if (typeof value !== 'string' && !Array.isArray(value) && isIterator(value)) {\n    const items: unknown[] = [];\n    const iter = (value as any)[Symbol.iterator]();\n    while (true) {\n      const { done, value: item } = iter.next();\n      if (done) break;\n      items.push(item);\n    }\n    return items;\n  }\n\n  return value;\n}\n\n/**\n * Attaches a `drain()` method to a command result object.\n * If the result has an `error` field, `drain()` returns `{ error }`.\n * Otherwise, resolves the result (unwrapping Promises, collecting iterables), catches errors,\n * and returns a discriminated union `{ value } | { error }` that never throws.\n */\nexport function withDrain<T extends Record<string, unknown>>(obj: T): T & { drain: () => Promise<any> } {\n  (obj as any).drain = async () => {\n    if ('error' in obj && obj.error !== undefined) {\n      return { error: obj.error };\n    }\n    try {\n      const value = await drainValue(obj.result);\n      return { value };\n    } catch (err) {\n      return { error: err };\n    }\n  };\n  return obj as any;\n}\n\n/**\n * Creates an error command result with a `drain()` that returns the error.\n */\nexport function errorResult(error: unknown, partial?: { command?: unknown; args?: unknown; argsResult?: unknown }) {\n  return withDrain({\n    error,\n    result: undefined,\n    command: partial?.command,\n    args: partial?.args,\n    argsResult: partial?.argsResult,\n  });\n}\n\nexport function isAsyncBranded(schema: unknown): boolean {\n  return !!schema && typeof schema === 'object' && '~async' in schema && (schema as any)['~async'] === true;\n}\n\nexport function hasInteractiveConfig(meta: unknown): boolean {\n  if (!meta || typeof meta !== 'object') return false;\n  const m = meta as Record<string, unknown>;\n  return m.interactive === true || Array.isArray(m.interactive) || m.optionalInteractive === true || Array.isArray(m.optionalInteractive);\n}\n\nexport function warnIfUnexpectedAsync<T>(value: T, command: AnyPadroneCommand): T {\n  const runtime = getCommandRuntime(command);\n  if (runtime.env().NODE_ENV === 'production') return value;\n  if (value instanceof Promise && !command.isAsync) {\n    runtime.error(\n      `[padrone] Command \"${command.path || command.name}\" returned a Promise from validation, ` +\n        `but was not marked as async. Use \\`.async()\\` on the builder or \\`asyncSchema()\\` to brand your schema. ` +\n        `Without this, TypeScript will infer a sync return type and the result will be a Promise at runtime.`,\n    );\n  }\n  return value;\n}\n"],"mappings":"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"}

package/dist/core/runtime.d.mts

@@ -0,0 +1,213 @@
+import { ColorConfig, ColorTheme } from "../output/colorizer.mjs";
+import { HelpFormat } from "../output/formatter.mjs";
+
+//#region src/core/runtime.d.ts
+/** Process signals that Padrone can handle for graceful shutdown. */
+type PadroneSignal = 'SIGINT' | 'SIGTERM' | 'SIGHUP';
+/** Value accepted by `PadroneProgress.update()`. */
+type PadroneProgressUpdate = string | number | {
+  message?: string;
+  progress?: number;
+  indeterminate?: boolean;
+  time?: boolean;
+};
+/**
+ * A progress indicator instance (spinner, progress bar, etc).
+ * Created by the runtime's `progress` factory and used to show loading state during command execution.
+ */
+type PadroneProgress = {
+  /**
+   * Update the indicator.
+   * - `string` — update the displayed message.
+   * - `number` — set progress ratio (0–1). Values outside this range are clamped.
+   * - `{ message?, progress?, indeterminate? }` — update message, progress, or both.
+   *
+   * Set `indeterminate: true` to force the bar into indeterminate mode (shows animation, no percentage).
+   * This makes the bar visible even in `show: 'auto'` mode without providing a number.
+   * Omitting `progress` (or passing a string) leaves the bar in its current state.
+   * Setting `progress` when bar mode is not enabled is a no-op for the bar portion.
+   *
+   * Set `time: true` to start the elapsed timer on demand (useful when `time` was not set in options).
+   * Set `time: false` to hide the elapsed timer.
+   */
+  update: (value: PadroneProgressUpdate) => void; /** Mark as succeeded and stop. Pass `null` to stop without rendering a final message. */
+  succeed: (message?: string | null, options?: {
+    indicator?: string;
+  }) => void; /** Mark as failed and stop. Pass `null` to stop without rendering a final message. */
+  fail: (message?: string | null, options?: {
+    indicator?: string;
+  }) => void; /** Control ETA (estimated time remaining) display at runtime. */
+  eta: {
+    /** Enable ETA tracking. Starts collecting samples from subsequent `update()` calls. */start: () => void; /** Disable ETA display. */
+    stop: () => void; /** Clear collected samples and restart estimation. Useful between operation phases. */
+    reset: () => void;
+  }; /** Stop without success/fail status. */
+  stop: () => void; /** Temporarily hide the indicator so other output can be written cleanly. */
+  pause: () => void; /** Redraw the indicator after a `pause()`. */
+  resume: () => void;
+};
+/** Controls when a progress element (spinner or bar) is visible. */
+type PadroneProgressShow = 'auto' | 'always' | 'never';
+/** Built-in spinner presets. */
+type PadroneSpinnerPreset = 'dots' | 'line' | 'arc' | 'bounce';
+/**
+ * Spinner configuration for progress indicators.
+ * - A preset name (e.g., `'dots'`) to use built-in frames.
+ * - `true` — default spinner with `show: 'always'` (visible even alongside a bar).
+ * - An object with custom `frames`, `interval`, and/or `show`.
+ * - `false` to disable the spinner (`show: 'never'`).
+ *
+ * Default `show` is `'auto'`: visible when the bar is not shown.
+ */
+type PadroneSpinnerConfig = PadroneSpinnerPreset | boolean | {
+  frames?: string[];
+  interval?: number;
+  show?: PadroneProgressShow;
+};
+/**
+ * Options passed to the runtime's `progress` factory.
+ */
+/** Common fill/empty character pairs for progress bars. */
+type PadroneBarChar = '█' | '░' | '▓' | '▒' | '─' | '━' | '■' | '□' | '#' | '-' | '=' | '·' | '▰' | '▱' | (string & {});
+/**
+ * Built-in indeterminate bar animation presets.
+ * - `'bounce'` — a filled segment slides back and forth (default).
+ * - `'slide'` — a filled segment slides left-to-right and wraps around.
+ * - `'pulse'` — the entire bar fades in and out using gradient characters (`░▒▓█▓▒░`).
+ */
+type PadroneBarAnimation = 'bounce' | 'slide' | 'pulse';
+/**
+ * Progress bar configuration.
+ */
+type PadroneBarConfig = {
+  /** Total width of the bar in characters. Defaults to `20`. */width?: number; /** Character used for the filled portion of the bar. Defaults to `'█'`. */
+  filled?: PadroneBarChar; /** Character used for the empty portion of the bar. Defaults to `'░'`. */
+  empty?: PadroneBarChar; /** Indeterminate animation style. Defaults to `'bounce'`. */
+  animation?: PadroneBarAnimation;
+  /**
+   * When the bar is visible. Defaults to `'always'` when bar is enabled, `'auto'` when bar is not explicitly configured.
+   * - `'always'` — bar is always shown (indeterminate until a number is provided).
+   * - `'auto'` — bar is shown only after `update()` is called with a number.
+   * - `'never'` — bar is never shown.
+   */
+  show?: PadroneProgressShow;
+};
+type PadroneProgressOptions = {
+  spinner?: PadroneSpinnerConfig; /** Enable a progress bar. `true` for defaults (`show: 'always'`), or a `PadroneBarConfig` object. `false` to disable entirely. When omitted, bar defaults to `show: 'auto'` (appears when a number is provided). */
+  bar?: boolean | PadroneBarConfig; /** Show elapsed time since the indicator started. Defaults to `false`. */
+  time?: boolean; /** Show estimated time remaining based on progress rate. Requires numeric `update()` calls. Defaults to `false`. */
+  eta?: boolean; /** Character/string shown before the success message. Defaults to `'✔'`. */
+  successIndicator?: string; /** Character/string shown before the error message. Defaults to `'✖'`. */
+  errorIndicator?: string;
+};
+/**
+ * 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.
+ */
+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.
+ */
+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.
+ */
+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'; /** Color theme for ANSI/console help output. A theme name or partial color config. */
+  theme?: ColorTheme | ColorConfig;
+  /**
+   * 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>;
+  /**
+   * Register a callback for process signals. Returns an unsubscribe function.
+   * The default runtime wires this to `process.on('SIGINT' | 'SIGTERM' | 'SIGHUP')`.
+   * Non-Node runtimes (web UIs, tests) can map their own cancellation semantics.
+   *
+   * When not provided, signal handling is disabled for this runtime.
+   */
+  onSignal?: (callback: (signal: PadroneSignal) => void) => () => void;
+  /**
+   * Terminal/output capabilities. Used for ANSI detection, text wrapping, and TTY checks.
+   * The default runtime auto-detects from `process.stdout`. Non-terminal runtimes
+   * (web UIs, tests) should provide explicit values.
+   */
+  terminal?: {
+    /** Number of columns in the terminal. Used for text wrapping. */columns?: number; /** Whether stdout is a TTY. Affects ANSI color output and interactive features. */
+    isTTY?: boolean;
+  };
+  /**
+   * Force-exit the process. The default runtime wires this to `process.exit()`.
+   * Non-Node runtimes can throw an error or no-op.
+   */
+  exit?: (code: number) => never;
+};
+/**
+ * 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.
+ */
+type ResolvedPadroneRuntime = Required<Omit<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin' | 'theme' | 'onSignal' | 'terminal' | 'exit'>> & Pick<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin' | 'theme' | 'onSignal' | 'terminal' | 'exit'>;
+/**
+ * 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).
+ */
+declare const REPL_SIGINT: unique symbol;
+//#endregion
+export { InteractiveMode, InteractivePromptConfig, PadroneBarAnimation, PadroneBarChar, PadroneBarConfig, PadroneProgress, PadroneProgressOptions, PadroneProgressShow, PadroneProgressUpdate, PadroneRuntime, PadroneSignal, PadroneSpinnerConfig, PadroneSpinnerPreset, REPL_SIGINT, ResolvedPadroneRuntime };
+//# sourceMappingURL=runtime.d.mts.map

package/dist/core/runtime.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.d.mts","names":[],"sources":["../../src/core/runtime.ts"],"mappings":";;;;;KAIY,aAAA;AAAZ;AAAA,KAGY,qBAAA;EAA4C,OAAA;EAAkB,QAAA;EAAmB,aAAA;EAAyB,IAAA;AAAA;;;;;KAM1G,eAAA;EAN0G;;AAAI;AAM1H;;;;;;;;;;;EAeE,MAAA,GAAS,KAAA,EAAO,qBAAqB,WAI9B;EAFP,OAAA,GAAU,OAAA,kBAAyB,OAAA;IAAY,SAAA;EAAA,YAM7C;EAJF,IAAA,GAAO,OAAA,kBAAyB,OAAA;IAAY,SAAA;EAAA,YAa5C;EAXA,GAAA;IAaM,uFAXJ,KAAA,cAeQ;IAbR,IAAA,cAa2B;IAX3B,KAAA;EAAA,GAcQ;EAXV,IAAA;EAEA,KAAA,cAS8B;EAP9B,MAAA;AAAA;;KAIU,mBAAA;;KAGA,oBAAA;;;;;AAW0H;AAMtI;;;;KANY,oBAAA,GAAuB,oBAAA;EAAmC,MAAA;EAAmB,QAAA;EAAmB,IAAA,GAAO,mBAAmB;AAAA;AAcvG;AAK/B;;;KAbY,cAAA;;;;;;;KAQA,mBAAA;;;;KAKA,gBAAA;EAQE,8DANZ,KAAA,WAaO;EAXP,MAAA,GAAS,cAAA,EAWiB;EAT1B,KAAA,GAAQ,cAAA,EAYwB;EAVhC,SAAA,GAAY,mBAAA;EAaoB;;;;;;EANhC,IAAA,GAAO,mBAAA;AAAA;AAAA,KAGG,sBAAA;EACV,OAAA,GAAU,oBAAA,EAUI;EARd,GAAA,aAAgB,gBAAgB,EAkBP;EAhBzB,IAAA,YAgByB;EAdzB,GAAA,YAoBU;EAlBV,gBAAA;EAEA,cAAA;AAAA;;;;;;;;KAUU,eAAA;AA0BZ;;;;AAAA,KApBY,uBAAA;EAgCF,qCA9BR,IAAA,UA2Cc;EAzCd,OAAA,UAuDc;EArDd,IAAA,+DA0D8C;EAxD9C,OAAA;IAAY,KAAA;IAAe,KAAA;EAAA,KA2EiB;EAzE5C,OAAA;AAAA;;;;;;;;KAUU,cAAA;EAYF,uGAVR,MAAA,OAAa,IAAA,sBAmBb;EAjBA,KAAA,IAAS,IAAA,mBAqBP;EAnBF,IAAA,mBAqBE;EAnBF,GAAA,SAAY,MAAA,8BA+BZ;EA7BA,MAAA,GAAS,UAAA,WAkCT;EAhCA,KAAA,GAAQ,UAAA,GAAa,WAAA;EAgCX;;;;;;;;EAvBV,KAAA;IA0CY,oEAxCV,KAAA,YAiDA;IA/CA,IAAA,QAAY,OAAA,UAwDd;IAtDE,KAAA,QAAa,aAAA;EAAA;EAsDK;AAOtB;;;;;;;;;EAjDE,WAAA,GAAc,eAAA;EAiDqB;;;;EA5CnC,MAAA,IAAU,MAAA,EAAQ,uBAAA,KAA4B,OAAA;EA+C3B;AAAA;AAMrB;;;;AAAgD;;;EA3C9C,QAAA,IAAY,MAAA,aAAmB,OAAA,iBAAwB,WAAA;;;;;;;;EASvD,QAAA,IAAY,QAAA,GAAW,MAAA,EAAQ,aAAA;;;;;;EAO/B,QAAA;qEAEE,OAAA;IAEA,KAAA;EAAA;;;;;EAOF,IAAA,IAAQ,IAAA;AAAA;;;;;KAOE,sBAAA,GAAyB,QAAA,CACnC,IAAA,CAAK,cAAA,mGAEL,IAAA,CAAK,cAAA;;;;;cAMM,WAAA"}

package/dist/core/runtime.mjs

@@ -0,0 +1,10 @@
+//#region src/core/runtime.ts
+/**
+* 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).
+*/
+const REPL_SIGINT = Symbol("REPL_SIGINT");
+//#endregion
+export { REPL_SIGINT };
+
+//# sourceMappingURL=runtime.mjs.map

package/dist/core/runtime.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.mjs","names":[],"sources":["../../src/core/runtime.ts"],"sourcesContent":["import type { ColorConfig, ColorTheme } from '../output/colorizer.ts';\nimport type { HelpFormat } from '../output/formatter.ts';\n\n/** Process signals that Padrone can handle for graceful shutdown. */\nexport type PadroneSignal = 'SIGINT' | 'SIGTERM' | 'SIGHUP';\n\n/** Value accepted by `PadroneProgress.update()`. */\nexport type PadroneProgressUpdate = string | number | { message?: string; progress?: number; indeterminate?: boolean; time?: boolean };\n\n/**\n * A progress indicator instance (spinner, progress bar, etc).\n * Created by the runtime's `progress` factory and used to show loading state during command execution.\n */\nexport type PadroneProgress = {\n  /**\n   * Update the indicator.\n   * - `string` — update the displayed message.\n   * - `number` — set progress ratio (0–1). Values outside this range are clamped.\n   * - `{ message?, progress?, indeterminate? }` — update message, progress, or both.\n   *\n   * Set `indeterminate: true` to force the bar into indeterminate mode (shows animation, no percentage).\n   * This makes the bar visible even in `show: 'auto'` mode without providing a number.\n   * Omitting `progress` (or passing a string) leaves the bar in its current state.\n   * Setting `progress` when bar mode is not enabled is a no-op for the bar portion.\n   *\n   * Set `time: true` to start the elapsed timer on demand (useful when `time` was not set in options).\n   * Set `time: false` to hide the elapsed timer.\n   */\n  update: (value: PadroneProgressUpdate) => void;\n  /** Mark as succeeded and stop. Pass `null` to stop without rendering a final message. */\n  succeed: (message?: string | null, options?: { indicator?: string }) => void;\n  /** Mark as failed and stop. Pass `null` to stop without rendering a final message. */\n  fail: (message?: string | null, options?: { indicator?: string }) => void;\n  /** Control ETA (estimated time remaining) display at runtime. */\n  eta: {\n    /** Enable ETA tracking. Starts collecting samples from subsequent `update()` calls. */\n    start: () => void;\n    /** Disable ETA display. */\n    stop: () => void;\n    /** Clear collected samples and restart estimation. Useful between operation phases. */\n    reset: () => void;\n  };\n  /** Stop without success/fail status. */\n  stop: () => void;\n  /** Temporarily hide the indicator so other output can be written cleanly. */\n  pause: () => void;\n  /** Redraw the indicator after a `pause()`. */\n  resume: () => void;\n};\n\n/** Controls when a progress element (spinner or bar) is visible. */\nexport type PadroneProgressShow = 'auto' | 'always' | 'never';\n\n/** Built-in spinner presets. */\nexport type PadroneSpinnerPreset = 'dots' | 'line' | 'arc' | 'bounce';\n\n/**\n * Spinner configuration for progress indicators.\n * - A preset name (e.g., `'dots'`) to use built-in frames.\n * - `true` — default spinner with `show: 'always'` (visible even alongside a bar).\n * - An object with custom `frames`, `interval`, and/or `show`.\n * - `false` to disable the spinner (`show: 'never'`).\n *\n * Default `show` is `'auto'`: visible when the bar is not shown.\n */\nexport type PadroneSpinnerConfig = PadroneSpinnerPreset | boolean | { frames?: string[]; interval?: number; show?: PadroneProgressShow };\n\n/**\n * Options passed to the runtime's `progress` factory.\n */\n/** Common fill/empty character pairs for progress bars. */\nexport type PadroneBarChar = '█' | '░' | '▓' | '▒' | '─' | '━' | '■' | '□' | '#' | '-' | '=' | '·' | '▰' | '▱' | (string & {});\n\n/**\n * Built-in indeterminate bar animation presets.\n * - `'bounce'` — a filled segment slides back and forth (default).\n * - `'slide'` — a filled segment slides left-to-right and wraps around.\n * - `'pulse'` — the entire bar fades in and out using gradient characters (`░▒▓█▓▒░`).\n */\nexport type PadroneBarAnimation = 'bounce' | 'slide' | 'pulse';\n\n/**\n * Progress bar configuration.\n */\nexport type PadroneBarConfig = {\n  /** Total width of the bar in characters. Defaults to `20`. */\n  width?: number;\n  /** Character used for the filled portion of the bar. Defaults to `'█'`. */\n  filled?: PadroneBarChar;\n  /** Character used for the empty portion of the bar. Defaults to `'░'`. */\n  empty?: PadroneBarChar;\n  /** Indeterminate animation style. Defaults to `'bounce'`. */\n  animation?: PadroneBarAnimation;\n  /**\n   * When the bar is visible. Defaults to `'always'` when bar is enabled, `'auto'` when bar is not explicitly configured.\n   * - `'always'` — bar is always shown (indeterminate until a number is provided).\n   * - `'auto'` — bar is shown only after `update()` is called with a number.\n   * - `'never'` — bar is never shown.\n   */\n  show?: PadroneProgressShow;\n};\n\nexport type PadroneProgressOptions = {\n  spinner?: PadroneSpinnerConfig;\n  /** Enable a progress bar. `true` for defaults (`show: 'always'`), or a `PadroneBarConfig` object. `false` to disable entirely. When omitted, bar defaults to `show: 'auto'` (appears when a number is provided). */\n  bar?: boolean | PadroneBarConfig;\n  /** Show elapsed time since the indicator started. Defaults to `false`. */\n  time?: boolean;\n  /** Show estimated time remaining based on progress rate. Requires numeric `update()` calls. Defaults to `false`. */\n  eta?: boolean;\n  /** Character/string shown before the success message. Defaults to `'✔'`. */\n  successIndicator?: string;\n  /** Character/string shown before the error message. Defaults to `'✖'`. */\n  errorIndicator?: string;\n};\n\n/**\n * Controls interactive prompting capability and default behavior at the runtime level.\n * - `'supported'` — capable; caller decides.\n * - `'unsupported'` — hard veto; nothing can override.\n * - `'forced'` — capable and forces prompts by default.\n * - `'disabled'` — capable but suppresses prompts by default.\n */\nexport type InteractiveMode = 'supported' | 'unsupported' | 'forced' | 'disabled';\n\n/**\n * Configuration passed to the runtime's `prompt` function for interactive field prompting.\n * The prompt type and choices are auto-detected from the field's JSON schema.\n */\nexport type InteractivePromptConfig = {\n  /** The field name being prompted. */\n  name: string;\n  /** Human-readable message/label for the prompt, derived from the field's description or name. */\n  message: string;\n  /** The prompt type, auto-detected from the JSON schema. */\n  type: 'input' | 'confirm' | 'select' | 'multiselect' | 'password';\n  /** Available choices for select/multiselect prompts. */\n  choices?: { label: string; value: unknown }[];\n  /** Default value from the schema. */\n  default?: unknown;\n};\n\n/**\n * Defines the execution context for a Padrone program.\n * Abstracts all environment-dependent I/O so the CLI framework\n * can run outside of a terminal (e.g., web UIs, chat interfaces, testing).\n *\n * All fields are optional — unspecified fields fall back to the Node.js/Bun defaults.\n */\nexport type PadroneRuntime = {\n  /** Write normal output (replaces console.log). Receives the raw value — runtime handles formatting. */\n  output?: (...args: unknown[]) => void;\n  /** Write error output (replaces console.error). */\n  error?: (text: string) => void;\n  /** Return the raw CLI arguments (replaces process.argv.slice(2)). */\n  argv?: () => string[];\n  /** Return environment variables (replaces process.env). */\n  env?: () => Record<string, string | undefined>;\n  /** Default help output format. */\n  format?: HelpFormat | 'auto';\n  /** Color theme for ANSI/console help output. A theme name or partial color config. */\n  theme?: ColorTheme | ColorConfig;\n  /**\n   * Standard input abstraction. Provides methods to read piped data from stdin.\n   * When not provided, defaults to reading from `process.stdin`.\n   *\n   * Used by commands that declare a `stdin` field in their arguments meta.\n   * The framework reads stdin automatically during the validate phase and\n   * injects the data into the specified argument field.\n   */\n  stdin?: {\n    /** Whether stdin is a TTY (interactive terminal) vs a pipe/file. */\n    isTTY?: boolean;\n    /** Read all of stdin as a string. */\n    text: () => Promise<string>;\n    /** Async iterable of lines for streaming. */\n    lines: () => AsyncIterable<string>;\n  };\n  /**\n   * Controls interactive prompting capability and default behavior.\n   * - `'supported'` — runtime can handle prompts; caller (flag/pref) decides whether to prompt. This is the default when `prompt` is provided.\n   * - `'unsupported'` — runtime cannot handle prompts; hard veto that nothing can override.\n   * - `'forced'` — runtime supports prompts and forces them by default (prompts even for provided values).\n   * - `'disabled'` — runtime supports prompts but suppresses them by default.\n   *\n   * `'unsupported'` is the only immutable state. For the others, the `--interactive`/`-i` flag\n   * and `cli()` preferences can override the default behavior.\n   */\n  interactive?: InteractiveMode;\n  /**\n   * Prompt the user for input. Called during `cli()` for fields marked as interactive.\n   * When `interactive` is `true` and this is not provided, defaults to an Enquirer-based terminal prompt.\n   */\n  prompt?: (config: InteractivePromptConfig) => Promise<unknown>;\n  /**\n   * Read a line of input from the user. Used by `repl()` for custom runtimes\n   * (web UIs, chat interfaces, testing).\n   * Returns the input string, `null` on EOF (e.g. Ctrl+D, closed connection),\n   * or `REPL_SIGINT` when the user presses Ctrl+C.\n   *\n   * When not provided, `repl()` uses a built-in Node.js readline session\n   * with command history (up/down arrows) and tab completion.\n   */\n  readLine?: (prompt: string) => Promise<string | typeof REPL_SIGINT | null>;\n\n  /**\n   * Register a callback for process signals. Returns an unsubscribe function.\n   * The default runtime wires this to `process.on('SIGINT' | 'SIGTERM' | 'SIGHUP')`.\n   * Non-Node runtimes (web UIs, tests) can map their own cancellation semantics.\n   *\n   * When not provided, signal handling is disabled for this runtime.\n   */\n  onSignal?: (callback: (signal: PadroneSignal) => void) => () => void;\n\n  /**\n   * Terminal/output capabilities. Used for ANSI detection, text wrapping, and TTY checks.\n   * The default runtime auto-detects from `process.stdout`. Non-terminal runtimes\n   * (web UIs, tests) should provide explicit values.\n   */\n  terminal?: {\n    /** Number of columns in the terminal. Used for text wrapping. */\n    columns?: number;\n    /** Whether stdout is a TTY. Affects ANSI color output and interactive features. */\n    isTTY?: boolean;\n  };\n\n  /**\n   * Force-exit the process. The default runtime wires this to `process.exit()`.\n   * Non-Node runtimes can throw an error or no-op.\n   */\n  exit?: (code: number) => never;\n};\n\n/**\n * Internal resolved runtime where all fields are guaranteed to be present.\n * The `prompt`, `interactive`, and `readLine` fields remain optional since not all runtimes provide them.\n */\nexport type ResolvedPadroneRuntime = Required<\n  Omit<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin' | 'theme' | 'onSignal' | 'terminal' | 'exit'>\n> &\n  Pick<PadroneRuntime, 'prompt' | 'interactive' | 'readLine' | 'stdin' | 'theme' | 'onSignal' | 'terminal' | 'exit'>;\n\n/**\n * Sentinel value returned by the terminal REPL session when Ctrl+C is pressed.\n * Distinguished from empty string (user pressed enter) and null (EOF/Ctrl+D).\n */\nexport const REPL_SIGINT = Symbol('REPL_SIGINT');\n\n/**\n * Internal session config for the REPL's persistent readline interface.\n */\nexport type ReplSessionConfig = {\n  completer?: (line: string) => [string[], string];\n  history?: string[];\n};\n"],"mappings":";;;;;AAsPA,MAAa,cAAc,OAAO,aAAa"}

package/dist/core/validate.mjs

@@ -0,0 +1,220 @@
+import { coerceArgs, detectUnknownArgs, extractSchemaMetadata, getJsonSchema, parsePositionalConfig, preprocessArgs } from "./args.mjs";
+import { getCommandRuntime } from "./commands.mjs";
+import { thenMaybe } from "./results.mjs";
+import { getNestedValue, parseCliInputToParts, setNestedValue } from "./parse.mjs";
+//#region src/core/validate.ts
+/**
+* Parses CLI input to find the command and extract raw arguments without validation.
+*/
+function parseCommand(input, rootCommand, findCommandByName) {
+	input ??= getCommandRuntime(rootCommand).argv().join(" ") || void 0;
+	if (!input) {
+		const defaultCommand = findCommandByName("", rootCommand.commands);
+		if (defaultCommand) return {
+			command: defaultCommand,
+			rawArgs: {},
+			args: [],
+			unmatchedTerms: []
+		};
+		return {
+			command: rootCommand,
+			rawArgs: {},
+			args: [],
+			unmatchedTerms: []
+		};
+	}
+	const parts = parseCliInputToParts(input);
+	const terms = parts.filter((p) => p.type === "term").map((p) => p.value);
+	const argTokens = parts.filter((p) => p.type === "arg").map((p) => p.value);
+	let curCommand = rootCommand;
+	let unmatchedTerms = [];
+	if (terms[0] === rootCommand.name) terms.shift();
+	for (let i = 0; i < terms.length; i++) {
+		const found = findCommandByName(terms[i] || "", curCommand.commands);
+		if (found) curCommand = found;
+		else {
+			unmatchedTerms = terms.slice(i);
+			argTokens.unshift(...unmatchedTerms);
+			break;
+		}
+	}
+	if (unmatchedTerms.length === 0 && curCommand.commands?.length) {
+		const defaultCommand = findCommandByName("", curCommand.commands);
+		if (defaultCommand) curCommand = defaultCommand;
+	}
+	if (!curCommand) return {
+		command: rootCommand,
+		rawArgs: {},
+		args: argTokens,
+		unmatchedTerms
+	};
+	const argsMeta = curCommand.meta?.fields;
+	const { flags, aliases, negatives, customNegation } = curCommand.argsSchema ? extractSchemaMetadata(curCommand.argsSchema, argsMeta, curCommand.meta?.autoAlias) : {
+		flags: {},
+		aliases: {},
+		negatives: {},
+		customNegation: /* @__PURE__ */ new Set()
+	};
+	const arrayArguments = /* @__PURE__ */ new Set();
+	if (curCommand.argsSchema) try {
+		const jsonSchema = getJsonSchema(curCommand.argsSchema);
+		if (jsonSchema.type === "object" && jsonSchema.properties) {
+			for (const [key, prop] of Object.entries(jsonSchema.properties)) if (prop?.type === "array") arrayArguments.add(key);
+		}
+	} catch {}
+	const argParts = parts.filter((p) => p.type === "named" || p.type === "alias");
+	const rawArgs = {};
+	for (const arg of argParts) {
+		let key;
+		if (arg.type === "alias" && arg.key.length === 1 && flags[arg.key[0]]) key = [flags[arg.key[0]]];
+		else if (arg.type === "named" && arg.key.length === 1 && aliases[arg.key[0]]) key = [aliases[arg.key[0]]];
+		else if (arg.type === "named" && arg.key.length === 1 && negatives[arg.key[0]]) {
+			setNestedValue(rawArgs, [negatives[arg.key[0]]], false);
+			continue;
+		} else key = arg.key;
+		const rootKey = key[0];
+		if (arg.type === "named" && arg.negated) {
+			if (customNegation.has(rootKey)) {
+				setNestedValue(rawArgs, [`no-${key.join(".")}`], false);
+				continue;
+			}
+			setNestedValue(rawArgs, key, false);
+			continue;
+		}
+		const value = arg.value ?? true;
+		if (arrayArguments.has(rootKey)) {
+			const existing = getNestedValue(rawArgs, key);
+			if (existing !== void 0) if (Array.isArray(existing)) if (Array.isArray(value)) existing.push(...value);
+			else existing.push(value);
+			else if (Array.isArray(value)) setNestedValue(rawArgs, key, [existing, ...value]);
+			else setNestedValue(rawArgs, key, [existing, value]);
+			else setNestedValue(rawArgs, key, Array.isArray(value) ? value : [value]);
+		} else {
+			const existing = getNestedValue(rawArgs, key);
+			if (existing !== void 0) if (Array.isArray(existing)) if (Array.isArray(value)) existing.push(...value);
+			else existing.push(value);
+			else if (Array.isArray(value)) setNestedValue(rawArgs, key, [existing, ...value]);
+			else setNestedValue(rawArgs, key, [existing, value]);
+			else setNestedValue(rawArgs, key, value);
+		}
+	}
+	return {
+		command: curCommand,
+		rawArgs,
+		args: argTokens,
+		unmatchedTerms
+	};
+}
+/**
+* Preprocesses raw arguments: maps positional arguments and performs auto-coercion.
+* External data sources (stdin, env, config) are handled by extensions before this runs.
+*/
+function buildCommandArgs(command, rawArgs, positionalArgs) {
+	let preprocessedArgs = preprocessArgs(rawArgs, {
+		flags: {},
+		aliases: {}
+	});
+	let issues;
+	const positionalConfig = command.meta?.positional ? parsePositionalConfig(command.meta.positional) : [];
+	if (positionalConfig.length > 0) {
+		let argIndex = 0;
+		for (let i = 0; i < positionalConfig.length; i++) {
+			const { name, variadic } = positionalConfig[i];
+			if (argIndex >= positionalArgs.length) break;
+			if (name in preprocessedArgs) {
+				issues ??= [];
+				issues.push({
+					path: [name],
+					message: `Ambiguous argument "${name}": provided both positionally and as a named option`
+				});
+				continue;
+			}
+			if (variadic) {
+				const nonVariadicAfter = positionalConfig.slice(i + 1).filter((p) => !p.variadic).length;
+				const variadicEnd = positionalArgs.length - nonVariadicAfter;
+				preprocessedArgs[name] = positionalArgs.slice(argIndex, variadicEnd);
+				argIndex = variadicEnd;
+			} else if (i === positionalConfig.length - 1 && positionalArgs.length > argIndex + 1) {
+				preprocessedArgs[name] = positionalArgs.slice(argIndex).join(" ");
+				argIndex = positionalArgs.length;
+			} else {
+				preprocessedArgs[name] = positionalArgs[argIndex];
+				argIndex++;
+			}
+		}
+	}
+	if (command.argsSchema) preprocessedArgs = coerceArgs(preprocessedArgs, command.argsSchema);
+	return {
+		args: preprocessedArgs,
+		issues
+	};
+}
+/**
+* Detects unknown options in args that aren't defined in the schema.
+* Returns unknown key info with suggestions, or empty array if schema is loose.
+*/
+function checkUnknownArgs(command, preprocessedArgs) {
+	if (!command.argsSchema) {
+		const unknowns = [];
+		for (const key of Object.keys(preprocessedArgs)) unknowns.push({ key });
+		return unknowns;
+	}
+	const argsMeta = command.meta?.fields;
+	const { flags, aliases, negatives } = extractSchemaMetadata(command.argsSchema, argsMeta, command.meta?.autoAlias);
+	return detectUnknownArgs(preprocessedArgs, command.argsSchema, flags, aliases, negatives);
+}
+/**
+* Validates preprocessed arguments against the command's schema.
+* First checks for unknown args (strict by default), then runs schema validation.
+* Returns sync or async result depending on the schema's validate method.
+*/
+function validateCommandArgs(command, preprocessedArgs) {
+	const unknownArgs = checkUnknownArgs(command, preprocessedArgs);
+	if (unknownArgs.length > 0) return {
+		args: void 0,
+		argsResult: { issues: unknownArgs.map(({ key }) => ({
+			path: [key],
+			message: `Unknown option: "${key}"`
+		})) }
+	};
+	const argsParsed = command.argsSchema ? command.argsSchema["~standard"].validate(preprocessedArgs) : { value: {} };
+	const buildResult = (parsed) => ({
+		args: parsed.issues ? void 0 : parsed.value,
+		argsResult: parsed
+	});
+	return thenMaybe(argsParsed, buildResult);
+}
+/**
+* Returns the list of known option names from a command's schema (for fuzzy suggestion).
+*/
+function getKnownOptionNames(command) {
+	if (!command.argsSchema) return [];
+	try {
+		const js = getJsonSchema(command.argsSchema);
+		if (js.type === "object" && js.properties) return Object.keys(js.properties);
+	} catch {}
+	return [];
+}
+/**
+* Formats validation issue messages for display.
+*/
+function formatIssueMessages(issues) {
+	return issues.map((i) => `  - ${i.path?.join(".") || "root"}: ${i.message}`).join("\n");
+}
+/**
+* Core validate function for parse() — preprocesses and validates CLI args.
+* Used by the parse program method (lighter weight than the full exec pipeline).
+* External data sources (stdin, env, config) are not resolved here — use eval() for that.
+*/
+function coreValidateForParse(command, rawArgs, positionalArgs) {
+	const { args: preprocessedArgs, issues } = buildCommandArgs(command, rawArgs, positionalArgs);
+	if (issues) return {
+		args: void 0,
+		argsResult: { issues }
+	};
+	return thenMaybe(validateCommandArgs(command, preprocessedArgs), (v) => v);
+}
+//#endregion
+export { buildCommandArgs, checkUnknownArgs, coreValidateForParse, formatIssueMessages, getKnownOptionNames, parseCommand, validateCommandArgs };
+
+//# sourceMappingURL=validate.mjs.map