politty 0.5.0 → 0.5.1

package/dist/completion/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_completion = require('../completion-Cqs1Ja7C.cjs');
+const require_completion = require('../completion-BFOAOg95.cjs');
 
 exports.CompletionDirective = require_completion.CompletionDirective;
 exports.createCompletionCommand = require_completion.createCompletionCommand;

package/dist/completion/index.d.cts

@@ -1,3 +1,3 @@
 import { f as CompletionDirectiveMask, g as DynamicCompletionResult, h as DynamicCompletionResolver, m as DynamicCompletionContext, p as DynamicCompletionCandidate } from "../arg-registry--NRaNFJM.cjs";
-import { C as CompletableOption, D as CompletionOptions, E as CompletionGenerator, O as CompletionResult, S as parseCompletionContext, T as CompletionData, _ as CompletionCandidate, a as generateCompletion, b as CompletionContext, c as ValueCompletionField, d as extractPositionals, f as ShellFormatOptions, g as CandidateResult, h as hasCompleteCommand, i as detectShell, k as ShellType, l as resolveValueCompletion, m as createDynamicCompleteCommand, n as createCompletionCommand, o as getSupportedShells, p as formatForShell, r as createRefreshCompletionCommand, s as withCompletionCommand, t as WithCompletionOptions, u as extractCompletionData, v as CompletionDirective, w as CompletableSubcommand, x as CompletionType, y as generateCandidates } from "../index-DJp8k5Bq.cjs";
+import { C as CompletableOption, D as CompletionOptions, E as CompletionGenerator, O as CompletionResult, S as parseCompletionContext, T as CompletionData, _ as CompletionCandidate, a as generateCompletion, b as CompletionContext, c as ValueCompletionField, d as extractPositionals, f as ShellFormatOptions, g as CandidateResult, h as hasCompleteCommand, i as detectShell, k as ShellType, l as resolveValueCompletion, m as createDynamicCompleteCommand, n as createCompletionCommand, o as getSupportedShells, p as formatForShell, r as createRefreshCompletionCommand, s as withCompletionCommand, t as WithCompletionOptions, u as extractCompletionData, v as CompletionDirective, w as CompletableSubcommand, x as CompletionType, y as generateCandidates } from "../index-Cg8qstsT.cjs";
 export { type CandidateResult, type CompletableOption, type CompletableSubcommand, type CompletionCandidate, type CompletionContext, type CompletionData, CompletionDirective, type CompletionDirectiveMask, type CompletionGenerator, type CompletionOptions, type CompletionResult, type CompletionType, type DynamicCompletionCandidate, type DynamicCompletionContext, type DynamicCompletionResolver, type DynamicCompletionResult, type ShellFormatOptions, type ShellType, type ValueCompletionField, WithCompletionOptions, createCompletionCommand, createDynamicCompleteCommand, createRefreshCompletionCommand, detectShell, extractCompletionData, extractPositionals, formatForShell, generateCandidates, generateCompletion, getSupportedShells, hasCompleteCommand, parseCompletionContext, resolveValueCompletion, withCompletionCommand };

package/dist/completion/index.d.ts

@@ -1,3 +1,3 @@
 import { f as CompletionDirectiveMask, g as DynamicCompletionResult, h as DynamicCompletionResolver, m as DynamicCompletionContext, p as DynamicCompletionCandidate } from "../arg-registry-6E0WHOh_.js";
