padrone 1.1.0 → 1.3.0

package/dist/index.mjs

@@ -1,983 +1,228 @@
-import { createRequire } from "node:module";
-
-//#region rolldown:runtime
-var __require = /* @__PURE__ */ createRequire(import.meta.url);
-
-//#endregion
-//#region src/options.ts
+import { a as parsePositionalConfig, i as extractSchemaMetadata, n as coerceArgs, o as parseStdinConfig, r as detectUnknownArgs, s as preprocessArgs } from "./args-DFEI7_G_.mjs";
+import { S as getVersion, _ as warnIfUnexpectedAsync, a as commandSymbol, b as createTerminalReplSession, c as hasInteractiveConfig, d as noop, f as outputValue, g as thenMaybe, h as suggestSimilar, i as buildReplCompleter, l as isAsyncBranded, m as runPluginChain, o as findCommandByName, p as repathCommandTree, r as asyncSchema, s as getCommandRuntime, t as generateHelp, u as mergeCommands, v as wrapWithLifecycle, x as resolveStdin, y as REPL_SIGINT } from "./help-CgGP7hQU.mjs";
+//#region src/errors.ts
 /**
-* Parse positional configuration to extract names and variadic info.
+* Base error class for all Padrone errors.
+* Carries structured metadata for user-friendly formatting and programmatic handling.
+*
+* @example
+* ```ts
+* throw new PadroneError('Something went wrong', {
+*   exitCode: 1,
+*   suggestions: ['Try --help for usage information'],
+* });
+* ```
 */
