padrone 1.8.2 → 2.0.0

package/dist/util/dotenv.mjs

@@ -0,0 +1,174 @@
+//#region src/util/dotenv.ts
+/** Returns ordered list of `.env` file names to load (no fs access). */
+function resolveEnvFiles(modes = [], local = true, base = true) {
+	const files = [];
+	if (base) {
+		files.push(".env");
+		if (local) files.push(".env.local");
+	}
+	for (const mode of modes) {
+		files.push(`.env.${mode}`);
+		if (local) files.push(`.env.${mode}.local`);
+	}
+	return files;
+}
+/** Parse a `.env` file string into key-value pairs. */
+function parseEnvFile(content) {
+	const result = {};
+	const lines = content.split("\n");
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i].trim();
+		i++;
+		if (!line || line.startsWith("#")) continue;
+		const stripped = line.startsWith("export ") ? line.slice(7) : line;
+		const eqIndex = stripped.indexOf("=");
+		if (eqIndex === -1) continue;
+		const key = stripped.slice(0, eqIndex).trim();
+		let raw = stripped.slice(eqIndex + 1);
+		const trimmedRaw = raw.trimStart();
+		const quote = trimmedRaw[0];
+		if (quote === "\"" || quote === "'" || quote === "`") {
+			let value = trimmedRaw.slice(1);
+			const closeIndex = findClosingQuote(value, quote);
+			if (closeIndex !== -1) value = value.slice(0, closeIndex);
+			else while (i < lines.length) {
+				const nextLine = lines[i];
+				i++;
+				const ci = findClosingQuote(nextLine, quote);
+				if (ci !== -1) {
+					value += `\n${nextLine.slice(0, ci)}`;
+					break;
+				}
+				value += `\n${nextLine}`;
+			}
+			if (quote === "\"") value = unescapeDoubleQuoted(value);
+			result[key] = value;
+		} else {
+			const commentIndex = raw.indexOf(" #");
+			if (commentIndex !== -1) raw = raw.slice(0, commentIndex);
+			result[key] = raw.trim();
+		}
+	}
+	return result;
+}
+function findClosingQuote(s, quote) {
+	let i = 0;
+	while (i < s.length) {
+		if (s[i] === "\\" && quote === "\"") {
+			i += 2;
+			continue;
+		}
+		if (s[i] === quote) return i;
+		i++;
+	}
+	return -1;
+}
+function unescapeDoubleQuoted(s) {
+	return s.replace(/\\n/g, "\n").replace(/\\r/g, "\r").replace(/\\t/g, "	").replace(/\\"/g, "\"").replace(/\\\\/g, "\\");
+}
+/**
+* Expand `$VAR`, `${VAR}`, `${VAR:-default}`, `${VAR-default}` in a string.
+* Escaped `\$` produces a literal `$`. Undefined variables resolve to `""`.
+*/
+function expandVariables(value, env) {
+	let result = "";
+	let i = 0;
+	while (i < value.length) {
+		if (value[i] === "\\" && value[i + 1] === "$") {
+			result += "$";
+			i += 2;
+			continue;
+		}
+		if (value[i] === "$") {
+			i++;
+			if (i >= value.length) {
+				result += "$";
+				break;
+			}
+			if (value[i] === "{") {
+				i++;
+				const closeIdx = value.indexOf("}", i);
+				if (closeIdx === -1) {
+					result += `\${${value.slice(i)}`;
+					break;
+				}
+				const expr = value.slice(i, closeIdx);
+				i = closeIdx + 1;
+				const colonDashIdx = expr.indexOf(":-");
+				const dashIdx = colonDashIdx === -1 ? expr.indexOf("-") : -1;
+				if (colonDashIdx !== -1) {
+					const varName = expr.slice(0, colonDashIdx);
+					const fallback = expr.slice(colonDashIdx + 2);
+					const val = env[varName];
+					result += val ? val : expandVariables(fallback, env);
+				} else if (dashIdx !== -1) {
+					const varName = expr.slice(0, dashIdx);
+					const fallback = expr.slice(dashIdx + 1);
+					const val = env[varName];
+					result += val !== void 0 ? val : expandVariables(fallback, env);
+				} else result += env[expr] ?? "";
+			} else {
+				let varName = "";
+				while (i < value.length && /[\w]/.test(value[i])) {
+					varName += value[i];
+					i++;
+				}
+				if (varName) result += env[varName] ?? "";
+				else result += "$";
+			}
+			continue;
+		}
+		result += value[i];
+		i++;
+	}
+	return result;
+}
+/**
+* Load and merge `.env` files, returning the combined key-value map.
+* Variable expansion uses the merged file values + process env as lookup.
+*
+* Returns synchronously when `node:fs`/`node:path` are already cached (typical),
+* or a Promise on the very first call.
+*/
+function loadEnvFiles(options, processEnv) {
+	if (typeof process === "undefined") return {};
+	try {
+		if (_fs && _path) return loadEnvFilesSync(_fs, _path, options, processEnv);
+		return initNodeModules().then(() => loadEnvFilesSync(_fs, _path, options, processEnv)).catch(() => ({}));
+	} catch {
+		return {};
+	}
+}
+let _fs;
+let _path;
+async function initNodeModules() {
+	if (_fs && _path) return;
+	_fs = await import("node:fs");
+	_path = await import("node:path");
+}
+if (typeof process !== "undefined") initNodeModules();
+function loadEnvFilesSync(fs, path, options, processEnv) {
+	const dir = options.dir ?? process.cwd();
+	const fileNames = resolveEnvFiles(options.modes, options.local ?? true, options.base ?? true);
+	const merged = {};
+	for (const name of fileNames) {
+		const filePath = path.resolve(dir, name);
+		if (!fs.existsSync(filePath)) continue;
+		const parsed = parseEnvFile(fs.readFileSync(filePath, "utf-8"));
+		Object.assign(merged, parsed);
+	}
+	const lookup = options.override ? {
+		...processEnv,
+		...merged
+	} : {
+		...merged,
+		...processEnv
+	};
+	for (const key of Object.keys(merged)) merged[key] = expandVariables(merged[key], lookup);
+	return merged;
+}
+//#endregion
+export { expandVariables, loadEnvFiles, parseEnvFile, resolveEnvFiles };
+
+//# sourceMappingURL=dotenv.mjs.map