-import { C as CompletableOption, D as CompletionOptions, E as CompletionGenerator, O as CompletionResult, S as parseCompletionContext, T as CompletionData, _ as CompletionCandidate, a as generateCompletion, b as CompletionContext, c as ValueCompletionField, d as extractPositionals, f as ShellFormatOptions, g as CandidateResult, h as hasCompleteCommand, i as detectShell, k as ShellType, l as resolveValueCompletion, m as createDynamicCompleteCommand, n as createCompletionCommand, o as getSupportedShells, p as formatForShell, r as createRefreshCompletionCommand, s as withCompletionCommand, t as WithCompletionOptions, u as extractCompletionData, v as CompletionDirective, w as CompletableSubcommand, x as CompletionType, y as generateCandidates } from "../index-DBMfKZ34.js";
+import { C as CompletableOption, D as CompletionOptions, E as CompletionGenerator, O as CompletionResult, S as parseCompletionContext, T as CompletionData, _ as CompletionCandidate, a as generateCompletion, b as CompletionContext, c as ValueCompletionField, d as extractPositionals, f as ShellFormatOptions, g as CandidateResult, h as hasCompleteCommand, i as detectShell, k as ShellType, l as resolveValueCompletion, m as createDynamicCompleteCommand, n as createCompletionCommand, o as getSupportedShells, p as formatForShell, r as createRefreshCompletionCommand, s as withCompletionCommand, t as WithCompletionOptions, u as extractCompletionData, v as CompletionDirective, w as CompletableSubcommand, x as CompletionType, y as generateCandidates } from "../index-O3yn97Ed.js";
 export { type CandidateResult, type CompletableOption, type CompletableSubcommand, type CompletionCandidate, type CompletionContext, type CompletionData, CompletionDirective, type CompletionDirectiveMask, type CompletionGenerator, type CompletionOptions, type CompletionResult, type CompletionType, type DynamicCompletionCandidate, type DynamicCompletionContext, type DynamicCompletionResolver, type DynamicCompletionResult, type ShellFormatOptions, type ShellType, type ValueCompletionField, WithCompletionOptions, createCompletionCommand, createDynamicCompleteCommand, createRefreshCompletionCommand, detectShell, extractCompletionData, extractPositionals, formatForShell, generateCandidates, generateCompletion, getSupportedShells, hasCompleteCommand, parseCompletionContext, resolveValueCompletion, withCompletionCommand };

package/dist/completion/index.js

@@ -1,3 +1,3 @@
-import { a as getSupportedShells, c as hasCompleteCommand, d as extractPositionals, f as CompletionDirective, h as resolveValueCompletion, i as generateCompletion, l as formatForShell, m as parseCompletionContext, n as createRefreshCompletionCommand, o as withCompletionCommand, p as generateCandidates, r as detectShell, s as createDynamicCompleteCommand, t as createCompletionCommand, u as extractCompletionData } from "../completion-BA5JMvVG.js";
+import { a as getSupportedShells, c as hasCompleteCommand, d as extractPositionals, f as CompletionDirective, h as resolveValueCompletion, i as generateCompletion, l as formatForShell, m as parseCompletionContext, n as createRefreshCompletionCommand, o as withCompletionCommand, p as generateCandidates, r as detectShell, s as createDynamicCompleteCommand, t as createCompletionCommand, u as extractCompletionData } from "../completion-K5LGh1hO.js";
 
 export { CompletionDirective, createCompletionCommand, createDynamicCompleteCommand, createRefreshCompletionCommand, detectShell, extractCompletionData, extractPositionals, formatForShell, generateCandidates, generateCompletion, getSupportedShells, hasCompleteCommand, parseCompletionContext, resolveValueCompletion, withCompletionCommand };

package/dist/{completion-Cqs1Ja7C.cjs → completion-BFOAOg95.cjs}

@@ -1924,6 +1924,87 @@ function buildHeaderLines(opts) {
 	return lines;
 }
 
