padrone 1.9.0 → 2.0.0

package/dist/core/parse.mjs

@@ -0,0 +1,181 @@
+//#region src/core/parse.ts
+/**
+* Split a string by a delimiter, respecting quoted segments and optional bracket nesting.
+* Handles escape sequences within quotes (\\" and \\\\).
+*/
+function splitQuoteAware(input, delimiter, opts) {
+	const results = [];
+	let current = "";
+	let inQuote = null;
+	let bracketDepth = 0;
+	let i = 0;
+	while (i < input.length) {
+		const char = input[i];
+		if (inQuote) {
+			if (char === "\\" && i + 1 < input.length) {
+				const nextChar = input[i + 1];
+				if (nextChar === inQuote || nextChar === "\\") {
+					current += nextChar;
+					i += 2;
+					continue;
+				}
+			}
+			if (char === inQuote) inQuote = null;
+			else current += char;
+		} else if (opts?.brackets && char === "[") {
+			bracketDepth++;
+			current += char;
+		} else if (opts?.brackets && char === "]") {
+			bracketDepth = Math.max(0, bracketDepth - 1);
+			current += char;
+		} else if (bracketDepth > 0) current += char;
+		else if (char === "\"" || char === "'" || char === "`") inQuote = char;
+		else if (char === delimiter || delimiter === " " && char === "	") {
+			if (delimiter === " " ? current : true) {
+				results.push(opts?.trim ? current.trim() : current);
+				current = "";
+			}
+		} else current += char;
+		i++;
+	}
+	if (delimiter === " " ? current : current || results.length > 0) results.push(opts?.trim ? current.trim() : current);
+	return results;
+}
+function parseCliInputToParts(input) {
+	const parts = splitQuoteAware(input.trim(), " ", { brackets: true });
+	const result = [];
+	let pendingIdx = -1;
+	let allowTerm = true;
+	let afterDoubleDash = false;
+	for (const part of parts) {
+		if (!part) continue;
+		if (part === "--" && !afterDoubleDash) {
+			pendingIdx = -1;
+			afterDoubleDash = true;
+			allowTerm = false;
+			continue;
+		}
+		if (afterDoubleDash) {
+			result.push({
+				type: "arg",
+				value: part
+			});
+			continue;
+		}
+		const hadPending = pendingIdx;
+		pendingIdx = -1;
+		if (part.startsWith("--no-") && part.length > 5) {
+			const key = part.slice(5).split(".");
+			result.push({
+				type: "named",
+				key,
+				value: void 0,
+				negated: true
+			});
+		} else if (part.startsWith("--")) {
+			const [keyStr = "", value] = splitNamedArgValue(part.slice(2));
+			const key = keyStr.split(".");
+			result.push({
+				type: "named",
+				key,
+				value
+			});
+			if (typeof value === "undefined") pendingIdx = result.length - 1;
+		} else if (part.startsWith("-") && part.length > 1 && !/^-\d/.test(part)) {
+			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
+				});
+				result.push({
+					type: "alias",
+					key: [keyStr[keyStr.length - 1]],
+					value: void 0
+				});
+				pendingIdx = result.length - 1;
+			} 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 {
+				result.push({
+					type: "alias",
+					key: [keyStr],
+					value
+				});
+				if (typeof value === "undefined") pendingIdx = result.length - 1;
+			}
+		} else if (hadPending >= 0) result[hadPending].value = part;
+		else if (/^[a-zA-Z0-9_-]+$/.test(part) && allowTerm) result.push({
+			type: "term",
+			value: part
+		});
+		else {
+			result.push({
+				type: "arg",
+				value: part
+			});
+			allowTerm = false;
+		}
+	}
+	return result;
+}
+/**
+* Split named arg key and value, handling quoted values after =.
+*/
+function splitNamedArgValue(str) {
+	const eqIndex = str.indexOf("=");
+	if (eqIndex === -1) return [str, void 0];
+	const key = str.slice(0, eqIndex);
+	let value = str.slice(eqIndex + 1);
+	if (value.startsWith("\"") && value.endsWith("\"") || value.startsWith("'") && value.endsWith("'") || value.startsWith("`") && value.endsWith("`")) {
+		value = value.slice(1, -1);
+		return [key, value];
+	}
+	if (value.startsWith("[") && value.endsWith("]")) {
+		const inner = value.slice(1, -1);
+		if (inner === "") return [key, []];
+		return [key, splitQuoteAware(inner, ",", { trim: true })];
+	}
+	return [key, value];
+}
+/**
+* Sets a value at a nested path in an object.
+* For example: setNestedValue(obj, ['user', 'profile', 'name'], 'John')
+* Creates intermediate objects as needed.
+*/
+function setNestedValue(obj, path, value) {
+	let current = obj;
+	for (let i = 0; i < path.length - 1; i++) {
+		const part = path[i];
+		if (!(part in current) || typeof current[part] !== "object" || current[part] === null) current[part] = {};
+		current = current[part];
+	}
+	const lastPart = path[path.length - 1];
+	current[lastPart] = value;
+}
+/**
+* Gets a value at a nested path in an object.
+* Returns undefined if the path doesn't exist.
+*/
+function getNestedValue(obj, path) {
+	let current = obj;
+	for (const part of path) {
+		if (current === null || current === void 0 || typeof current !== "object") return;
+		current = current[part];
+	}
+	return current;
+}
+//#endregion
+export { getNestedValue, parseCliInputToParts, setNestedValue };
+
+//# sourceMappingURL=parse.mjs.map

