politty 0.4.3 → 0.4.6

package/dist/{zsh-hjvdI8uZ.js → completion-_AnQsWh9.js}

@@ -1,4 +1,4 @@
-import { c as arg, i as extractFields, r as resolveSubCommandMeta } from "./lazy-BrEg8SgI.js";
+import { i as extractFields, l as arg, r as resolveSubCommandMeta } from "./lazy-DSyfzR-F.js";
 import { z } from "zod";
 import { execSync } from "node:child_process";
 
@@ -16,6 +16,30 @@ function defineCommand(config) {
 		examples: config.examples
 	};
 }
+/**
+* Create a typed defineCommand factory with pre-bound global args type.
+* This is the recommended pattern for type-safe global options.
+*
+* @example
+* ```ts
+* // global-args.ts
+* type GlobalArgsType = { verbose: boolean; config?: string };
+* export const defineAppCommand = createDefineCommand<GlobalArgsType>();
+*
+* // commands/build.ts
+* export const buildCommand = defineAppCommand({
+*   name: "build",
+*   args: z.object({ output: arg(z.string().default("dist")) }),
+*   run: (args) => {
+*     args.verbose; // typed via GlobalArgsType
+*     args.output;  // typed via local args
+*   },
+* });
+* ```
+*/
+function createDefineCommand() {
+	return defineCommand;
+}
 
 //#endregion
 //#region src/completion/value-completion-resolver.ts