-function parsePositionalConfig(positional) {
-	return positional.map((p) => {
-		const isVariadic = p.startsWith("...");
+var PadroneError = class extends Error {
+	exitCode;
+	suggestions;
+	command;
+	phase;
+	constructor(message, options) {
+		super(message, options?.cause ? { cause: options.cause } : void 0);
+		this.name = "PadroneError";
+		this.exitCode = options?.exitCode ?? 1;
+		this.suggestions = options?.suggestions ?? [];
+		this.command = options?.command;
+		this.phase = options?.phase;
+	}
+	/**
+	* Returns a serializable representation of the error,
+	* suitable for non-terminal runtimes (web UIs, APIs, etc.).
+	*/
+	toJSON() {
 		return {
-			name: isVariadic ? p.slice(3) : p,
-			variadic: isVariadic
+			name: this.name,
+			message: this.message,
+			exitCode: this.exitCode,
+			suggestions: this.suggestions,
+			command: this.command,
+			phase: this.phase
 		};
-	});
-}
-/**
-* Extract all option metadata from schema and meta in a single pass.
-* This consolidates aliases, env bindings, and config keys extraction.
-*/
-function extractSchemaMetadata(schema, meta) {
-	const aliases = {};
-	if (meta) for (const [key, value] of Object.entries(meta)) {
-		if (!value) continue;
-		if (value.alias) {
-			const list = typeof value.alias === "string" ? [value.alias] : value.alias;
-			for (const aliasKey of list) if (typeof aliasKey === "string" && aliasKey && aliasKey !== key) aliases[aliasKey] = key;
-		}
-	}
-	try {
-		const jsonSchema = schema["~standard"].jsonSchema.input({ target: "draft-2020-12" });
-		if (jsonSchema.type === "object" && jsonSchema.properties) for (const [propertyName, propertySchema] of Object.entries(jsonSchema.properties)) {
-			if (!propertySchema) continue;
-			const propAlias = propertySchema.alias;
-			if (propAlias) {
-				const list = typeof propAlias === "string" ? [propAlias] : propAlias;
-				if (Array.isArray(list)) {
-					for (const aliasKey of list) if (typeof aliasKey === "string" && aliasKey && aliasKey !== propertyName && !(aliasKey in aliases)) aliases[aliasKey] = propertyName;
-				}
-			}
-		}
-	} catch {}
-	return { aliases };
-}
-function preprocessAliases(data, aliases) {
-	const result = { ...data };
-	for (const [aliasKey, fullOptionName] of Object.entries(aliases)) if (aliasKey in data && aliasKey !== fullOptionName) {
-		const aliasValue = data[aliasKey];
-		if (!(fullOptionName in result)) result[fullOptionName] = aliasValue;
-		delete result[aliasKey];
-	}
-	return result;
-}
-/**
-* Apply values directly to options.
-* CLI values take precedence over the provided values.
-*/
-function applyValues(data, values) {
-	const result = { ...data };
-	for (const [key, value] of Object.entries(values)) {
-		if (key in result && result[key] !== void 0) continue;
-		if (value !== void 0) result[key] = value;
-	}
-	return result;
-}
-/**
-* Combined preprocessing of options with all features.
-* Precedence order (highest to lowest): CLI args > env vars > config file
-*/
-function preprocessOptions(data, ctx) {
-	let result = { ...data };
-	if (ctx.aliases && Object.keys(ctx.aliases).length > 0) result = preprocessAliases(result, ctx.aliases);
-	if (ctx.envData) result = applyValues(result, ctx.envData);
-	if (ctx.configData) result = applyValues(result, ctx.configData);
-	return result;
-}
-
-//#endregion
-//#region src/completion.ts
-/**
-* Detects the current shell from environment variables and process info.
-* @returns The detected shell type, or undefined if unknown
-*/
-function detectShell() {
-	if (typeof process === "undefined") return void 0;
-	const shellEnv = process.env.SHELL || "";
-	if (shellEnv.includes("zsh")) return "zsh";
-	if (shellEnv.includes("bash")) return "bash";
-	if (shellEnv.includes("fish")) return "fish";
-	if (process.env.PSModulePath || process.env.POWERSHELL_DISTRIBUTION_CHANNEL) return "powershell";
-	try {
-		const { execSync } = __require("node:child_process");
-		const ppid = process.ppid;
-		if (ppid) {
-			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 {}
-}
-/**
-* Collects all commands from a program recursively.
-*/
-function collectAllCommands(cmd) {
-	const result = [];
-	if (cmd.commands) {
-		for (const subcmd of cmd.commands) if (!subcmd.hidden) {
-			result.push(subcmd);
-			result.push(...collectAllCommands(subcmd));
-		}
-	}
-	return result;
-}
-/**
-* Extracts all option names from a command's schema.
-*/
-function extractOptions(cmd) {
-	const options = [];
-	if (!cmd.options) return options;
-	try {
-		const optionsMeta = cmd.meta?.options;
-		const { aliases } = extractSchemaMetadata(cmd.options, optionsMeta);
-		const aliasToOption = {};
-		for (const [opt, alias] of Object.entries(aliases)) aliasToOption[alias] = opt;
-		const jsonSchema = cmd.options["~standard"].jsonSchema.input({ target: "draft-2020-12" });
-		if (jsonSchema.type === "object" && jsonSchema.properties) for (const [key, prop] of Object.entries(jsonSchema.properties)) {
-			const alias = Object.entries(aliases).find(([opt]) => opt === key)?.[1];
-			options.push({
-				name: key,
-				alias,
-				isBoolean: prop?.type === "boolean"
-			});
-		}
-	} catch {}
-	return options;
-}
-/**
-* Generates a Bash completion script for the program.
-*/
-function generateBashCompletion(program) {
-	const programName = program.name;
-	const commands = collectAllCommands(program);
-	const commandNames = commands.map((c) => c.name).join(" ");
-	const allOptions = /* @__PURE__ */ new Set();
-	allOptions.add("--help");
-	allOptions.add("--version");
-	for (const cmd of [program, ...commands]) for (const opt of extractOptions(cmd)) {
-		allOptions.add(`--${opt.name}`);
-		if (opt.alias) allOptions.add(`-${opt.alias}`);
 	}
-	const optionsList = Array.from(allOptions).join(" ");
-	return `###-begin-${programName}-completion-###
-#
-# ${programName} command completion script
-#
-# Installation: ${programName} completion >> ~/.bashrc  (or ~/.zshrc)
-# Or, maybe: ${programName} completion > /usr/local/etc/bash_completion.d/${programName}
-#
-
-if type complete &>/dev/null; then
-  _${programName}_completion() {
-    local cur prev words cword
-    if type _get_comp_words_by_ref &>/dev/null; then
-      _get_comp_words_by_ref -n = -n @ -n : -w words -i cword
-    else
-      cword="$COMP_CWORD"
-      words=("\${COMP_WORDS[@]}")
-    fi
-
-    cur="\${words[cword]}"
-    prev="\${words[cword-1]}"
-
-    local commands="${commandNames}"
-    local options="${optionsList}"
-
-    # Complete options when current word starts with -
-    if [[ "$cur" == -* ]]; then
-      COMPREPLY=($(compgen -W "$options" -- "$cur"))
-      return 0
-    fi
-
-    # Complete commands
-    COMPREPLY=($(compgen -W "$commands" -- "$cur"))
-  }
-  complete -o bashdefault -o default -o nospace -F _${programName}_completion ${programName}
-elif type compdef &>/dev/null; then
-  _${programName}_completion() {
-    local si=$IFS
-    local commands="${commandNames}"
-    local options="${optionsList}"
-
-    if [[ "\${words[CURRENT]}" == -* ]]; then
-      compadd -- \${=options}
-    else
-      compadd -- \${=commands}
-    fi
-    IFS=$si
-  }
-  compdef _${programName}_completion ${programName}
-elif type compctl &>/dev/null; then
-  _${programName}_completion() {
-    local commands="${commandNames}"
-    local options="${optionsList}"
-
-    if [[ "\${words[CURRENT]}" == -* ]]; then
-      reply=(\${=options})
-    else
-      reply=(\${=commands})
-    fi
-  }
-  compctl -K _${programName}_completion ${programName}
-fi
-###-end-${programName}-completion-###`;
-}
+};
 /**
-* Generates a Zsh completion script for the program.
+* Thrown when command routing fails — unknown command, unexpected arguments, etc.
 */
-function generateZshCompletion(program) {
-	const programName = program.name;
-	const commands = collectAllCommands(program);
-	const commandCompletions = commands.map((cmd) => {
-		const escapedDesc = (cmd.description || cmd.title || "").replace(/'/g, "'\\''").replace(/:/g, "\\:");
-		return `      '${cmd.name}:${escapedDesc}'`;
-	}).join("\n");
-	const optionCompletions = [];
-	optionCompletions.push("      '--help[Show help information]'");
-	optionCompletions.push("      '--version[Show version number]'");
-	const seenOptions = new Set(["help", "version"]);
-	for (const cmd of [program, ...commands]) for (const opt of extractOptions(cmd)) {
-		if (seenOptions.has(opt.name)) continue;
-		seenOptions.add(opt.name);
-		const escapedDesc = (cmd.meta?.options?.[opt.name]?.description || "").replace(/'/g, "'\\''").replace(/\[/g, "\\[").replace(/\]/g, "\\]");
-		if (opt.alias) optionCompletions.push(`      {-${opt.alias},--${opt.name}}'[${escapedDesc}]'`);
-		else optionCompletions.push(`      '--${opt.name}[${escapedDesc}]'`);
+var RoutingError = class extends PadroneError {
+	constructor(message, options) {
+		super(message, {
+			phase: "parse",
+			...options
+		});
+		this.name = "RoutingError";
 	}
-	return `#compdef ${programName}
-###-begin-${programName}-completion-###
-#
-# ${programName} command completion script for Zsh
-#
-# Installation: ${programName} completion >> ~/.zshrc
-# Or: ${programName} completion > ~/.zsh/completions/_${programName}
-#
-
-_${programName}() {
-  local -a commands
-  local -a options
-
-  commands=(
-${commandCompletions}
-  )
-
-  options=(
-${optionCompletions.join("\n")}
-  )
-
-  _arguments -s \\
-    $options \\
-    '1: :->command' \\
-    '*::arg:->args'
-
-  case "$state" in
-    command)
-      _describe 'command' commands
-      ;;
-  esac
-}
-
-_${programName}
-###-end-${programName}-completion-###`;
-}
+};
 /**
-* Generates a Fish completion script for the program.
+* Thrown when argument or schema validation fails.
+* Carries the structured issues from the schema validator.
 */
-function generateFishCompletion(program) {
-	const programName = program.name;
-	const commands = collectAllCommands(program);
-	const lines = [
-		`###-begin-${programName}-completion-###`,
-		"#",
-		`# ${programName} command completion script for Fish`,
-		"#",
-		`# Installation: ${programName} completion > ~/.config/fish/completions/${programName}.fish`,
-		"#",
-		"",
-		`# Clear existing completions`,
-		`complete -c ${programName} -e`,
-		"",
-		"# Commands"
-	];
-	for (const cmd of commands) {
-		const escapedDesc = (cmd.description || cmd.title || "").replace(/'/g, "\\'");
-		lines.push(`complete -c ${programName} -n "__fish_use_subcommand" -a "${cmd.name}" -d '${escapedDesc}'`);
+var ValidationError = class extends PadroneError {
+	issues;
+	constructor(message, issues, options) {
+		super(message, {
+			phase: "validate",
+			...options
+		});
+		this.name = "ValidationError";
+		this.issues = issues;
 	}
-	lines.push("");
-	lines.push("# Global options");
-	lines.push(`complete -c ${programName} -l help -d 'Show help information'`);
-	lines.push(`complete -c ${programName} -l version -d 'Show version number'`);
-	const seenOptions = new Set(["help", "version"]);
-	for (const cmd of [program, ...commands]) for (const opt of extractOptions(cmd)) {
-		if (seenOptions.has(opt.name)) continue;
-		seenOptions.add(opt.name);
-		const escapedDesc = (cmd.meta?.options?.[opt.name]?.description || "").replace(/'/g, "\\'");
-		if (opt.alias) lines.push(`complete -c ${programName} -s ${opt.alias} -l ${opt.name} -d '${escapedDesc}'`);
-		else lines.push(`complete -c ${programName} -l ${opt.name} -d '${escapedDesc}'`);
+	toJSON() {
+		return {
+			...super.toJSON(),
+			issues: this.issues.map((i) => ({
+				path: i.path?.map(String),
+				message: i.message
+			}))
+		};
 	}
-	lines.push(`###-end-${programName}-completion-###`);
-	return lines.join("\n");
-}
-/**
-* Generates a PowerShell completion script for the program.
-*/
-function generatePowerShellCompletion(program) {
-	const programName = program.name;
-	return `###-begin-${programName}-completion-###
-#
-# ${programName} command completion script for PowerShell
-#
-# Installation: ${programName} completion >> $PROFILE
-#
-
-Register-ArgumentCompleter -Native -CommandName ${programName} -ScriptBlock {
-  param($wordToComplete, $commandAst, $cursorPosition)
-
-  $commands = @(${collectAllCommands(program).map((c) => `'${c.name}'`).join(", ")})
-  $options = @('--help', '--version')
-
-  if ($wordToComplete -like '-*') {
-    $options | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
-      [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
-    }
-  } else {
-    $commands | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
-      [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
-    }
-  }
-}
-###-end-${programName}-completion-###`;
-}
+};
 /**
-* Generates a completion script for the specified shell.
+* Thrown when config file loading or validation fails.
 */
-function generateCompletion(program, shell) {
-	switch (shell) {
-		case "bash": return generateBashCompletion(program);
-		case "zsh": return generateZshCompletion(program);
-		case "fish": return generateFishCompletion(program);
-		case "powershell": return generatePowerShellCompletion(program);
-		default: throw new Error(`Unsupported shell: ${shell}`);
+var ConfigError = class extends PadroneError {
+	constructor(message, options) {
+		super(message, {
+			phase: "config",
+			...options
+		});
+		this.name = "ConfigError";
 	}
-}
+};
 /**
-* Gets the installation instructions for a shell completion script.
+* Thrown from user action handlers to surface structured errors with exit codes and suggestions.
+* This is the primary error class users should throw from their command actions.
+*
+* @example
+* ```ts
+* throw new ActionError('Missing environment', {
+*   exitCode: 1,
+*   suggestions: ['Use --env production or --env staging'],
+* });
+* ```
 */
-function getCompletionInstallInstructions(programName, shell) {
-	switch (shell) {
-		case "bash": return `# Add to ~/.bashrc:
-${programName} completion bash >> ~/.bashrc
-
-# Or install system-wide:
-${programName} completion bash > /usr/local/etc/bash_completion.d/${programName}`;
-		case "zsh": return `# Add to ~/.zshrc:
-${programName} completion zsh >> ~/.zshrc
-
-# Or add to completions directory:
-${programName} completion zsh > ~/.zsh/completions/_${programName}`;
-		case "fish": return `# Install to Fish completions:
-${programName} completion fish > ~/.config/fish/completions/${programName}.fish`;
-		case "powershell": return `# Add to PowerShell profile:
-${programName} completion powershell >> $PROFILE`;
-		default: return `# Run: ${programName} completion <shell>
-# Supported shells: bash, zsh, fish, powershell`;
+var ActionError = class extends PadroneError {
+	constructor(message, options) {
+		super(message, {
+			phase: "execute",
+			...options
+		});
+		this.name = "ActionError";
 	}
-}
-/**
-* Generates the completion output with automatic shell detection.
-* If shell is not specified, detects the current shell and provides instructions.
-*/
-function generateCompletionOutput(program, shell) {
-	const programName = program.name;
-	if (shell) return generateCompletion(program, shell);
-	const detectedShell = detectShell();
-	if (detectedShell) return `# Detected shell: ${detectedShell}
-#
-${getCompletionInstallInstructions(programName, detectedShell)}
-#
-# Or evaluate directly (temporary, for current session only):
-# eval "$(${programName} completion ${detectedShell})"
-
-${generateCompletion(program, detectedShell)}`;
-	return `# Shell auto-detection failed.
-#
-# Usage: ${programName} completion <shell>
-#
-# Supported shells:
-#   bash       - Bash completion script
-#   zsh        - Zsh completion script
-#   fish       - Fish completion script
-#   powershell - PowerShell completion script
-#
-# Example:
-#   ${programName} completion bash >> ~/.bashrc
-#   ${programName} completion zsh >> ~/.zshrc
-#   ${programName} completion fish > ~/.config/fish/completions/${programName}.fish
-#   ${programName} completion powershell >> $PROFILE`;
-}
-
-//#endregion
-//#region src/colorizer.ts
-const colors = {
-	reset: "\x1B[0m",
-	bold: "\x1B[1m",
-	dim: "\x1B[2m",
-	italic: "\x1B[3m",
-	underline: "\x1B[4m",
-	strikethrough: "\x1B[9m",
-	cyan: "\x1B[36m",
-	green: "\x1B[32m",
-	yellow: "\x1B[33m",
-	blue: "\x1B[34m",
-	magenta: "\x1B[35m",
-	gray: "\x1B[90m"
 };
-function createColorizer() {
-	return {
-		command: (text) => `${colors.cyan}${colors.bold}${text}${colors.reset}`,
-		option: (text) => `${colors.green}${text}${colors.reset}`,
-		type: (text) => `${colors.yellow}${text}${colors.reset}`,
-		description: (text) => `${colors.dim}${text}${colors.reset}`,
-		label: (text) => `${colors.bold}${text}${colors.reset}`,
-		meta: (text) => `${colors.gray}${text}${colors.reset}`,
-		example: (text) => `${colors.underline}${text}${colors.reset}`,
-		exampleValue: (text) => `${colors.italic}${text}${colors.reset}`,
-		deprecated: (text) => `${colors.strikethrough}${colors.gray}${text}${colors.reset}`
-	};
-}
-
 //#endregion
-//#region src/formatter.ts
-function createTextStyler() {
-	return {
-		command: (text) => text,
-		option: (text) => text,
-		type: (text) => text,
-		description: (text) => text,
-		label: (text) => text,
-		meta: (text) => text,
-		example: (text) => text,
-		exampleValue: (text) => text,
-		deprecated: (text) => text
-	};
-}
-function createAnsiStyler() {
-	const colorizer = createColorizer();
-	return {
-		command: colorizer.command,
-		option: colorizer.option,
-		type: colorizer.type,
-		description: colorizer.description,
-		label: colorizer.label,
-		meta: colorizer.meta,
-		example: colorizer.example,
-		exampleValue: colorizer.exampleValue,
-		deprecated: colorizer.deprecated
-	};
-}
-function createConsoleStyler() {
-	const colors = {
-		reset: "\x1B[0m",
-		bold: "\x1B[1m",
-		dim: "\x1B[2m",
-		italic: "\x1B[3m",
-		underline: "\x1B[4m",
-		strikethrough: "\x1B[9m",
-		cyan: "\x1B[36m",
-		green: "\x1B[32m",
-		yellow: "\x1B[33m",
-		gray: "\x1B[90m"
-	};
-	return {
-		command: (text) => `${colors.cyan}${colors.bold}${text}${colors.reset}`,
-		option: (text) => `${colors.green}${text}${colors.reset}`,
-		type: (text) => `${colors.yellow}${text}${colors.reset}`,
-		description: (text) => `${colors.dim}${text}${colors.reset}`,
-		label: (text) => `${colors.bold}${text}${colors.reset}`,
-		meta: (text) => `${colors.gray}${text}${colors.reset}`,
-		example: (text) => `${colors.underline}${text}${colors.reset}`,
-		exampleValue: (text) => `${colors.italic}${text}${colors.reset}`,
-		deprecated: (text) => `${colors.strikethrough}${colors.gray}${text}${colors.reset}`
+//#region src/interactive.ts
+/**
+* Auto-detect the prompt type for a field based on its JSON schema property definition.
+*/
+function detectPromptConfig(name, propSchema, description) {
+	const message = description || propSchema?.description || name;
+	if (!propSchema) return {
+		name,
+		message,
+		type: "input"
 	};
-}
-function createMarkdownStyler() {
-	return {
-		command: (text) => `**${text}**`,
-		option: (text) => `\`${text}\``,
-		type: (text) => `\`${text}\``,
-		description: (text) => text,
-		label: (text) => `### ${text}`,
-		meta: (text) => `*${text}*`,
-		example: (text) => `**${text}**`,
-		exampleValue: (text) => `\`${text}\``,
-		deprecated: (text) => `~~${text}~~`
+	if (propSchema.type === "boolean") return {
+		name,
+		message,
+		type: "confirm",
+		default: propSchema.default
 	};
-}
-function escapeHtml(text) {
-	return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#039;");
-}
-function createHtmlStyler() {
-	return {
-		command: (text) => `<strong style="color: #00bcd4;">${escapeHtml(text)}</strong>`,
-		option: (text) => `<code style="color: #4caf50;">${escapeHtml(text)}</code>`,
-		type: (text) => `<code style="color: #ff9800;">${escapeHtml(text)}</code>`,
-		description: (text) => `<span style="color: #666;">${escapeHtml(text)}</span>`,
-		label: (text) => `<h3>${escapeHtml(text)}</h3>`,
-		meta: (text) => `<span style="color: #999;">${escapeHtml(text)}</span>`,
-		example: (text) => `<strong style="text-decoration: underline;">${escapeHtml(text)}</strong>`,
-		exampleValue: (text) => `<em>${escapeHtml(text)}</em>`,
-		deprecated: (text) => `<del style="color: #999;">${escapeHtml(text)}</del>`
+	if (propSchema.enum) return {
+		name,
+		message,
+		type: "select",
+		choices: propSchema.enum.map((v) => ({
+			label: String(v),
+			value: v
+		})),
+		default: propSchema.default
 	};
-}
-function createTextLayout() {
-	return {
-		newline: "\n",
-		indent: (level) => "  ".repeat(level),
-		join: (parts) => parts.filter(Boolean).join(" "),
-		usageLabel: "Usage:"
+	if (propSchema.type === "array" && propSchema.items?.enum) return {
+		name,
+		message,
+		type: "multiselect",
+		choices: propSchema.items.enum.map((v) => ({
+			label: String(v),
+			value: v
+		})),
+		default: propSchema.default
 	};
-}
-function createMarkdownLayout() {
-	return {
-		newline: "\n\n",
-		indent: (level) => {
-			if (level === 0) return "";
-			if (level === 1) return "  ";
-			return "    ";
-		},
-		join: (parts) => parts.filter(Boolean).join(" "),
-		usageLabel: "Usage:"
+	if (propSchema.format === "password") return {
+		name,
+		message,
+		type: "password",
+		default: propSchema.default
 	};
-}
-function createHtmlLayout() {
 	return {
-		newline: "<br>",
-		indent: (level) => "&nbsp;&nbsp;".repeat(level),
-		join: (parts) => parts.filter(Boolean).join(" "),
-		wrapDocument: (content) => `<div style="font-family: monospace; line-height: 1.6;">${content}</div>`,
-		usageLabel: "<strong>Usage:</strong>"
+		name,
+		message,
+		type: "input",
+		default: propSchema.default
 	};
 }
 /**
-* Creates a formatter that uses the given styler and layout configuration.
+* Prompt for missing interactive fields.
+* Runs after env/config preprocessing and before schema validation.
+*
+* When `force` is true, all configured interactive fields are prompted even if they already
+* have values. The current values are used as defaults in the prompts.
 */
-function createGenericFormatter(styler, layout) {
-	const { newline, indent, join, wrapDocument, usageLabel } = layout;
-	function formatUsageSection(info) {
-		return [`${usageLabel} ${join([
-			styler.command(info.usage.command),
-			info.usage.hasSubcommands ? styler.meta("[command]") : "",
-			info.usage.hasArguments ? styler.meta("[args...]") : "",
-			info.usage.hasOptions ? styler.meta("[options]") : ""
-		])}`];
-	}
-	function formatSubcommandsSection(info) {
-		const lines = [];
-		const subcommands = info.subcommands;
-		lines.push(styler.label("Commands:"));
-		const maxNameLength = Math.max(...subcommands.map((c) => {
-			const aliases = c.aliases ? ` (${c.aliases.join(", ")})` : "";
-			return (c.name + aliases).length;
-		}));
-		for (const subCmd of subcommands) {
-			const aliases = subCmd.aliases ? ` (${subCmd.aliases.join(", ")})` : "";
-			const commandDisplay = subCmd.name + aliases;
-			const padding = " ".repeat(Math.max(0, maxNameLength - commandDisplay.length + 2));
-			const isDeprecated = !!subCmd.deprecated;
-			const lineParts = [isDeprecated ? styler.deprecated(commandDisplay) : styler.command(subCmd.name) + aliases, padding];
-			const displayText = subCmd.title ?? subCmd.description;
-			if (displayText) lineParts.push(isDeprecated ? styler.deprecated(displayText) : styler.description(displayText));
-			if (isDeprecated) {
-				const deprecatedMeta = typeof subCmd.deprecated === "string" ? styler.meta(` (deprecated: ${subCmd.deprecated})`) : styler.meta(" (deprecated)");
-				lineParts.push(deprecatedMeta);
-			}
-			lines.push(indent(1) + lineParts.join(""));
-		}
-		lines.push("");
-		lines.push(styler.meta(`Run "${info.name} [command] --help" for more information on a command.`));
-		return lines;
-	}
-	function formatArgumentsSection(info) {
-		const lines = [];
-		const args = info.arguments;
-		lines.push(styler.label("Arguments:"));
-		for (const arg of args) {
-			const parts = [styler.option(arg.name)];
-			if (arg.optional) parts.push(styler.meta("(optional)"));
-			if (arg.default !== void 0) parts.push(styler.meta(`(default: ${String(arg.default)})`));
-			lines.push(indent(1) + join(parts));
-			if (arg.description) lines.push(indent(2) + styler.description(arg.description));
-		}
-		return lines;
-	}
-	function formatOptionsSection(info) {
-		const lines = [];
-		const options = info.options;
-		lines.push(styler.label("Options:"));
-		const maxNameLength = Math.max(...options.map((opt) => opt.name.length));
-		for (const opt of options) {
-			const optionName = opt.negatable ? `--[no-]${opt.name}` : `--${opt.name}`;
-			const aliasNames = opt.aliases && opt.aliases.length > 0 ? opt.aliases.map((a) => `-${a}`).join(", ") : "";
-			const fullOptionName = aliasNames ? `${optionName}, ${aliasNames}` : optionName;
-			const padding = " ".repeat(Math.max(0, maxNameLength - opt.name.length + 2));
-			const isDeprecated = !!opt.deprecated;
-			const parts = [isDeprecated ? styler.deprecated(fullOptionName) : styler.option(fullOptionName)];
-			if (opt.type) parts.push(styler.type(`<${opt.type}>`));
-			if (opt.optional && !opt.deprecated) parts.push(styler.meta("(optional)"));
-			if (opt.default !== void 0) parts.push(styler.meta(`(default: ${String(opt.default)})`));
-			if (opt.enum) parts.push(styler.meta(`(choices: ${opt.enum.join(", ")})`));
-			if (opt.variadic) parts.push(styler.meta("(repeatable)"));
-			if (isDeprecated) {
-				const deprecatedMeta = typeof opt.deprecated === "string" ? styler.meta(`(deprecated: ${opt.deprecated})`) : styler.meta("(deprecated)");
-				parts.push(deprecatedMeta);
-			}
-			const description = opt.description ? styler.description(opt.description) : "";
-			lines.push(indent(1) + join(parts) + padding + description);
-			if (opt.env) {
-				const envVars = typeof opt.env === "string" ? [opt.env] : opt.env;
-				const envParts = [styler.example("Env:"), styler.exampleValue(envVars.join(", "))];
-				lines.push(indent(3) + join(envParts));
-			}
-			if (opt.configKey) {
-				const configParts = [styler.example("Config:"), styler.exampleValue(opt.configKey)];
-				lines.push(indent(3) + join(configParts));
-			}
-			if (opt.examples && opt.examples.length > 0) {
-				const exampleValues = opt.examples.map((example) => typeof example === "string" ? example : JSON.stringify(example)).join(", ");
-				const exampleParts = [styler.example("Example:"), styler.exampleValue(exampleValues)];
-				lines.push(indent(3) + join(exampleParts));
-			}
-		}
-		return lines;
-	}
-	return { format(info) {
-		const lines = [];
-		if (info.deprecated) {
-			const deprecationMessage = typeof info.deprecated === "string" ? `⚠️  This command is deprecated: ${info.deprecated}` : "⚠️  This command is deprecated";
-			lines.push(styler.deprecated(deprecationMessage));
-			lines.push("");
-		}
-		lines.push(...formatUsageSection(info));
-		lines.push("");
-		if (info.title) {
-			lines.push(styler.label(info.title));
-			lines.push("");
-		}
-		if (info.aliases && info.aliases.length > 0) {
-			lines.push(styler.meta(`Aliases: ${info.aliases.join(", ")}`));
-			lines.push("");
-		}
-		if (info.description) {
-			lines.push(styler.description(info.description));
-			lines.push("");
-		}
-		if (info.subcommands && info.subcommands.length > 0) {
-			lines.push(...formatSubcommandsSection(info));
-			lines.push("");
-		}
-		if (info.arguments && info.arguments.length > 0) {
-			lines.push(...formatArgumentsSection(info));
-			lines.push("");
-		}
-		if (info.options && info.options.length > 0) {
-			lines.push(...formatOptionsSection(info));
-			lines.push("");
-		}
-		if (info.nestedCommands?.length) {
-			lines.push(styler.label("Subcommand Details:"));
-			lines.push("");
-			for (const nestedCmd of info.nestedCommands) {
-				lines.push(styler.meta("─".repeat(60)));
-				lines.push(this.format(nestedCmd));
-			}
-		}
-		const result = lines.join(newline);
-		return wrapDocument ? wrapDocument(result) : result;
-	} };
-}
-function createJsonFormatter() {
-	return { format(info) {
-		return JSON.stringify(info, null, 2);
-	} };
-}
-function shouldUseAnsi() {
-	if (typeof process === "undefined") return false;
-	if (process.env.NO_COLOR) return false;
-	if (process.env.CI) return false;
-	if (process.stdout && typeof process.stdout.isTTY === "boolean") return process.stdout.isTTY;
-	return false;
-}
-/**
-* Creates a minimal formatter that outputs just a single-line usage string.
-*/
-function createMinimalFormatter() {
-	return { format(info) {
-		const parts = [info.usage.command];
-		if (info.usage.hasSubcommands) parts.push("[command]");
-		if (info.usage.hasArguments) parts.push("[args...]");
-		if (info.usage.hasOptions) parts.push("[options]");
-		return parts.join(" ");
-	} };
-}
-function createFormatter(format, detail = "standard") {
-	if (detail === "minimal") return createMinimalFormatter();
-	if (format === "json") return createJsonFormatter();
-	if (format === "ansi" || format === "auto" && shouldUseAnsi()) return createGenericFormatter(createAnsiStyler(), createTextLayout());
-	if (format === "console") return createGenericFormatter(createConsoleStyler(), createTextLayout());
-	if (format === "markdown") return createGenericFormatter(createMarkdownStyler(), createMarkdownLayout());
-	if (format === "html") return createGenericFormatter(createHtmlStyler(), createHtmlLayout());
-	return createGenericFormatter(createTextStyler(), createTextLayout());
-}
-
-//#endregion
-//#region src/utils.ts
-function getRootCommand(cmd) {
-	let current = cmd;
-	while (current.parent) current = current.parent;
-	return current;
-}
-/**
-* Attempts to get the version from various sources:
-* 1. Explicit version set on the command
-* 2. npm_package_version environment variable (set by npm/yarn/pnpm when running scripts)
-* 3. package.json in current or parent directories
-* @param explicitVersion - Version explicitly set via .version()
-* @returns The version string or '0.0.0' if not found
-*/
-function getVersion(explicitVersion) {
-	if (explicitVersion) return explicitVersion;
-	if (typeof process !== "undefined" && process.env?.npm_package_version) return process.env.npm_package_version;
-	if (typeof process !== "undefined") try {
-		const fs = __require("node:fs");
-		const path = __require("node:path");
-		let dir = process.cwd();
-		for (let i = 0; i < 10; i++) {
-			const pkgPath = path.join(dir, "package.json");
-			if (fs.existsSync(pkgPath)) {
-				const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-				if (pkg.version) return pkg.version;
-			}
-			const parentDir = path.dirname(dir);
-			if (parentDir === dir) break;
-			dir = parentDir;
-		}
+async function promptInteractiveFields(data, command, runtime, force) {
+	if (!runtime.prompt) return data;
+	const meta = command.meta;
+	const interactiveConfig = meta?.interactive;
+	const optionalInteractiveConfig = meta?.optionalInteractive;
+	if (!interactiveConfig && !optionalInteractiveConfig) return data;
+	let jsonProperties = {};
+	let requiredFields = /* @__PURE__ */ new Set();
+	if (command.argsSchema) try {
+		const jsonSchema = command.argsSchema["~standard"].jsonSchema.input({ target: "draft-2020-12" });
+		if (jsonSchema.type === "object" && jsonSchema.properties) jsonProperties = jsonSchema.properties;
+		if (Array.isArray(jsonSchema.required)) requiredFields = new Set(jsonSchema.required);
 	} catch {}
-	return "0.0.0";
-}
-/**
-* Loads and parses a config file from the given path.
-* Supports JSON, JSONC (JSON with comments), and attempts to parse other formats.
-* @param configPath - Path to the config file
-* @returns Parsed config data or undefined if loading fails
-*/
-function loadConfigFile(configPath) {
-	if (typeof process === "undefined") return void 0;
-	try {
-		const fs = __require("node:fs");
-		const path = __require("node:path");
-		const absolutePath = path.isAbsolute(configPath) ? configPath : path.resolve(process.cwd(), configPath);
-		if (!fs.existsSync(absolutePath)) {
-			console.error(`Config file not found: ${absolutePath}`);
-			return;
-		}
-		const getContent = () => fs.readFileSync(absolutePath, "utf-8");
-		const ext = path.extname(absolutePath).toLowerCase();
-		if (ext === ".yaml" || ext === ".yml") return Bun.YAML.parse(getContent());
-		if (ext === ".toml") return Bun.TOML.parse(getContent());
-		if (ext === ".json") {
-			if (Bun.JSONC) return Bun.JSONC.parse(getContent());
-			try {
-				return JSON.parse(getContent());
-			} catch {
-				return Bun.JSONC.parse(getContent());
-			}
-		}
-		if (ext === ".jsonc") return Bun.JSONC.parse(getContent());
-		if (ext === ".js" || ext === ".cjs" || ext === ".mjs" || ext === ".ts" || ext === ".cts" || ext === ".mts") return __require(absolutePath);
-		try {
-			return JSON.parse(getContent());
-		} catch {
-			console.error(`Unable to parse config file: ${absolutePath}`);
-			return;
-		}
-	} catch (error) {
-		console.error(`Error loading config file: ${error}`);
-		return;
+	const fieldDescriptions = {};
+	if (meta?.fields) {
+		for (const [key, value] of Object.entries(meta.fields)) if (value?.description) fieldDescriptions[key] = value.description;
 	}
-}
-/**
-* Searches for a config file from a list of possible file names.
-* Searches in the current working directory.
-* @param configFiles - Array of possible config file names to search for
-* @returns The path to the first found config file, or undefined if none found
-*/
-function findConfigFile(configFiles) {
-	if (typeof process === "undefined" || !configFiles?.length) return void 0;
-	try {
-		const fs = __require("node:fs");
-		const path = __require("node:path");
-		const cwd = process.cwd();
-		for (const configFile of configFiles) {
-			const configPath = path.isAbsolute(configFile) ? configFile : path.resolve(cwd, configFile);
-			if (fs.existsSync(configPath)) return configPath;
-		}
-	} catch {}
-}
-
-//#endregion
-//#region src/help.ts
-/**
-* Extract positional arguments info from schema based on meta.positional config.
-*/
-function extractPositionalArgsInfo(schema, meta) {
-	const args = [];
-	const positionalNames = /* @__PURE__ */ new Set();
-	if (!schema || !meta?.positional || meta.positional.length === 0) return {
-		args,
-		positionalNames
-	};
-	const positionalConfig = parsePositionalConfig(meta.positional);
-	try {
-		const jsonSchema = schema["~standard"].jsonSchema.input({ target: "draft-2020-12" });
-		if (jsonSchema.type === "object" && jsonSchema.properties) {
-			const properties = jsonSchema.properties;
-			const required = jsonSchema.required || [];
-			for (const { name, variadic } of positionalConfig) {
-				const prop = properties[name];
-				if (!prop) continue;
-				positionalNames.add(name);
-				const optMeta = meta.options?.[name];
-				args.push({
-					name: variadic ? `...${name}` : name,
-					description: optMeta?.description ?? prop.description,
-					optional: !required.includes(name),
-					default: prop.default,
-					type: variadic ? `array<${prop.items?.type || "string"}>` : prop.type
-				});
-			}
-		}
-	} catch {}
-	return {
-		args,
-		positionalNames
-	};
-}
-function extractOptionsInfo(schema, meta, positionalNames) {
-	const result = [];
-	if (!schema) return result;
-	if (!schema["~standard"].vendor.includes("zod")) return result;
-	const optionsMeta = meta?.options;
-	try {
-		const jsonSchema = schema["~standard"].jsonSchema.input({ target: "draft-2020-12" });
-		if (jsonSchema.type === "object" && jsonSchema.properties) {
-			const properties = jsonSchema.properties;
-			const required = jsonSchema.required || [];
-			const propertyNames = new Set(Object.keys(properties));
-			const hasExplicitNegation = (key) => {
-				const camelNegated = `no${key.charAt(0).toUpperCase()}${key.slice(1)}`;
-				if (propertyNames.has(camelNegated)) return true;
-				const kebabNegated = `no-${key}`;
-				if (propertyNames.has(kebabNegated)) return true;
-				return false;
-			};
-			const isNegationOf = (key) => {
-				if (key.startsWith("no") && key.length > 2 && key[2] === key[2]?.toUpperCase()) {
-					const positiveKey = key.charAt(2).toLowerCase() + key.slice(3);
-					if (propertyNames.has(positiveKey)) return true;
-				}
-				if (key.startsWith("no-")) {
-					const positiveKey = key.slice(3);
-					if (propertyNames.has(positiveKey)) return true;
-				}
-				return false;
-			};
-			for (const [key, prop] of Object.entries(properties)) {
-				if (positionalNames?.has(key)) continue;
-				const isOptional = !required.includes(key);
-				const enumValues = prop.enum;
-				const optMeta = optionsMeta?.[key];
-				const propType = prop.type;
-				const isNegatable = propType === "boolean" && !hasExplicitNegation(key) && !isNegationOf(key);
-				result.push({
-					name: key,
-					description: optMeta?.description ?? prop.description,
-					optional: isOptional,
-					default: prop.default,
-					type: propType,
-					enum: enumValues,
-					deprecated: optMeta?.deprecated ?? prop?.deprecated,
-					hidden: optMeta?.hidden ?? prop?.hidden,
-					examples: optMeta?.examples ?? prop?.examples,
-					variadic: propType === "array",
-					negatable: isNegatable
-				});
-			}
-		}
-	} catch {}
-	return result;
-}
-/**
-* Builds a comprehensive HelpInfo structure from a command.
-* This is the single source of truth that all formatters use.
-* @param cmd - The command to build help info for
-* @param detail - The level of detail ('minimal', 'standard', or 'full')
-*/
-function getHelpInfo(cmd, detail = "standard") {
-	const rootCmd = getRootCommand(cmd);
-	const commandName = cmd.path || cmd.name || "program";
-	const { args: positionalArgs, positionalNames } = cmd.options ? extractPositionalArgsInfo(cmd.options, cmd.meta) : {
-		args: [],
-		positionalNames: /* @__PURE__ */ new Set()
-	};
-	const hasArguments = positionalArgs.length > 0;
-	const helpInfo = {
-		name: commandName,
-		title: cmd.title,
-		description: cmd.description,
-		aliases: cmd.aliases,
-		deprecated: cmd.deprecated,
-		hidden: cmd.hidden,
-		usage: {
-			command: rootCmd === cmd ? commandName : `${rootCmd.name} ${commandName}`,
-			hasSubcommands: !!(cmd.commands && cmd.commands.length > 0),
-			hasArguments,
-			hasOptions: !!cmd.options
-		}
-	};
-	if (cmd.commands && cmd.commands.length > 0) {
-		const visibleCommands = detail === "full" ? cmd.commands : cmd.commands.filter((c) => !c.hidden);
-		helpInfo.subcommands = visibleCommands.map((c) => {
-			return {
-				name: c.name,
-				title: c.title,
-				description: c.description,
-				aliases: c.aliases,
-				deprecated: c.deprecated,
-				hidden: c.hidden
-			};
-		});
-		if (detail === "full") helpInfo.nestedCommands = visibleCommands.map((c) => getHelpInfo(c, "full"));
+	const result = { ...data };
+	let fieldsToPrompt = [];
+	if (interactiveConfig === true) if (force) fieldsToPrompt = [...requiredFields];
+	else fieldsToPrompt = [...requiredFields].filter((name) => result[name] === void 0);
+	else if (Array.isArray(interactiveConfig)) if (force) fieldsToPrompt = [...interactiveConfig];
+	else fieldsToPrompt = interactiveConfig.filter((name) => result[name] === void 0);
+	for (const field of fieldsToPrompt) {
+		const config = detectPromptConfig(field, jsonProperties[field], fieldDescriptions[field]);
+		if (force && result[field] !== void 0) config.default = result[field];
+		result[field] = await runtime.prompt(config);
 	}
-	if (hasArguments) helpInfo.arguments = positionalArgs;
-	if (cmd.options) {
-		const optionsInfo = extractOptionsInfo(cmd.options, cmd.meta, positionalNames);
-		const optMap = Object.fromEntries(optionsInfo.map((opt) => [opt.name, opt]));
-		const { aliases } = extractSchemaMetadata(cmd.options, cmd.meta?.options);
-		for (const [alias, name] of Object.entries(aliases)) {
-			const opt = optMap[name];
-			if (!opt) continue;
-			opt.aliases = [...opt.aliases || [], alias];
+	let optionalFields = [];
+	if (optionalInteractiveConfig === true) if (force) optionalFields = Object.keys(jsonProperties).filter((name) => !requiredFields.has(name));
+	else optionalFields = Object.keys(jsonProperties).filter((name) => !requiredFields.has(name) && result[name] === void 0);
+	else if (Array.isArray(optionalInteractiveConfig)) if (force) optionalFields = [...optionalInteractiveConfig];
+	else optionalFields = optionalInteractiveConfig.filter((name) => result[name] === void 0);
+	if (optionalFields.length > 0) {
+		const selected = await runtime.prompt({
+			name: "_optionalFields",
+			message: "Would you also like to configure:",
+			type: "multiselect",
+			choices: optionalFields.map((f) => {
+				const label = fieldDescriptions[f] || jsonProperties[f]?.description || f;
+				const currentValue = result[f];
+				return {
+					label: force && currentValue !== void 0 ? `${label} (current: ${currentValue})` : label,
+					value: f
+				};
+			})
+		});
+		if (Array.isArray(selected)) for (const field of selected) {
+			const config = detectPromptConfig(field, jsonProperties[field], fieldDescriptions[field]);
+			if (force && result[field] !== void 0) config.default = result[field];
+			result[field] = await runtime.prompt(config);
 		}
-		const visibleOptions = optionsInfo.filter((opt) => !opt.hidden);
-		if (visibleOptions.length > 0) helpInfo.options = visibleOptions;
 	}
-	return helpInfo;
-}
-function generateHelp(rootCommand, commandObj = rootCommand, options) {
-	const helpInfo = getHelpInfo(commandObj, options?.detail);
-	return createFormatter(options?.format ?? "auto", options?.detail).format(helpInfo);
+	return result;
 }
-
 //#endregion
 //#region src/parse.ts
 /**
@@ -1027,36 +272,76 @@ function parseCliInputToParts(input) {
 	const result = [];
 	let pendingValue;
 	let allowTerm = true;
+	let afterDoubleDash = false;
 	for (const part of parts) {
 		if (!part) continue;
+		if (part === "--" && !afterDoubleDash) {
+			if (pendingValue) pendingValue = void 0;
+			afterDoubleDash = true;
+			allowTerm = false;
+			continue;
+		}
+		if (afterDoubleDash) {
+			result.push({
+				type: "arg",
+				value: part
+			});
+			continue;
+		}
 		const wasPending = pendingValue;
 		pendingValue = void 0;
 		if (part.startsWith("--no-") && part.length > 5) {
 			const p = {
-				type: "option",
+				type: "named",
 				key: part.slice(5).split("."),
 				value: void 0,
 				negated: true
 			};
 			result.push(p);
 		} else if (part.startsWith("--")) {
-			const [keyStr = "", value] = splitOptionValue(part.slice(2));
+			const [keyStr = "", value] = splitNamedArgValue(part.slice(2));
 			const p = {
-				type: "option",
+				type: "named",
 				key: keyStr.split("."),
 				value
 			};
 			if (typeof value === "undefined") pendingValue = p;
 			result.push(p);
 		} else if (part.startsWith("-") && part.length > 1 && !/^-\d/.test(part)) {
-			const [keyStr = "", value] = splitOptionValue(part.slice(1));
-			const p = {
-				type: "alias",
-				key: [keyStr],
-				value
-			};
-			if (typeof value === "undefined") pendingValue = p;
-			result.push(p);
+			const [keyStr = "", value] = splitNamedArgValue(part.slice(1));
+			if (keyStr.length > 1 && typeof value === "undefined") {
+				for (let ci = 0; ci < keyStr.length - 1; ci++) result.push({
+					type: "alias",
+					key: [keyStr[ci]],
+					value: void 0
+				});
+				const lastFlag = {
+					type: "alias",
+					key: [keyStr[keyStr.length - 1]],
+					value: void 0
+				};
+				pendingValue = lastFlag;
+				result.push(lastFlag);
+			} else if (keyStr.length > 1 && typeof value !== "undefined") {
+				for (let ci = 0; ci < keyStr.length - 1; ci++) result.push({
+					type: "alias",
+					key: [keyStr[ci]],
+					value: void 0
+				});
+				result.push({
+					type: "alias",
+					key: [keyStr[keyStr.length - 1]],
+					value
+				});
+			} else {
+				const p = {
+					type: "alias",
+					key: [keyStr],
+					value
+				};
+				if (typeof value === "undefined") pendingValue = p;
+				result.push(p);
+			}
 		} else if (wasPending) wasPending.value = part;
 		else if (/^[a-zA-Z0-9_-]+$/.test(part) && allowTerm) result.push({
 			type: "term",
@@ -1073,9 +358,9 @@ function parseCliInputToParts(input) {
 	return result;
 }
 /**
-* Split option key and value, handling quoted values after =.
+* Split named arg key and value, handling quoted values after =.
 */
-function splitOptionValue(str) {
+function splitNamedArgValue(str) {
 	const eqIndex = str.indexOf("=");
 	if (eqIndex === -1) return [str, void 0];
 	const key = str.slice(0, eqIndex);
@@ -1146,20 +431,215 @@ function parseArrayItems(input) {
 	if (current || items.length > 0) items.push(current.trim());
 	return items;
 }
-
+//#endregion
+//#region src/repl-loop.ts
+/**
+* Creates a REPL async iterable for running commands interactively.
+*/
+function createReplIterator(deps, options) {
+	const { existingCommand, evalCommand, replActiveRef } = deps;
+	if (replActiveRef.value) {
+		getCommandRuntime(existingCommand).error("REPL is already running. Nested REPL sessions are not supported.");
+		return (async function* () {})();
+	}
+	const runtime = getCommandRuntime(existingCommand);
+	const programName = existingCommand.name || "padrone";
+	const useAnsi = runtime.format === "ansi" || runtime.format === "auto" && typeof process !== "undefined" && !process.env.NO_COLOR && !process.env.CI && process.stdout?.isTTY;
+	const commandHistory = [];
+	const resolveScope = (scope) => {
+		const parts = scope.split(/\s+/);
+		const stack = [];
+		let current = existingCommand;
+		for (const part of parts) {
+			const found = findCommandByName(part, current.commands);
+			if (!found) break;
+			stack.push(found);
+			current = found;
+		}
+		return stack;
+	};
+	async function* replIterator() {
+		replActiveRef.value = true;
+		const showGreeting = options?.greeting !== false;
+		const showHint = options?.hint !== false;
+		if (showGreeting || showHint) runtime.output("");
+		if (showGreeting) if (options?.greeting) runtime.output(options.greeting);
+		else {
+			const displayName = existingCommand.title || programName;
+			const version = existingCommand.version ? getVersion(existingCommand.version) : void 0;
+			const greeting = version ? `Welcome to ${displayName} v${version}` : `Welcome to ${displayName}`;
+			runtime.output(greeting);
+		}
+		if (showHint) {
+			const hintText = (typeof options?.hint === "string" ? options.hint : void 0) ?? "Type \".help\" for more information, \".exit\" to quit.";
+			runtime.output(useAnsi ? `\x1b[2m${hintText}\x1b[0m` : hintText);
+		}
+		if (showGreeting || showHint) runtime.output("");
+		const scopeStack = options?.scope ? resolveScope(options.scope) : [];
+		const getScopeCommand = () => scopeStack.length ? scopeStack[scopeStack.length - 1] : existingCommand;
+		const getScopePath = () => scopeStack.map((c) => c.name).join(" ");
+		const buildPrompt = () => {
+			if (options?.prompt) return typeof options.prompt === "function" ? options.prompt() : options.prompt;
+			const scopePath = getScopePath();
+			const label = scopePath ? `${programName}/${scopePath.replace(/ /g, "/")}` : programName;
+			return useAnsi ? `\x1b[1m${label}\x1b[0m ❯ ` : `${label} ❯ `;
+		};
+		const buildScopedCompleter = () => {
+			return buildReplCompleter(getScopeCommand(), { inScope: scopeStack.length > 0 });
+		};
+		const sessionConfig = { history: options?.history };
+		if (options?.completion !== false) sessionConfig.completer = buildScopedCompleter();
+		const session = runtime.readLine ? void 0 : createTerminalReplSession(sessionConfig);
+		const questionFn = session ? (prompt) => session.question(prompt) : runtime.readLine;
+		const updateCompleter = () => {
+			if (options?.completion === false) return;
+			const completer = buildScopedCompleter();
+			if (session) session.completer = completer;
+			sessionConfig.completer = completer;
+		};
+		let lastSigintTime = 0;
+		try {
+			while (true) {
+				const input = await questionFn(buildPrompt());
+				if (input === null) break;
+				if (input === REPL_SIGINT) {
+					const now = Date.now();
+					if (now - lastSigintTime < 2e3) break;
+					lastSigintTime = now;
+					runtime.output("(press Ctrl+C again to exit, or Ctrl+D)");
+					continue;
+				}
+				const trimmed = input.trim();
+				if (!trimmed) continue;
+				lastSigintTime = 0;
+				commandHistory.push(trimmed);
+				if (trimmed === ".exit" || trimmed === ".quit") break;
+				if (trimmed === ".clear") {
+					runtime.output("\x1B[2J\x1B[H");
+					continue;
+				}
+				if (trimmed === ".help") {
+					const lines = [
+						"REPL Commands:",
+						"  .                 Execute the current scoped command",
+						"  .help             Print this help message",
+						"  .exit             Exit the REPL",
+						"  .clear            Clear the screen",
+						"  .history          Show command history",
+						"  .scope <cmd>      Scope into a subcommand",
+						"  .scope ..         Go up one scope level"
+					];
+					lines.push("", "Keybindings:", "  Ctrl+C       Cancel current line (press twice to exit)", "  Ctrl+D       Exit the REPL", "  Up/Down      Navigate history", "  Tab          Auto-complete", "", "Type \"help\" to see available commands.");
+					runtime.output(lines.join("\n"));
+					continue;
+				}
+				if (trimmed === ".history") {
+					const entries = commandHistory.slice(0, -1);
+					if (entries.length === 0) runtime.output("No history.");
+					else runtime.output(entries.map((entry, i) => `${i + 1}  ${entry}`).join("\n"));
+					continue;
+				}
+				if (trimmed.startsWith(".scope ") || trimmed === ".scope") {
+					const target = trimmed.slice(6).trim();
+					if (target === ".." || target === "") {
+						if (scopeStack.length > 0) {
+							scopeStack.pop();
+							updateCompleter();
+						}
+					} else {
+						const found = findCommandByName(target, getScopeCommand().commands);
+						if (found) if (found.commands?.length) {
+							scopeStack.push(found);
+							updateCompleter();
+						} else runtime.error(`"${target}" has no subcommands to scope into.`);
+						else runtime.error(`Unknown command: ${target}`);
+					}
+					continue;
+				}
+				if (trimmed === "..") {
+					if (scopeStack.length > 0) {
+						scopeStack.pop();
+						updateCompleter();
+					}
+					continue;
+				}
+				let evalInput = trimmed;
+				if (trimmed === ".") evalInput = "";
+				const prefix = options?.outputPrefix;
+				const prefixLines = prefix ? (text) => text.split("\n").map((l) => prefix + l).join("\n") : void 0;
+				const savedRuntimes = [];
+				if (prefixLines) {
+					const prefixedRuntime = {
+						...existingCommand.runtime,
+						output: (...args) => {
+							const first = args[0];
+							runtime.output(typeof first === "string" ? prefixLines(first) : first, ...args.slice(1));
+						},
+						error: (text) => runtime.error(prefixLines(text))
+					};
+					const patchAll = (cmd) => {
+						savedRuntimes.push({
+							cmd,
+							runtime: cmd.runtime
+						});
+						cmd.runtime = prefixedRuntime;
+						cmd.commands?.forEach(patchAll);
+					};
+					patchAll(existingCommand);
+				}
+				const sp = options?.spacing;
+				const isSpacingObject = typeof sp === "object" && sp !== null && !Array.isArray(sp);
+				const spacingBefore = isSpacingObject ? sp.before : sp;
+				const spacingAfter = isSpacingObject ? sp.after : sp;
+				const emitSpacingLine = (value) => {
+					if (typeof value === "string") {
+						const sep = value.length === 1 ? value.repeat(typeof process !== "undefined" && process.stdout?.columns ? process.stdout.columns : 80) : value;
+						runtime.output(sep);
+					} else if (value) runtime.output("");
+				};
+				const emitSpacing = (value) => {
+					if (!value) return;
+					if (Array.isArray(value)) for (const line of value) emitSpacingLine(line);
+					else emitSpacingLine(value);
+				};
+				emitSpacing(spacingBefore);
+				const scopePath = getScopePath();
+				const scopedInput = scopePath ? evalInput ? `${scopePath} ${evalInput}` : scopePath : evalInput;
+				try {
+					const result = await evalCommand(scopedInput, options?.autoOutput === false ? { autoOutput: false } : void 0);
+					if (result.argsResult?.issues) {
+						const msg = `Validation error:\n${result.argsResult.issues.map((i) => `  - ${i.path?.join(".") || "root"}: ${i.message}`).join("\n")}`;
+						runtime.error(prefixLines ? prefixLines(msg) : msg);
+					}
+					yield result;
+				} catch (err) {
+					const msg = err instanceof Error ? err.message : String(err);
+					runtime.error(prefixLines ? prefixLines(msg) : msg);
+				} finally {
+					for (const { cmd, runtime: saved } of savedRuntimes) cmd.runtime = saved;
+					emitSpacing(spacingAfter);
+				}
+			}
+		} finally {
+			replActiveRef.value = false;
+			session?.close();
+		}
+	}
+	return replIterator();
+}
 //#endregion
 //#region src/wrap.ts
 /**
-* Converts parsed options to CLI arguments for an external command.
+* Converts parsed arguments to CLI arguments for an external command.
 */
-function optionsToArgs(options, positional = []) {
+function argsToCliArgs(input, positional = []) {
 	const args = [];
-	if (!options) return args;
+	if (!input) return args;
 	const positionalValues = {};
-	const regularOptions = {};
-	for (const [key, value] of Object.entries(options)) if (positional.includes(key) || positional.includes(`...${key}`)) positionalValues[key] = value;
-	else regularOptions[key] = value;
-	for (const [key, value] of Object.entries(regularOptions)) {
+	const regularArguments = {};
+	for (const [key, value] of Object.entries(input)) if (positional.includes(key) || positional.includes(`...${key}`)) positionalValues[key] = value;
+	else regularArguments[key] = value;
+	for (const [key, value] of Object.entries(regularArguments)) {
 		if (value === void 0 || value === null) continue;
 		const flag = `--${key}`;
 		if (typeof value === "boolean") {
@@ -1179,21 +659,19 @@ function optionsToArgs(options, positional = []) {
 /**
 * Creates an action handler that wraps an external CLI tool.
 * @param config - Configuration for wrapping the external command (includes optional schema)
-* @param commandOptions - The command's options schema
+* @param commandArguments - The command's arguments schema
 * @param commandPositional - Default positional config from the wrapping command
 */
-function createWrapHandler(config, commandOptions, commandPositional) {
-	return async (options) => {
+function createWrapHandler(config, commandArguments, commandPositional) {
+	return async (args) => {
 		const { command, args: fixedArgs = [], inheritStdio = true, positional = commandPositional, schema: wrapSchema } = config;
-		const result = (wrapSchema ? typeof wrapSchema === "function" ? wrapSchema(commandOptions) : wrapSchema : commandOptions)["~standard"].validate(options);
-		if (result instanceof Promise) throw new Error("Async validation is not supported. Wrap schema validate() must return a synchronous result.");
-		if (result.issues) {
-			const issueMessages = result.issues.map((i) => `  - ${i.path?.join(".") || "root"}: ${i.message}`).join("\n");
-			throw new Error(`Wrap schema validation failed:\n${issueMessages}`);
-		}
-		const externalOptions = result.value;
-		const optionArgs = optionsToArgs(externalOptions, positional);
-		const allArgs = [...fixedArgs, ...optionArgs];
+		const validationResult = (wrapSchema ? typeof wrapSchema === "function" ? wrapSchema(commandArguments) : wrapSchema : commandArguments)["~standard"].validate(args);
+		const processResult = (result) => {
+			if (result.issues) throw new ValidationError(`Wrap schema validation failed:\n${result.issues.map((i) => `  - ${i.path?.join(".") || "root"}: ${i.message}`).join("\n")}`, result.issues);
+			return result.value;
+		};
+		const regularArgs = argsToCliArgs(validationResult instanceof Promise ? await validationResult.then(processResult) : processResult(validationResult), positional);
+		const allArgs = [...fixedArgs, ...regularArgs];
 		const proc = Bun.spawn([command, ...allArgs], {
 			stdout: inheritStdio ? "inherit" : "pipe",
 			stderr: inheritStdio ? "inherit" : "pipe",
@@ -1220,11 +698,8 @@ function createWrapHandler(config, commandOptions, commandPositional) {
 		};
 	};
 }
-
 //#endregion
 //#region src/create.ts
-const commandSymbol = Symbol("padrone_command");
-const noop = () => void 0;
 function createPadrone(name) {
 	return createPadroneBuilder({
 		name,
@@ -1232,162 +707,268 @@ function createPadrone(name) {
 		commands: []
 	});
 }
-function createPadroneBuilder(existingCommand) {
-	function findCommandByName(name, commands) {
-		if (!commands) return void 0;
-		const foundByName = commands.find((cmd) => cmd.name === name);
-		if (foundByName) return foundByName;
-		const foundByAlias = commands.find((cmd) => cmd.aliases?.includes(name));
-		if (foundByAlias) return foundByAlias;
-		for (const cmd of commands) {
-			if (cmd.commands && name.startsWith(`${cmd.name} `)) {
-				const subCommand = findCommandByName(name.slice(cmd.name.length + 1), cmd.commands);
-				if (subCommand) return subCommand;
-			}
-			if (cmd.commands && cmd.aliases) {
-				for (const alias of cmd.aliases) if (name.startsWith(`${alias} `)) {
-					const subCommand = findCommandByName(name.slice(alias.length + 1), cmd.commands);
-					if (subCommand) return subCommand;
-				}
-			}
-		}
-	}
+function createPadroneBuilder(inputCommand) {
+	const existingCommand = inputCommand.commands?.length && inputCommand.commands.some((c) => c.parent && c.parent !== inputCommand) ? {
+		...inputCommand,
+		commands: inputCommand.commands.map((c) => c.parent && c.parent !== inputCommand ? {
+			...c,
+			parent: inputCommand
+		} : c)
+	} : inputCommand;
+	/** Creates the action context passed to command handlers. References `builder` which is defined later but only called at runtime. */
+	const createActionContext = (cmd) => ({
+		runtime: getCommandRuntime(cmd),
+		command: cmd,
+		program: builder
+	});
 	const find = (command) => {
 		if (typeof command !== "string") return findCommandByName(command.path, existingCommand.commands);
 		return findCommandByName(command, existingCommand.commands);
 	};
 	/**
-	* Parses CLI input to find the command and extract raw options without validation.
+	* Parses CLI input to find the command and extract raw arguments without validation.
 	*/
 	const parseCommand = (input) => {
-		input ??= typeof process !== "undefined" ? process.argv.slice(2).join(" ") : void 0;
-		if (!input) return {
-			command: existingCommand,
-			rawOptions: {},
-			args: []
-		};
+		input ??= getCommandRuntime(existingCommand).argv().join(" ") || void 0;
+		if (!input) {
+			const defaultCommand = findCommandByName("", existingCommand.commands);
+			if (defaultCommand) return {
+				command: defaultCommand,
+				rawArgs: {},
+				args: [],
+				unmatchedTerms: []
+			};
+			return {
+				command: existingCommand,
+				rawArgs: {},
+				args: [],
+				unmatchedTerms: []
+			};
+		}
 		const parts = parseCliInputToParts(input);
 		const terms = parts.filter((p) => p.type === "term").map((p) => p.value);
 		const args = parts.filter((p) => p.type === "arg").map((p) => p.value);
 		let curCommand = existingCommand;
+		let unmatchedTerms = [];
 		if (terms[0] === existingCommand.name) terms.shift();
 		for (let i = 0; i < terms.length; i++) {
 			const found = findCommandByName(terms[i] || "", curCommand.commands);
 			if (found) curCommand = found;
 			else {
-				args.unshift(...terms.slice(i));
+				unmatchedTerms = terms.slice(i);
+				args.unshift(...unmatchedTerms);
 				break;
 			}
 		}
+		if (unmatchedTerms.length === 0 && curCommand.commands?.length) {
+			const defaultCommand = findCommandByName("", curCommand.commands);
+			if (defaultCommand) curCommand = defaultCommand;
+		}
 		if (!curCommand) return {
 			command: existingCommand,
-			rawOptions: {},
-			args
+			rawArgs: {},
+			args,
+			unmatchedTerms
 		};
-		const optionsMeta = curCommand.meta?.options;
-		const { aliases } = curCommand.options ? extractSchemaMetadata(curCommand.options, optionsMeta) : { aliases: {} };
-		const arrayOptions = /* @__PURE__ */ new Set();
-		if (curCommand.options) try {
-			const jsonSchema = curCommand.options["~standard"].jsonSchema.input({ target: "draft-2020-12" });
+		const argsMeta = curCommand.meta?.fields;
+		const { flags, aliases } = curCommand.argsSchema ? extractSchemaMetadata(curCommand.argsSchema, argsMeta, curCommand.meta?.autoAlias) : {
+			flags: {},
+			aliases: {}
+		};
+		const arrayArguments = /* @__PURE__ */ new Set();
+		if (curCommand.argsSchema) try {
+			const jsonSchema = curCommand.argsSchema["~standard"].jsonSchema.input({ target: "draft-2020-12" });
 			if (jsonSchema.type === "object" && jsonSchema.properties) {
-				for (const [key, prop] of Object.entries(jsonSchema.properties)) if (prop?.type === "array") arrayOptions.add(key);
+				for (const [key, prop] of Object.entries(jsonSchema.properties)) if (prop?.type === "array") arrayArguments.add(key);
 			}
 		} catch {}
-		const opts = parts.filter((p) => p.type === "option" || p.type === "alias");
-		const rawOptions = {};
-		for (const opt of opts) {
-			const key = opt.type === "alias" && opt.key.length === 1 && aliases[opt.key[0]] ? [aliases[opt.key[0]]] : opt.key;
+		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 key = arg.key;
 			const rootKey = key[0];
-			if (opt.type === "option" && opt.negated) {
-				setNestedValue(rawOptions, key, false);
+			if (arg.type === "named" && arg.negated) {
+				setNestedValue(rawArgs, key, false);
 				continue;
 			}
-			const value = opt.value ?? true;
-			if (arrayOptions.has(rootKey)) {
-				const existing = getNestedValue(rawOptions, key);
+			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(rawOptions, key, [existing, ...value]);
-				else setNestedValue(rawOptions, key, [existing, value]);
-				else setNestedValue(rawOptions, key, Array.isArray(value) ? value : [value]);
-			} else setNestedValue(rawOptions, key, 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 setNestedValue(rawArgs, key, value);
 		}
 		return {
 			command: curCommand,
-			rawOptions,
-			args
+			rawArgs,
+			args,
+			unmatchedTerms
 		};
 	};
 	/**
-	* Validates raw options against the command's schema and applies preprocessing.
+	* Preprocesses raw arguments: applies env/config values and maps positional arguments.
+	* Also performs auto-coercion (string→number/boolean) and unknown arg detection.
 	*/
-	const validateOptions = (command, rawOptions, args, parseOptions) => {
-		const preprocessedOptions = preprocessOptions(rawOptions, {
+	const buildCommandArgs = (command, rawArgs, args, context) => {
+		let preprocessedArgs = preprocessArgs(rawArgs, {
+			flags: {},
 			aliases: {},
-			envData: parseOptions?.envData,
-			configData: parseOptions?.configData
+			stdinData: context?.stdinData,
+			envData: context?.envData,
+			configData: context?.configData
 		});
 		const positionalConfig = command.meta?.positional ? parsePositionalConfig(command.meta.positional) : [];
 		if (positionalConfig.length > 0) {
 			let argIndex = 0;
-			for (const { name, variadic } of positionalConfig) {
+			for (let i = 0; i < positionalConfig.length; i++) {
+				const { name, variadic } = positionalConfig[i];
 				if (argIndex >= args.length) break;
 				if (variadic) {
-					const nonVariadicAfter = positionalConfig.slice(positionalConfig.indexOf({
-						name,
-						variadic
-					}) + 1).filter((p) => !p.variadic).length;
+					const nonVariadicAfter = positionalConfig.slice(i + 1).filter((p) => !p.variadic).length;
 					const variadicEnd = args.length - nonVariadicAfter;
-					preprocessedOptions[name] = args.slice(argIndex, variadicEnd);
+					preprocessedArgs[name] = args.slice(argIndex, variadicEnd);
 					argIndex = variadicEnd;
+				} else if (i === positionalConfig.length - 1 && args.length > argIndex + 1) {
+					preprocessedArgs[name] = args.slice(argIndex).join(" ");
+					argIndex = args.length;
 				} else {
-					preprocessedOptions[name] = args[argIndex];
+					preprocessedArgs[name] = args[argIndex];
 					argIndex++;
 				}
 			}
 		}
-		const optionsParsed = command.options ? command.options["~standard"].validate(preprocessedOptions) : { value: preprocessedOptions };
-		if (optionsParsed instanceof Promise) throw new Error("Async validation is not supported. Schema validate() must return a synchronous result.");
-		const hasOptions = command.options || Object.keys(preprocessedOptions).length > 0;
-		return {
-			options: optionsParsed.issues ? void 0 : hasOptions ? optionsParsed.value : void 0,
-			optionsResult: optionsParsed
-		};
+		if (command.argsSchema) preprocessedArgs = coerceArgs(preprocessedArgs, command.argsSchema);
+		return preprocessedArgs;
 	};
-	const parse = (input, parseOptions) => {
-		const { command, rawOptions, args } = parseCommand(input);
-		const resolveEnvSchema = (cmd) => {
-			if (cmd.envSchema !== void 0) return cmd.envSchema;
-			if (cmd.parent) return resolveEnvSchema(cmd.parent);
+	/**
+	* 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.
+	*/
+	const checkUnknownArgs = (command, preprocessedArgs) => {
+		if (!command.argsSchema) return [];
+		const argsMeta = command.meta?.fields;
+		const { flags, aliases } = extractSchemaMetadata(command.argsSchema, argsMeta, command.meta?.autoAlias);
+		return detectUnknownArgs(preprocessedArgs, command.argsSchema, flags, aliases, suggestSimilar);
+	};
+	/**
+	* 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.
+	*/
+	const validateCommandArgs = (command, preprocessedArgs) => {
+		const unknownArgs = checkUnknownArgs(command, preprocessedArgs);
+		if (unknownArgs.length > 0) return {
+			args: void 0,
+			argsResult: { issues: unknownArgs.map(({ key, suggestion }) => ({
+				path: [key],
+				message: suggestion ? `Unknown option: "${key}". ${suggestion}` : `Unknown option: "${key}"`
+			})) }
 		};
-		const envSchema = resolveEnvSchema(command);
-		let envData = parseOptions?.envData;
-		if (envSchema && !envData) {
-			const rawEnv = parseOptions?.env ?? (typeof process !== "undefined" ? process.env : {});
-			const envValidated = envSchema["~standard"].validate(rawEnv);
-			if (envValidated instanceof Promise) throw new Error("Async validation is not supported. Env schema validate() must return a synchronous result.");
-			if (!envValidated.issues) envData = envValidated.value;
-		}
-		const { options, optionsResult } = validateOptions(command, rawOptions, args, {
-			envData,
-			configData: parseOptions?.configData
+		const argsParsed = command.argsSchema ? command.argsSchema["~standard"].validate(preprocessedArgs) : { value: preprocessedArgs };
+		const hasArgs = command.argsSchema || Object.keys(preprocessedArgs).length > 0;
+		const buildResult = (parsed) => ({
+			args: parsed.issues ? void 0 : hasArgs ? parsed.value : void 0,
+			argsResult: parsed
 		});
-		return {
-			command,
-			options,
-			optionsResult
+		return thenMaybe(argsParsed, buildResult);
+	};
+	/**
+	* Preprocesses and validates raw arguments against the command's schema.
+	* Returns sync or async result depending on the schema's validate method.
+	*/
+	const validateArgs = (command, rawArgs, args, context) => {
+		return validateCommandArgs(command, buildCommandArgs(command, rawArgs, args, context));
+	};
+	const parse = (input) => {
+		const state = {};
+		const parseCtx = {
+			input,
+			command: existingCommand,
+			state
 		};
+		const coreParse = () => {
+			const { command, rawArgs, args } = parseCommand(parseCtx.input);
+			return {
+				command,
+				rawArgs,
+				positionalArgs: args
+			};
+		};
+		const parsedOrPromise = runPluginChain("parse", existingCommand.plugins ?? [], parseCtx, coreParse);
+		const continueAfterParse = (parsed) => {
+			const { command } = parsed;
+			const commandPlugins = collectPlugins(command);
+			const validateCtx = {
+				command,
+				rawArgs: parsed.rawArgs,
+				positionalArgs: parsed.positionalArgs,
+				state
+			};
+			const coreValidate = () => {
+				const resolveEnvSchema = (cmd) => {
+					if (cmd.envSchema !== void 0) return cmd.envSchema;
+					if (cmd.parent) return resolveEnvSchema(cmd.parent);
+				};
+				const envSchema = resolveEnvSchema(command);
+				const readStdinForParse = () => {
+					const stdinConfig = command.meta?.stdin;
+					if (!stdinConfig) return {};
+					const { field, as } = parseStdinConfig(stdinConfig);
+					if (field in validateCtx.rawArgs && validateCtx.rawArgs[field] !== void 0) return {};
+					const stdin = resolveStdin(getCommandRuntime(existingCommand));
+					if (!stdin) return {};
+					if (as === "lines") return (async () => {
+						const lines = [];
+						for await (const line of stdin.lines()) lines.push(line);
+						return { [field]: lines };
+					})();
+					return stdin.text().then((text) => text ? { [field]: text } : {});
+				};
+				const finalize = (envData, stdinData) => {
+					return thenMaybe(validateArgs(command, validateCtx.rawArgs, validateCtx.positionalArgs, {
+						stdinData,
+						envData
+					}), (v) => v);
+				};
+				let envData;
+				const afterEnv = (envResult) => {
+					return thenMaybe(readStdinForParse(), (stdinData) => {
+						return finalize(envResult, Object.keys(stdinData).length > 0 ? stdinData : void 0);
+					});
+				};
+				if (envSchema) {
+					const rawEnv = getCommandRuntime(existingCommand).env();
+					return thenMaybe(envSchema["~standard"].validate(rawEnv), (result) => {
+						if (!result.issues) envData = result.value;
+						return afterEnv(envData);
+					});
+				}
+				return afterEnv(envData);
+			};
+			return warnIfUnexpectedAsync(thenMaybe(runPluginChain("validate", commandPlugins, validateCtx, coreValidate), (v) => ({
+				command,
+				args: v.args,
+				argsResult: v.argsResult
+			})), command);
+		};
+		return thenMaybe(parsedOrPromise, continueAfterParse);
 	};
-	const stringify = (command = "", options) => {
+	const stringify = (command = "", args) => {
 		const commandObj = typeof command === "string" ? findCommandByName(command, existingCommand.commands) : command;
-		if (!commandObj) throw new Error(`Command "${command ?? ""}" not found`);
+		if (!commandObj) throw new RoutingError(`Command "${command ?? ""}" not found`);
 		const parts = [];
 		if (commandObj.path) parts.push(commandObj.path);
 		const positionalConfig = commandObj.meta?.positional ? parsePositionalConfig(commandObj.meta.positional) : [];
 		const positionalNames = new Set(positionalConfig.map((p) => p.name));
-		if (options && typeof options === "object") {
+		if (args && typeof args === "object") {
 			for (const { name, variadic } of positionalConfig) {
-				const value = options[name];
+				const value = args[name];
 				if (value === void 0) continue;
 				if (variadic && Array.isArray(value)) for (const v of value) {
 					const vStr = String(v);
@@ -1414,7 +995,7 @@ function createPadroneBuilder(existingCommand) {
 				else parts.push(`--${key}=${value}`);
 				else parts.push(`--${key}=${value}`);
 			};
-			for (const [key, value] of Object.entries(options)) {
+			for (const [key, value] of Object.entries(args)) {
 				if (value === void 0 || positionalNames.has(key)) continue;
 				stringifyValue(key, value);
 			}
@@ -1429,16 +1010,16 @@ function createPadroneBuilder(existingCommand) {
 		if (!input) return null;
 		const parts = parseCliInputToParts(input);
 		const terms = parts.filter((p) => p.type === "term").map((p) => p.value);
-		const opts = parts.filter((p) => p.type === "option" || p.type === "alias");
+		const args = parts.filter((p) => p.type === "named" || p.type === "alias");
 		const keyIs = (key, name) => key.length === 1 && key[0] === name;
-		const hasHelpFlag = opts.some((p) => p.type === "option" && keyIs(p.key, "help") || p.type === "alias" && keyIs(p.key, "h"));
+		const hasHelpFlag = args.some((p) => p.type === "named" && keyIs(p.key, "help") || p.type === "alias" && keyIs(p.key, "h"));
 		const getDetailLevel = () => {
-			for (const opt of opts) {
-				if (opt.type === "option" && keyIs(opt.key, "detail") && typeof opt.value === "string") {
-					if (opt.value === "minimal" || opt.value === "standard" || opt.value === "full") return opt.value;
+			for (const arg of args) {
+				if (arg.type === "named" && keyIs(arg.key, "detail") && typeof arg.value === "string") {
+					if (arg.value === "minimal" || arg.value === "standard" || arg.value === "full") return arg.value;
 				}
-				if (opt.type === "alias" && keyIs(opt.key, "d") && typeof opt.value === "string") {
-					if (opt.value === "minimal" || opt.value === "standard" || opt.value === "full") return opt.value;
+				if (arg.type === "alias" && keyIs(arg.key, "d") && typeof arg.value === "string") {
+					if (arg.value === "minimal" || arg.value === "standard" || arg.value === "full") return arg.value;
 				}
 			}
 		};
@@ -1453,17 +1034,17 @@ function createPadroneBuilder(existingCommand) {
 				"json",
 				"auto"
 			];
-			for (const opt of opts) {
-				if (opt.type === "option" && keyIs(opt.key, "format") && typeof opt.value === "string") {
-					if (validFormats.includes(opt.value)) return opt.value;
+			for (const arg of args) {
+				if (arg.type === "named" && keyIs(arg.key, "format") && typeof arg.value === "string") {
+					if (validFormats.includes(arg.value)) return arg.value;
 				}
-				if (opt.type === "alias" && keyIs(opt.key, "f") && typeof opt.value === "string") {
-					if (validFormats.includes(opt.value)) return opt.value;
+				if (arg.type === "alias" && keyIs(arg.key, "f") && typeof arg.value === "string") {
+					if (validFormats.includes(arg.value)) return arg.value;
 				}
 			}
 		};
 		const format = getFormat();
-		const hasVersionFlag = opts.some((p) => p.type === "option" && keyIs(p.key, "version") || p.type === "alias" && (keyIs(p.key, "v") || keyIs(p.key, "V")));
+		const hasVersionFlag = args.some((p) => p.type === "named" && keyIs(p.key, "version") || p.type === "alias" && (keyIs(p.key, "v") || keyIs(p.key, "V")));
 		const normalizedTerms = [...terms];
 		if (normalizedTerms[0] === existingCommand.name) normalizedTerms.shift();
 		const userHelpCommand = findCommandByName("help", existingCommand.commands);
@@ -1478,6 +1059,24 @@ function createPadroneBuilder(existingCommand) {
 				format
 			};
 		}
+		if (!userHelpCommand && normalizedTerms.length > 0 && normalizedTerms[normalizedTerms.length - 1] === "help") {
+			const commandTerms = normalizedTerms.slice(0, -1);
+			let targetCommand;
+			let current = existingCommand;
+			for (const term of commandTerms) {
+				const found = findCommandByName(term, current.commands);
+				if (found) {
+					targetCommand = found;
+					current = found;
+				} else break;
+			}
+			return {
+				type: "help",
+				command: targetCommand,
+				detail,
+				format
+			};
+		}
 		if (!userVersionCommand && normalizedTerms[0] === "version") return { type: "version" };
 		if (!userCompletionCommand && normalizedTerms[0] === "completion") {
 			const shellArg = normalizedTerms[1];
@@ -1488,7 +1087,8 @@ function createPadroneBuilder(existingCommand) {
 					"zsh",
 					"fish",
 					"powershell"
-				].includes(shellArg) ? shellArg : void 0
+				].includes(shellArg) ? shellArg : void 0,
+				setup: args.some((p) => p.type === "named" && keyIs(p.key, "setup"))
 			};
 		}
 		if (hasHelpFlag) {
@@ -1501,6 +1101,10 @@ function createPadroneBuilder(existingCommand) {
 			};
 		}
 		if (hasVersionFlag && normalizedTerms.length === 0) return { type: "version" };
+		if (args.some((p) => p.type === "named" && keyIs(p.key, "repl"))) return {
+			type: "repl",
+			scope: normalizedTerms.length > 0 ? normalizedTerms.join(" ") : void 0
+		};
 		return null;
 	};
 	/**
@@ -1508,139 +1112,455 @@ function createPadroneBuilder(existingCommand) {
 	*/
 	const extractConfigPath = (input) => {
 		if (!input) return void 0;
-		const opts = parseCliInputToParts(input).filter((p) => p.type === "option" || p.type === "alias");
-		for (const opt of opts) {
-			if (opt.type === "option" && opt.key.length === 1 && opt.key[0] === "config" && typeof opt.value === "string") return opt.value;
-			if (opt.type === "alias" && opt.key.length === 1 && opt.key[0] === "c" && typeof opt.value === "string") return opt.value;
+		const args = parseCliInputToParts(input).filter((p) => p.type === "named" || p.type === "alias");
+		for (const arg of args) {
+			if (arg.type === "named" && arg.key.length === 1 && arg.key[0] === "config" && typeof arg.value === "string") return arg.value;
+			if (arg.type === "alias" && arg.key.length === 1 && arg.key[0] === "c" && typeof arg.value === "string") return arg.value;
 		}
 	};
-	const cli = (input, cliOptions) => {
-		const resolvedInput = input ?? (typeof process !== "undefined" ? process.argv.slice(2).join(" ") : void 0);
+	/**
+	* Core execution logic shared by eval() and cli().
+	* errorMode controls validation error behavior:
+	* - 'soft': return result with issues (eval behavior)
+	* - 'hard': print error + help and throw (cli-without-input behavior)
+	*/
+	const execCommand = (resolvedInput, evalOptions, errorMode = "soft") => {
+		const baseRuntime = getCommandRuntime(existingCommand);
+		const runtime = evalOptions?.runtime ? Object.assign({}, baseRuntime, Object.fromEntries(Object.entries(evalOptions.runtime).filter(([, v]) => v !== void 0))) : baseRuntime;
 		const builtin = checkBuiltinCommands(resolvedInput);
 		if (builtin) {
 			if (builtin.type === "help") {
 				const helpText = generateHelp(existingCommand, builtin.command ?? existingCommand, {
 					detail: builtin.detail,
-					format: builtin.format
+					format: builtin.format ?? runtime.format
 				});
-				console.log(helpText);
+				runtime.output(helpText);
 				return {
 					command: existingCommand,
 					args: void 0,
-					options: void 0,
 					result: helpText
 				};
 			}
 			if (builtin.type === "version") {
 				const version = getVersion(existingCommand.version);
-				console.log(version);
+				runtime.output(version);
 				return {
 					command: existingCommand,
-					options: void 0,
+					args: void 0,
 					result: version
 				};
 			}
-			if (builtin.type === "completion") {
+			if (builtin.type === "completion") return import("./completion.mjs").then(({ detectShell, generateCompletionOutput, setupCompletions }) => {
+				if (builtin.setup) {
+					const shell = builtin.shell ?? detectShell();
+					if (!shell) throw new Error("Could not detect shell. Specify one: completion bash --setup");
+					const result = setupCompletions(existingCommand.name, shell);
+					const message = `${result.updated ? "Updated" : "Added"} ${existingCommand.name} completions in ${result.file}`;
+					runtime.output(message);
+					return {
+						command: existingCommand,
+						args: void 0,
+						result: message
+					};
+				}
 				const completionScript = generateCompletionOutput(existingCommand, builtin.shell);
-				console.log(completionScript);
+				runtime.output(completionScript);
 				return {
 					command: existingCommand,
-					options: void 0,
+					args: void 0,
 					result: completionScript
 				};
-			}
+			});
 		}
-		const { command, rawOptions, args } = parseCommand(resolvedInput);
-		const configPath = extractConfigPath(resolvedInput);
-		const resolveConfigFiles = (cmd) => {
-			if (cmd.configFiles !== void 0) return cmd.configFiles;
-			if (cmd.parent) return resolveConfigFiles(cmd.parent);
-		};
-		const effectiveConfigFiles = resolveConfigFiles(command);
-		const resolveConfigSchema = (cmd) => {
-			if (cmd.config !== void 0) return cmd.config;
-			if (cmd.parent) return resolveConfigSchema(cmd.parent);
-		};
-		const configSchema = resolveConfigSchema(command);
-		const resolveEnvSchema = (cmd) => {
-			if (cmd.envSchema !== void 0) return cmd.envSchema;
-			if (cmd.parent) return resolveEnvSchema(cmd.parent);
+		const state = {};
+		const rootPlugins = existingCommand.plugins ?? [];
+		const runPipeline = () => {
+			const parseCtx = {
+				input: resolvedInput,
+				command: existingCommand,
+				state
+			};
+			const coreParse = () => {
+				const { command, rawArgs, args, unmatchedTerms } = parseCommand(parseCtx.input);
+				const hasSubcommands = command.commands && command.commands.length > 0;
+				const hasSchema = command.argsSchema != null;
+				if (!command.action && (hasSubcommands || !hasSchema) && unmatchedTerms.length === 0) {
+					const helpText = generateHelp(existingCommand, command, { format: runtime.format });
+					runtime.output(helpText);
+					return {
+						command,
+						rawArgs: { "~help": helpText },
+						positionalArgs: []
+					};
+				}
+				if (unmatchedTerms.length > 0) {
+					if (!(command.meta?.positional && command.meta.positional.length > 0)) {
+						const isRootCommand = command === existingCommand;
+						const commandDisplayName = command.name || command.aliases?.[0] || command.path || "(default)";
+						const candidateNames = [];
+						if (isRootCommand && existingCommand.commands) {
+							for (const cmd of existingCommand.commands) if (!cmd.hidden) {
+								candidateNames.push(cmd.name);
+								if (cmd.aliases) candidateNames.push(...cmd.aliases);
+							}
+						} else if (command.commands) {
+							for (const cmd of command.commands) if (!cmd.hidden) {
+								candidateNames.push(cmd.name);
+								if (cmd.aliases) candidateNames.push(...cmd.aliases);
+							}
+						}
+						const suggestion = suggestSimilar(unmatchedTerms[0], candidateNames);
+						const suggestions = suggestion ? [suggestion] : [];
+						const baseMsg = isRootCommand ? `Unknown command: ${unmatchedTerms[0]}` : `Unexpected arguments for '${commandDisplayName}': ${unmatchedTerms.join(" ")}`;
+						const errorMsg = suggestions.length ? `${baseMsg}\n\n  ${suggestions[0]}` : baseMsg;
+						if (errorMode === "hard") {
+							runtime.error(errorMsg);
+							if (suggestions.length > 0) {
+								const visibleCommands = ((isRootCommand ? existingCommand : command).commands ?? []).filter((c) => !c.hidden && c.name);
+								if (visibleCommands.length > 0) {
+									const cmdList = visibleCommands.map((c) => c.name).join(", ");
+									runtime.output(`\nAvailable commands: ${cmdList}`);
+								}
+							} else {
+								const helpText = generateHelp(existingCommand, isRootCommand ? existingCommand : command, { format: runtime.format });
+								runtime.error(helpText);
+							}
+							throw new RoutingError(errorMsg, {
+								suggestions,
+								command: command.path || command.name
+							});
+						}
+						throw new RoutingError(errorMsg, {
+							suggestions,
+							command: command.path || command.name
+						});
+					}
+				}
+				return {
+					command,
+					rawArgs,
+					positionalArgs: args
+				};
+			};
+			const parsedOrPromise = runPluginChain("parse", rootPlugins, parseCtx, coreParse);
+			const continueAfterParse = (parsed) => {
+				const { command } = parsed;
+				const commandPlugins = collectPlugins(command);
+				if (parsed.rawArgs["~help"]) return {
+					command,
+					args: void 0,
+					result: parsed.rawArgs["~help"]
+				};
+				const validateCtx = {
+					command,
+					rawArgs: parsed.rawArgs,
+					positionalArgs: parsed.positionalArgs,
+					state
+				};
+				const coreValidate = () => {
+					let flagInteractive;
+					if (hasInteractiveConfig(command.meta)) {
+						if (validateCtx.rawArgs.interactive !== void 0) {
+							flagInteractive = validateCtx.rawArgs.interactive !== false && validateCtx.rawArgs.interactive !== "false";
+							delete validateCtx.rawArgs.interactive;
+						}
+						if (validateCtx.rawArgs.i !== void 0) {
+							flagInteractive = validateCtx.rawArgs.i !== false && validateCtx.rawArgs.i !== "false";
+							delete validateCtx.rawArgs.i;
+						}
+					}
+					const runtimeDefault = runtime.interactive === "forced" ? true : runtime.interactive === "disabled" ? false : void 0;
+					const effectiveInteractive = flagInteractive ?? evalOptions?.interactive ?? runtimeDefault;
+					const stdinIsPiped = !!command.meta?.stdin && (runtime.stdin ? !runtime.stdin.isTTY : typeof process !== "undefined" && process.stdin?.isTTY !== true);
+					const interactivitySuppressed = runtime.interactive === "unsupported" || effectiveInteractive === false || stdinIsPiped && effectiveInteractive !== true;
+					const forceInteractive = !interactivitySuppressed && effectiveInteractive === true;
+					const configPath = extractConfigPath(parseCtx.input);
+					const resolveConfigFiles = (cmd) => {
+						if (cmd.configFiles !== void 0) return cmd.configFiles;
+						if (cmd.parent) return resolveConfigFiles(cmd.parent);
+					};
+					const effectiveConfigFiles = resolveConfigFiles(command);
+					const resolveConfigSchema = (cmd) => {
+						if (cmd.configSchema !== void 0) return cmd.configSchema;
+						if (cmd.parent) return resolveConfigSchema(cmd.parent);
+					};
+					const configSchema = resolveConfigSchema(command);
+					const resolveEnvSchema = (cmd) => {
+						if (cmd.envSchema !== void 0) return cmd.envSchema;
+						if (cmd.parent) return resolveEnvSchema(cmd.parent);
+					};
+					const envSchema = resolveEnvSchema(command);
+					let configData;
+					if (configPath) configData = runtime.loadConfigFile(configPath);
+					else if (effectiveConfigFiles?.length) {
+						const foundConfigPath = runtime.findFile(effectiveConfigFiles);
+						if (foundConfigPath) configData = runtime.loadConfigFile(foundConfigPath) ?? configData;
+					}
+					const validateConfig = () => {
+						if (configData && configSchema) return thenMaybe(configSchema["~standard"].validate(configData), (result) => {
+							if (result.issues) throw new ConfigError(`Invalid config file:\n${result.issues.map((i) => `  - ${i.path?.join(".") || "root"}: ${i.message}`).join("\n")}`, { command: command.path || command.name });
+							return result.value;
+						});
+						return configData;
+					};
+					const validateEnv = () => {
+						let envData;
+						if (envSchema) {
+							const rawEnv = runtime.env();
+							return thenMaybe(envSchema["~standard"].validate(rawEnv), (result) => {
+								if (!result.issues) envData = result.value;
+								return envData;
+							});
+						}
+						return envData;
+					};
+					const readStdin = () => {
+						const stdinConfig = command.meta?.stdin;
+						if (!stdinConfig) return {};
+						const { field, as } = parseStdinConfig(stdinConfig);
+						if (field in validateCtx.rawArgs && validateCtx.rawArgs[field] !== void 0) return {};
+						const stdin = resolveStdin(runtime);
+						if (!stdin) return {};
+						if (as === "lines") return (async () => {
+							const lines = [];
+							for await (const line of stdin.lines()) lines.push(line);
+							return { [field]: lines };
+						})();
+						return stdin.text().then((text) => {
+							if (!text) return {};
+							return { [field]: text };
+						});
+					};
+					const finalizeValidation = (validatedConfigData, envData, stdinData) => {
+						const preprocessedArgs = buildCommandArgs(command, validateCtx.rawArgs, validateCtx.positionalArgs, {
+							stdinData,
+							envData,
+							configData: validatedConfigData
+						});
+						if (!interactivitySuppressed && runtime.prompt && hasInteractiveConfig(command.meta)) {
+							const unknowns = checkUnknownArgs(command, preprocessedArgs);
+							if (unknowns.length > 0) return {
+								args: void 0,
+								argsResult: { issues: unknowns.map(({ key, suggestion }) => ({
+									path: [key],
+									message: suggestion ? `Unknown option: "${key}". ${suggestion}` : `Unknown option: "${key}"`
+								})) }
+							};
+							if (command.argsSchema) {
+								const providedKeys = new Set(Object.keys(preprocessedArgs).filter((k) => preprocessedArgs[k] !== void 0));
+								const earlyCheck = command.argsSchema["~standard"].validate(preprocessedArgs);
+								const checkForProvidedFieldErrors = (result) => {
+									if (!result.issues) return void 0;
+									const providedFieldIssues = result.issues.filter((issue) => {
+										const rootKey = issue.path?.[0];
+										return rootKey !== void 0 && providedKeys.has(String(rootKey));
+									});
+									if (providedFieldIssues.length > 0) return {
+										args: void 0,
+										argsResult: { issues: providedFieldIssues }
+									};
+								};
+								const earlyResult = thenMaybe(earlyCheck, (result) => {
+									const errors = checkForProvidedFieldErrors(result);
+									if (errors) return errors;
+								});
+								if (earlyResult instanceof Promise) return earlyResult.then((err) => {
+									if (err) return err;
+									return continueWithPrompt(preprocessedArgs);
+								});
+								if (earlyResult) return earlyResult;
+							}
+						}
+						return continueWithPrompt(preprocessedArgs);
+					};
+					const continueWithPrompt = (preprocessedArgs) => {
+						return thenMaybe(!interactivitySuppressed && runtime.prompt && hasInteractiveConfig(command.meta) ? promptInteractiveFields(preprocessedArgs, command, runtime, forceInteractive || void 0) : preprocessedArgs, (filledArgs) => {
+							return thenMaybe(validateCommandArgs(command, filledArgs), (v) => v);
+						});
+					};
+					return thenMaybe(validateConfig(), (cfgData) => {
+						return thenMaybe(validateEnv(), (envData) => {
+							return thenMaybe(readStdin(), (stdinData) => {
+								return finalizeValidation(cfgData, envData, Object.keys(stdinData).length > 0 ? stdinData : void 0);
+							});
+						});
+					});
+				};
+				const validatedOrPromise = runPluginChain("validate", commandPlugins, validateCtx, coreValidate);
+				const continueAfterValidate = (v) => {
+					if (v.argsResult?.issues) {
+						let knownOptions;
+						const getKnownOptions = () => {
+							if (knownOptions) return knownOptions;
+							knownOptions = [];
+							if (command.argsSchema) try {
+								const js = command.argsSchema["~standard"].jsonSchema.input({ target: "draft-2020-12" });
+								if (js.type === "object" && js.properties) knownOptions = Object.keys(js.properties);
+							} catch {}
+							return knownOptions;
+						};
+						const issueMessages = v.argsResult.issues.map((i) => {
+							const base = `  - ${i.path?.join(".") || "root"}: ${i.message}`;
+							const unrecognizedKeys = i.keys ?? i.message?.match(/[Uu]nrecognized key(?:s)?[^"]*"([^"]+)"/)?.slice(1);
+							if (unrecognizedKeys?.length) {
+								const hints = unrecognizedKeys.map((k) => suggestSimilar(k, getKnownOptions())).filter(Boolean);
+								if (hints.length) return `${base}\n    ${hints.join("\n    ")}`;
+							}
+							return base;
+						}).join("\n");
+						if (errorMode === "hard") {
+							const helpText = generateHelp(existingCommand, command, { format: runtime.format });
+							runtime.error(`Validation error:\n${issueMessages}`);
+							runtime.error(helpText);
+							throw new ValidationError(`Validation error:\n${issueMessages}`, v.argsResult.issues, {
+								suggestions: v.argsResult.issues.flatMap((i) => {
+									const keys = i.keys ?? i.message?.match(/[Uu]nrecognized key(?:s)?[^"]*"([^"]+)"/)?.slice(1);
+									if (!keys?.length) return [];
+									return keys.map((k) => suggestSimilar(k, getKnownOptions())).filter(Boolean);
+								}),
+								command: command.path || command.name
+							});
+						}
+						return {
+							command,
+							args: void 0,
+							argsResult: v.argsResult,
+							result: void 0
+						};
+					}
+					const executeCtx = {
+						command,
+						args: v.args,
+						state
+					};
+					const coreExecute = () => {
+						const handler = command.action ?? noop;
+						const ctx = evalOptions?.runtime ? {
+							...createActionContext(command),
+							runtime
+						} : createActionContext(command);
+						return { result: handler(executeCtx.args, ctx) };
+					};
+					return thenMaybe(runPluginChain("execute", commandPlugins, executeCtx, coreExecute), (e) => {
+						const commandResult = {
+							command,
+							args: v.args,
+							argsResult: v.argsResult,
+							result: e.result
+						};
+						if (command.autoOutput ?? evalOptions?.autoOutput ?? true) {
+							const outputOrPromise = outputValue(e.result, runtime.output);
+							if (outputOrPromise instanceof Promise) return outputOrPromise.then(() => commandResult);
+						}
+						return commandResult;
+					});
+				};
+				return warnIfUnexpectedAsync(thenMaybe(validatedOrPromise, continueAfterValidate), command);
+			};
+			return thenMaybe(parsedOrPromise, continueAfterParse);
 		};
-		const envSchema = resolveEnvSchema(command);
-		let configData = cliOptions?.configData;
-		if (configPath) configData = loadConfigFile(configPath);
-		else if (effectiveConfigFiles?.length) {
-			const foundConfigPath = findConfigFile(effectiveConfigFiles);
-			if (foundConfigPath) configData = loadConfigFile(foundConfigPath) ?? configData;
+		return wrapWithLifecycle(rootPlugins, existingCommand, state, resolvedInput, runPipeline, (result) => ({
+			command: existingCommand,
+			args: void 0,
+			argsResult: void 0,
+			result
+		}));
+	};
+	const evalCommand = (input, evalOptions) => {
+		return execCommand(input, evalOptions, "soft");
+	};
+	/**
+	* Collects plugins from the command's parent chain (root → ... → target).
+	* Root/program plugins come first (outermost), target command's plugins last (innermost).
+	*
+	* The `programRoot` parameter provides the current program command, because
+	* subcommands' `.parent` references may be stale (builders are immutable — each
+	* method returns a new builder, so a subcommand's parent was captured before
+	* `.use()` was called on the program). We substitute `programRoot` for the
+	* top of the chain to ensure program-level plugins are always included.
+	*/
+	const collectPlugins = (cmd) => {
+		const chain = [];
+		let current = cmd;
+		while (current) {
+			if (!current.parent) {
+				if (existingCommand.plugins?.length) chain.unshift(existingCommand.plugins);
+			} else if (current.plugins?.length) chain.unshift(current.plugins);
+			current = current.parent;
 		}
-		if (configData && configSchema) {
-			const configValidated = configSchema["~standard"].validate(configData);
-			if (configValidated instanceof Promise) throw new Error("Async validation is not supported. Config schema validate() must return a synchronous result.");
-			if (configValidated.issues) {
-				const issueMessages = configValidated.issues.map((i) => `  - ${i.path?.join(".") || "root"}: ${i.message}`).join("\n");
-				throw new Error(`Invalid config file:\n${issueMessages}`);
+		return chain.flat();
+	};
+	let replFn;
+	const replActiveRef = { value: false };
+	const cli = (cliOptions) => {
+		const runtime = getCommandRuntime(existingCommand);
+		const resolvedInput = runtime.argv().join(" ") || void 0;
+		if (cliOptions?.repl !== false) {
+			const builtin = checkBuiltinCommands(resolvedInput);
+			if (builtin?.type === "repl") {
+				const replPrefs = {
+					...typeof cliOptions?.repl === "object" ? cliOptions.repl : {},
+					scope: builtin.scope,
+					autoOutput: (typeof cliOptions?.repl === "object" ? cliOptions.repl.autoOutput : void 0) ?? cliOptions?.autoOutput
+				};
+				const drainRepl = async () => {
+					for await (const _ of replFn(replPrefs));
+					return {
+						command: existingCommand,
+						args: void 0,
+						result: void 0
+					};
+				};
+				return drainRepl();
 			}
-			configData = configValidated.value;
-		}
-		let envData = cliOptions?.envData;
-		if (envSchema) {
-			const rawEnv = cliOptions?.env ?? (typeof process !== "undefined" ? process.env : {});
-			const envValidated = envSchema["~standard"].validate(rawEnv);
-			if (envValidated instanceof Promise) throw new Error("Async validation is not supported. Env schema validate() must return a synchronous result.");
-			if (!envValidated.issues) envData = envValidated.value;
 		}
-		const { options, optionsResult } = validateOptions(command, rawOptions, args, {
-			envData,
-			configData
-		});
-		if (optionsResult?.issues) {
-			const issueMessages = optionsResult.issues.map((i) => `  - ${i.path?.join(".") || "root"}: ${i.message}`).join("\n");
-			if (input === void 0) {
-				const helpText = generateHelp(existingCommand, command, { format: "text" });
-				console.error(`Validation error:\n${issueMessages}`);
-				console.error(helpText);
-				throw new Error(`Validation error:\n${issueMessages}`);
+		let updateCheckPromise;
+		if (existingCommand.updateCheck) {
+			if (!(resolvedInput && parseCliInputToParts(resolvedInput).some((p) => p.type === "named" && p.key.length === 1 && p.key[0] === "no-update-check"))) {
+				const currentVersion = getVersion(existingCommand.version);
+				updateCheckPromise = import("./update-check-EbNDkzyV.mjs").then(({ createUpdateChecker }) => createUpdateChecker(existingCommand.name, currentVersion, existingCommand.updateCheck, runtime));
 			}
-			return {
-				command,
-				options: void 0,
-				optionsResult,
-				result: void 0
-			};
 		}
-		return {
-			...run(command, options),
-			optionsResult
-		};
+		const result = execCommand(resolvedInput, cliOptions, "hard");
+		if (updateCheckPromise) {
+			if (result instanceof Promise) return result.then(async (r) => {
+				(await updateCheckPromise)?.();
+				return r;
+			});
+			updateCheckPromise.then((show) => show?.());
+		}
+		return result;
 	};
-	const run = (command, options) => {
+	const run = (command, args) => {
 		const commandObj = typeof command === "string" ? findCommandByName(command, existingCommand.commands) : command;
-		if (!commandObj) throw new Error(`Command "${command ?? ""}" not found`);
-		if (!commandObj.handler) throw new Error(`Command "${commandObj.path}" has no handler`);
-		return {
+		if (!commandObj) throw new RoutingError(`Command "${command ?? ""}" not found`);
+		if (!commandObj.action) throw new RoutingError(`Command "${commandObj.path}" has no action`, { command: commandObj.path });
+		const executeCtx = {
 			command: commandObj,
-			options,
-			result: commandObj.handler(options)
+			args,
+			state: {}
+		};
+		const coreExecute = () => {
+			return { result: commandObj.action(executeCtx.args, createActionContext(commandObj)) };
 		};
+		const executedOrPromise = runPluginChain("execute", collectPlugins(commandObj), executeCtx, coreExecute);
+		const toResult = (e) => ({
+			command: commandObj,
+			args,
+			result: e.result
+		});
+		if (executedOrPromise instanceof Promise) return executedOrPromise.then(toResult);
+		return toResult(executedOrPromise);
 	};
 	const tool = () => {
-		const description = `\n
-This is a CLI tool created with Padrone. You can run any of the defined commands described in the help text below. If you need assistance, refer to the documentation or use the help command.
-
-<help_output>
-${generateHelp(existingCommand, void 0, {
-			format: "text",
-			detail: "full"
-		})}
-</help_output>
-`;
+		const description = `Run a command. Pass the full command string including arguments. Use "help <command>" for detailed usage.\n\n${generateHelp(existingCommand, void 0, { format: "text" })}`;
 		return {
 			type: "function",
 			name: existingCommand.name,
 			strict: true,
 			title: existingCommand.description,
 			description,
-			inputExamples: [{ input: { command: "<command> [args...] [options...]" } }],
+			inputExamples: [{ input: { command: "<command> [positionals...] [arguments...]" } }],
 			inputSchema: {
 				[Symbol.for("vercel.ai.schema")]: true,
 				jsonSchema: {
@@ -1661,64 +1581,105 @@ ${generateHelp(existingCommand, void 0, {
 					};
 				}
 			},
-			needsApproval: (input) => {
-				const { command, options } = parse(input.command);
-				if (typeof command.needsApproval === "function") return command.needsApproval(options);
-				return !!command.needsApproval;
+			needsApproval: async (input) => {
+				const parsed = await parse(input.command);
+				if (typeof parsed.command.needsApproval === "function") return parsed.command.needsApproval(parsed.args);
+				return !!parsed.command.needsApproval;
 			},
-			execute: (input) => {
-				return cli(input.command).result;
+			execute: async (input) => {
+				const output = [];
+				const errors = [];
+				return {
+					result: (await evalCommand(input.command, {
+						autoOutput: false,
+						runtime: {
+							output: (...args) => output.push(args.map(String).join(" ")),
+							error: (text) => errors.push(text),
+							interactive: "unsupported",
+							format: "text"
+						}
+					})).result,
+					logs: output.join("\n"),
+					error: errors.join("\n")
+				};
 			}
 		};
 	};
-	return {
+	const builder = {
 		configure(config) {
 			return createPadroneBuilder({
 				...existingCommand,
 				...config
 			});
 		},
-		arguments(options, meta) {
-			const resolvedOptions = typeof options === "function" ? options(existingCommand.options) : options;
+		runtime(runtimeConfig) {
+			return createPadroneBuilder({
+				...existingCommand,
+				runtime: {
+					...existingCommand.runtime,
+					...runtimeConfig
+				}
+			});
+		},
+		async() {
 			return createPadroneBuilder({
 				...existingCommand,
-				options: resolvedOptions,
-				meta
+				isAsync: true
+			});
+		},
+		arguments(schema, meta) {
+			const resolvedArgs = typeof schema === "function" ? schema(existingCommand.argsSchema) : schema;
+			const isAsync = existingCommand.isAsync || isAsyncBranded(resolvedArgs) || hasInteractiveConfig(meta);
+			return createPadroneBuilder({
+				...existingCommand,
+				argsSchema: resolvedArgs,
+				meta,
+				isAsync
 			});
 		},
 		configFile(file, schema) {
 			const configFiles = file === void 0 ? void 0 : Array.isArray(file) ? file : [file];
-			const resolvedConfig = typeof schema === "function" ? schema(existingCommand.options) : schema ?? existingCommand.options;
+			const resolvedConfig = typeof schema === "function" ? schema(existingCommand.argsSchema) : schema ?? existingCommand.argsSchema;
+			const isAsync = existingCommand.isAsync || isAsyncBranded(resolvedConfig);
 			return createPadroneBuilder({
 				...existingCommand,
 				configFiles,
-				config: resolvedConfig
+				configSchema: resolvedConfig,
+				isAsync
 			});
 		},
 		env(schema) {
-			const resolvedEnv = typeof schema === "function" ? schema(existingCommand.options) : schema;
+			const resolvedEnv = typeof schema === "function" ? schema(existingCommand.argsSchema) : schema;
+			const isAsync = existingCommand.isAsync || isAsyncBranded(resolvedEnv);
 			return createPadroneBuilder({
 				...existingCommand,
-				envSchema: resolvedEnv
+				envSchema: resolvedEnv,
+				isAsync
 			});
 		},
 		action(handler = noop) {
+			const baseHandler = existingCommand.action ?? noop;
 			return createPadroneBuilder({
 				...existingCommand,
-				handler
+				action: (args, ctx) => handler(args, ctx, baseHandler)
 			});
 		},
 		wrap(config) {
-			const handler = createWrapHandler(config, existingCommand.options, existingCommand.meta?.positional);
+			const handler = createWrapHandler(config, existingCommand.argsSchema, existingCommand.meta?.positional);
 			return createPadroneBuilder({
 				...existingCommand,
-				handler
+				action: handler
 			});
 		},
 		command(nameOrNames, builderFn) {
 			const name = Array.isArray(nameOrNames) ? nameOrNames[0] : nameOrNames;
 			const aliases = Array.isArray(nameOrNames) && nameOrNames.length > 1 ? nameOrNames.slice(1) : void 0;
-			const initialCommand = {
+			const existingSubcommand = existingCommand.commands?.find((c) => c.name === name);
+			const initialCommand = existingSubcommand ? {
+				...existingSubcommand,
+				aliases: aliases ?? existingSubcommand.aliases,
+				parent: existingCommand
+			} : {
 				name,
 				path: existingCommand.path ? `${existingCommand.path} ${name}` : name,
 				aliases,
@@ -1727,39 +1688,94 @@ ${generateHelp(existingCommand, void 0, {
 			};
 			const builder = createPadroneBuilder(initialCommand);
 			const commandObj = (builderFn?.(builder))?.[commandSymbol] ?? initialCommand;
+			const mergedCommandObj = existingSubcommand ? mergeCommands(existingSubcommand, commandObj) : commandObj;
+			const commands = existingCommand.commands || [];
+			const existingIndex = commands.findIndex((c) => c.name === name);
+			const updatedCommands = existingIndex >= 0 ? [
+				...commands.slice(0, existingIndex),
+				mergedCommandObj,
+				...commands.slice(existingIndex + 1)
+			] : [...commands, mergedCommandObj];
+			return createPadroneBuilder({
+				...existingCommand,
+				commands: updatedCommands
+			});
+		},
+		mount(nameOrNames, program) {
+			const name = Array.isArray(nameOrNames) ? nameOrNames[0] : nameOrNames;
+			const aliases = Array.isArray(nameOrNames) && nameOrNames.length > 1 ? nameOrNames.slice(1) : void 0;
+			const programCommand = program[commandSymbol];
+			if (!programCommand) throw new RoutingError("Cannot mount: not a valid Padrone program");
+			const remounted = repathCommandTree(programCommand, name, existingCommand.path || "", existingCommand);
+			remounted.aliases = aliases;
+			const existingSubcommand = existingCommand.commands?.find((c) => c.name === name);
+			const mergedCommandObj = existingSubcommand ? mergeCommands(existingSubcommand, remounted) : remounted;
+			const commands = existingCommand.commands || [];
+			const existingIndex = commands.findIndex((c) => c.name === name);
+			const updatedCommands = existingIndex >= 0 ? [
+				...commands.slice(0, existingIndex),
+				mergedCommandObj,
+				...commands.slice(existingIndex + 1)
+			] : [...commands, mergedCommandObj];
 			return createPadroneBuilder({
 				...existingCommand,
-				commands: [...existingCommand.commands || [], commandObj]
+				commands: updatedCommands
+			});
+		},
+		use(plugin) {
+			return createPadroneBuilder({
+				...existingCommand,
+				plugins: [...existingCommand.plugins ?? [], plugin]
+			});
+		},
+		updateCheck(config = {}) {
+			return createPadroneBuilder({
+				...existingCommand,
+				updateCheck: config
 			});
 		},
 		run,
 		find,
 		parse,
 		stringify,
+		eval: evalCommand,
 		cli,
 		tool,
+		repl: replFn = (options) => {
+			return createReplIterator({
+				existingCommand,
+				evalCommand,
+				replActiveRef
+			}, options);
+		},
 		api() {
 			function buildApi(command) {
-				const runCommand = ((options) => run(command, options).result);
+				const runCommand = ((args) => run(command, args).result);
 				if (!command.commands) return runCommand;
 				for (const cmd of command.commands) runCommand[cmd.name] = buildApi(cmd);
 				return runCommand;
 			}
 			return buildApi(existingCommand);
 		},
-		help(command, options) {
+		help(command, prefs) {
 			const commandObj = !command ? existingCommand : typeof command === "string" ? findCommandByName(command, existingCommand.commands) : command;
-			if (!commandObj) throw new Error(`Command "${command ?? ""}" not found`);
-			return generateHelp(existingCommand, commandObj, options);
+			if (!commandObj) throw new RoutingError(`Command "${command ?? ""}" not found`);
+			const runtime = getCommandRuntime(existingCommand);
+			return generateHelp(existingCommand, commandObj, {
+				...prefs,
+				format: prefs?.format ?? runtime.format
+			});
 		},
-		completion(shell) {
+		async completion(shell) {
+			const { generateCompletionOutput } = await import("./completion.mjs");
 			return generateCompletionOutput(existingCommand, shell);
 		},
 		"~types": {},
 		[commandSymbol]: existingCommand
 	};
+	return builder;
 }
-
 //#endregion
-export { createPadrone };
+export { ActionError, ConfigError, PadroneError, REPL_SIGINT, RoutingError, ValidationError, asyncSchema, buildReplCompleter, createPadrone };
+
 //# sourceMappingURL=index.mjs.map