+//#endregion
+//#region src/completion/self-refresh.ts
+/**
+* Self-refresh guards embedded in generated bash/zsh scripts.
+*
+* These guards make the default `completion <shell>` output safe to
+* save as a static completion file: when the CLI binary changes, the
+* script asks the hidden refresh subcommand to rewrite the sourced
+* file in place, then sources the fresh file and stops executing the
+* stale body.
+*/
+function statSigExpr() {
+	return `$(stat -L -c '%Y' "$_bin" 2>/dev/null || stat -L -f '%m' "$_bin" 2>/dev/null)`;
+}
+function generateBashSelfRefresh(opts) {
+	const { programName, binPath } = opts;
+	const fn = sanitize(programName);
+	const sig = computeBinSig(resolveBinPath(programName, binPath));
+	const refreshFn = `__${fn}_self_refresh`;
+	return [
+		`${refreshFn}() {`,
+		`    local _self _bin _sig`,
+		`    _self=\${BASH_SOURCE[0]:-}`,
+		`    [[ -n "$_self" && -f "$_self" ]] || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# politty-completion-version:" || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# program: ${programName}" || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# shell: bash" || return 1`,
+		`    _bin=$(type -P ${programName} 2>/dev/null)`,
+		`    [[ -n "$_bin" ]] || return 1`,
+		`    _sig=${statSigExpr()} || return 1`,
+		`    [[ "$_sig" != "${sig}" ]] || return 1`,
+		`    "$_bin" __refresh-completion bash "$_self" 2>/dev/null || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# politty-bin-sig: $_sig" || return 1`,
+		`    source "$_self" 2>/dev/null || return 1`,
+		`    return 0`,
+		`}`,
+		`if ${refreshFn}; then`,
+		`    unset -f ${refreshFn}`,
+		`    return 0 2>/dev/null || true`,
+		`else`,
+		`    unset -f ${refreshFn}`,
+		`fi`,
+		``
+	];
+}
+function generateZshSelfRefresh(opts) {
+	const { programName, binPath } = opts;
+	const fn = sanitize(programName);
+	const completionFn = `_${programName}`;
+	const sig = computeBinSig(resolveBinPath(programName, binPath));
+	const refreshFn = `__${fn}_self_refresh`;
+	return [
+		`${refreshFn}() {`,
+		`    emulate -L zsh`,
+		`    setopt local_options no_aliases`,
+		`    local _self _bin _sig`,
+		`    _self="\${(%):-%x}"`,
+		`    [[ -n "$_self" && -f "$_self" ]] || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# politty-completion-version:" || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# program: ${programName}" || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# shell: zsh" || return 1`,
+		`    _bin=$(whence -p ${programName} 2>/dev/null)`,
+		`    [[ -n "$_bin" ]] || return 1`,
+		`    _sig=${statSigExpr()} || return 1`,
+		`    [[ "$_sig" != "${sig}" ]] || return 1`,
+		`    "$_bin" __refresh-completion zsh "$_self" 2>/dev/null || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# politty-bin-sig: $_sig" || return 1`,
+		`    source "$_self" 2>/dev/null || return 1`,
+		`    ${completionFn} "$@"`,
+		`    return 0`,
+		`}`,
+		`if ${refreshFn} "$@"; then`,
+		`    unfunction ${refreshFn} 2>/dev/null`,
+		`    return 0 2>/dev/null || true`,
+		`else`,
+		`    unfunction ${refreshFn} 2>/dev/null`,
+		`fi`,
+		``
+	];
+}
+
 //#endregion
 //#region src/completion/bash.ts
 /** Escape a string for use inside bash double-quotes */
@@ -2186,6 +2267,10 @@ function generateBashCompletion(command, options) {
 	}));
 	lines.push(`# Generated by politty`);
 	lines.push(``);
+	lines.push(...generateBashSelfRefresh({
+		programName,
+		binPath: options.binPath
+	}));
 	const hasExpand = expandSpecs.length > 0;
 	const arrayExpandSpecs = expandSpecs.filter((s) => s.isArrayOption);
 	const hasArrayExpand = arrayExpandSpecs.length > 0;