package/dist/core/parse.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.mjs","names":[],"sources":["../../src/core/parse.ts"],"sourcesContent":["type ParseParts = {\n  /**\n   * An alphanumeric term representing a command, subcommand, or positional argument.\n   * Note that a term can be ambiguous until fully matched within the command hierarchy.\n   * We cannot fully distinguish between a nested command or a positional argument until\n   * the command structure is known.\n   */\n  term: {\n    type: 'term';\n    value: string;\n  };\n  /**\n   * A positional argument provided to the command.\n   * Unlike `term`, this is definitively an argument. This can be determined when\n   * the argument is non-alphanumeric, like a path or a number.\n   */\n  arg: {\n    type: 'arg';\n    value: string;\n  };\n  /**\n   * An arg provided to the command, prefixed with `--`.\n   * If the arg has an `=` sign, the value after it is used as the arg's value.\n   * Otherwise, the value is obtained from the next part or set to `true` if no value is provided.\n   * The key is an array representing the path for nested args (e.g., `--user.id=123` becomes `['user', 'id']`).\n   */\n  named: {\n    type: 'named';\n    key: string[];\n    value?: string | string[];\n    negated?: boolean;\n  };\n  /**\n   * An alias arg provided to the command, prefixed with `-`.\n   * Which arg it maps to cannot be determined until the command structure is known.\n   * Aliases cannot be nested, so the key is always a single-element array.\n   */\n  alias: {\n    type: 'alias';\n    key: string[];\n    value?: string | string[];\n  };\n};\n\ntype ParsePart = ParseParts[keyof ParseParts];\n\ntype QuoteChar = '\"' | \"'\" | '`';\n\n/**\n * Split a string by a delimiter, respecting quoted segments and optional bracket nesting.\n * Handles escape sequences within quotes (\\\\\" and \\\\\\\\).\n */\nfunction splitQuoteAware(input: string, delimiter: ' ' | ',', opts?: { brackets?: boolean; trim?: boolean }): string[] {\n  const results: string[] = [];\n  let current = '';\n  let inQuote: QuoteChar | null = null;\n  let bracketDepth = 0;\n  let i = 0;\n\n  while (i < input.length) {\n    const char = input[i];\n\n    if (inQuote) {\n      if (char === '\\\\' && i + 1 < input.length) {\n        const nextChar = input[i + 1];\n        if (nextChar === inQuote || nextChar === '\\\\') {\n          current += nextChar;\n          i += 2;\n          continue;\n        }\n      }\n      if (char === inQuote) {\n        inQuote = null;\n      } else {\n        current += char;\n      }\n    } else if (opts?.brackets && char === '[') {\n      bracketDepth++;\n      current += char;\n    } else if (opts?.brackets && char === ']') {\n      bracketDepth = Math.max(0, bracketDepth - 1);\n      current += char;\n    } else if (bracketDepth > 0) {\n      current += char;\n    } else if (char === '\"' || char === \"'\" || char === '`') {\n      inQuote = char;\n    } else if (char === delimiter || (delimiter === ' ' && char === '\\t')) {\n      if (delimiter === ' ' ? current : true) {\n        results.push(opts?.trim ? current.trim() : current);\n        current = '';\n      }\n    } else {\n      current += char;\n    }\n    i++;\n  }\n\n  if (delimiter === ' ' ? current : current || results.length > 0) {\n    results.push(opts?.trim ? current.trim() : current);\n  }\n\n  return results;\n}\n\nexport function parseCliInputToParts(input: string): ParsePart[] {\n  const parts = splitQuoteAware(input.trim(), ' ', { brackets: true });\n  const result: ParsePart[] = [];\n\n  // Index into `result` of the last part that can accept a pending value (-1 = none)\n  let pendingIdx = -1;\n  // Once a non-term positional arg appears, all subsequent bare values become args\n  let allowTerm = true;\n  let afterDoubleDash = false;\n\n  for (const part of parts) {\n    if (!part) continue;\n\n    // Bare `--` separator: everything after is a literal positional arg\n    if (part === '--' && !afterDoubleDash) {\n      pendingIdx = -1;\n      afterDoubleDash = true;\n      allowTerm = false;\n      continue;\n    }\n\n    if (afterDoubleDash) {\n      result.push({ type: 'arg', value: part });\n      continue;\n    }\n\n    const hadPending = pendingIdx;\n    pendingIdx = -1;\n\n    if (part.startsWith('--no-') && part.length > 5) {\n      // Negated boolean arg (--no-verbose or --no-config.debug)\n      const key = part.slice(5).split('.');\n      result.push({ type: 'named', key, value: undefined, negated: true });\n    } else if (part.startsWith('--')) {\n      const [keyStr = '', value] = splitNamedArgValue(part.slice(2));\n      const key = keyStr.split('.');\n      result.push({ type: 'named', key, value });\n      if (typeof value === 'undefined') pendingIdx = result.length - 1;\n    } else if (part.startsWith('-') && part.length > 1 && !/^-\\d/.test(part)) {\n      // Short flag(s) (but not negative numbers like -5)\n      // Supports flag stacking: -abc → -a -b -c (last flag can take a value)\n      const [keyStr = '', value] = splitNamedArgValue(part.slice(1));\n\n      if (keyStr.length > 1 && typeof value === 'undefined') {\n        // Flag stacking: -abc → -a, -b, -c (all set to true except last which can take next arg's value)\n        for (let ci = 0; ci < keyStr.length - 1; ci++) {\n          result.push({ type: 'alias', key: [keyStr[ci]!], value: undefined });\n        }\n        result.push({ type: 'alias', key: [keyStr[keyStr.length - 1]!], value: undefined });\n        pendingIdx = result.length - 1;\n      } else if (keyStr.length > 1 && typeof value !== 'undefined') {\n        // -abc=val → -a, -b, -c=val (stacked with value on last)\n        for (let ci = 0; ci < keyStr.length - 1; ci++) {\n          result.push({ type: 'alias', key: [keyStr[ci]!], value: undefined });\n        }\n        result.push({ type: 'alias', key: [keyStr[keyStr.length - 1]!], value });\n      } else {\n        // Single char: -v or -v=value\n        result.push({ type: 'alias', key: [keyStr], value });\n        if (typeof value === 'undefined') pendingIdx = result.length - 1;\n      }\n    } else if (hadPending >= 0) {\n      result[hadPending]!.value = part;\n    } else if (/^[a-zA-Z0-9_-]+$/.test(part) && allowTerm) {\n      result.push({ type: 'term', value: part });\n    } else {\n      result.push({ type: 'arg', value: part });\n      allowTerm = false;\n    }\n  }\n  return result;\n}\n\n/**\n * Split named arg key and value, handling quoted values after =.\n */\nfunction splitNamedArgValue(str: string): [string, string | string[] | undefined] {\n  const eqIndex = str.indexOf('=');\n  if (eqIndex === -1) return [str, undefined];\n\n  const key = str.slice(0, eqIndex);\n  let value = str.slice(eqIndex + 1);\n\n  // Remove surrounding quotes from value if present\n  if (\n    (value.startsWith('\"') && value.endsWith('\"')) ||\n    (value.startsWith(\"'\") && value.endsWith(\"'\")) ||\n    (value.startsWith('`') && value.endsWith('`'))\n  ) {\n    value = value.slice(1, -1);\n    return [key, value];\n  }\n\n  // Handle array syntax: [a,b,c] -> ['a', 'b', 'c']\n  if (value.startsWith('[') && value.endsWith(']')) {\n    const inner = value.slice(1, -1);\n    if (inner === '') return [key, []];\n    return [key, splitQuoteAware(inner, ',', { trim: true })];\n  }\n\n  return [key, value];\n}\n\n/**\n * Sets a value at a nested path in an object.\n * For example: setNestedValue(obj, ['user', 'profile', 'name'], 'John')\n * Creates intermediate objects as needed.\n */\nexport function setNestedValue(obj: Record<string, unknown>, path: string[], value: unknown): void {\n  let current: Record<string, unknown> = obj;\n\n  for (let i = 0; i < path.length - 1; i++) {\n    const part = path[i]!;\n    if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {\n      current[part] = {};\n    }\n    current = current[part] as Record<string, unknown>;\n  }\n\n  const lastPart = path[path.length - 1]!;\n  current[lastPart] = value;\n}\n\n/**\n * Gets a value at a nested path in an object.\n * Returns undefined if the path doesn't exist.\n */\nexport function getNestedValue(obj: Record<string, unknown>, path: string[]): unknown {\n  let current: unknown = obj;\n\n  for (const part of path) {\n    if (current === null || current === undefined || typeof current !== 'object') {\n      return undefined;\n    }\n    current = (current as Record<string, unknown>)[part];\n  }\n\n  return current;\n}\n"],"mappings":"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"}

