padrone 1.4.0 → 1.6.0

package/dist/{completion.mjs → completion-BEuflbDO.mjs}

@@ -1,75 +1,5 @@
-import { t as __require } from "./chunk-y_GBKt04.mjs";
-import { i as extractSchemaMetadata } from "./args-CVDbyyzG.mjs";
-//#region src/shell-utils.ts
-/**
-* Detects the current shell from environment variables and process info.
-* @returns The detected shell type, or undefined if unknown
-*/
-function detectShell() {
-	if (typeof process === "undefined") return void 0;
-	const shellEnv = process.env.SHELL || "";
-	if (shellEnv.includes("zsh")) return "zsh";
-	if (shellEnv.includes("bash")) return "bash";
-	if (shellEnv.includes("fish")) return "fish";
-	if (process.env.PSModulePath || process.env.POWERSHELL_DISTRIBUTION_CHANNEL) return "powershell";
-	try {
-		const ppid = process.ppid;
-		if (ppid) {
-			const { execSync } = __require("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 {}
-}
-function getRcFile(shell, home) {
-	const { homedir } = __require("node:os");
-	const { join } = __require("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 process.env.PROFILE || 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.
-*/
-function writeToRcFile(rcFile, snippet, beginMarker, endMarker) {
-	const { existsSync, mkdirSync, readFileSync, writeFileSync } = __require("node:fs");
-	const { dirname } = __require("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
-//#region src/completion.ts
+import { a as getJsonSchema, d as detectShell, i as extractSchemaMetadata, m as writeToRcFile, p as getRcFile } from "./args-Cnq0nwSM.mjs";
+//#region src/feature/completion.ts
 /**
 * Collects all commands from a program recursively.
 */
@@ -92,35 +22,55 @@ function extractArguments(cmd) {
 	try {
 		const argsMeta = cmd.meta?.fields;
 		const { aliases } = extractSchemaMetadata(cmd.argsSchema, argsMeta, cmd.meta?.autoAlias);
-		const aliasToArgument = {};
-		for (const [arg, alias] of Object.entries(aliases)) aliasToArgument[alias] = arg;
-		const jsonSchema = cmd.argsSchema["~standard"].jsonSchema.input({ target: "draft-2020-12" });
+		const argToAlias = {};
+		for (const [aliasName, argName] of Object.entries(aliases)) if (!argToAlias[argName]) argToAlias[argName] = aliasName;
+		const jsonSchema = getJsonSchema(cmd.argsSchema);
 		if (jsonSchema.type === "object" && jsonSchema.properties) for (const [key, prop] of Object.entries(jsonSchema.properties)) {
-			const alias = Object.entries(aliases).find(([arg]) => arg === key)?.[1];
+			const enumValues = prop.enum ?? prop.items?.enum;
+			const optMeta = argsMeta?.[key];
 			argList.push({
 				name: key,
-				alias,
-				isBoolean: prop?.type === "boolean"
+				alias: argToAlias[key],
+				isBoolean: prop?.type === "boolean",
+				enum: enumValues,
+				description: optMeta?.description ?? prop.description
 			});
 		}
 	} catch {}
 	return argList;
 }
 /**
+* Collects unique args across all commands, preserving first-seen enum values.
+*/
+function collectUniqueArgs(program, commands) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const cmd of [program, ...commands]) for (const arg of extractArguments(cmd)) if (!seen.has(arg.name)) seen.set(arg.name, arg);
+	return seen;
+}
+/**
 * Generates a Bash completion script for the program.
 */
 function generateBashCompletion(program) {
 	const programName = program.name;
 	const commands = collectAllCommands(program);
 	const commandNames = commands.map((c) => c.name).join(" ");
+	const uniqueArgs = collectUniqueArgs(program, commands);
 	const allArguments = /* @__PURE__ */ new Set();
 	allArguments.add("--help");
 	allArguments.add("--version");
-	for (const cmd of [program, ...commands]) for (const arg of extractArguments(cmd)) {
+	for (const arg of uniqueArgs.values()) {
 		allArguments.add(`--${arg.name}`);
-		if (arg.alias) allArguments.add(`-${arg.alias}`);
+		if (arg.alias) allArguments.add(`--${arg.alias}`);
 	}
 	const argsList = Array.from(allArguments).join(" ");
+	const enumCases = [];
+	for (const arg of uniqueArgs.values()) {
+		if (!arg.enum || arg.enum.length === 0) continue;
+		const values = arg.enum.join(" ");
+		const patterns = [`--${arg.name}`];
+		if (arg.alias) patterns.push(`--${arg.alias}`);
+		enumCases.push(`      ${patterns.join("|")}) COMPREPLY=($(compgen -W "${values}" -- "$cur")); return 0 ;;`);
+	}
 	return `###-begin-${programName}-completion-###
 #
 # ${programName} command completion script
@@ -144,8 +94,13 @@ if type complete &>/dev/null; then
 
     local commands="${commandNames}"
     local args="${argsList}"
+${enumCases.length > 0 ? `
+    # Complete option values
+    case "$prev" in
+${enumCases.join("\n")}
+    esac
 
-    # Complete args when current word starts with -
+` : "\n"}    # Complete args when current word starts with -
     if [[ "$cur" == -* ]]; then
       COMPREPLY=($(compgen -W "$args" -- "$cur"))
       return 0
@@ -197,13 +152,12 @@ function generateZshCompletion(program) {
 	const argumentCompletions = [];
 	argumentCompletions.push("      '--help[Show help information]'");
 	argumentCompletions.push("      '--version[Show version number]'");
-	const seenArgs = new Set(["help", "version"]);
-	for (const cmd of [program, ...commands]) for (const arg of extractArguments(cmd)) {
-		if (seenArgs.has(arg.name)) continue;
-		seenArgs.add(arg.name);
-		const escapedDesc = (cmd.meta?.fields?.[arg.name]?.description || "").replace(/'/g, "'\\''").replace(/\[/g, "\\[").replace(/\]/g, "\\]");
-		if (arg.alias) argumentCompletions.push(`      {-${arg.alias},--${arg.name}}'[${escapedDesc}]'`);
-		else argumentCompletions.push(`      '--${arg.name}[${escapedDesc}]'`);
+	const uniqueArgs = collectUniqueArgs(program, commands);
+	for (const arg of uniqueArgs.values()) {
+		const escapedDesc = (arg.description || "").replace(/'/g, "'\\''").replace(/\[/g, "\\[").replace(/\]/g, "\\]");
+		const valueAction = arg.enum?.length ? `: :(${arg.enum.join(" ")})` : "";
+		if (arg.alias) argumentCompletions.push(`      {--${arg.alias},--${arg.name}}'[${escapedDesc}]${valueAction}'`);
+		else argumentCompletions.push(`      '--${arg.name}[${escapedDesc}]${valueAction}'`);
 	}
 	return `#compdef ${programName}
 ###-begin-${programName}-completion-###
@@ -268,13 +222,12 @@ function generateFishCompletion(program) {
 	lines.push("# Global arguments");
 	lines.push(`complete -c ${programName} -l help -d 'Show help information'`);
 	lines.push(`complete -c ${programName} -l version -d 'Show version number'`);
-	const seenArgs = new Set(["help", "version"]);
-	for (const cmd of [program, ...commands]) for (const arg of extractArguments(cmd)) {
-		if (seenArgs.has(arg.name)) continue;
-		seenArgs.add(arg.name);
-		const escapedDesc = (cmd.meta?.fields?.[arg.name]?.description || "").replace(/'/g, "\\'");
-		if (arg.alias) lines.push(`complete -c ${programName} -s ${arg.alias} -l ${arg.name} -d '${escapedDesc}'`);
-		else lines.push(`complete -c ${programName} -l ${arg.name} -d '${escapedDesc}'`);
+	const uniqueArgs = collectUniqueArgs(program, commands);
+	for (const arg of uniqueArgs.values()) {
+		const escapedDesc = (arg.description || "").replace(/'/g, "\\'");
+		const valueFlag = arg.enum?.length ? ` -xa '${arg.enum.join(" ")}'` : "";
+		if (arg.alias) lines.push(`complete -c ${programName} -l ${arg.name} -s ${arg.alias} -d '${escapedDesc}'${valueFlag}`);
+		else lines.push(`complete -c ${programName} -l ${arg.name} -d '${escapedDesc}'${valueFlag}`);
 	}
 	lines.push(`###-end-${programName}-completion-###`);
 	return lines.join("\n");
@@ -284,6 +237,32 @@ function generateFishCompletion(program) {
 */
 function generatePowerShellCompletion(program) {
 	const programName = program.name;
+	const commands = collectAllCommands(program);
+	const uniqueArgs = collectUniqueArgs(program, commands);
+	const commandNames = commands.map((c) => `'${c.name}'`).join(", ");
+	const argNames = ["'--help'", "'--version'"];
+	for (const arg of uniqueArgs.values()) {
+		argNames.push(`'--${arg.name}'`);
+		if (arg.alias) argNames.push(`'--${arg.alias}'`);
+	}
+	const enumCases = [];
+	for (const arg of uniqueArgs.values()) {
+		if (!arg.enum || arg.enum.length === 0) continue;
+		const values = arg.enum.map((v) => `'${v}'`).join(", ");
+		const patterns = [`'--${arg.name}'`];
+		if (arg.alias) patterns.push(`'--${arg.alias}'`);
+		enumCases.push(`      ${patterns.join(", ")} { @(${values}) | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
+        [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
+      }; return }`);
+	}
+	const enumBlock = enumCases.length > 0 ? `
+  # Complete option values
+  $prevWord = $commandAst.CommandElements | Select-Object -Last 2 | Select-Object -First 1
+  switch ($prevWord) {
+${enumCases.join("\n")}
+  }
+
+` : "\n";
 	return `###-begin-${programName}-completion-###
 #
 # ${programName} command completion script for PowerShell
@@ -294,10 +273,9 @@ function generatePowerShellCompletion(program) {
 Register-ArgumentCompleter -Native -CommandName ${programName} -ScriptBlock {
   param($wordToComplete, $commandAst, $cursorPosition)
 
-  $commands = @(${collectAllCommands(program).map((c) => `'${c.name}'`).join(", ")})
-  $args = @('--help', '--version')
-
-  if ($wordToComplete -like '-*') {
+  $commands = @(${commandNames})
+  $args = @(${argNames.join(", ")})
+${enumBlock}  if ($wordToComplete -like '-*') {
     $args | Where-Object { $_ -like "$wordToComplete*" } | ForEach-Object {
       [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)
     }
@@ -348,10 +326,10 @@ ${programName} completion powershell >> $PROFILE`;
 * Generates the completion output with automatic shell detection.
 * If shell is not specified, detects the current shell and provides instructions.
 */
-function generateCompletionOutput(program, shell) {
+async function generateCompletionOutput(program, shell) {
 	const programName = program.name;
 	if (shell) return generateCompletion(program, shell);
-	const detectedShell = detectShell();
+	const detectedShell = await detectShell();
 	if (detectedShell) return `# Detected shell: ${detectedShell}
 #
 ${getCompletionInstallInstructions(programName, detectedShell)}
@@ -380,10 +358,10 @@ ${generateCompletion(program, detectedShell)}`;
 * Sets up shell completions by writing an eval snippet to the appropriate shell config file.
 * Uses marker comments for idempotency — re-running replaces the existing block.
 */
-function setupCompletions(programName, shell) {
-	const { existsSync, mkdirSync, writeFileSync } = __require("node:fs");
-	const { join } = __require("node:path");
-	const { homedir } = __require("node:os");
+async function setupCompletions(programName, shell) {
+	const { existsSync, mkdirSync, writeFileSync } = await import("node:fs");
+	const { join } = await import("node:path");
+	const { homedir } = await import("node:os");
 	const beginMarker = `###-begin-${programName}-completion-###`;
 	const endMarker = `###-end-${programName}-completion-###`;
 	const snippet = buildSetupSnippet(programName, shell, beginMarker, endMarker);
@@ -398,7 +376,7 @@ function setupCompletions(programName, shell) {
 			updated: existed
 		};
 	}
-	const rcFile = getRcFile(shell);
+	const rcFile = await getRcFile(shell);
 	if (!rcFile) throw new Error(`Could not determine config file for ${shell}.`);
 	return writeToRcFile(rcFile, snippet, beginMarker, endMarker);
 }
@@ -412,6 +390,6 @@ function buildSetupSnippet(programName, shell, beginMarker, endMarker) {
 	}
 }
 //#endregion
-export { detectShell, escapeRegExp, generateBashCompletion, generateCompletion, generateCompletionOutput, generateFishCompletion, generatePowerShellCompletion, generateZshCompletion, getCompletionInstallInstructions, getRcFile, setupCompletions, writeToRcFile };
+export { detectShell, generateCompletionOutput, setupCompletions };
 
-//# sourceMappingURL=completion.mjs.map
+//# sourceMappingURL=completion-BEuflbDO.mjs.map

package/dist/completion-BEuflbDO.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"completion-BEuflbDO.mjs","names":[],"sources":["../src/feature/completion.ts"],"sourcesContent":["import { extractSchemaMetadata, getJsonSchema } from '../core/args.ts';\nimport type { AnyPadroneCommand } from '../types/index.ts';\nimport { detectShell, getRcFile, type ShellType, writeToRcFile } from '../util/shell-utils.ts';\n\nexport { detectShell, escapeRegExp, getRcFile, type ShellType, writeToRcFile } from '../util/shell-utils.ts';\n\n/**\n * Collects all commands from a program recursively.\n */\nfunction collectAllCommands(cmd: AnyPadroneCommand): AnyPadroneCommand[] {\n  const result: AnyPadroneCommand[] = [];\n\n  if (cmd.commands) {\n    for (const subcmd of cmd.commands) {\n      if (!subcmd.hidden) {\n        result.push(subcmd);\n        result.push(...collectAllCommands(subcmd));\n      }\n    }\n  }\n\n  return result;\n}\n\ninterface ExtractedArg {\n  name: string;\n  alias?: string;\n  isBoolean: boolean;\n  enum?: string[];\n  description?: string;\n}\n\n/**\n * Extracts all argument names from a command's schema.\n */\nfunction extractArguments(cmd: AnyPadroneCommand): ExtractedArg[] {\n  const argList: ExtractedArg[] = [];\n\n  if (!cmd.argsSchema) return argList;\n\n  try {\n    const argsMeta = cmd.meta?.fields;\n    const { aliases } = extractSchemaMetadata(cmd.argsSchema, argsMeta, cmd.meta?.autoAlias);\n\n    // Build reverse map: argName → aliasName\n    const argToAlias: Record<string, string> = {};\n    for (const [aliasName, argName] of Object.entries(aliases)) {\n      if (!argToAlias[argName]) argToAlias[argName] = aliasName;\n    }\n\n    const jsonSchema = getJsonSchema(cmd.argsSchema) as Record<string, any>;\n\n    if (jsonSchema.type === 'object' && jsonSchema.properties) {\n      for (const [key, prop] of Object.entries(jsonSchema.properties as Record<string, any>)) {\n        const enumValues = (prop.enum ?? prop.items?.enum) as string[] | undefined;\n        const optMeta = argsMeta?.[key];\n        argList.push({\n          name: key,\n          alias: argToAlias[key],\n          isBoolean: prop?.type === 'boolean',\n          enum: enumValues,\n          description: optMeta?.description ?? prop.description,\n        });\n      }\n    }\n  } catch {\n    // Ignore schema parsing errors\n  }\n\n  return argList;\n}\n\n/**\n * Collects unique args across all commands, preserving first-seen enum values.\n */\nfunction collectUniqueArgs(program: AnyPadroneCommand, commands: AnyPadroneCommand[]): Map<string, ExtractedArg> {\n  const seen = new Map<string, ExtractedArg>();\n\n  for (const cmd of [program, ...commands]) {\n    for (const arg of extractArguments(cmd)) {\n      if (!seen.has(arg.name)) {\n        seen.set(arg.name, arg);\n      }\n    }\n  }\n\n  return seen;\n}\n\n/**\n * Generates a Bash completion script for the program.\n */\nexport function generateBashCompletion(program: AnyPadroneCommand): string {\n  const programName = program.name;\n  const commands = collectAllCommands(program);\n  const commandNames = commands.map((c) => c.name).join(' ');\n  const uniqueArgs = collectUniqueArgs(program, commands);\n\n  // Collect all option names\n  const allArguments = new Set<string>();\n  allArguments.add('--help');\n  allArguments.add('--version');\n\n  for (const arg of uniqueArgs.values()) {\n    allArguments.add(`--${arg.name}`);\n    if (arg.alias) allArguments.add(`--${arg.alias}`);\n  }\n\n  const argsList = Array.from(allArguments).join(' ');\n\n  // Build case branches for options with enum values\n  const enumCases: string[] = [];\n  for (const arg of uniqueArgs.values()) {\n    if (!arg.enum || arg.enum.length === 0) continue;\n    const values = arg.enum.join(' ');\n    const patterns = [`--${arg.name}`];\n    if (arg.alias) patterns.push(`--${arg.alias}`);\n    enumCases.push(`      ${patterns.join('|')}) COMPREPLY=($(compgen -W \"${values}\" -- \"$cur\")); return 0 ;;`);\n  }\n\n  const enumBlock =\n    enumCases.length > 0\n      ? `\n    # Complete option values\n    case \"$prev\" in\n${enumCases.join('\\n')}\n    esac\n\n`\n      : '\\n';\n\n  return `###-begin-${programName}-completion-###\n#\n# ${programName} command completion script\n#\n# Installation: ${programName} completion >> ~/.bashrc  (or ~/.zshrc)\n# Or, maybe: ${programName} completion > /usr/local/etc/bash_completion.d/${programName}\n#\n\nif type complete &>/dev/null; then\n  _${programName}_completion() {\n    local cur prev words cword\n    if type _get_comp_words_by_ref &>/dev/null; then\n      _get_comp_words_by_ref -n = -n @ -n : -w words -i cword\n    else\n      cword=\"$COMP_CWORD\"\n      words=(\"\\${COMP_WORDS[@]}\")\n    fi\n\n    cur=\"\\${words[cword]}\"\n    prev=\"\\${words[cword-1]}\"\n\n    local commands=\"${commandNames}\"\n    local args=\"${argsList}\"\n${enumBlock}    # Complete args when current word starts with -\n    if [[ \"$cur\" == -* ]]; then\n      COMPREPLY=($(compgen -W \"$args\" -- \"$cur\"))\n      return 0\n    fi\n\n    # Complete commands\n    COMPREPLY=($(compgen -W \"$commands\" -- \"$cur\"))\n  }\n  complete -o bashdefault -o default -o nospace -F _${programName}_completion ${programName}\nelif type compdef &>/dev/null; then\n  _${programName}_completion() {\n    local si=$IFS\n    local commands=\"${commandNames}\"\n    local args=\"${argsList}\"\n\n    if [[ \"\\${words[CURRENT]}\" == -* ]]; then\n      compadd -- \\${=args}\n    else\n      compadd -- \\${=commands}\n    fi\n    IFS=$si\n  }\n  compdef _${programName}_completion ${programName}\nelif type compctl &>/dev/null; then\n  _${programName}_completion() {\n    local commands=\"${commandNames}\"\n    local args=\"${argsList}\"\n\n    if [[ \"\\${words[CURRENT]}\" == -* ]]; then\n      reply=(\\${=args})\n    else\n      reply=(\\${=commands})\n    fi\n  }\n  compctl -K _${programName}_completion ${programName}\nfi\n###-end-${programName}-completion-###`;\n}\n\n/**\n * Generates a Zsh completion script for the program.\n */\nexport function generateZshCompletion(program: AnyPadroneCommand): string {\n  const programName = program.name;\n  const commands = collectAllCommands(program);\n\n  // Generate command completions with descriptions\n  const commandCompletions = commands\n    .map((cmd) => {\n      const desc = cmd.description || cmd.title || '';\n      const escapedDesc = desc.replace(/'/g, \"'\\\\''\").replace(/:/g, '\\\\:');\n      return `      '${cmd.name}:${escapedDesc}'`;\n    })\n    .join('\\n');\n\n  // Collect all args with descriptions and enum values\n  const argumentCompletions: string[] = [];\n  argumentCompletions.push(\"      '--help[Show help information]'\");\n  argumentCompletions.push(\"      '--version[Show version number]'\");\n\n  const uniqueArgs = collectUniqueArgs(program, commands);\n\n  for (const arg of uniqueArgs.values()) {\n    const desc = arg.description || '';\n    const escapedDesc = desc.replace(/'/g, \"'\\\\''\").replace(/\\[/g, '\\\\[').replace(/\\]/g, '\\\\]');\n\n    // Zsh action spec for enum values: :label:(val1 val2 val3)\n    const valueAction = arg.enum?.length ? `: :(${arg.enum.join(' ')})` : '';\n\n    if (arg.alias) {\n      argumentCompletions.push(`      {--${arg.alias},--${arg.name}}'[${escapedDesc}]${valueAction}'`);\n    } else {\n      argumentCompletions.push(`      '--${arg.name}[${escapedDesc}]${valueAction}'`);\n    }\n  }\n\n  return `#compdef ${programName}\n###-begin-${programName}-completion-###\n#\n# ${programName} command completion script for Zsh\n#\n# Installation: ${programName} completion >> ~/.zshrc\n# Or: ${programName} completion > ~/.zsh/completions/_${programName}\n#\n\n_${programName}() {\n  local -a commands\n  local -a args\n\n  commands=(\n${commandCompletions}\n  )\n\n  args=(\n${argumentCompletions.join('\\n')}\n  )\n\n  _arguments -s \\\\\n    $args \\\\\n    '1: :->command' \\\\\n    '*::arg:->args'\n\n  case \"$state\" in\n    command)\n      _describe 'command' commands\n      ;;\n  esac\n}\n\n_${programName}\n###-end-${programName}-completion-###`;\n}\n\n/**\n * Generates a Fish completion script for the program.\n */\nexport function generateFishCompletion(program: AnyPadroneCommand): string {\n  const programName = program.name;\n  const commands = collectAllCommands(program);\n\n  const lines: string[] = [\n    `###-begin-${programName}-completion-###`,\n    '#',\n    `# ${programName} command completion script for Fish`,\n    '#',\n    `# Installation: ${programName} completion > ~/.config/fish/completions/${programName}.fish`,\n    '#',\n    '',\n    `# Clear existing completions`,\n    `complete -c ${programName} -e`,\n    '',\n    '# Commands',\n  ];\n\n  for (const cmd of commands) {\n    const desc = cmd.description || cmd.title || '';\n    const escapedDesc = desc.replace(/'/g, \"\\\\'\");\n    lines.push(`complete -c ${programName} -n \"__fish_use_subcommand\" -a \"${cmd.name}\" -d '${escapedDesc}'`);\n  }\n\n  lines.push('');\n  lines.push('# Global arguments');\n  lines.push(`complete -c ${programName} -l help -d 'Show help information'`);\n  lines.push(`complete -c ${programName} -l version -d 'Show version number'`);\n\n  const uniqueArgs = collectUniqueArgs(program, commands);\n\n  for (const arg of uniqueArgs.values()) {\n    const desc = arg.description || '';\n    const escapedDesc = desc.replace(/'/g, \"\\\\'\");\n    // Fish: -xa 'val1 val2' provides exclusive value completions\n    const valueFlag = arg.enum?.length ? ` -xa '${arg.enum.join(' ')}'` : '';\n\n    if (arg.alias) {\n      lines.push(`complete -c ${programName} -l ${arg.name} -s ${arg.alias} -d '${escapedDesc}'${valueFlag}`);\n    } else {\n      lines.push(`complete -c ${programName} -l ${arg.name} -d '${escapedDesc}'${valueFlag}`);\n    }\n  }\n\n  lines.push(`###-end-${programName}-completion-###`);\n\n  return lines.join('\\n');\n}\n\n/**\n * Generates a PowerShell completion script for the program.\n */\nexport function generatePowerShellCompletion(program: AnyPadroneCommand): string {\n  const programName = program.name;\n  const commands = collectAllCommands(program);\n  const uniqueArgs = collectUniqueArgs(program, commands);\n\n  const commandNames = commands.map((c) => `'${c.name}'`).join(', ');\n\n  // Collect all option names\n  const argNames: string[] = [\"'--help'\", \"'--version'\"];\n  for (const arg of uniqueArgs.values()) {\n    argNames.push(`'--${arg.name}'`);\n    if (arg.alias) argNames.push(`'--${arg.alias}'`);\n  }\n\n  // Build switch cases for option value completion\n  const enumCases: string[] = [];\n  for (const arg of uniqueArgs.values()) {\n    if (!arg.enum || arg.enum.length === 0) continue;\n    const values = arg.enum.map((v) => `'${v}'`).join(', ');\n    const patterns = [`'--${arg.name}'`];\n    if (arg.alias) patterns.push(`'--${arg.alias}'`);\n    enumCases.push(`      ${patterns.join(', ')} { @(${values}) | Where-Object { $_ -like \"$wordToComplete*\" } | ForEach-Object {\n        [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)\n      }; return }`);\n  }\n\n  const enumBlock =\n    enumCases.length > 0\n      ? `\n  # Complete option values\n  $prevWord = $commandAst.CommandElements | Select-Object -Last 2 | Select-Object -First 1\n  switch ($prevWord) {\n${enumCases.join('\\n')}\n  }\n\n`\n      : '\\n';\n\n  return `###-begin-${programName}-completion-###\n#\n# ${programName} command completion script for PowerShell\n#\n# Installation: ${programName} completion >> $PROFILE\n#\n\nRegister-ArgumentCompleter -Native -CommandName ${programName} -ScriptBlock {\n  param($wordToComplete, $commandAst, $cursorPosition)\n\n  $commands = @(${commandNames})\n  $args = @(${argNames.join(', ')})\n${enumBlock}  if ($wordToComplete -like '-*') {\n    $args | Where-Object { $_ -like \"$wordToComplete*\" } | ForEach-Object {\n      [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)\n    }\n  } else {\n    $commands | Where-Object { $_ -like \"$wordToComplete*\" } | ForEach-Object {\n      [System.Management.Automation.CompletionResult]::new($_, $_, 'ParameterValue', $_)\n    }\n  }\n}\n###-end-${programName}-completion-###`;\n}\n\n/**\n * Generates a completion script for the specified shell.\n */\nexport function generateCompletion(program: AnyPadroneCommand, shell: ShellType): string {\n  switch (shell) {\n    case 'bash':\n      return generateBashCompletion(program);\n    case 'zsh':\n      return generateZshCompletion(program);\n    case 'fish':\n      return generateFishCompletion(program);\n    case 'powershell':\n      return generatePowerShellCompletion(program);\n    default:\n      throw new Error(`Unsupported shell: ${shell}`);\n  }\n}\n\n/**\n * Gets the installation instructions for a shell completion script.\n */\nexport function getCompletionInstallInstructions(programName: string, shell: ShellType): string {\n  switch (shell) {\n    case 'bash':\n      return `# Add to ~/.bashrc:\n${programName} completion bash >> ~/.bashrc\n\n# Or install system-wide:\n${programName} completion bash > /usr/local/etc/bash_completion.d/${programName}`;\n\n    case 'zsh':\n      return `# Add to ~/.zshrc:\n${programName} completion zsh >> ~/.zshrc\n\n# Or add to completions directory:\n${programName} completion zsh > ~/.zsh/completions/_${programName}`;\n\n    case 'fish':\n      return `# Install to Fish completions:\n${programName} completion fish > ~/.config/fish/completions/${programName}.fish`;\n\n    case 'powershell':\n      return `# Add to PowerShell profile:\n${programName} completion powershell >> $PROFILE`;\n\n    default:\n      return `# Run: ${programName} completion <shell>\n# Supported shells: bash, zsh, fish, powershell`;\n  }\n}\n\n/**\n * Generates the completion output with automatic shell detection.\n * If shell is not specified, detects the current shell and provides instructions.\n */\nexport async function generateCompletionOutput(program: AnyPadroneCommand, shell?: ShellType): Promise<string> {\n  const programName = program.name;\n\n  if (shell) {\n    return generateCompletion(program, shell);\n  }\n\n  // Auto-detect shell and provide instructions\n  const detectedShell = await detectShell();\n\n  if (detectedShell) {\n    const instructions = getCompletionInstallInstructions(programName, detectedShell);\n    const script = generateCompletion(program, detectedShell);\n\n    return `# Detected shell: ${detectedShell}\n#\n${instructions}\n#\n# Or evaluate directly (temporary, for current session only):\n# eval \"$(${programName} completion ${detectedShell})\"\n\n${script}`;\n  }\n\n  // Could not detect shell - provide usage info\n  return `# Shell auto-detection failed.\n#\n# Usage: ${programName} completion <shell>\n#\n# Supported shells:\n#   bash       - Bash completion script\n#   zsh        - Zsh completion script\n#   fish       - Fish completion script\n#   powershell - PowerShell completion script\n#\n# Example:\n#   ${programName} completion bash >> ~/.bashrc\n#   ${programName} completion zsh >> ~/.zshrc\n#   ${programName} completion fish > ~/.config/fish/completions/${programName}.fish\n#   ${programName} completion powershell >> $PROFILE`;\n}\n\nexport interface SetupCompletionsResult {\n  /** The file that was written to. */\n  file: string;\n  /** Whether an existing completion block was replaced (true) or a new one was appended (false). */\n  updated: boolean;\n}\n\n/**\n * Sets up shell completions by writing an eval snippet to the appropriate shell config file.\n * Uses marker comments for idempotency — re-running replaces the existing block.\n */\nexport async function setupCompletions(programName: string, shell: ShellType): Promise<SetupCompletionsResult> {\n  const { existsSync, mkdirSync, writeFileSync } = await import('node:fs');\n  const { join } = await import('node:path');\n  const { homedir } = await import('node:os');\n\n  const beginMarker = `###-begin-${programName}-completion-###`;\n  const endMarker = `###-end-${programName}-completion-###`;\n  const snippet = buildSetupSnippet(programName, shell, beginMarker, endMarker);\n\n  if (shell === 'fish') {\n    const completionsDir = join(homedir(), '.config', 'fish', 'completions');\n    const filePath = join(completionsDir, `${programName}.fish`);\n    mkdirSync(completionsDir, { recursive: true });\n    const existed = existsSync(filePath);\n    writeFileSync(filePath, `${snippet}\\n`);\n    return { file: filePath, updated: existed };\n  }\n\n  const rcFile = await getRcFile(shell);\n  if (!rcFile) {\n    throw new Error(`Could not determine config file for ${shell}.`);\n  }\n\n  return writeToRcFile(rcFile, snippet, beginMarker, endMarker);\n}\n\nfunction buildSetupSnippet(programName: string, shell: ShellType, beginMarker: string, endMarker: string): string {\n  const evalCmd = `${programName} completion ${shell}`;\n\n  switch (shell) {\n    case 'bash':\n    case 'zsh':\n      return `${beginMarker}\\neval \"$(${evalCmd})\"\\n${endMarker}`;\n    case 'fish':\n      return `${beginMarker}\\n${evalCmd} | source\\n${endMarker}`;\n    case 'powershell':\n      return `${beginMarker}\\n${evalCmd} | Invoke-Expression\\n${endMarker}`;\n  }\n}\n"],"mappings":"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"}

package/dist/docs/index.d.mts

@@ -1,4 +1,4 @@
-import { r as HelpInfo } from "../formatter-ClUK5hcQ.mjs";
+import { r as HelpInfo } from "../formatter-DrvhDMrq.mjs";
 
 //#region src/docs/index.d.ts
 type DocsFormat = 'markdown' | 'html' | 'man' | 'json';
@@ -29,6 +29,26 @@ type DocsResult = {
  * Accepts either a PadroneProgram (from createPadrone()) or a raw AnyPadroneCommand.
  */
 declare function generateDocs(program: object, options?: DocsOptions): DocsResult;
+type SetupManPagesResult = {
+  /** Directory where man pages were written. */dir: string; /** Man page files that were written. */
+  written: string[]; /** Whether existing pages were overwritten (true) or newly created (false). */
+  updated: boolean;
+};
+/**
+ * Installs man pages for a Padrone CLI program into the local man directory.
+ * Generates man pages for all commands and writes them to `~/.local/share/man/man1/`.
+ *
+ * After installation, `man <program>` and `man <program>-<subcommand>` should work
+ * (assuming `~/.local/share/man` is in `MANPATH` or `manpath` picks it up).
+ */
+declare function setupManPages(program: object): Promise<SetupManPagesResult>;
+/**
+ * Removes installed man pages for a Padrone CLI program.
+ */
+declare function removeManPages(program: object): Promise<{
+  dir: string;
+  removed: string[];
+}>;
 //#endregion
-export { DocsFormat, DocsOptions, DocsPage, DocsResult, generateDocs };
+export { DocsFormat, DocsOptions, DocsPage, DocsResult, SetupManPagesResult, generateDocs, removeManPages, setupManPages };
 //# sourceMappingURL=index.d.mts.map

package/dist/docs/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/docs/index.ts"],"mappings":";;;KAWY,UAAA;AAAA,KAEA,WAAA;EAFA,6CAIV,MAAA,GAAS,UAAA;EAET,MAAA,WANoB;EAQpB,aAAA,YANqB;EAQrB,WAAA,IAAe,IAAA,EAAM,QAAA,EAAU,KAAA,aAAkB,MAAA,mBANxC;EAQT,SAAA,YAFiD;EAIjD,MAAA;AAAA;AAAA,KAGU,QAAA;EAbD,8EAeT,IAAA,UAXA;EAaA,OAAA,UAXqB;EAarB,OAAA;AAAA;AAAA,KAGU,UAAA;EAdV,2BAgBA,KAAA,EAAO,QAAA,IAdD;EAgBN,OAAA,YAbU;EAeV,OAAA;EAEA,MAAA;IAAU,IAAA;IAAc,KAAA,EAAO,KAAA;EAAA;AAAA;;AARjC;;;iBA2egB,YAAA,CAAa,OAAA,UAAiB,OAAA,GAAS,WAAA,GAAmB,UAAA"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/docs/index.ts"],"mappings":";;;KAWY,UAAA;AAAA,KAEA,WAAA;EAFA,6CAIV,MAAA,GAAS,UAAA;EAET,MAAA,WANoB;EAQpB,aAAA,YANqB;EAQrB,WAAA,IAAe,IAAA,EAAM,QAAA,EAAU,KAAA,aAAkB,MAAA,mBANxC;EAQT,SAAA,YAFiD;EAIjD,MAAA;AAAA;AAAA,KAGU,QAAA;EAbD,8EAeT,IAAA,UAXA;EAaA,OAAA,UAXqB;EAarB,OAAA;AAAA;AAAA,KAGU,UAAA;EAdV,2BAgBA,KAAA,EAAO,QAAA,IAdD;EAgBN,OAAA,YAbU;EAeV,OAAA;EAEA,MAAA;IAAU,IAAA;IAAc,KAAA,EAAO,KAAA;EAAA;AAAA;;AARjC;;;iBAigBgB,YAAA,CAAa,OAAA,UAAiB,OAAA,GAAS,WAAA,GAAmB,UAAA;AAAA,KAoF9D,mBAAA;EAnlBH,8CAqlBP,GAAA,UAjlBA;EAmlBA,OAAA,YAjlBU;EAmlBV,OAAA;AAAA;;;AA1FF;;;;;iBAqHsB,aAAA,CAAc,OAAA,WAAkB,OAAA,CAAQ,mBAAA;;;;iBA+BxC,cAAA,CAAe,OAAA,WAAkB,OAAA;EAAU,GAAA;EAAa,OAAA;AAAA"}

package/dist/docs/index.mjs

@@ -1,4 +1,5 @@
-import { a as commandSymbol, n as getHelpInfo } from "../help-CcBe91bV.mjs";
+import { s as getCommand } from "../commands-B_gufyR9.mjs";
+import { n as getHelpInfo } from "../help-B5Kk83of.mjs";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 //#region src/docs/index.ts
@@ -122,6 +123,14 @@ function generateMarkdownPage(info, depth, frontmatterFn) {
 	lines.push(usageParts.join(" "));
 	lines.push("```");
 	lines.push("");
+	if (info.examples?.length) {
+		lines.push("## Examples");
+		lines.push("");
+		lines.push("```");
+		for (const ex of info.examples) lines.push(`$ ${ex}`);
+		lines.push("```");
+		lines.push("");
+	}
 	if (info.subcommands?.length) {
 		const visibleSubs = info.subcommands.filter((s) => !s.hidden);
 		if (visibleSubs.length > 0) {
@@ -170,6 +179,10 @@ function generateHtmlPage(info, depth) {
 	if (info.usage.hasArguments) usageParts.push("[options]");
 	sections.push("  <h2>Usage</h2>");
 	sections.push(`  <pre><code>${escapeHtml(usageParts.join(" "))}</code></pre>`);
+	if (info.examples?.length) {
+		sections.push("  <h2>Examples</h2>");
+		sections.push(`  <pre><code>${info.examples.map((ex) => `$ ${escapeHtml(ex)}`).join("\n")}</code></pre>`);
+	}
 	if (info.subcommands?.length) {
 		const visibleSubs = info.subcommands.filter((s) => !s.hidden);
 		if (visibleSubs.length > 0) {
@@ -249,6 +262,13 @@ function generateManPage(info, _depth, programName) {
 		lines.push(".SH DESCRIPTION");
 		lines.push(escapeMan(info.description));
 	}
+	if (info.examples?.length) {
+		lines.push(".SH EXAMPLES");
+		for (const ex of info.examples) {
+			lines.push(".PP");
+			lines.push(`.nf\n$ ${escapeMan(ex)}\n.fi`);
+		}
+	}
 	if (info.subcommands?.length) {
 		const visibleSubs = info.subcommands.filter((s) => !s.hidden);
 		if (visibleSubs.length > 0) {
@@ -321,17 +341,13 @@ function generateMarkdownIndex(rootInfo, allInfos) {
 	}
 	return `${lines.join("\n").trimEnd()}\n`;
 }
-function resolveCommand(programOrCommand) {
-	if (commandSymbol in programOrCommand) return programOrCommand[commandSymbol];
-	return programOrCommand;
-}
 /**
 * Generate documentation for a Padrone CLI program or command tree.
 * Accepts either a PadroneProgram (from createPadrone()) or a raw AnyPadroneCommand.
 */
 function generateDocs(program, options = {}) {
 	const { format = "markdown", output, includeHidden = false, frontmatter, overwrite = true, dryRun = false } = options;
-	const cmd = resolveCommand(program);
+	const cmd = getCommand(program);
 	const allInfos = collectAllHelpInfo(cmd, includeHidden);
 	const rootInfo = allInfos[0];
 	const programName = cmd.name || "program";
@@ -399,7 +415,76 @@ function generateDocs(program, options = {}) {
 	}
 	return result;
 }
+/**
+* Returns the local man page directory for the given section.
+* Uses `~/.local/share/man/man<section>` (XDG convention).
+*/
+async function getManPageDir(section = 1) {
+	const { homedir } = await import("node:os");
+	return join(process.env.XDG_DATA_HOME || join(homedir(), ".local", "share"), "man", `man${section}`);
+}
+/**
+* Converts a command name to a man page filename.
+* "myapp" → "myapp.1", "myapp deploy" → "myapp-deploy.1"
+*/
+function manPageFilename(commandName, section = 1) {
+	return `${commandName.replace(/\s+/g, "-")}.${section}`;
+}
+/**
+* Installs man pages for a Padrone CLI program into the local man directory.
+* Generates man pages for all commands and writes them to `~/.local/share/man/man1/`.
+*
+* After installation, `man <program>` and `man <program>-<subcommand>` should work
+* (assuming `~/.local/share/man` is in `MANPATH` or `manpath` picks it up).
+*/
+async function setupManPages(program) {
+	const cmd = getCommand(program);
+	const allInfos = collectAllHelpInfo(cmd, false);
+	const programName = cmd.name || "program";
+	const manDir = await getManPageDir(1);
+	mkdirSync(manDir, { recursive: true });
+	const written = [];
+	let updated = false;
+	for (let i = 0; i < allInfos.length; i++) {
+		const info = allInfos[i];
+		const depth = i === 0 ? 0 : info.name.split(/\s+/).length;
+		const filename = manPageFilename(info.name === "<root>" || !info.name ? programName : info.name);
+		const fullPath = join(manDir, filename);
+		if (existsSync(fullPath)) updated = true;
+		writeFileSync(fullPath, generateManPage(info, depth, programName), "utf-8");
+		written.push(filename);
+	}
+	return {
+		dir: manDir,
+		written,
+		updated
+	};
+}
+/**
+* Removes installed man pages for a Padrone CLI program.
+*/
+async function removeManPages(program) {
+	const { unlinkSync } = await import("node:fs");
+	const cmd = getCommand(program);
+	const allInfos = collectAllHelpInfo(cmd, false);
+	const programName = cmd.name || "program";
+	const manDir = await getManPageDir(1);
+	const removed = [];
+	for (let i = 0; i < allInfos.length; i++) {
+		const info = allInfos[i];
+		const filename = manPageFilename(info.name === "<root>" || !info.name ? programName : info.name);
+		const fullPath = join(manDir, filename);
+		if (existsSync(fullPath)) {
+			unlinkSync(fullPath);
+			removed.push(filename);
+		}
+	}
+	return {
+		dir: manDir,
+		removed
+	};
+}
 //#endregion
-export { generateDocs };
+export { generateDocs, removeManPages, setupManPages };
 
 //# sourceMappingURL=index.mjs.map