@@ -2430,12 +2515,11 @@ function generateBashCompletion(command, options) {
 	return {
 		script: lines.join("\n"),
 		shell: "bash",
-		installInstructions: `# To enable completions, add the following to your ~/.bashrc:
-
-# Option 1: Source directly
+		installInstructions: `# To enable auto-refreshing bash completions, add this to your ~/.bashrc:
 eval "$(${programName} completion bash)"
 
-# Option 2: Save to a file
+# For faster shell startup, save the script instead:
+mkdir -p ~/.local/share/bash-completion/completions
 ${programName} completion bash > ~/.local/share/bash-completion/completions/${programName}
 
 # Then reload your shell or run:
@@ -2819,8 +2903,9 @@ function generateFishCompletion(command, options) {
 	lines.push(`    test -z "$_bin"; and return 1`);
 	lines.push(`    set -l _sig (stat -L -c '%Y' "$_bin" 2>/dev/null; or stat -L -f '%m' "$_bin" 2>/dev/null)`);
 	lines.push(`    test "$_sig" = "${sig}"; and return 1`);
-	lines.push(`    set -l _target "$__fish_config_dir/completions/${programName}.fish"`);
-	lines.push(`    "$_bin" __refresh-completion fish 2>/dev/null`);
+	lines.push(`    set -l _target (status current-filename)`);
+	lines.push(`    test -n "$_target"; and test -f "$_target"; or return 1`);
+	lines.push(`    "$_bin" __refresh-completion fish "$_target" 2>/dev/null`);
 	lines.push(`    and source "$_target" 2>/dev/null`);
 	lines.push(`    and return 0`);
 	lines.push(`    return 1`);
@@ -3097,17 +3182,8 @@ function generateFishCompletion(command, options) {
 	return {
 		script: lines.join("\n"),
 		shell: "fish",
-		installInstructions: `# To enable completions, run one of the following:
-
-# Option 1: Source directly
-${programName} completion fish | source
-
-# Option 2: Save to the fish completions directory
-${programName} completion fish > ~/.config/fish/completions/${programName}.fish
-
-# The completion will be available immediately in new shell sessions.
-# To use in the current session, run:
-source ~/.config/fish/completions/${programName}.fish`
+		installInstructions: `# To enable auto-refreshing fish completions, run:
+${programName} completion fish --install`
 	};
 }
 
@@ -3136,11 +3212,11 @@ source ~/.config/fish/completions/${programName}.fish`
 * from env / config — we must not let metachars in the path execute as
 * commands when the rc snippet is sourced.
 */
-function shSingleQuote(s) {
+function shSingleQuote$1(s) {
 	return `'${s.replace(/'/g, "'\\''")}'`;
 }
 function bashCachePathExpr(programName, cacheDir, shell) {
-	if (cacheDir) return shSingleQuote(`${cacheDir}/completion.${shell}`);
+	if (cacheDir) return shSingleQuote$1(`${cacheDir}/completion.${shell}`);
 	return `"\${XDG_CACHE_HOME:-$HOME/.cache}/${programName}/completion.${shell}"`;
 }
 function generateBashLoader(opts) {
@@ -3284,6 +3360,15 @@ function readCachedSig(path) {
 		return null;
 	}
 }