package/dist/util/dotenv.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"dotenv.mjs","names":[],"sources":["../../src/util/dotenv.ts"],"sourcesContent":["// ── File resolution ─────────────────────────────────────────────────────\n\n/** Returns ordered list of `.env` file names to load (no fs access). */\nexport function resolveEnvFiles(modes: string[] = [], local = true, base = true): string[] {\n  const files: string[] = [];\n  if (base) {\n    files.push('.env');\n    if (local) files.push('.env.local');\n  }\n  for (const mode of modes) {\n    files.push(`.env.${mode}`);\n    if (local) files.push(`.env.${mode}.local`);\n  }\n  return files;\n}\n\n// ── Parser ──────────────────────────────────────────────────────────────\n\n/** Parse a `.env` file string into key-value pairs. */\nexport function parseEnvFile(content: string): Record<string, string> {\n  const result: Record<string, string> = {};\n  const lines = content.split('\\n');\n  let i = 0;\n\n  while (i < lines.length) {\n    const line = lines[i]!.trim();\n    i++;\n\n    // Skip empty lines and comments\n    if (!line || line.startsWith('#')) continue;\n\n    // Strip optional `export ` prefix\n    const stripped = line.startsWith('export ') ? line.slice(7) : line;\n\n    const eqIndex = stripped.indexOf('=');\n    if (eqIndex === -1) continue;\n\n    const key = stripped.slice(0, eqIndex).trim();\n    let raw = stripped.slice(eqIndex + 1);\n\n    // Detect quoted values\n    const trimmedRaw = raw.trimStart();\n    const quote = trimmedRaw[0];\n\n    if (quote === '\"' || quote === \"'\" || quote === '`') {\n      let value = trimmedRaw.slice(1);\n\n      // Check for closing quote on the same line\n      const closeIndex = findClosingQuote(value, quote);\n      if (closeIndex !== -1) {\n        value = value.slice(0, closeIndex);\n      } else {\n        // Multiline: accumulate until closing quote\n        while (i < lines.length) {\n          const nextLine = lines[i]!;\n          i++;\n          const ci = findClosingQuote(nextLine, quote);\n          if (ci !== -1) {\n            value += `\\n${nextLine.slice(0, ci)}`;\n            break;\n          }\n          value += `\\n${nextLine}`;\n        }\n      }\n\n      if (quote === '\"') value = unescapeDoubleQuoted(value);\n      result[key] = value;\n    } else {\n      // Unquoted: strip inline comments, trim\n      const commentIndex = raw.indexOf(' #');\n      if (commentIndex !== -1) raw = raw.slice(0, commentIndex);\n      result[key] = raw.trim();\n    }\n  }\n\n  return result;\n}\n\nfunction findClosingQuote(s: string, quote: string): number {\n  let i = 0;\n  while (i < s.length) {\n    if (s[i] === '\\\\' && quote === '\"') {\n      i += 2; // skip escaped char\n      continue;\n    }\n    if (s[i] === quote) return i;\n    i++;\n  }\n  return -1;\n}\n\nfunction unescapeDoubleQuoted(s: string): string {\n  return s.replace(/\\\\n/g, '\\n').replace(/\\\\r/g, '\\r').replace(/\\\\t/g, '\\t').replace(/\\\\\"/g, '\"').replace(/\\\\\\\\/g, '\\\\');\n}\n\n// ── Variable expansion ──────────────────────────────────────────────────\n\n/**\n * Expand `$VAR`, `${VAR}`, `${VAR:-default}`, `${VAR-default}` in a string.\n * Escaped `\\$` produces a literal `$`. Undefined variables resolve to `\"\"`.\n */\nexport function expandVariables(value: string, env: Record<string, string | undefined>): string {\n  let result = '';\n  let i = 0;\n\n  while (i < value.length) {\n    if (value[i] === '\\\\' && value[i + 1] === '$') {\n      result += '$';\n      i += 2;\n      continue;\n    }\n\n    if (value[i] === '$') {\n      i++;\n      if (i >= value.length) {\n        result += '$';\n        break;\n      }\n\n      if (value[i] === '{') {\n        // ${VAR}, ${VAR:-default}, ${VAR-default}\n        i++;\n        const closeIdx = value.indexOf('}', i);\n        if (closeIdx === -1) {\n          result += `\\${${value.slice(i)}`;\n          break;\n        }\n\n        const expr = value.slice(i, closeIdx);\n        i = closeIdx + 1;\n\n        const colonDashIdx = expr.indexOf(':-');\n        const dashIdx = colonDashIdx === -1 ? expr.indexOf('-') : -1;\n\n        if (colonDashIdx !== -1) {\n          // ${VAR:-default} — use default if unset or empty\n          const varName = expr.slice(0, colonDashIdx);\n          const fallback = expr.slice(colonDashIdx + 2);\n          const val = env[varName];\n          result += val ? val : expandVariables(fallback, env);\n        } else if (dashIdx !== -1) {\n          // ${VAR-default} — use default only if unset\n          const varName = expr.slice(0, dashIdx);\n          const fallback = expr.slice(dashIdx + 1);\n          const val = env[varName];\n          result += val !== undefined ? val : expandVariables(fallback, env);\n        } else {\n          result += env[expr] ?? '';\n        }\n      } else {\n        // $VAR — collect word chars\n        let varName = '';\n        while (i < value.length && /[\\w]/.test(value[i]!)) {\n          varName += value[i];\n          i++;\n        }\n        if (varName) {\n          result += env[varName] ?? '';\n        } else {\n          result += '$';\n        }\n      }\n      continue;\n    }\n\n    result += value[i];\n    i++;\n  }\n\n  return result;\n}\n\n// ── File loading ────────────────────────────────────────────────────────\n\nexport type LoadEnvFilesOptions = {\n  dir?: string;\n  modes?: string[];\n  local?: boolean;\n  override?: boolean;\n  base?: boolean;\n};\n\n/**\n * Load and merge `.env` files, returning the combined key-value map.\n * Variable expansion uses the merged file values + process env as lookup.\n *\n * Returns synchronously when `node:fs`/`node:path` are already cached (typical),\n * or a Promise on the very first call.\n */\nexport function loadEnvFiles(\n  options: LoadEnvFilesOptions,\n  processEnv: Record<string, string | undefined>,\n): Record<string, string> | Promise<Record<string, string>> {\n  if (typeof process === 'undefined') return {};\n\n  try {\n    if (_fs && _path) return loadEnvFilesSync(_fs, _path, options, processEnv);\n    return initNodeModules()\n      .then(() => loadEnvFilesSync(_fs!, _path!, options, processEnv))\n      .catch(() => ({}) as Record<string, string>);\n  } catch {\n    return {};\n  }\n}\n\n// ── Internals ───────────────────────────────────────────────────────────\n\nlet _fs: typeof import('node:fs') | undefined;\nlet _path: typeof import('node:path') | undefined;\n\nasync function initNodeModules(): Promise<void> {\n  if (_fs && _path) return;\n  _fs = await import('node:fs');\n  _path = await import('node:path');\n}\n\nif (typeof process !== 'undefined') initNodeModules();\n\nfunction loadEnvFilesSync(\n  fs: typeof import('node:fs'),\n  path: typeof import('node:path'),\n  options: LoadEnvFilesOptions,\n  processEnv: Record<string, string | undefined>,\n): Record<string, string> {\n  const dir = options.dir ?? process.cwd();\n  const fileNames = resolveEnvFiles(options.modes, options.local ?? true, options.base ?? true);\n  const merged: Record<string, string> = {};\n\n  for (const name of fileNames) {\n    const filePath = path.resolve(dir, name);\n    if (!fs.existsSync(filePath)) continue;\n    const content = fs.readFileSync(filePath, 'utf-8');\n    const parsed = parseEnvFile(content);\n    Object.assign(merged, parsed);\n  }\n\n  // Expand variables: file values + processEnv as lookup (processEnv wins in lookup unless override)\n  const lookup = options.override ? { ...processEnv, ...merged } : { ...merged, ...processEnv };\n  for (const key of Object.keys(merged)) {\n    merged[key] = expandVariables(merged[key]!, lookup);\n  }\n\n  return merged;\n}\n"],"mappings":"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"}

package/dist/util/shell-utils.mjs