@@ -68,6 +92,13 @@ function resolveValueCompletion(field) {
 /**
 * Sanitize a name for use as a shell function/variable identifier.
 * Replaces any character that is not alphanumeric or underscore with underscore.
+*
+* Note: This is not injective -- distinct names may produce the same output
+* (e.g., "foo-bar" and "foo_bar" both become "foo_bar"). When used for nested
+* path encoding (`path.map(sanitize).join("_")`), cross-level collisions are
+* theoretically possible (e.g., "foo-bar:baz" vs "foo:bar-baz") but extremely
+* unlikely in real CLI designs. If collision-safety is needed, sanitize must be
+* replaced with an injective encoding.
 */
 function sanitize(name) {
 	return name.replace(/[^a-zA-Z0-9_]/g, "_");
@@ -147,29 +178,80 @@ function extractSubcommand(name, command) {
 		positionals: extractCompletablePositionals(command)
 	};
 }
+/** Join parent and child with a separator, omitting separator when parent is empty. */
+function joinPrefix(parent, child, sep) {
+	return parent ? `${parent}${sep}${child}` : child;
+}
 /**
 * Collect opt-takes-value case entries for a subcommand tree.
-* Used by bash and zsh generators (identical case syntax: `subcmd:--opt) return 0 ;;`).
+* Used by bash and zsh generators (identical case syntax: `path:--opt) return 0 ;;`).
+* parentPath is a colon-delimited path (e.g., "" for root, "workspace:user" for nested).
 */
-function optTakesValueEntries(sub, subcmdName) {
+function optTakesValueEntries(sub, parentPath) {
 	const lines = [];
 	for (const opt of sub.options) if (opt.takesValue) {
-		const patterns = [`${subcmdName}:--${opt.cliName}`];
-		if (opt.alias) patterns.push(`${subcmdName}:-${opt.alias}`);
+		const patterns = [`${parentPath}:--${opt.cliName}`];
+		if (opt.alias) patterns.push(`${parentPath}:-${opt.alias}`);
 		lines.push(`        ${patterns.join("|")}) return 0 ;;`);
 	}
-	for (const child of getVisibleSubs(sub.subcommands)) lines.push(...optTakesValueEntries(child, child.name));
+	for (const child of getVisibleSubs(sub.subcommands)) lines.push(...optTakesValueEntries(child, joinPrefix(parentPath, child.name, ":")));
 	return lines;
 }
 /**
+* Recursively collect all subcommand route entries.
+* Returns entries used by all shell generators for both dispatch routing
+* and subcommand lookup (is_subcmd) tables.
+*/
+function collectRouteEntries(sub, parentPath = "", parentFunc = "") {
+	const entries = [];
+	for (const child of getVisibleSubs(sub.subcommands)) {
+		const pathStr = joinPrefix(parentPath, child.name, ":");
+		const funcSuffix = joinPrefix(parentFunc, sanitize(child.name), "_");
+		entries.push(...collectRouteEntries(child, pathStr, funcSuffix));
+		entries.push({
+			pathStr,
+			funcSuffix,
+			lookupPattern: `${parentPath}:${child.name}`
+		});
+	}
+	return entries;
+}
+/**
+* Generate is_subcmd case/switch body lines (bash/zsh case syntax).
+* Returns lines for the case statement body only (caller wraps in function).
+*/
+function isSubcmdCaseLines(routeEntries) {
+	return routeEntries.map((r) => `        ${r.lookupPattern}) return 0 ;;`);
+}
+/**
+* Recursively merge global options into a subcommand and all its descendants.
+* Avoids duplicates by checking existing option names.
+*/
+function propagateGlobalOptions(sub, globalOptions) {
+	const existingNames = new Set(sub.options.map((o) => o.name));
+	const newOpts = globalOptions.filter((o) => !existingNames.has(o.name));
+	sub.options = [...sub.options, ...newOpts];
+	for (const child of sub.subcommands) propagateGlobalOptions(child, globalOptions);
+}
+/**
 * Extract completion data from a command tree
+*
+* @param command - The root command
+* @param programName - Program name for completion scripts
+* @param globalArgsSchema - Optional global args schema. When provided, global options
+*   are derived from this schema instead of the root command's options.
 */
-function extractCompletionData(command, programName) {
+function extractCompletionData(command, programName, globalArgsSchema) {
 	const rootSubcommand = extractSubcommand(programName, command);
+	let globalOptions;
+	if (globalArgsSchema) {
+		globalOptions = extractFields(globalArgsSchema).fields.filter((field) => !field.positional).map(fieldToOption);
+		propagateGlobalOptions(rootSubcommand, globalOptions);
+	} else globalOptions = rootSubcommand.options;
 	return {
 		command: rootSubcommand,
 		programName,
-		globalOptions: rootSubcommand.options
+		globalOptions
 	};
 }
 
@@ -317,8 +399,9 @@ function generateSubHandler$2(sub, fn, path) {
 	for (const child of visibleSubs) lines.push(...generateSubHandler$2(child, fn, fullPath));
 	lines.push(`${funcName}() {`);
 	lines.push(...valueCompletionBlocks(sub.options));
-	lines.push(`    if [[ -z "$_inline_prefix" ]] && __${fn}_opt_takes_value "${sub.name}" "$_prev"; then return; fi`);
-	lines.push(`    if [[ -n "$_inline_prefix" ]] && __${fn}_opt_takes_value "${sub.name}" "\${_inline_prefix%=}"; then return; fi`);
+	const fullPathStr = fullPath.join(":");
+	lines.push(`    if [[ -z "$_inline_prefix" ]] && __${fn}_opt_takes_value "${fullPathStr}" "$_prev"; then return; fi`);
+	lines.push(`    if [[ -n "$_inline_prefix" ]] && __${fn}_opt_takes_value "${fullPathStr}" "\${_inline_prefix%=}"; then return; fi`);
 	if (sub.positionals.length > 0) {
 		lines.push(`    if (( _after_dd )); then`);
 		lines.push(...positionalBlock$2(sub.positionals).map((l) => `    ${l}`));
@@ -343,7 +426,7 @@ function generateSubHandler$2(sub, fn, path) {
 }
 function generateBashCompletion(command, options) {
 	const { programName } = options;
-	const data = extractCompletionData(command, programName);
+	const data = extractCompletionData(command, programName, options.globalArgsSchema);
 	const fn = sanitize(programName);
 	const root = data.command;
 	const visibleSubs = getVisibleSubs(root.subcommands);
@@ -367,6 +450,16 @@ function generateBashCompletion(command, options) {
 	lines.push(`    return 1`);
 	lines.push(`}`);
 	lines.push(``);
+	const routeEntries = collectRouteEntries(root);
+	if (routeEntries.length > 0) {
+		lines.push(`__${fn}_is_subcmd() {`);
+		lines.push(`    case "$1:$2" in`);
+		lines.push(...isSubcmdCaseLines(routeEntries));
+		lines.push(`    esac`);
+		lines.push(`    return 1`);
+		lines.push(`}`);
+		lines.push(``);
+	}
 	for (const sub of visibleSubs) lines.push(...generateSubHandler$2(sub, fn, []));
 	lines.push(`__${fn}_complete_root() {`);
 	lines.push(...valueCompletionBlocks(root.options));
@@ -395,7 +488,7 @@ function generateBashCompletion(command, options) {
 	lines.push(`    fi`);
 	lines.push(`}`);
 	lines.push(``);
-	const subRouting = visibleSubs.map((s) => `        ${s.name}) __${fn}_complete_${sanitize(s.name)} ;;`).join("\n");
+	const subRouting = routeEntries.map((r) => `        ${r.pathStr}) __${fn}_complete_${r.funcSuffix} ;;`).join("\n");
 	lines.push(`_${fn}_completions() {`);
 	lines.push(`    COMPREPLY=()`);
 	lines.push(``);
@@ -439,7 +532,7 @@ function generateBashCompletion(command, options) {
 	lines.push(`            __${fn}_opt_takes_value "$_subcmd" "$_w" && _skip_next=1`);
 	lines.push(`            (( _j++ )); continue`);
 	lines.push(`        fi`);
-	if (visibleSubs.length > 0) lines.push(`        if [[ -z "$_subcmd" ]]; then _subcmd="$_w"; _used_opts=(); else (( _pos_count++ )); fi`);
+	if (routeEntries.length > 0) lines.push(`        if __${fn}_is_subcmd "$_subcmd" "$_w"; then _subcmd="\${_subcmd:+\${_subcmd}:}$_w"; _used_opts=(); _pos_count=0; else (( _pos_count++ )); fi`);
 	else lines.push(`        (( _pos_count++ ))`);
 	lines.push(`        (( _j++ ))`);
 	lines.push(`    done`);
@@ -1112,7 +1205,8 @@ function generateSubHandler$1(sub, fn, path) {
 	for (const child of visibleSubs) lines.push(...generateSubHandler$1(child, fn, fullPath));
 	lines.push(`function ${funcName} --no-scope-shadowing`);
 	lines.push(...valueCompletionBlock$1(sub.options));
-	lines.push(`    if __${fn}_opt_takes_value "${sub.name}" "$_prev"; return; end`);
+	const fullPathStr = fullPath.join(":");
+	lines.push(`    if __${fn}_opt_takes_value "${fullPathStr}" "$_prev"; return; end`);
 	if (sub.positionals.length > 0) {
 		lines.push(`    if test $_after_dd -eq 1`);
 		lines.push(...positionalBlock$1(sub.positionals).map((l) => `    ${l}`));
@@ -1133,20 +1227,23 @@ function generateSubHandler$1(sub, fn, path) {
 	return lines;
 }
 /** Generate opt-takes-value entries for fish switch cases */
-function optTakesValueCases(sub, subcmdName) {
+function optTakesValueCases(sub, parentPath) {
 	const lines = [];
 	for (const opt of sub.options) if (opt.takesValue) {
-		const patterns = [`"${subcmdName}:--${opt.cliName}"`];
-		if (opt.alias) patterns.push(`"${subcmdName}:-${opt.alias}"`);
+		const patterns = [`"${parentPath}:--${opt.cliName}"`];
+		if (opt.alias) patterns.push(`"${parentPath}:-${opt.alias}"`);
 		lines.push(`        case ${patterns.join(" ")}`);
 		lines.push(`            return 0`);
 	}
-	for (const child of getVisibleSubs(sub.subcommands)) lines.push(...optTakesValueCases(child, child.name));
+	for (const child of getVisibleSubs(sub.subcommands)) {
+		const childPath = parentPath ? `${parentPath}:${child.name}` : child.name;
+		lines.push(...optTakesValueCases(child, childPath));
+	}
 	return lines;
 }
 function generateFishCompletion(command, options) {
 	const { programName } = options;
-	const data = extractCompletionData(command, programName);
+	const data = extractCompletionData(command, programName, options.globalArgsSchema);
 	const fn = sanitize(programName);
 	const root = data.command;
 	const visibleSubs = getVisibleSubs(root.subcommands);
@@ -1170,6 +1267,19 @@ function generateFishCompletion(command, options) {
 	lines.push(`    return 1`);
 	lines.push(`end`);
 	lines.push(``);
+	const routeEntries = collectRouteEntries(root);
+	if (routeEntries.length > 0) {
+		lines.push(`function __${fn}_is_subcmd`);
+		lines.push(`    switch "$argv[1]:$argv[2]"`);
+		for (const r of routeEntries) {
+			lines.push(`        case "${r.lookupPattern}"`);
+			lines.push(`            return 0`);
+		}
+		lines.push(`    end`);
+		lines.push(`    return 1`);
+		lines.push(`end`);
+		lines.push(``);
+	}
 	for (const sub of visibleSubs) lines.push(...generateSubHandler$1(sub, fn, []));
 	lines.push(`function __${fn}_complete_root --no-scope-shadowing`);
 	lines.push(...valueCompletionBlock$1(root.options));
@@ -1232,13 +1342,13 @@ function generateFishCompletion(command, options) {
 	lines.push(`            __${fn}_opt_takes_value "$_subcmd" "$_w"; and set _skip_next 1`);
 	lines.push(`            set _j (math $_j + 1); continue`);
 	lines.push(`        end`);
-	if (visibleSubs.length > 0) lines.push(`        if test -z "$_subcmd"; set _subcmd "$_w"; set _used_opts; else; set _pos_count (math $_pos_count + 1); end`);
+	if (routeEntries.length > 0) lines.push(`        if __${fn}_is_subcmd "$_subcmd" "$_w"; test -n "$_subcmd"; and set _subcmd "$_subcmd:$_w"; or set _subcmd "$_w"; set _used_opts; set _pos_count 0; else; set _pos_count (math $_pos_count + 1); end`);
 	else lines.push(`        set _pos_count (math $_pos_count + 1)`);
 	lines.push(`        set _j (math $_j + 1)`);
 	lines.push(`    end`);
 	lines.push(``);
 	lines.push(`    switch "$_subcmd"`);
-	for (const s of visibleSubs) lines.push(`        case "${s.name}"; __${fn}_complete_${sanitize(s.name)}`);
+	for (const r of routeEntries) lines.push(`        case "${r.pathStr}"; __${fn}_complete_${r.funcSuffix}`);
 	lines.push(`        case '*'; __${fn}_complete_root`);
 	lines.push(`    end`);
 	lines.push(`end`);
@@ -1357,7 +1467,8 @@ function generateSubHandler(sub, fn, path) {
 	lines.push(`${funcName}() {`);
 	lines.push(`    local -a _vals=()`);
 	lines.push(...valueCompletionBlock(sub.options, fn));
-	lines.push(`    if __${fn}_opt_takes_value "${sub.name}" "\${words[CURRENT-1]}"; then return 0; fi`);
+	const fullPathStr = fullPath.join(":");
+	lines.push(`    if __${fn}_opt_takes_value "${fullPathStr}" "\${words[CURRENT-1]}"; then return 0; fi`);
 	if (sub.positionals.length > 0) {
 		lines.push(`    if (( _after_dd )); then`);
 		lines.push(...positionalBlock(sub.positionals, fn).map((l) => `    ${l}`));
@@ -1384,7 +1495,7 @@ function generateSubHandler(sub, fn, path) {
 }
 function generateZshCompletion(command, options) {
 	const { programName } = options;
-	const data = extractCompletionData(command, programName);
+	const data = extractCompletionData(command, programName, options.globalArgsSchema);
 	const fn = sanitize(programName);
 	const root = data.command;
 	const visibleSubs = getVisibleSubs(root.subcommands);
@@ -1419,6 +1530,16 @@ function generateZshCompletion(command, options) {
 	lines.push(`    return 1`);
 	lines.push(`}`);
 	lines.push(``);
+	const routeEntries = collectRouteEntries(root);
+	if (routeEntries.length > 0) {
+		lines.push(`__${fn}_is_subcmd() {`);
+		lines.push(`    case "$1:$2" in`);
+		lines.push(...isSubcmdCaseLines(routeEntries));
+		lines.push(`    esac`);
+		lines.push(`    return 1`);
+		lines.push(`}`);
+		lines.push(``);
+	}
 	for (const sub of visibleSubs) lines.push(...generateSubHandler(sub, fn, []));
 	lines.push(`__${fn}_complete_root() {`);
 	lines.push(`    local -a _vals=()`);
@@ -1449,7 +1570,7 @@ function generateZshCompletion(command, options) {
 	lines.push(`    fi`);
 	lines.push(`}`);
 	lines.push(``);
-	const subRouting = visibleSubs.map((s) => `        ${s.name}) __${fn}_complete_${sanitize(s.name)} ;;`).join("\n");
+	const subRouting = routeEntries.map((r) => `        ${r.pathStr}) __${fn}_complete_${r.funcSuffix} ;;`).join("\n");
 	lines.push(`_${fn}() {`);
 	lines.push(`    (( CURRENT )) || CURRENT=\${#words}`);
 	lines.push(``);
@@ -1468,7 +1589,7 @@ function generateZshCompletion(command, options) {
 	lines.push(`            __${fn}_opt_takes_value "$_subcmd" "$_w" && _skip_next=1`);
 	lines.push(`            (( _j++ )); continue`);
 	lines.push(`        fi`);
-	if (visibleSubs.length > 0) lines.push(`        if [[ -z "$_subcmd" ]]; then _subcmd="$_w"; _used_opts=(); else (( _pos_count++ )); fi`);
+	if (routeEntries.length > 0) lines.push(`        if __${fn}_is_subcmd "$_subcmd" "$_w"; then _subcmd="\${_subcmd:+\${_subcmd}:}$_w"; _used_opts=(); _pos_count=0; else (( _pos_count++ )); fi`);
 	else lines.push(`        (( _pos_count++ ))`);
 	lines.push(`        (( _j++ ))`);
 	lines.push(`    done`);
@@ -1504,5 +1625,155 @@ source ~/.zshrc`
 }
 
 //#endregion
-export { formatForShell as a, generateCandidates as c, extractPositionals as d, resolveValueCompletion as f, hasCompleteCommand as i, generateBashCompletion as l, generateFishCompletion as n, parseCompletionContext as o, defineCommand as p, createDynamicCompleteCommand as r, CompletionDirective as s, generateZshCompletion as t, extractCompletionData as u };
-//# sourceMappingURL=zsh-hjvdI8uZ.js.map
+//#region src/completion/index.ts
+/**
+* Shell completion generation module
+*
+* Provides utilities to generate shell completion scripts for bash, zsh, and fish.
+*
+* @example
+* ```typescript
+* import { generateCompletion, createCompletionCommand } from "politty/completion";
+*
+* // Generate completion script directly
+* const result = generateCompletion(myCommand, {
+*   shell: "bash",
+*   programName: "mycli"
+* });
+* console.log(result.script);
+*
+* // Or add a completion subcommand to your CLI
+* const mainCommand = withCompletionCommand(
+*   defineCommand({
+*     name: "mycli",
+*     subCommands: { ... },
+*   }),
+* );
+* ```
+*/
+/**
+* Generate completion script for the specified shell
+*/
+function generateCompletion(command, options) {
+	switch (options.shell) {
+		case "bash": return generateBashCompletion(command, options);
+		case "zsh": return generateZshCompletion(command, options);
+		case "fish": return generateFishCompletion(command, options);
+		default: throw new Error(`Unsupported shell: ${options.shell}`);
+	}
+}
+/**
+* Get the list of supported shells
+*/
+function getSupportedShells() {
+	return [
+		"bash",
+		"zsh",
+		"fish"
+	];
+}
+/**
+* Detect the current shell from environment
+*/
+function detectShell() {
+	const shellName = (process.env.SHELL || "").split("/").pop()?.toLowerCase() || "";
+	if (shellName.includes("bash")) return "bash";
+	if (shellName.includes("zsh")) return "zsh";
+	if (shellName.includes("fish")) return "fish";
+	return null;
+}
+/**
+* Schema for the completion command arguments
+*/
+const completionArgsSchema = z.object({
+	shell: arg(z.enum([
+		"bash",
+		"zsh",
+		"fish"
+	]).optional().describe("Shell type (auto-detected if not specified)"), {
+		positional: true,
+		description: "Shell type (bash, zsh, or fish)",
+		placeholder: "SHELL"
+	}),
+	instructions: arg(z.boolean().default(false), {
+		alias: "i",
+		description: "Show installation instructions"
+	})
+});
+/**
+* Create a completion subcommand for your CLI
+*
+* This creates a ready-to-use subcommand that generates completion scripts.
+*
+* @example
+* ```typescript
+* const mainCommand = defineCommand({
+*   name: "mycli",
+*   subCommands: {
+*     completion: createCompletionCommand(mainCommand)
+*   }
+* });
+* ```
+*/
+function createCompletionCommand(rootCommand, programName, globalArgsSchema) {
+	const resolvedProgramName = programName ?? rootCommand.name;
+	if (!rootCommand.subCommands?.__complete) rootCommand.subCommands = {
+		...rootCommand.subCommands,
+		__complete: createDynamicCompleteCommand(rootCommand, resolvedProgramName)
+	};
+	return defineCommand({
+		name: "completion",
+		description: "Generate shell completion script",
+		args: completionArgsSchema,
+		run(args) {
+			const shellType = args.shell || detectShell();
+			if (!shellType) {
+				console.error("Could not detect shell type. Please specify one of: bash, zsh, fish");
+				process.exitCode = 1;
+				return;
+			}
+			const result = generateCompletion(rootCommand, {
+				shell: shellType,
+				programName: resolvedProgramName,
+				includeDescriptions: true,
+				...globalArgsSchema !== void 0 && { globalArgsSchema }
+			});
+			if (args.instructions) console.log(result.installInstructions);
+			else console.log(result.script);
+		}
+	});
+}
+/**
+* Wrap a command with a completion subcommand
+*
+* This avoids circular references that occur when a command references itself
+* in its subCommands (e.g., for completion generation).
+*
+* @param command - The command to wrap
+* @param options - Options including programName
+* @returns A new command with the completion subcommand added
+*
+* @example
+* ```typescript
+* const mainCommand = withCompletionCommand(
+*   defineCommand({
+*     name: "mycli",
+*     subCommands: { ... },
+*   }),
+* );
+* ```
+*/
+function withCompletionCommand(command, options) {
+	const { programName, globalArgsSchema } = typeof options === "string" ? { programName: options } : options ?? {};
+	const wrappedCommand = { ...command };
+	wrappedCommand.subCommands = {
+		...command.subCommands,
+		completion: createCompletionCommand(wrappedCommand, programName, globalArgsSchema),
+		__complete: createDynamicCompleteCommand(wrappedCommand, programName)
+	};
+	return wrappedCommand;
+}
+
+//#endregion
+export { withCompletionCommand as a, formatForShell as c, generateCandidates as d, extractCompletionData as f, defineCommand as g, createDefineCommand as h, getSupportedShells as i, parseCompletionContext as l, resolveValueCompletion as m, detectShell as n, createDynamicCompleteCommand as o, extractPositionals as p, generateCompletion as r, hasCompleteCommand as s, createCompletionCommand as t, CompletionDirective as u };
+//# sourceMappingURL=completion-_AnQsWh9.js.map