+function isManagedTarget(path, programName, shell) {
+	try {
+		if (!(0, node_fs.existsSync)(path)) return false;
+		const head = (0, node_fs.readFileSync)(path, "utf8").split("\n", 8).join("\n");
+		return /^# politty-completion-version: \S+/m.test(head) && head.includes(`# program: ${programName}`) && head.includes(`# shell: ${shell}`);
+	} catch {
+		return false;
+	}
+}
 /**
 * Rewrite the cache only when stale. Used by:
 *   - `<program> __refresh-completion <shell>` (the hidden subcommand
@@ -3299,7 +3384,8 @@ function readCachedSig(path) {
 */
 function refreshIfStale(ctx, shell) {
 	try {
-		const target = installPath(ctx.programName, shell, ctx.cacheDir);
+		const target = ctx.targetPath ? (0, node_fs.realpathSync)(ctx.targetPath) : installPath(ctx.programName, shell, ctx.cacheDir);
+		if (ctx.targetPath && !isManagedTarget(target, ctx.programName, shell)) return;
 		const binPath = resolveBinPath(ctx.programName, ctx.binPath);
 		if (!binPath) return;
 		let currentSig;
@@ -3361,6 +3447,10 @@ function escapeDesc(s) {
 function escapeDescribeValue(s) {
 	return s.replace(/\\/g, "\\\\").replace(/:/g, "\\:");
 }
+/** Escape a string for use inside zsh double-quotes. */
+function escapeZshDQ(s) {
+	return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\$/g, "\\$").replace(/`/g, "\\`");
+}
 /**
 * Generate zsh value completion lines for a ValueCompletion spec.
 * Uses `_vals` array (must be declared in the calling function scope).
@@ -3547,6 +3637,8 @@ function generateZshCompletion(command, options) {
 	const { programName } = options;
 	const data = extractCompletionData(command, programName, options.globalArgsSchema);
 	const fn = sanitize(programName);
+	const completionFn = `_${programName}`;
+	const autoloadCheck = `"\${funcstack[1]:-}" == "${escapeZshDQ(completionFn)}"`;
 	const root = data.command;
 	const visibleSubs = getVisibleSubs(root.subcommands);
 	const expandSpecs = collectExpandSpecs(root);
@@ -3565,6 +3657,10 @@ function generateZshCompletion(command, options) {
 	}));
 	lines.push(`# Generated by politty`);
 	lines.push(``);
+	lines.push(...generateZshSelfRefresh({
+		programName,
+		binPath: options.binPath
+	}));
 	for (const spec of expandSpecs) {
 		const varName = expandTableVarName(fn, spec.funcSuffix, spec.fieldName);
 		if (spec.vc.table.length === 0) lines.push(`typeset -gA ${varName}=()`);
@@ -3707,7 +3803,7 @@ function generateZshCompletion(command, options) {
 	lines.push(`}`);
 	lines.push(``);
 	const subRouting = subDispatchCaseLines(routeEntries, fn).join("\n");
-	lines.push(`_${fn}() {`);
+	lines.push(`${completionFn}() {`);
 	lines.push(`    (( CURRENT )) || CURRENT=\${#words}`);
 	lines.push(``);
 	lines.push(`    local _subcmd="" _after_dd=0 _pos_count=0 _skip_next=0`);
@@ -3773,22 +3869,28 @@ function generateZshCompletion(command, options) {
 	lines.push(``);
 	lines.push(`zstyle ':completion:*:*:${programName}:*' file-patterns '%p:globbed-files *(-/):directories'`);
 	lines.push(``);
-	lines.push(`compdef _${fn} ${programName}`);
+	lines.push(`if [[ ${autoloadCheck} ]]; then`);
+	lines.push(`    ${completionFn} "$@"`);
+	lines.push(`else`);
+	lines.push(`    compdef ${completionFn} ${programName}`);
+	lines.push(`fi`);
 	lines.push(``);
 	return {
 		script: lines.join("\n"),
 		shell: "zsh",
-		installInstructions: `# To enable completions, add the following to your ~/.zshrc:
-
-# Option 1: Source directly (add before compinit)
+		installInstructions: `# To enable auto-refreshing zsh completions, add this to your ~/.zshrc after compinit:
 eval "$(${programName} completion zsh)"
 
-# Option 2: Save to a file in your fpath
+# For faster shell startup, save the script in your fpath:
+mkdir -p ~/.zsh/completions
 ${programName} completion zsh > ~/.zsh/completions/_${programName}
 
-# Make sure your fpath includes the completions directory:
-# fpath=(~/.zsh/completions $fpath)
-# autoload -Uz compinit && compinit
+# Make sure your ~/.zshrc includes the fpath line before compinit:
+fpath=(~/.zsh/completions $fpath)
+autoload -Uz compinit && compinit
+
+# If ~/.zshrc already calls compinit, add only the fpath line before
+# the existing compinit call.
 
 # Then reload your shell or run:
 source ~/.zshrc`
@@ -3843,6 +3945,21 @@ function getSupportedShells() {
 		"fish"
 	];
 }
+function shSingleQuote(s) {
+	return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function printZshFpathSetup(programName, target) {
+	console.error("");
+	console.error("Configure zsh fpath with:");
+	console.error("");
+	console.error("    mkdir -p ~/.zsh/completions");
+	console.error(`    ln -sf ${shSingleQuote(target)} ~/.zsh/completions/_${programName}`);
+	console.error("");
+	console.error("Add only this block to your ~/.zshrc before compinit:");
+	console.error("");
+	console.error("    fpath=(~/.zsh/completions $fpath)");
+	console.error("    autoload -Uz compinit && compinit");
+}
 /**
 * Detect the current shell from environment
 */
@@ -3873,15 +3990,22 @@ const completionArgsSchema = zod.z.object({
 	loader: require_schema_extractor.arg(zod.z.boolean().default(false), { description: "Print just the rc loader snippet (bash/zsh). Add it to ~/.bashrc or ~/.zshrc; it auto-regenerates the cache when the binary changes." }),
 	install: require_schema_extractor.arg(zod.z.boolean().default(false), { description: "Write the completion script to its on-disk cache (bash/zsh) or autoload location (fish) instead of printing it." })
 });
-const refreshArgsSchema = zod.z.object({ shell: require_schema_extractor.arg(zod.z.enum([
-	"bash",
-	"zsh",
-	"fish"
-]), {
-	positional: true,
-	description: "Shell to refresh",
-	placeholder: "SHELL"
-}) });
+const refreshArgsSchema = zod.z.object({
+	shell: require_schema_extractor.arg(zod.z.enum([
+		"bash",
+		"zsh",
+		"fish"
+	]), {
+		positional: true,
+		description: "Shell to refresh",
+		placeholder: "SHELL"
+	}),
+	target: require_schema_extractor.arg(zod.z.string().optional(), {
+		positional: true,
+		description: "Existing politty-generated completion file to refresh",
+		placeholder: "TARGET"
+	})
+});
 /**
 * Create a completion subcommand for your CLI
 *
@@ -3943,7 +4067,7 @@ function createCompletionCommand(rootCommand, programName, globalArgsSchema, ext
 					throw new Error(`install failed: ${e instanceof Error ? e.message : String(e)}`);
 				}
 				console.error(`installed: ${target}`);
-				if (shellType !== "fish") {
+				if (shellType === "bash") {
 					console.error("");
 					console.error(`Add to your ~/.${shellType}rc:`);
 					console.error("");
@@ -3951,7 +4075,7 @@ function createCompletionCommand(rootCommand, programName, globalArgsSchema, ext
 						...loaderOptsBase,
 						shell: shellType
 					}).trim().replace(/^/gm, "    "));
-				}
+				} else if (shellType === "zsh") printZshFpathSetup(resolvedProgramName, target);
 				return;
 			}
 			if (args.loader) {
@@ -3989,7 +4113,8 @@ function createRefreshCompletionCommand(rootCommand, programName, extra = {}) {
 			refreshIfStale({
 				rootCommand,
 				programName,
-				...extra
+				...extra,
+				...args.target !== void 0 && { targetPath: args.target }
 			}, args.shell);
 		}
 	});
@@ -4166,4 +4291,4 @@ Object.defineProperty(exports, 'withCompletionCommand', {
     return withCompletionCommand;
   }
 });
-//# sourceMappingURL=completion-Cqs1Ja7C.cjs.map
+//# sourceMappingURL=completion-BFOAOg95.cjs.map