@@ -0,0 +1,80 @@
+//#region src/util/shell-utils.ts
+/**
+* Convert a camelCase string to kebab-case.
+* Returns null if the string has no uppercase letters (no conversion needed).
+*/
+function camelToKebab(str) {
+	if (!/[A-Z]/.test(str)) return null;
+	return str.replace(/[A-Z]/g, (ch) => `-${ch.toLowerCase()}`);
+}
+/**
+* Detects the current shell from environment variables and process info.
+* @returns The detected shell type, or undefined if unknown
+*/
+async 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 ppid = process.ppid;
+		if (ppid) {
+			const { execSync } = await import("node:child_process");
+			const processName = execSync(`ps -p ${ppid} -o comm=`, {
+				encoding: "utf-8",
+				stdio: [
+					"pipe",
+					"pipe",
+					"ignore"
+				]
+			}).trim();
+			if (processName.includes("zsh")) return "zsh";
+			if (processName.includes("bash")) return "bash";
+			if (processName.includes("fish")) return "fish";
+		}
+	} catch {}
+}
+async function getRcFile(shell, home) {
+	const { homedir } = await import("node:os");
+	const { join } = await import("node:path");
+	const h = home ?? homedir();
+	switch (shell) {
+		case "bash": return join(h, ".bashrc");
+		case "zsh": return join(h, ".zshrc");
+		case "fish": return join(h, ".config", "fish", "config.fish");
+		case "powershell": return (typeof process !== "undefined" ? process.env.PROFILE : void 0) || join(h, "Documents", "PowerShell", "Microsoft.PowerShell_profile.ps1");
+		default: return null;
+	}
+}
+function escapeRegExp(str) {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+* Writes a snippet to a shell config file using begin/end markers for idempotency.
+* If a block with the same begin marker exists, it is replaced. Otherwise the snippet is appended.
+*/
+async function writeToRcFile(rcFile, snippet, beginMarker, endMarker) {
+	const { existsSync, mkdirSync, readFileSync, writeFileSync } = await import("node:fs");
+	const { dirname } = await import("node:path");
+	const existing = existsSync(rcFile) ? readFileSync(rcFile, "utf-8") : "";
+	if (existing.includes(beginMarker)) {
+		const pattern = new RegExp(`${escapeRegExp(beginMarker)}[\\s\\S]*?${escapeRegExp(endMarker)}`);
+		writeFileSync(rcFile, existing.replace(pattern, snippet));
+		return {
+			file: rcFile,
+			updated: true
+		};
+	}
+	mkdirSync(dirname(rcFile), { recursive: true });
+	writeFileSync(rcFile, `${existing}${existing.length > 0 && !existing.endsWith("\n") ? "\n" : ""}\n${snippet}\n`);
+	return {
+		file: rcFile,
+		updated: false
+	};
+}
+//#endregion
+export { camelToKebab, detectShell, escapeRegExp, getRcFile, writeToRcFile };
+
+//# sourceMappingURL=shell-utils.mjs.map

package/dist/util/shell-utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-utils.mjs","names":[],"sources":["../../src/util/shell-utils.ts"],"sourcesContent":["/**\n * Convert a camelCase string to kebab-case.\n * Returns null if the string has no uppercase letters (no conversion needed).\n */\nexport function camelToKebab(str: string): string | null {\n  if (!/[A-Z]/.test(str)) return null;\n  return str.replace(/[A-Z]/g, (ch) => `-${ch.toLowerCase()}`);\n}\n\nexport type ShellType = 'bash' | 'zsh' | 'fish' | 'powershell';\n\n/**\n * Detects the current shell from environment variables and process info.\n * @returns The detected shell type, or undefined if unknown\n */\nexport async function detectShell(): Promise<ShellType | undefined> {\n  if (typeof process === 'undefined') return undefined;\n\n  // Method 1: Check SHELL environment variable (most common)\n  const shellEnv = process.env.SHELL || '';\n  if (shellEnv.includes('zsh')) return 'zsh';\n  if (shellEnv.includes('bash')) return 'bash';\n  if (shellEnv.includes('fish')) return 'fish';\n\n  // Method 2: Check Windows-specific shells\n  if (process.env.PSModulePath || process.env.POWERSHELL_DISTRIBUTION_CHANNEL) {\n    return 'powershell';\n  }\n\n  // Method 3: Check parent process on Unix-like systems\n  try {\n    const ppid = process.ppid;\n    if (ppid) {\n      const { execSync } = (await import('node:child_process')) as typeof import('node:child_process');\n      const processName = execSync(`ps -p ${ppid} -o comm=`, {\n        encoding: 'utf-8',\n        stdio: ['pipe', 'pipe', 'ignore'],\n      }).trim();\n\n      if (processName.includes('zsh')) return 'zsh';\n      if (processName.includes('bash')) return 'bash';\n      if (processName.includes('fish')) return 'fish';\n    }\n  } catch {\n    // Ignore errors (e.g., ps not available)\n  }\n\n  return undefined;\n}\n\nexport async function getRcFile(shell: ShellType, home?: string): Promise<string | null> {\n  const { homedir } = await import('node:os');\n  const { join } = await import('node:path');\n  const h = home ?? homedir();\n  switch (shell) {\n    case 'bash':\n      return join(h, '.bashrc');\n    case 'zsh':\n      return join(h, '.zshrc');\n    case 'fish':\n      return join(h, '.config', 'fish', 'config.fish');\n    case 'powershell':\n      return (\n        (typeof process !== 'undefined' ? process.env.PROFILE : undefined) ||\n        join(h, 'Documents', 'PowerShell', 'Microsoft.PowerShell_profile.ps1')\n      );\n    default:\n      return null;\n  }\n}\n\nexport function escapeRegExp(str: string): string {\n  return str.replace(/[.*+?^${}()|[\\]\\\\]/g, '\\\\$&');\n}\n\n/**\n * Writes a snippet to a shell config file using begin/end markers for idempotency.\n * If a block with the same begin marker exists, it is replaced. Otherwise the snippet is appended.\n */\nexport async function writeToRcFile(\n  rcFile: string,\n  snippet: string,\n  beginMarker: string,\n  endMarker: string,\n): Promise<{ file: string; updated: boolean }> {\n  const { existsSync, mkdirSync, readFileSync, writeFileSync } = await import('node:fs');\n  const { dirname } = await import('node:path');\n  const existing = existsSync(rcFile) ? readFileSync(rcFile, 'utf-8') : '';\n\n  if (existing.includes(beginMarker)) {\n    const pattern = new RegExp(`${escapeRegExp(beginMarker)}[\\\\s\\\\S]*?${escapeRegExp(endMarker)}`);\n    writeFileSync(rcFile, existing.replace(pattern, snippet));\n    return { file: rcFile, updated: true };\n  }\n\n  mkdirSync(dirname(rcFile), { recursive: true });\n  const separator = existing.length > 0 && !existing.endsWith('\\n') ? '\\n' : '';\n  writeFileSync(rcFile, `${existing}${separator}\\n${snippet}\\n`);\n  return { file: rcFile, updated: false };\n}\n"],"mappings":";;;;;AAIA,SAAgB,aAAa,KAA4B;CACvD,IAAI,CAAC,QAAQ,KAAK,GAAG,GAAG,OAAO;CAC/B,OAAO,IAAI,QAAQ,WAAW,OAAO,IAAI,GAAG,YAAY,GAAG;AAC7D;;;;;AAQA,eAAsB,cAA8C;CAClE,IAAI,OAAO,YAAY,aAAa,OAAO,KAAA;CAG3C,MAAM,WAAW,QAAQ,IAAI,SAAS;CACtC,IAAI,SAAS,SAAS,KAAK,GAAG,OAAO;CACrC,IAAI,SAAS,SAAS,MAAM,GAAG,OAAO;CACtC,IAAI,SAAS,SAAS,MAAM,GAAG,OAAO;CAGtC,IAAI,QAAQ,IAAI,gBAAgB,QAAQ,IAAI,iCAC1C,OAAO;CAIT,IAAI;EACF,MAAM,OAAO,QAAQ;EACrB,IAAI,MAAM;GACR,MAAM,EAAE,aAAc,MAAM,OAAO;GACnC,MAAM,cAAc,SAAS,SAAS,KAAK,YAAY;IACrD,UAAU;IACV,OAAO;KAAC;KAAQ;KAAQ;IAAQ;GAClC,CAAC,CAAC,CAAC,KAAK;GAER,IAAI,YAAY,SAAS,KAAK,GAAG,OAAO;GACxC,IAAI,YAAY,SAAS,MAAM,GAAG,OAAO;GACzC,IAAI,YAAY,SAAS,MAAM,GAAG,OAAO;EAC3C;CACF,QAAQ,CAER;AAGF;AAEA,eAAsB,UAAU,OAAkB,MAAuC;CACvF,MAAM,EAAE,YAAY,MAAM,OAAO;CACjC,MAAM,EAAE,SAAS,MAAM,OAAO;CAC9B,MAAM,IAAI,QAAQ,QAAQ;CAC1B,QAAQ,OAAR;EACE,KAAK,QACH,OAAO,KAAK,GAAG,SAAS;EAC1B,KAAK,OACH,OAAO,KAAK,GAAG,QAAQ;EACzB,KAAK,QACH,OAAO,KAAK,GAAG,WAAW,QAAQ,aAAa;EACjD,KAAK,cACH,QACG,OAAO,YAAY,cAAc,QAAQ,IAAI,UAAU,KAAA,MACxD,KAAK,GAAG,aAAa,cAAc,kCAAkC;EAEzE,SACE,OAAO;CACX;AACF;AAEA,SAAgB,aAAa,KAAqB;CAChD,OAAO,IAAI,QAAQ,uBAAuB,MAAM;AAClD;;;;;AAMA,eAAsB,cACpB,QACA,SACA,aACA,WAC6C;CAC7C,MAAM,EAAE,YAAY,WAAW,cAAc,kBAAkB,MAAM,OAAO;CAC5E,MAAM,EAAE,YAAY,MAAM,OAAO;CACjC,MAAM,WAAW,WAAW,MAAM,IAAI,aAAa,QAAQ,OAAO,IAAI;CAEtE,IAAI,SAAS,SAAS,WAAW,GAAG;EAClC,MAAM,UAAU,IAAI,OAAO,GAAG,aAAa,WAAW,EAAE,YAAY,aAAa,SAAS,GAAG;EAC7F,cAAc,QAAQ,SAAS,QAAQ,SAAS,OAAO,CAAC;EACxD,OAAO;GAAE,MAAM;GAAQ,SAAS;EAAK;CACvC;CAEA,UAAU,QAAQ,MAAM,GAAG,EAAE,WAAW,KAAK,CAAC;CAE9C,cAAc,QAAQ,GAAG,WADP,SAAS,SAAS,KAAK,CAAC,SAAS,SAAS,IAAI,IAAI,OAAO,GAC7B,IAAI,QAAQ,GAAG;CAC7D,OAAO;EAAE,MAAM;EAAQ,SAAS;CAAM;AACxC"}

package/dist/util/stream.d.mts

@@ -0,0 +1,33 @@
+import { PadroneSchema } from "../types/schema.mjs";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/util/stream.d.ts
+interface AsyncStreamMeta {
+  [x: string]: unknown;
+  readonly asyncStream: number;
+  readonly itemSchema?: StandardSchemaV1;
+}
+/**
+ * Returns metadata to mark a schema field as an async stream via `.meta()`.
+ *
+ * When used with `stdin`, padrone pipes stdin data as an `AsyncIterable` instead of
+ * buffering it. Each line is validated against the item schema (if provided) as it arrives.
+ *
+ * @param itemSchema - Optional item schema for per-item validation.
+ *   Non-string schemas cause each stdin line to be `JSON.parse`'d before validation.
+ *
+ * @example
+ * ```ts
+ * import { asyncStream } from 'padrone';
+ *
+ * // String lines
+ * z.object({ lines: z.custom<AsyncIterable<string>>().meta(asyncStream()) })
+ *
+ * // Typed items — each line JSON.parse'd and validated
+ * z.object({ records: z.custom<AsyncIterable<{ name: string }>>().meta(asyncStream(recordSchema)) })
+ * ```
+ */
+declare function asyncStream<T = string>(itemSchema?: PadroneSchema<T>): AsyncStreamMeta;
+//#endregion
+export { AsyncStreamMeta, asyncStream };
+//# sourceMappingURL=stream.d.mts.map

package/dist/util/stream.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.d.mts","names":[],"sources":["../../src/util/stream.ts"],"mappings":";;;;UAGiB,eAAA;EAAA,CACd,CAAA;EAAA,SACQ,WAAA;EAAA,SACA,UAAA,GAAa,gBAAgB;AAAA;;;;;;;AAAA;AA0BxC;;;;;;;;;;;;;iBAAgB,WAAA,aAAwB,UAAA,GAAa,aAAA,CAAc,CAAA,IAAK,eAAA"}

package/dist/{stream-DC4H8YTx.mjs → util/stream.mjs}

@@ -72,6 +72,6 @@ async function readStreamAsText(stream) {
 	return textDecoder.decode(concatBytes(chunks));
 }
 //#endregion
-export { readStreamAsText as a, createStdinStream as i, asyncStreamRegistry as n, concatBytes as r, asyncStream as t };
+export { asyncStream, asyncStreamRegistry, concatBytes, createStdinStream, readStreamAsText };
 
-//# sourceMappingURL=stream-DC4H8YTx.mjs.map
+//# sourceMappingURL=stream.mjs.map

package/dist/util/stream.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream.mjs","names":[],"sources":["../../src/util/stream.ts"],"sourcesContent":["import type { StandardSchemaV1 } from '@standard-schema/spec';\nimport type { PadroneSchema } from '../types/index.ts';\n\nexport interface AsyncStreamMeta {\n  [x: string]: unknown;\n  readonly asyncStream: number;\n  readonly itemSchema?: StandardSchemaV1;\n}\n\nlet asyncStreamIdCounter = 1;\nexport const asyncStreamRegistry = new Map<number, AsyncStreamMeta>();\n\n/**\n * Returns metadata to mark a schema field as an async stream via `.meta()`.\n *\n * When used with `stdin`, padrone pipes stdin data as an `AsyncIterable` instead of\n * buffering it. Each line is validated against the item schema (if provided) as it arrives.\n *\n * @param itemSchema - Optional item schema for per-item validation.\n *   Non-string schemas cause each stdin line to be `JSON.parse`'d before validation.\n *\n * @example\n * ```ts\n * import { asyncStream } from 'padrone';\n *\n * // String lines\n * z.object({ lines: z.custom<AsyncIterable<string>>().meta(asyncStream()) })\n *\n * // Typed items — each line JSON.parse'd and validated\n * z.object({ records: z.custom<AsyncIterable<{ name: string }>>().meta(asyncStream(recordSchema)) })\n * ```\n */\nexport function asyncStream<T = string>(itemSchema?: PadroneSchema<T>): AsyncStreamMeta {\n  const id = asyncStreamIdCounter++;\n  const meta: AsyncStreamMeta = itemSchema ? { asyncStream: id, itemSchema } : { asyncStream: id };\n  asyncStreamRegistry.set(id, meta);\n  return meta;\n}\n\n/** Stdin interface matching PadroneRuntime.stdin */\ninterface StdinSource {\n  isTTY?: boolean;\n  text(): Promise<string>;\n  lines(): AsyncIterable<string>;\n}\n\n/**\n * Creates an `AsyncIterable` from a stdin source, optionally validating each item.\n * When no stdin is available (TTY / undefined), yields nothing.\n *\n * - No item schema: yields raw string lines\n * - With item schema: `JSON.parse`s each line, validates, then yields\n */\nexport function createStdinStream(stdin: StdinSource | undefined, itemSchema?: StandardSchemaV1): AsyncIterable<unknown> {\n  if (!stdin) return emptyAsyncIterable;\n\n  if (!itemSchema) return stdin.lines();\n\n  return {\n    async *[Symbol.asyncIterator]() {\n      for await (const line of stdin.lines()) {\n        const result = itemSchema['~standard'].validate(line);\n        const resolved = result instanceof Promise ? await result : result;\n        if ('issues' in resolved && resolved.issues) {\n          throw new Error(`Stream item validation failed: ${resolved.issues.map((i) => i.message).join(', ')}`);\n        }\n        yield (resolved as { value: unknown }).value;\n      }\n    },\n  };\n}\n\nconst emptyAsyncIterable: AsyncIterable<never> = {\n  async *[Symbol.asyncIterator]() {},\n};\n\nconst textEncoder = /* @__PURE__ */ new TextEncoder();\nconst textDecoder = /* @__PURE__ */ new TextDecoder();\n\n/** Concatenate multiple `Uint8Array` chunks into a single array. */\nexport function concatBytes(chunks: Uint8Array[]): Uint8Array {\n  if (chunks.length === 1) return chunks[0]!;\n  let totalLength = 0;\n  for (const chunk of chunks) totalLength += chunk.byteLength;\n  const result = new Uint8Array(totalLength);\n  let offset = 0;\n  for (const chunk of chunks) {\n    result.set(chunk, offset);\n    offset += chunk.byteLength;\n  }\n  return result;\n}\n\n/** Read an async iterable of chunks into a UTF-8 string. */\nexport async function readStreamAsText(stream: AsyncIterable<Uint8Array | string>): Promise<string> {\n  const chunks: Uint8Array[] = [];\n  for await (const chunk of stream) {\n    chunks.push(typeof chunk === 'string' ? textEncoder.encode(chunk) : chunk);\n  }\n  return textDecoder.decode(concatBytes(chunks));\n}\n"],"mappings":";AASA,IAAI,uBAAuB;AAC3B,MAAa,sCAAsB,IAAI,IAA6B;;;;;;;;;;;;;;;;;;;;;AAsBpE,SAAgB,YAAwB,YAAgD;CACtF,MAAM,KAAK;CACX,MAAM,OAAwB,aAAa;EAAE,aAAa;EAAI;CAAW,IAAI,EAAE,aAAa,GAAG;CAC/F,oBAAoB,IAAI,IAAI,IAAI;CAChC,OAAO;AACT;;;;;;;;AAgBA,SAAgB,kBAAkB,OAAgC,YAAuD;CACvH,IAAI,CAAC,OAAO,OAAO;CAEnB,IAAI,CAAC,YAAY,OAAO,MAAM,MAAM;CAEpC,OAAO,EACL,QAAQ,OAAO,iBAAiB;EAC9B,WAAW,MAAM,QAAQ,MAAM,MAAM,GAAG;GACtC,MAAM,SAAS,WAAW,YAAY,CAAC,SAAS,IAAI;GACpD,MAAM,WAAW,kBAAkB,UAAU,MAAM,SAAS;GAC5D,IAAI,YAAY,YAAY,SAAS,QACnC,MAAM,IAAI,MAAM,kCAAkC,SAAS,OAAO,KAAK,MAAM,EAAE,OAAO,CAAC,CAAC,KAAK,IAAI,GAAG;GAEtG,MAAO,SAAgC;EACzC;CACF,EACF;AACF;AAEA,MAAM,qBAA2C,EAC/C,QAAQ,OAAO,iBAAiB,CAAC,EACnC;AAEA,MAAM,8BAA8B,IAAI,YAAY;AACpD,MAAM,8BAA8B,IAAI,YAAY;;AAGpD,SAAgB,YAAY,QAAkC;CAC5D,IAAI,OAAO,WAAW,GAAG,OAAO,OAAO;CACvC,IAAI,cAAc;CAClB,KAAK,MAAM,SAAS,QAAQ,eAAe,MAAM;CACjD,MAAM,SAAS,IAAI,WAAW,WAAW;CACzC,IAAI,SAAS;CACb,KAAK,MAAM,SAAS,QAAQ;EAC1B,OAAO,IAAI,OAAO,MAAM;EACxB,UAAU,MAAM;CAClB;CACA,OAAO;AACT;;AAGA,eAAsB,iBAAiB,QAA6D;CAClG,MAAM,SAAuB,CAAC;CAC9B,WAAW,MAAM,SAAS,QACxB,OAAO,KAAK,OAAO,UAAU,WAAW,YAAY,OAAO,KAAK,IAAI,KAAK;CAE3E,OAAO,YAAY,OAAO,YAAY,MAAM,CAAC;AAC/C"}

package/dist/util/type-helpers.d.mts

@@ -0,0 +1,74 @@
+import { PickCommandByName, PossibleCommands } from "./type-utils.mjs";
+import { PadroneContextInterceptor, PadroneInterceptorFn } from "../types/interceptor.mjs";
+import { AnyPadroneCommand, PadroneCommand } from "../types/command.mjs";
+import { AnyPadroneProgram } from "../types/builder.mjs";
+//#region src/util/type-helpers.d.ts
+/**
+ * Extracts the input type of the arguments schema from a command.
+ * @example
+ * ```ts
+ * type Args = InferArgsInput<typeof myCommand>;
+ * ```
+ */
+type InferArgsInput<T extends AnyPadroneCommand> = T['~types']['argsInput'];
+/**
+ * Extracts the output type of the arguments schema from a command.
+ * @example
+ * ```ts
+ * type Args = InferArgsOutput<typeof myCommand>;
+ * ```
+ */
+type InferArgsOutput<T extends AnyPadroneCommand> = T['~types']['argsOutput'];
+/**
+ * Extracts the user-defined context type from a command (excludes interceptor-provided context).
+ * @example
+ * ```ts
+ * type Ctx = InferContext<typeof myCommand>;
+ * ```
+ */
+type InferContext<T extends AnyPadroneCommand> = T['~types']['context'];
+/**
+ * Extracts the interceptor-provided context type from a command.
+ * @example
+ * ```ts
+ * type Provided = InferContextProvided<typeof myCommand>;
+ * ```
+ */
+type InferContextProvided<T extends AnyPadroneCommand> = T['~types']['contextProvided'];
+/**
+ * Extracts the context type that a context-providing interceptor injects.
+ * @example
+ * ```ts
+ * type AuthCtx = InferInterceptorContext<typeof withAuth>;
+ * ```
+ */
+type InferInterceptorContext<T extends PadroneContextInterceptor<any>> = T['~context'];
+/**
+ * Extracts the required context type from an interceptor with `.requires()`.
+ * @example
+ * ```ts
+ * type Requires = InferInterceptorRequires<typeof withAuth>;
+ * ```
+ */
+type InferInterceptorRequires<T extends PadroneInterceptorFn & {
+  '~contextRequires': any;
+}> = T['~contextRequires'] extends ((ctx: infer R) => void) ? R : unknown;
+/**
+ * Gets a command type by its path from a program or command tree.
+ * Supports both full paths (e.g., "config set") and alias paths.
+ * @example
+ * ```ts
+ * const program = createPadrone('cli')
+ *   .command('config', c => c
+ *     .command('set', c => c.arguments(...).action(...))
+ *     .command('get', c => c.arguments(...).action(...))
+ *   );
+ *
+ * type SetCommand = InferCommand<typeof program, 'config set'>;
+ * type GetCommand = InferCommand<typeof program, 'config get'>;
+ * ```
+ */
+type InferCommand<T extends AnyPadroneCommand | AnyPadroneProgram, TPath extends PossibleCommands<T extends AnyPadroneCommand ? [T] : T['~types']['commands'], true, true>> = T extends AnyPadroneProgram ? PickCommandByName<[PadroneCommand<'', '', any, any, T['~types']['commands']>], TPath> : T extends AnyPadroneCommand ? PickCommandByName<[T], TPath> : never;
+//#endregion
+export { InferArgsInput, InferArgsOutput, InferCommand, InferContext, InferContextProvided, InferInterceptorContext, InferInterceptorRequires };
+//# sourceMappingURL=type-helpers.d.mts.map

package/dist/util/type-helpers.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-helpers.d.mts","names":[],"sources":["../../src/util/type-helpers.ts"],"mappings":";;;;;;;;;;AAgBA;;KAAY,cAAA,WAAyB,iBAAA,IAAqB,CAAC;;;;;;AAAA;AAS3D;KAAY,eAAA,WAA0B,iBAAA,IAAqB,CAAC;;;;;;;AAAA;KAShD,YAAA,WAAuB,iBAAA,IAAqB,CAAC;;;;;;;;KAS7C,oBAAA,WAA+B,iBAAA,IAAqB,CAAC;AAAjE;;;;;;;AAAA,KASY,uBAAA,WAAkC,yBAAA,SAAkC,CAAC;AAThB;AASjE;;;;;;AATiE,KAkBrD,wBAAA,WAAmC,oBAAA;EAAyB,kBAAA;AAAA,KAA6B,CAAC,+BACpG,GAAA,sBAEE,CAAA;AAHJ;;;;;;;;;;;;AAGK;AAkBL;;AArBA,KAqBY,YAAA,WACA,iBAAA,GAAoB,iBAAA,gBAChB,gBAAA,CAAiB,CAAA,SAAU,iBAAA,IAAqB,CAAA,IAAK,CAAA,uCACjE,CAAA,SAAU,iBAAA,GACV,iBAAA,EAAmB,cAAA,mBAAiC,CAAA,0BAA2B,KAAA,IAC/E,CAAA,SAAU,iBAAA,GACR,iBAAA,EAAmB,CAAA,GAAI,KAAA"}

package/dist/util/type-utils.d.mts

@@ -0,0 +1,186 @@
+import { PadroneSchema } from "../types/schema.mjs";
+import { AnyPadroneCommand, PadroneCommand } from "../types/command.mjs";
+import { PadroneBuilder, PadroneProgram } from "../types/builder.mjs";
+//#region src/util/type-utils.d.ts
+type SafeString = string & {};
+type IsUnknown<T> = unknown extends T ? true : false;
+type IsAny<T> = any extends T ? true : false;
+type IsNever<T> = [T] extends [never] ? true : false;
+type IsGeneric<T> = IsAny<T> extends true ? true : IsUnknown<T> extends true ? true : IsNever<T> extends true ? true : false;
+/**
+ * Detects whether a schema has been branded as async via the `'~async'` property.
+ * Standard Schema V1's `validate()` always types its return as `Result | Promise<Result>`
+ * regardless of whether the schema is actually async, so we rely on an explicit brand instead.
+ *
+ * Use `asyncSchema(schema)` to brand a schema, or check for the `{ '~async': true }` property.
+ */
+type IsAsyncSchema<T> = IsAny<T> extends true ? false : T extends {
+  '~async': true;
+} ? true : false;
+/**
+ * Computes the new TAsync flag when a schema is added to a builder.
+ * Once TAsync is `true`, it stays `true`. Otherwise, checks if the new schema is branded async.
+ */
+type OrAsync<TExisting extends boolean, TSchema> = TExisting extends true ? true : IsAsyncSchema<TSchema> extends true ? true : false;
+/**
+ * Detects whether argument meta contains interactive or optionalInteractive configuration.
+ * When either is `true` or a `string[]`, the command requires async execution for prompting.
+ */
+type HasInteractive<TMeta> = TMeta extends {
+  interactive: true | readonly string[];
+} ? true : TMeta extends {
+  optionalInteractive: true | readonly string[];
+} ? true : false;
+/**
+ * Combines schema-level async detection with meta-level interactive detection.
+ * Returns `true` if the existing async flag is set, the schema is branded async, or the meta has interactive fields.
+ */
+type OrAsyncMeta<TExisting extends boolean, TMeta> = TExisting extends true ? true : HasInteractive<TMeta> extends true ? true : false;
+/**
+ * Unwraps a result type by resolving Promises and collecting iterables into arrays.
+ * - `AsyncIterable<U>` → `U[]`
+ * - `Iterable<U>` (excluding strings) → `U[]`
+ * - `Promise<U>` → `Drained<U>` (recursively unwraps)
+ * - `T` → `T`
+ */
+type Drained<T> = T extends Promise<infer U> ? Drained<U> : T extends AsyncIterable<infer U> ? U[] : T extends string ? T : T extends Iterable<infer U> ? U[] : T;
+/**
+ * A sync value augmented with Promise-like methods (.then, .catch, .finally).
+ * Unlike a real Promise, properties of T are accessible synchronously.
+ */
+type Thenable<T> = T & PromiseLike<T> & {
+  catch: Promise<T>['catch'];
+  finally: Promise<T>['finally'];
+};
+/**
+ * Conditionally wraps a type in Promise based on the TAsync flag.
+ * - `true` → `Promise<T>`
+ * - `false` → `T & Thenable<T>` (thenable: supports `.then()`, `.catch()`, `.finally()`, and `await`)
+ * - `boolean` (union of true|false) → `Promise<T>` (safe default when async-ness is uncertain)
+ * - `any` → `T` (for generic/any typed commands like AnyPadroneCommand)
+ */
+type MaybePromise<T, TAsync> = IsAny<TAsync> extends true ? T : true extends TAsync ? Promise<T> : Thenable<T>;
+type SplitString<TName extends string, TSplitBy extends string = ' '> = TName extends `${infer FirstPart}${TSplitBy}${infer RestParts}` ? [FirstPart, ...SplitString<RestParts, TSplitBy>] : [TName];
+type JoinString<TParts extends string[], TJoinBy extends string = ' '> = TParts extends [infer FirstPart extends string, ...infer RestParts extends string[]] ? RestParts extends [] ? FirstPart : `${FirstPart}${TJoinBy}${JoinString<RestParts, TJoinBy>}` : TParts extends [] ? '' : TParts[number];
+type SplitLastSpace<S extends string> = SplitString<S> extends [...infer Init extends string[], infer Last extends string] ? Init extends [] ? [S, never] : [JoinString<Init>, Last] : [S, never];
+type AnyPartExtends<U, T> = [U] extends [never] ? false : U extends any ? (U extends T ? true : never) : never extends true ? true : false;
+type FullCommandName<TName extends string, TParentName extends string = ''> = TParentName extends '' ? TName : `${TParentName} ${TName}`;
+/**
+ * Generate full alias paths by combining parent path with each alias.
+ */
+type FullAliasPaths<TAliases extends string[], TParentName extends string = ''> = TAliases extends [infer First extends string, ...infer Rest extends string[]] ? FullCommandName<First, TParentName> | FullAliasPaths<Rest, TParentName> : never;
+/**
+ * Get all paths for a command including its primary path and all alias paths.
+ */
+type GetCommandPathsAndAliases<TCommand extends AnyPadroneCommand> = TCommand['~types']['path'] extends infer Path extends string ? TCommand['~types']['aliases'] extends infer Aliases extends string[] ? TCommand['~types']['parentName'] extends infer ParentName extends string ? Path | FullAliasPaths<Aliases, ParentName> : Path : Path : never;
+/**
+ * Find a direct child command in a tuple by name.
+ * Unlike PickCommandByName, this does NOT flatten — it only checks direct children by their `name` field.
+ * Uses indexed access (O(1) depth) instead of recursive tuple walking.
+ */
+type FindDirectChild<TCommands extends AnyPadroneCommand[], TName extends string> = Extract<TCommands[number], {
+  '~types': {
+    name: TName;
+  };
+}>;
+/**
+ * Replace a command in a tuple by name, or append if not found.
+ * Used by `.command()` override semantics: re-registering a name replaces that entry.
+ * Uses mapped type (O(1) depth) instead of recursive tuple walking.
+ */
+type ReplaceOrAppendCommand<TCommands extends [...AnyPadroneCommand[]], TName extends string, TNew extends AnyPadroneCommand> = HasDirectChild<TCommands, TName> extends true ? ReplaceInTuple<TCommands, TName, TNew> : [...TCommands, TNew];
+type HasDirectChild<TCommands extends AnyPadroneCommand[], TName extends string> = TName extends TCommands[number]['~types']['name'] ? true : false;
+type ReplaceInTuple<TCommands extends AnyPadroneCommand[], TName extends string, TNew extends AnyPadroneCommand> = { [K in keyof TCommands]: TCommands[K] extends AnyPadroneCommand ? TCommands[K]['~types']['name'] extends TName ? TNew : TCommands[K] : TCommands[K] };
+/**
+ * Utility type for extensions that add a command to a builder/program.
+ * Replaces the boilerplate `With*<T>` pattern used across all extension files.
+ */
+type WithCommand<T, TName extends string, TCmd extends AnyPadroneCommand> = T extends {
+  '~types': {
+    programName: infer PN extends string;
+    name: infer N extends string;
+    parentName: infer PaN extends string;
+    argsSchema: infer A extends PadroneSchema;
+    result: infer R;
+    commands: infer C extends [...AnyPadroneCommand[]];
+    async: infer AS extends boolean;
+    context: infer CTX;
+    contextProvided: infer CTXP;
+  };
+} ? T extends {
+  run: any;
+} ? PadroneProgram<PN, N, PaN, A, R, ReplaceOrAppendCommand<C, TName, TCmd>, any, AS, CTX, CTXP> : PadroneBuilder<PN, N, PaN, A, R, ReplaceOrAppendCommand<C, TName, TCmd>, any, AS, CTX, CTXP> : T;
+/**
+ * Utility type for extensions that register a context-providing interceptor.
+ * Extends `TContextProvided` with `TProvides` while preserving all other builder/program type params.
+ */
+type WithInterceptor<T, TProvides> = T extends {
+  '~types': {
+    programName: infer PN extends string;
+    name: infer N extends string;
+    parentName: infer PaN extends string;
+    argsSchema: infer A extends PadroneSchema;
+    result: infer R;
+    commands: infer C extends [...AnyPadroneCommand[]];
+    async: infer AS extends boolean;
+    context: infer CTX;
+    contextProvided: infer CTXP;
+  };
+} ? T extends {
+  run: any;
+} ? PadroneProgram<PN, N, PaN, A, R, C, any, AS, CTX, CTXP & TProvides> : PadroneBuilder<PN, N, PaN, A, R, C, any, AS, CTX, CTXP & TProvides> : T;
+/**
+ * Utility type for extensions that force the builder/program into async mode.
+ * Sets `TAsync` to `true` while preserving all other type params.
+ */
+type WithAsync<T> = T extends {
+  '~types': {
+    programName: infer PN extends string;
+    name: infer N extends string;
+    parentName: infer PaN extends string;
+    argsSchema: infer A extends PadroneSchema;
+    result: infer R;
+    commands: infer C extends [...AnyPadroneCommand[]];
+    async: any;
+    context: infer CTX;
+    contextProvided: infer CTXP;
+  };
+} ? T extends {
+  run: any;
+} ? PadroneProgram<PN, N, PaN, A, R, C, any, true, CTX, CTXP> : PadroneBuilder<PN, N, PaN, A, R, C, any, true, CTX, CTXP> : T;
+type PickCommandByName<TCommands extends AnyPadroneCommand[], TName extends string | AnyPadroneCommand> = TName extends AnyPadroneCommand ? TName : FlattenCommands<TCommands> extends infer Cmd extends AnyPadroneCommand ? Cmd extends AnyPadroneCommand ? TName extends GetCommandPathsAndAliases<Cmd> ? Cmd : never : never : never;
+type FlattenCommands<TCommands extends AnyPadroneCommand[]> = TCommands extends [] ? never : number extends TCommands['length'] ? IsAny<TCommands[number]> extends true ? never : TCommands[number] : TCommands[number] extends infer Cmd extends AnyPadroneCommand ? Cmd | FlattenCommands<Cmd['~types']['commands']> : never;
+/**
+ * Get all command paths including alias paths for all commands.
+ */
+type GetCommandPathsOrAliases<TCommands extends AnyPadroneCommand[]> = GetCommandPathsAndAliases<FlattenCommands<TCommands>>;
+/**
+ * Find all the commands that are prefixed with a command name or alias.
+ * This is needed to avoid matching other commands when followed by a space and another word.
+ * For example, let's say `level1` and `level1 level2` are commands.
+ * Then `level1 ${string}` would also match `level1 level2`,
+ * and it would cause `level1 level2` to not show up in the autocomplete.
+ * By excluding those cases, we can ensure autocomplete works correctly.
+ */
+type PrefixedCommands<TCommands extends AnyPadroneCommand[]> = GetCommandPathsOrAliases<TCommands> extends infer CommandNames ? CommandNames extends string ? AnyPartExtends<GetCommandPathsOrAliases<TCommands>, `${CommandNames} ${string}`> extends true ? never : `${CommandNames} ${string}` : never : never;
+/**
+ * The possible commands are the commands that can be parsed by the program.
+ * This includes the string that are exact matches to a command name or alias, and strings that are prefixed with a command name or alias.
+ */
+type PossibleCommands<TCommands extends AnyPadroneCommand[], TWithPrefixed extends boolean = false, TWithObjects extends boolean = false, TWithFallback extends boolean = true> = GetCommandPathsOrAliases<TCommands> | (TWithPrefixed extends true ? PrefixedCommands<TCommands> : never) | (TWithObjects extends true ? FlattenCommands<TCommands> : never) | (TWithFallback extends true ? SafeString : never);
+type CommandIsUnknownable<TCommand> = IsGeneric<TCommand> extends true ? true : string extends TCommand ? true : SafeString extends TCommand ? true : false;
+/**
+ * Match a string to a command by the possible commands.
+ * This is done by recursively splitting the string by the last space, and then checking if the prefix is a valid command name or alias.
+ * This is needed to avoid matching the top-level command when there are nested commands.
+ */
+/**
+ * Recursively re-paths a command's children under a new parent path.
+ * Used by `mount()` to update all nested command paths when a program is mounted as a subcommand.
+ */
+type RepathCommands<TCommands extends [...AnyPadroneCommand[]], TNewParentPath extends string> = TCommands extends [infer First extends AnyPadroneCommand, ...infer Rest extends AnyPadroneCommand[]] ? [RepathCommand<First, TNewParentPath>, ...RepathCommands<Rest, TNewParentPath>] : [];
+type RepathCommand<TCommand extends AnyPadroneCommand, TNewParentName extends string> = PadroneCommand<TCommand['~types']['name'], TNewParentName, TCommand['~types']['argsSchema'], TCommand['~types']['result'], RepathCommands<TCommand['~types']['commands'], FullCommandName<TCommand['~types']['name'], TNewParentName>>, TCommand['~types']['aliases'], TCommand['~types']['async'], TCommand['~types']['context'], TCommand['~types']['contextProvided']>;
+type PickCommandByPossibleCommands<TCommands extends AnyPadroneCommand[], TCommand extends PossibleCommands<TCommands, true, true> | SafeString> = CommandIsUnknownable<TCommand> extends true ? FlattenCommands<TCommands> : TCommand extends AnyPadroneCommand ? TCommand : TCommand extends string ? TCommand extends GetCommandPathsOrAliases<TCommands> ? PickCommandByName<TCommands, TCommand> : SplitLastSpace<TCommand> extends [infer Prefix extends string, infer Rest] ? IsNever<Rest> extends true ? PickCommandByName<TCommands, Prefix> : PickCommandByPossibleCommands<TCommands, Prefix> : never : never;
+//#endregion
+export { Drained, FindDirectChild, FlattenCommands, FullCommandName, HasInteractive, IsAsyncSchema, IsGeneric, MaybePromise, OrAsync, OrAsyncMeta, PickCommandByName, PickCommandByPossibleCommands, PossibleCommands, RepathCommands, ReplaceOrAppendCommand, SafeString, Thenable, WithAsync, WithCommand, WithInterceptor };
+//# sourceMappingURL=type-utils.d.mts.map

package/dist/util/type-utils.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-utils.d.mts","names":[],"sources":["../../src/util/type-utils.ts"],"mappings":";;;;KAUY,UAAA;AAAA,KACP,SAAA,sBAA+B,CAAC;AAAA,KAChC,KAAA,kBAAuB,CAAC;AAAA,KACxB,OAAA,OAAc,CAAC;AAAA,KAER,SAAA,MAAe,KAAA,CAAM,CAAA,wBAAyB,SAAA,CAAU,CAAA,wBAAyB,OAAA,CAAQ,CAAA;;;AAJhE;AAAA;;;;KAazB,aAAA,MAAmB,KAAA,CAAM,CAAA,yBAA0B,CAAA;EAAY,QAAA;AAAA;;;AAXvD;AAEpB;KAeY,OAAA,uCAA8C,SAAA,uBAEtD,aAAA,CAAc,OAAA;;;;;KAQN,cAAA,UAAwB,KAAA;EAAgB,WAAA;AAAA,WAEhD,KAAK;EAAW,mBAAA;AAAA;;;;;KAQR,WAAA,qCAAgD,SAAA,uBAExD,cAAA,CAAe,KAAA;;;;AArCmF;AAStG;;;KAuCY,OAAA,MACV,CAAA,SAAU,OAAA,YACN,OAAA,CAAQ,CAAA,IACR,CAAA,SAAU,aAAA,YACR,CAAA,KACA,CAAA,kBACE,CAAA,GACA,CAAA,SAAU,QAAA,YACR,CAAA,KACA,CAAA;;;;;KAMA,QAAA,MAAc,CAAA,GAAI,WAAA,CAAY,CAAA;EAAO,KAAA,EAAO,OAAA,CAAQ,CAAA;EAAa,OAAA,EAAS,OAAA,CAAQ,CAAA;AAAA;;;AAtDX;AAMnF;;;;KAyDY,YAAA,cAA0B,KAAA,CAAM,MAAA,iBAAuB,CAAA,gBAAiB,MAAA,GAAS,OAAA,CAAQ,CAAA,IAAK,QAAA,CAAS,CAAA;AAAA,KAE9G,WAAA,wDAAmE,KAAA,8BAAmC,QAAA,wBACtG,SAAA,KAAc,WAAA,CAAY,SAAA,EAAW,QAAA,MACrC,KAAA;AAAA,KAEA,UAAA,0DAAoE,MAAA,iFAIrE,SAAA,cACE,SAAA,MACG,SAAA,GAAY,OAAA,GAAU,UAAA,CAAW,SAAA,EAAW,OAAA,MACjD,MAAA,mBAEE,MAAA;AAAA,KAED,cAAA,qBACH,WAAA,CAAY,CAAA,wEACR,IAAA,eACG,CAAA,YACA,UAAA,CAAW,IAAA,GAAO,IAAA,KACpB,CAAA;AAAA,KAEF,cAAA,UAAwB,CAAA,4BAA6B,CAAA,gBAAiB,CAAA,SAAU,CAAA;AAAA,KAEzE,eAAA,0DAAyE,WAAA,cACjF,KAAA,MACG,WAAA,IAAe,KAAA;;AAnFG;AAQzB;KAgFK,cAAA,+DAA6E,QAAA,wEAI9E,eAAA,CAAgB,KAAA,EAAO,WAAA,IAAe,cAAA,CAAe,IAAA,EAAM,WAAA;;;;KAM1D,yBAAA,kBAA2C,iBAAA,IAAqB,QAAA,uDACjE,QAAA,+DACE,QAAA,mEACE,IAAA,GAAO,cAAA,CAAe,OAAA,EAAS,UAAA,IAC/B,IAAA,GACF,IAAA;;AA7FiC;AAQvC;;;KA6FY,eAAA,mBAAkC,iBAAA,4BAA6C,OAAA,CACzF,SAAA;EACE,QAAA;IAAY,IAAA,EAAM,KAAA;EAAA;AAAA;;;;;;KAQV,sBAAA,uBAA6C,iBAAA,wCAAyD,iBAAA,IAChH,cAAA,CAAe,SAAA,EAAW,KAAA,iBAAsB,cAAA,CAAe,SAAA,EAAW,KAAA,EAAO,IAAA,QAAY,SAAA,EAAW,IAAA;AAAA,KAErG,cAAA,mBAAiC,iBAAA,4BAA6C,KAAA,SAAc,SAAA;AAAA,KAI5F,cAAA,mBAAiC,iBAAA,uCAAwD,iBAAA,kBAChF,SAAA,GAAY,SAAA,CAAU,CAAA,UAAW,iBAAA,GACzC,SAAA,CAAU,CAAA,4BAA6B,KAAA,GACrC,IAAA,GACA,SAAA,CAAU,CAAA,IACZ,SAAA,CAAU,CAAA;;;;;KAOJ,WAAA,uCAAkD,iBAAA,IAAqB,CAAA;EACjF,QAAA;IACE,WAAA;IACA,IAAA;IACA,UAAA;IACA,UAAA,kBAA4B,aAAA;IAC5B,MAAA;IACA,QAAA,sBAA8B,iBAAA;IAC9B,KAAA;IACA,OAAA;IACA,eAAA;EAAA;AAAA,IAGA,CAAA;EAAY,GAAA;AAAA,IACV,cAAA,CAAe,EAAA,EAAI,CAAA,EAAG,GAAA,EAAK,CAAA,EAAG,CAAA,EAAG,sBAAA,CAAuB,CAAA,EAAG,KAAA,EAAO,IAAA,QAAY,EAAA,EAAI,GAAA,EAAK,IAAA,IACvF,cAAA,CAAe,EAAA,EAAI,CAAA,EAAG,GAAA,EAAK,CAAA,EAAG,CAAA,EAAG,sBAAA,CAAuB,CAAA,EAAG,KAAA,EAAO,IAAA,QAAY,EAAA,EAAI,GAAA,EAAK,IAAA,IACzF,CAAA;;;;;KAMQ,eAAA,iBAAgC,CAAA;EAC1C,QAAA;IACE,WAAA;IACA,IAAA;IACA,UAAA;IACA,UAAA,kBAA4B,aAAA;IAC5B,MAAA;IACA,QAAA,sBAA8B,iBAAA;IAC9B,KAAA;IACA,OAAA;IACA,eAAA;EAAA;AAAA,IAGA,CAAA;EAAY,GAAA;AAAA,IACV,cAAA,CAAe,EAAA,EAAI,CAAA,EAAG,GAAA,EAAK,CAAA,EAAG,CAAA,EAAG,CAAA,OAAQ,EAAA,EAAI,GAAA,EAAK,IAAA,GAAO,SAAA,IACzD,cAAA,CAAe,EAAA,EAAI,CAAA,EAAG,GAAA,EAAK,CAAA,EAAG,CAAA,EAAG,CAAA,OAAQ,EAAA,EAAI,GAAA,EAAK,IAAA,GAAO,SAAA,IAC3D,CAAA;;;;;KAMQ,SAAA,MAAe,CAAA;EACzB,QAAA;IACE,WAAA;IACA,IAAA;IACA,UAAA;IACA,UAAA,kBAA4B,aAAA;IAC5B,MAAA;IACA,QAAA,sBAA8B,iBAAA;IAC9B,KAAA;IACA,OAAA;IACA,eAAA;EAAA;AAAA,IAGA,CAAA;EAAY,GAAA;AAAA,IACV,cAAA,CAAe,EAAA,EAAI,CAAA,EAAG,GAAA,EAAK,CAAA,EAAG,CAAA,EAAG,CAAA,aAAc,GAAA,EAAK,IAAA,IACpD,cAAA,CAAe,EAAA,EAAI,CAAA,EAAG,GAAA,EAAK,CAAA,EAAG,CAAA,EAAG,CAAA,aAAc,GAAA,EAAK,IAAA,IACtD,CAAA;AAAA,KAEQ,iBAAA,mBACQ,iBAAA,2BACK,iBAAA,IACrB,KAAA,SAAc,iBAAA,GACd,KAAA,GACA,eAAA,CAAgB,SAAA,4BAAqC,iBAAA,GACnD,GAAA,SAAY,iBAAA,GACV,KAAA,SAAc,yBAAA,CAA0B,GAAA,IACtC,GAAA;AAAA,KAKE,eAAA,mBAAkC,iBAAA,MAAuB,SAAA,qCAElD,SAAA,aACb,KAAA,CAAM,SAAA,iCAEJ,SAAA,WACF,SAAA,mCAA4C,iBAAA,GAC1C,GAAA,GAAM,eAAA,CAAgB,GAAA;;;;KAMzB,wBAAA,mBAA2C,iBAAA,MAAuB,yBAAA,CAA0B,eAAA,CAAgB,SAAA;;;;;;;;;KAU5G,gBAAA,mBAAmC,iBAAA,MACtC,wBAAA,CAAyB,SAAA,+BACrB,YAAA,kBACE,cAAA,CAAe,wBAAA,CAAyB,SAAA,MAAe,YAAA,wCAElD,YAAA;;;;;KAQD,gBAAA,mBACQ,iBAAA,yHAKhB,wBAAA,CAAyB,SAAA,KACxB,aAAA,gBAA6B,gBAAA,CAAiB,SAAA,cAC9C,YAAA,gBAA4B,eAAA,CAAgB,SAAA,cAC5C,aAAA,gBAA6B,UAAA;AAAA,KAE7B,oBAAA,aACH,SAAA,CAAU,QAAA,uCAA+C,QAAA,UAAkB,UAAA,SAAmB,QAAA;;;;;AAhNoB;AAAE;;;;AAAA,KA2N1G,cAAA,uBAAqC,iBAAA,sCAAuD,SAAA,8BAClF,iBAAA,wBACE,iBAAA,OAEnB,aAAA,CAAc,KAAA,EAAO,cAAA,MAAoB,cAAA,CAAe,IAAA,EAAM,cAAA;AAAA,KAG9D,aAAA,kBAA+B,iBAAA,mCAAoD,cAAA,CACtF,QAAA,oBACA,cAAA,EACA,QAAA,0BACA,QAAA,sBACA,cAAA,CAAe,QAAA,wBAAgC,eAAA,CAAgB,QAAA,oBAA4B,cAAA,IAC3F,QAAA,uBACA,QAAA,qBACA,QAAA,uBACA,QAAA;AAAA,KAGU,6BAAA,mBACQ,iBAAA,qBACD,gBAAA,CAAiB,SAAA,gBAAyB,UAAA,IAE3D,oBAAA,CAAqB,QAAA,iBACjB,eAAA,CAAgB,SAAA,IAChB,QAAA,SAAiB,iBAAA,GACf,QAAA,GACA,QAAA,kBACE,QAAA,SAAiB,wBAAA,CAAyB,SAAA,IACxC,iBAAA,CAAkB,SAAA,EAAW,QAAA,IAC7B,cAAA,CAAe,QAAA,sDACb,OAAA,CAAQ,IAAA,iBACN,iBAAA,CAAkB,SAAA,EAAW,MAAA,IAC7B,6BAAA,CAA8B,SAAA,EAAW,MAAA"}