package/dist/core/program-methods.mjs

@@ -0,0 +1,256 @@
+import { extractSchemaMetadata, parsePositionalConfig } from "./args.mjs";
+import { findCommandByName, getCommandRuntime, resolveAllCommands } from "./commands.mjs";
+import { errorResult, makeThenable, thenMaybe, warnIfUnexpectedAsync, withDrain, withPromiseDrain } from "./results.mjs";
+import { resolveRegisteredInterceptors, runInterceptorChain } from "./interceptors.mjs";
+import { RoutingError } from "./errors.mjs";
+import { coreValidateForParse } from "./validate.mjs";
+import { generateHelp } from "../output/help.mjs";
+import { collectInterceptors, errorResultWithSignal, execCommand } from "./exec.mjs";
+import { createReplIterator } from "../feature/repl-loop.mjs";
+//#region src/core/program-methods.ts
+function createProgramMethods(ctx, evalCommand) {
+	const { rootCommand } = ctx;
+	const inertSignal = new AbortController().signal;
+	const stringify = (command = "", args) => {
+		const commandObj = typeof command === "string" ? findCommandByName(command, rootCommand.commands) : command;
+		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));
+		const negativeKeyword = {};
+		if (commandObj.argsSchema) {
+			const { negatives } = extractSchemaMetadata(commandObj.argsSchema, commandObj.meta?.fields, commandObj.meta?.autoAlias);
+			for (const [keyword, argName] of Object.entries(negatives)) if (!(argName in negativeKeyword)) negativeKeyword[argName] = keyword;
+		}
+		if (args && typeof args === "object") {
+			for (const { name, variadic } of positionalConfig) {
+				const value = args[name];
+				if (value === void 0) continue;
+				if (variadic && Array.isArray(value)) for (const v of value) {
+					const vStr = String(v);
+					if (vStr.includes(" ")) parts.push(`"${vStr}"`);
+					else parts.push(vStr);
+				}
+				else {
+					const argStr = String(value);
+					if (argStr.includes(" ")) parts.push(`"${argStr}"`);
+					else parts.push(argStr);
+				}
+			}
+			const stringifyValue = (key, value) => {
+				if (value === void 0) return;
+				if (typeof value === "boolean") if (value) parts.push(`--${key}`);
+				else if (negativeKeyword[key]) parts.push(`--${negativeKeyword[key]}`);
+				else parts.push(`--no-${key}`);
+				else if (Array.isArray(value)) for (const v of value) {
+					const vStr = String(v);
+					if (vStr.includes(" ")) parts.push(`--${key}="${vStr}"`);
+					else parts.push(`--${key}=${vStr}`);
+				}
+				else if (typeof value === "object" && value !== null) for (const [nestedKey, nestedValue] of Object.entries(value)) stringifyValue(`${key}.${nestedKey}`, nestedValue);
+				else if (typeof value === "string") if (value.includes(" ")) parts.push(`--${key}="${value}"`);
+				else parts.push(`--${key}=${value}`);
+				else parts.push(`--${key}=${value}`);
+			};
+			for (const [key, value] of Object.entries(args)) {
+				if (value === void 0 || positionalNames.has(key)) continue;
+				stringifyValue(key, value);
+			}
+		}
+		return parts.join(" ");
+	};
+	const resolveContext = (command, initialContext) => {
+		const chain = [];
+		let current = command;
+		while (current) {
+			chain.unshift(current);
+			current = current.parent;
+		}
+		let resolved = initialContext;
+		for (const cmd of chain) if (cmd.contextTransform) resolved = cmd.contextTransform(resolved);
+		return resolved;
+	};
+	const run = (command, args, prefs) => {
+		try {
+			const commandObj = typeof command === "string" ? findCommandByName(command, rootCommand.commands) : command;
+			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,
+				input: void 0,
+				rawArgs: {},
+				positionalArgs: [],
+				args,
+				signal: inertSignal,
+				context: resolveContext(commandObj, prefs?.context),
+				runtime: getCommandRuntime(commandObj),
+				program: ctx.builder,
+				caller: "run"
+			};
+			const coreExecute = (executeCtx) => {
+				const actionCtx = {
+					runtime: executeCtx.runtime,
+					command: executeCtx.command,
+					program: ctx.builder,
+					signal: inertSignal,
+					context: executeCtx.context,
+					caller: "run"
+				};
+				return { result: commandObj.action(executeCtx.args, actionCtx) };
+			};
+			const executedOrPromise = runInterceptorChain("execute", resolveRegisteredInterceptors(collectInterceptors(commandObj, rootCommand), /* @__PURE__ */ new Map()), executeCtx, coreExecute);
+			const toResult = (e) => withDrain({
+				command: commandObj,
+				args,
+				result: e.result
+			});
+			if (executedOrPromise instanceof Promise) return executedOrPromise.then(toResult).catch((err) => errorResult(err, {
+				command: commandObj,
+				args
+			}));
+			return toResult(executedOrPromise);
+		} catch (err) {
+			return errorResult(err);
+		}
+	};
+	const tool = () => {
+		resolveAllCommands(rootCommand);
+		const description = `Run a command. Pass the full command string including arguments. Use "help <command>" for detailed usage.\n\n${generateHelp(rootCommand, void 0, { format: "text" })}`;
+		return {
+			type: "function",
+			name: rootCommand.name,
+			strict: true,
+			title: rootCommand.description,
+			description,
+			inputExamples: [{ input: { command: "<command> [positionals...] [arguments...]" } }],
+			inputSchema: {
+				[Symbol.for("vercel.ai.schema")]: true,
+				jsonSchema: {
+					type: "object",
+					properties: { command: { type: "string" } },
+					additionalProperties: false
+				},
+				_type: void 0,
+				validate: (value) => {
+					const command = value?.command;
+					if (typeof command === "string") return {
+						success: true,
+						value: { command }
+					};
+					return {
+						success: false,
+						error: /* @__PURE__ */ new Error("Expected an object with command property as string.")
+					};
+				}
+			},
+			needsApproval: async (input) => {
+				const parsed = await parse(input.command);
+				if (typeof parsed.command.needsApproval === "function") return parsed.command.needsApproval(parsed.args);
+				if (parsed.command.needsApproval != null) return !!parsed.command.needsApproval;
+				return !!parsed.command.mutation;
+			},
+			execute: async (input) => {
+				const output = [];
+				const errors = [];
+				return {
+					result: (await evalCommand(input.command, {
+						caller: "tool",
+						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")
+				};
+			}
+		};
+	};
+	const replActiveRef = { value: false };
+	const replFn = (options) => createReplIterator({
+		existingCommand: rootCommand,
+		evalCommand,
+		replActiveRef
+	}, options);
+	const cli = (cliOptions) => {
+		try {
+			const result = execCommand(getCommandRuntime(rootCommand).argv().join(" ") || void 0, ctx, cliOptions, "hard", "cli");
+			if (result instanceof Promise) return withPromiseDrain(result.catch((err) => errorResultWithSignal(err)));
+			return makeThenable(result);
+		} catch (err) {
+			return makeThenable(errorResultWithSignal(err));
+		}
+	};
+	const find = (command) => {
+		if (typeof command !== "string") return findCommandByName(command.path, rootCommand.commands);
+		return findCommandByName(command, rootCommand.commands);
+	};
+	const parse = (input) => {
+		const { command, rawArgs, args } = ctx.parseCommandFn(input);
+		return makeThenable(warnIfUnexpectedAsync(thenMaybe(coreValidateForParse(command, rawArgs, args), (v) => ({
+			command,
+			args: v.args,
+			argsResult: v.argsResult
+		})), command));
+	};
+	const help = (command, prefs) => {
+		resolveAllCommands(rootCommand);
+		const commandObj = !command ? rootCommand : typeof command === "string" ? findCommandByName(command, rootCommand.commands) : command;
+		if (!commandObj) throw new RoutingError(`Command "${command ?? ""}" not found`);
+		const runtime = getCommandRuntime(rootCommand);
+		return generateHelp(rootCommand, commandObj, {
+			...prefs,
+			format: prefs?.format ?? runtime.format,
+			theme: prefs?.theme ?? runtime.theme,
+			terminal: prefs?.terminal ?? runtime.terminal,
+			env: prefs?.env ?? runtime.env()
+		});
+	};
+	const api = () => {
+		resolveAllCommands(rootCommand);
+		function buildApi(command) {
+			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(rootCommand);
+	};
+	const completion = async (shell) => {
+		resolveAllCommands(rootCommand);
+		const { generateCompletionOutput } = await import("../feature/completion.mjs");
+		return generateCompletionOutput(rootCommand, shell);
+	};
+	const mcp = async (prefs) => {
+		resolveAllCommands(rootCommand);
+		const { startMcpServer } = await import("../feature/mcp.mjs");
+		return startMcpServer(ctx.builder, rootCommand, evalCommand, prefs);
+	};
+	const serve = async (prefs) => {
+		resolveAllCommands(rootCommand);
+		const { startServeServer } = await import("../feature/serve.mjs");
+		return startServeServer(ctx.builder, rootCommand, evalCommand, prefs);
+	};
+	return {
+		find,
+		parse,
+		stringify,
+		run,
+		eval: evalCommand,
+		cli,
+		tool,
+		repl: replFn,
+		api,
+		help,
+		completion,
+		mcp,
+		serve
+	};
+}
+//#endregion
+export { createProgramMethods };
+
+//# sourceMappingURL=program-methods.mjs.map

package/dist/core/program-methods.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"program-methods.mjs","names":[],"sources":["../../src/core/program-methods.ts"],"sourcesContent":["import type { Schema } from 'ai';\nimport type { ShellType } from '../feature/completion.ts';\nimport { createReplIterator } from '../feature/repl-loop.ts';\nimport { generateHelp } from '../output/help.ts';\nimport type {\n  AnyPadroneCommand,\n  AnyPadroneProgram,\n  InterceptorExecuteContext,\n  InterceptorExecuteResult,\n  PadroneActionContext,\n  PadroneAPI,\n  PadroneReplPreferences,\n} from '../types/index.ts';\nimport { extractSchemaMetadata, parsePositionalConfig } from './args.ts';\nimport { findCommandByName, getCommandRuntime, resolveAllCommands } from './commands.ts';\nimport { RoutingError } from './errors.ts';\nimport type { ExecContext } from './exec.ts';\nimport { collectInterceptors, errorResultWithSignal, execCommand } from './exec.ts';\nimport { resolveRegisteredInterceptors, runInterceptorChain } from './interceptors.ts';\nimport { errorResult, makeThenable, thenMaybe, warnIfUnexpectedAsync, withDrain, withPromiseDrain } from './results.ts';\nimport { coreValidateForParse } from './validate.ts';\n\nexport function createProgramMethods(ctx: ExecContext, evalCommand: AnyPadroneProgram['eval']) {\n  const { rootCommand } = ctx;\n\n  // A never-aborted signal for contexts that don't need signal handling (parse, run).\n  const inertSignal = new AbortController().signal;\n\n  const stringify: AnyPadroneProgram['stringify'] = (command = '' as any, args) => {\n    const commandObj = typeof command === 'string' ? findCommandByName(command, rootCommand.commands) : (command as AnyPadroneCommand);\n    if (!commandObj) throw new RoutingError(`Command \"${command ?? ''}\" not found`);\n\n    const parts: string[] = [];\n\n    if (commandObj.path) parts.push(commandObj.path);\n\n    const positionalConfig = commandObj.meta?.positional ? parsePositionalConfig(commandObj.meta.positional) : [];\n    const positionalNames = new Set(positionalConfig.map((p) => p.name));\n\n    // Build reverse map: arg name → first negative keyword (for stringify)\n    const negativeKeyword: Record<string, string> = {};\n    if (commandObj.argsSchema) {\n      const { negatives } = extractSchemaMetadata(commandObj.argsSchema, commandObj.meta?.fields, commandObj.meta?.autoAlias);\n      for (const [keyword, argName] of Object.entries(negatives)) {\n        if (!(argName in negativeKeyword)) negativeKeyword[argName] = keyword;\n      }\n    }\n\n    if (args && typeof args === 'object') {\n      for (const { name, variadic } of positionalConfig) {\n        const value = (args as Record<string, unknown>)[name];\n        if (value === undefined) continue;\n\n        if (variadic && Array.isArray(value)) {\n          for (const v of value) {\n            const vStr = String(v);\n            if (vStr.includes(' ')) parts.push(`\"${vStr}\"`);\n            else parts.push(vStr);\n          }\n        } else {\n          const argStr = String(value);\n          if (argStr.includes(' ')) parts.push(`\"${argStr}\"`);\n          else parts.push(argStr);\n        }\n      }\n\n      const stringifyValue = (key: string, value: unknown) => {\n        if (value === undefined) return;\n\n        if (typeof value === 'boolean') {\n          if (value) parts.push(`--${key}`);\n          else if (negativeKeyword[key]) parts.push(`--${negativeKeyword[key]}`);\n          else parts.push(`--no-${key}`);\n        } else if (Array.isArray(value)) {\n          for (const v of value) {\n            const vStr = String(v);\n            if (vStr.includes(' ')) parts.push(`--${key}=\"${vStr}\"`);\n            else parts.push(`--${key}=${vStr}`);\n          }\n        } else if (typeof value === 'object' && value !== null) {\n          for (const [nestedKey, nestedValue] of Object.entries(value)) {\n            stringifyValue(`${key}.${nestedKey}`, nestedValue);\n          }\n        } else if (typeof value === 'string') {\n          if (value.includes(' ')) parts.push(`--${key}=\"${value}\"`);\n          else parts.push(`--${key}=${value}`);\n        } else {\n          parts.push(`--${key}=${value}`);\n        }\n      };\n\n      for (const [key, value] of Object.entries(args)) {\n        if (value === undefined || positionalNames.has(key)) continue;\n        stringifyValue(key, value);\n      }\n    }\n\n    return parts.join(' ');\n  };\n\n  const resolveContext = (command: AnyPadroneCommand, initialContext: unknown): unknown => {\n    const chain: AnyPadroneCommand[] = [];\n    let current: AnyPadroneCommand | undefined = command;\n    while (current) {\n      chain.unshift(current);\n      current = current.parent;\n    }\n    let resolved = initialContext;\n    for (const cmd of chain) {\n      if (cmd.contextTransform) resolved = cmd.contextTransform(resolved);\n    }\n    return resolved;\n  };\n\n  const run: AnyPadroneProgram['run'] = (command, args, prefs?: { context?: unknown }) => {\n    try {\n      const commandObj = typeof command === 'string' ? findCommandByName(command, rootCommand.commands) : (command as AnyPadroneCommand);\n      if (!commandObj) throw new RoutingError(`Command \"${command ?? ''}\" not found`);\n      if (!commandObj.action) throw new RoutingError(`Command \"${commandObj.path}\" has no action`, { command: commandObj.path });\n\n      const resolvedCtx = resolveContext(commandObj, prefs?.context);\n      const commandRuntime = getCommandRuntime(commandObj);\n      const executeCtx: InterceptorExecuteContext = {\n        command: commandObj,\n        input: undefined,\n        rawArgs: {},\n        positionalArgs: [],\n        args,\n        signal: inertSignal,\n        context: resolvedCtx as object,\n        runtime: commandRuntime,\n        program: ctx.builder as any,\n        caller: 'run',\n      };\n\n      const coreExecute = (executeCtx: InterceptorExecuteContext): InterceptorExecuteResult => {\n        const actionCtx: PadroneActionContext = {\n          runtime: executeCtx.runtime,\n          command: executeCtx.command,\n          program: ctx.builder as any,\n          signal: inertSignal,\n          context: executeCtx.context,\n          caller: 'run',\n        };\n        const result = commandObj.action!(executeCtx.args as any, actionCtx);\n        return { result };\n      };\n\n      const commandInterceptors = resolveRegisteredInterceptors(collectInterceptors(commandObj, rootCommand), new Map());\n      const executedOrPromise = runInterceptorChain('execute', commandInterceptors, executeCtx, coreExecute);\n\n      const toResult = (e: InterceptorExecuteResult) => withDrain({ command: commandObj as any, args: args as any, result: e.result });\n\n      if (executedOrPromise instanceof Promise) {\n        return executedOrPromise.then(toResult).catch((err: unknown) => errorResult(err, { command: commandObj, args })) as any;\n      }\n      return toResult(executedOrPromise);\n    } catch (err) {\n      return errorResult(err) as any;\n    }\n  };\n\n  const tool: AnyPadroneProgram['tool'] = () => {\n    resolveAllCommands(rootCommand);\n    const helpText = generateHelp(rootCommand, undefined, { format: 'text' });\n\n    const description = `Run a command. Pass the full command string including arguments. Use \"help <command>\" for detailed usage.\\n\\n${helpText}`;\n\n    return {\n      type: 'function',\n      name: rootCommand.name,\n      strict: true,\n      title: rootCommand.description,\n      description,\n      inputExamples: [{ input: { command: '<command> [positionals...] [arguments...]' } }],\n      inputSchema: {\n        [Symbol.for('vercel.ai.schema') as keyof Schema & symbol]: true,\n        jsonSchema: {\n          type: 'object',\n          properties: { command: { type: 'string' } },\n          additionalProperties: false,\n        },\n        _type: undefined as unknown as { command: string },\n        validate: (value) => {\n          const command = (value as any)?.command;\n          if (typeof command === 'string') return { success: true, value: { command } };\n          return { success: false, error: new Error('Expected an object with command property as string.') };\n        },\n      } satisfies Schema<{ command: string }> as Schema<{ command: string }>,\n      needsApproval: async (input) => {\n        const parsed = await parse(input.command);\n        if (typeof parsed.command.needsApproval === 'function') return parsed.command.needsApproval(parsed.args);\n        if (parsed.command.needsApproval != null) return !!parsed.command.needsApproval;\n        return !!parsed.command.mutation;\n      },\n      execute: async (input) => {\n        const output: string[] = [];\n        const errors: string[] = [];\n        const result = await evalCommand(input.command, {\n          caller: 'tool',\n          runtime: {\n            output: (...args) => output.push(args.map(String).join(' ')),\n            error: (text) => errors.push(text),\n            interactive: 'unsupported',\n            format: 'text',\n          },\n        });\n        return { result: result.result, logs: output.join('\\n'), error: errors.join('\\n') };\n      },\n    };\n  };\n\n  const replActiveRef = { value: false };\n  const replFn = (options?: PadroneReplPreferences) =>\n    createReplIterator({ existingCommand: rootCommand, evalCommand, replActiveRef }, options);\n\n  const cli: AnyPadroneProgram['cli'] = (cliOptions) => {\n    try {\n      const runtime = getCommandRuntime(rootCommand);\n      const resolvedInput = (runtime.argv().join(' ') || undefined) as string | undefined;\n\n      const result = execCommand(resolvedInput, ctx, cliOptions, 'hard', 'cli');\n\n      if (result instanceof Promise) return withPromiseDrain(result.catch((err: unknown) => errorResultWithSignal(err))) as any;\n      return makeThenable(result);\n    } catch (err) {\n      return makeThenable(errorResultWithSignal(err)) as any;\n    }\n  };\n\n  const find: AnyPadroneProgram['find'] = (command) => {\n    if (typeof command !== 'string') return findCommandByName(command.path, rootCommand.commands) as any;\n    return findCommandByName(command, rootCommand.commands) as any;\n  };\n\n  const parse: AnyPadroneProgram['parse'] = (input) => {\n    const { command, rawArgs, args } = ctx.parseCommandFn(input as string | undefined);\n\n    const validatedOrPromise = coreValidateForParse(command, rawArgs, args);\n\n    return makeThenable(\n      warnIfUnexpectedAsync(\n        thenMaybe(validatedOrPromise, (v: any) => ({ command: command as any, args: v.args, argsResult: v.argsResult })),\n        command,\n      ),\n    ) as any;\n  };\n\n  const help: AnyPadroneProgram['help'] = (command, prefs) => {\n    resolveAllCommands(rootCommand);\n    const commandObj = !command\n      ? rootCommand\n      : typeof command === 'string'\n        ? findCommandByName(command, rootCommand.commands)\n        : (command as AnyPadroneCommand);\n    if (!commandObj) throw new RoutingError(`Command \"${command ?? ''}\" not found`);\n    const runtime = getCommandRuntime(rootCommand);\n    return generateHelp(rootCommand, commandObj, {\n      ...prefs,\n      format: prefs?.format ?? runtime.format,\n      theme: prefs?.theme ?? runtime.theme,\n      terminal: prefs?.terminal ?? runtime.terminal,\n      env: prefs?.env ?? runtime.env(),\n    });\n  };\n\n  const api: AnyPadroneProgram['api'] = () => {\n    resolveAllCommands(rootCommand);\n    function buildApi(command: AnyPadroneCommand) {\n      const runCommand = ((args) => run(command, args).result) as PadroneAPI<AnyPadroneCommand>;\n      if (!command.commands) return runCommand;\n      for (const cmd of command.commands) runCommand[cmd.name] = buildApi(cmd);\n      return runCommand;\n    }\n    return buildApi(rootCommand);\n  };\n\n  const completion: AnyPadroneProgram['completion'] = async (shell) => {\n    resolveAllCommands(rootCommand);\n    const { generateCompletionOutput } = await import('../feature/completion.ts');\n    return generateCompletionOutput(rootCommand, shell as ShellType | undefined);\n  };\n\n  const mcp: AnyPadroneProgram['mcp'] = async (prefs) => {\n    resolveAllCommands(rootCommand);\n    const { startMcpServer } = await import('../feature/mcp.ts');\n    return startMcpServer(ctx.builder as any, rootCommand, evalCommand, prefs);\n  };\n\n  const serve: AnyPadroneProgram['serve'] = async (prefs) => {\n    resolveAllCommands(rootCommand);\n    const { startServeServer } = await import('../feature/serve.ts');\n    return startServeServer(ctx.builder as any, rootCommand, evalCommand, prefs);\n  };\n\n  return {\n    find,\n    parse,\n    stringify,\n    run,\n    eval: evalCommand,\n    cli,\n    tool,\n    repl: replFn,\n    api,\n    help,\n    completion,\n    mcp,\n    serve,\n  };\n}\n"],"mappings":"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"}

package/dist/core/results.d.mts

@@ -0,0 +1,13 @@
+import { PadroneSchema } from "../types/schema.mjs";
+//#region src/core/results.d.ts
+/**
+ * Brands a schema as async, signaling that its `validate()` may return a Promise.
+ * When an async-branded schema is passed to `.arguments()`, `.configFile()`, or `.env()`,
+ * the command's `parse()` and `cli()` will return Promises.
+ */
+declare function asyncSchema<T extends PadroneSchema>(schema: T): T & {
+  '~async': true;
+};
+//#endregion
+export { asyncSchema };
+//# sourceMappingURL=results.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"results.d.mts","names":[],"sources":["../../src/core/results.ts"],"mappings":";;;;;AASA;;iBAAgB,WAAA,WAAsB,aAAA,EAAe,MAAA,EAAQ,CAAA,GAAI,CAAA;EAAM,QAAA;AAAA"}

package/dist/core/results.mjs

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