politty 0.4.15 → 0.4.16

package/dist/{completion-B5fgnUGm.cjs → completion-BlZxMSeU.cjs}

@@ -1,6 +1,8 @@
 const require_log_collector = require('./log-collector-Cd2_mv87.cjs');
-const require_subcommand_router = require('./subcommand-router-CqZX3orq.cjs');
+const require_subcommand_router = require('./subcommand-router-DQy0KZU-.cjs');
 let zod = require("zod");
+let node_fs = require("node:fs");
+let node_path = require("node:path");
 let node_child_process = require("node:child_process");
 
 //#region src/core/command.ts
@@ -139,6 +141,8 @@ function fieldToOption(field) {
 		name: field.name,
 		cliName: field.cliName,
 		alias: field.alias,
+		negation: field.negationDisplay,
+		negationDescription: field.negationDescription,
 		description: field.description,
 		takesValue: field.type !== "boolean",
 		valueType: field.type,
@@ -290,6 +294,79 @@ function extractCompletionData(command, programName, globalArgsSchema) {
 	};
 }
 
+//#endregion
+//#region src/completion/header.ts
+/**
+* Static-script header utilities.
+*
+* Every completion script generated by politty starts with a small
+* machine-readable header. The rc loader and the runMain background
+* refresh path use the `# politty-bin-sig:` line to detect when the
+* cached script is stale relative to the binary on disk.
+*/
+/** Schema version of the header itself. Bump when the header layout changes. */
+const COMPLETION_VERSION = 1;
+/**
+* Read the binary's mtime in whole seconds (matches POSIX `stat -c %Y` /
+* BSD `stat -f %m`). Returns `"0"` on failure so the header is always
+* well-formed.
+*/
+function computeBinSig(binPath) {
+	try {
+		return Math.floor((0, node_fs.statSync)(binPath).mtimeMs / 1e3).toString();
+	} catch {
+		return "0";
+	}
+}
+/**
+* Walk `$PATH` looking for an executable named `programName`. Returns
+* the first match's full path, or `null` when not found. We mirror the
+* shell's `command -v <prog>` here so the sig embedded in the header
+* (computed by Node) lines up with what the rc loader stat-checks at
+* runtime — including pnpm/npm bin shims that wrap the real entrypoint.
+* Without this alignment, shimmed installs would never match the
+* embedded sig and the cache would regenerate on every shell startup.
+*/
+function findOnPath(programName) {
+	if (!programName || /[/\\\0]/.test(programName)) return null;
+	const path = process.env.PATH ?? "";
+	for (const dir of path.split(":")) {
+		if (!dir) continue;
+		const candidate = (0, node_path.join)(dir, programName);
+		try {
+			if ((0, node_fs.statSync)(candidate).isFile()) return candidate;
+		} catch {}
+	}
+	return null;
+}
+/**
+* Resolve the binary path used for sig computation and stat checks.
+*
+* Order: explicit override → `$PATH` lookup of `programName` → `process.argv[1]`.
+* The `$PATH` lookup keeps Node-side and shell-side stats pointed at the
+* same shim file when the CLI is invoked through a package-manager bin shim.
+*/
+function resolveBinPath(programName, override) {
+	if (override) return override;
+	return findOnPath(programName) ?? process.argv[1] ?? "";
+}
+/**
+* Build the header lines (no trailing blank line). Returned without a
+* leading `#!` so each generator can prepend its own shebang/compdef
+* marker.
+*/
+function buildHeaderLines(opts) {
+	const sig = computeBinSig(resolveBinPath(opts.programName, opts.binPath));
+	const lines = [
+		`# politty-completion-version: ${1}`,
+		`# politty-bin-sig: ${sig}`,
+		`# program: ${opts.programName}`
+	];
+	if (opts.programVersion) lines.push(`# program-version: ${opts.programVersion}`);
+	lines.push(`# shell: ${opts.shell}`);
+	return lines;
+}
+
 //#endregion
 //#region src/completion/bash.ts
 /** Escape a string for use inside bash double-quotes */
@@ -417,7 +494,9 @@ function availableOptionLines$2(options, fn) {
 	else {
 		const patterns = [`"--${opt.cliName}"`];
 		if (opt.alias) for (const a of opt.alias) patterns.push(a.length === 1 ? `"-${a}"` : `"--${a}"`);
+		if (opt.negation) patterns.push(`"--${opt.negation}"`);
 		lines.push(`        __${fn}_not_used ${patterns.join(" ")} && _avail+=(--${opt.cliName})`);
+		if (opt.negation) lines.push(`        __${fn}_not_used ${patterns.join(" ")} && _avail+=(--${opt.negation})`);
 	}
 	lines.push(`        __${fn}_not_used "--help" && _avail+=(--help)`);
 	return lines;
@@ -466,7 +545,12 @@ function generateBashCompletion(command, options) {
 	const root = data.command;
 	const visibleSubs = getVisibleSubs(root.subcommands);
 	const lines = [];
-	lines.push(`# Bash completion for ${programName}`);
+	lines.push(...buildHeaderLines({
+		programName,
+		shell: "bash",
+		binPath: options.binPath,
+		programVersion: options.programVersion
+	}));
 	lines.push(`# Generated by politty`);
 	lines.push(``);
 	lines.push(`__${fn}_not_used() {`);
@@ -605,13 +689,21 @@ source ~/.bashrc`
 * Completion directive flags (bitwise)
 */
 const CompletionDirective = {
+	/** Default completion behavior */
 	Default: 0,
+	/** Don't add space after completion */
 	NoSpace: 1,
+	/** Don't offer file completion (even if no other completions) */
 	NoFileCompletion: 2,
+	/** Filter completions using current word as prefix */
 	FilterPrefix: 4,
+	/** Keep the order of completions */
 	KeepOrder: 8,
+	/** Trigger file completion */
 	FileCompletion: 16,
+	/** Trigger directory completion */
 	DirectoryCompletion: 32,
+	/** Error occurred during completion */
 	Error: 64
 };
 /**
@@ -737,13 +829,21 @@ function generateOptionNameCandidates(context) {
 		if (opt.valueType === "array") return true;
 		if (context.usedOptions.has(opt.cliName)) return false;
 		if (opt.alias && opt.alias.some((a) => context.usedOptions.has(a))) return false;
+		if (opt.negation && context.usedOptions.has(opt.negation)) return false;
 		return true;
 	});
-	for (const opt of availableOptions) candidates.push({
-		value: `--${opt.cliName}`,
-		description: opt.description,
-		type: "option"
-	});
+	for (const opt of availableOptions) {
+		candidates.push({
+			value: `--${opt.cliName}`,
+			description: opt.description,
+			type: "option"
+		});
+		if (opt.negation) candidates.push({
+			value: `--${opt.negation}`,
+			description: opt.negationDescription ?? opt.description,
+			type: "option"
+		});
+	}
 	if (!context.usedOptions.has("help")) candidates.push({
 		value: "--help",
 		description: "Show help information",
@@ -809,6 +909,8 @@ function extractOptions(command) {
 		name: field.name,
 		cliName: field.cliName,
 		alias: field.alias,
+		negation: field.negationDisplay,
+		negationDescription: field.negationDescription,
 		description: field.description,
 		takesValue: field.type !== "boolean",
 		valueType: field.type,
@@ -890,6 +992,10 @@ function findOption(options, nameOrAlias) {
 		if (nameOrAlias.length > 1) {
 			if (opt.cliName.includes("-") && require_subcommand_router.toCamelCase(opt.cliName) === nameOrAlias) return true;
 			if (opt.alias?.some((a) => a.includes("-") && require_subcommand_router.toCamelCase(a) === nameOrAlias)) return true;
+			if (opt.negation) {
+				if (opt.negation === nameOrAlias) return true;
+				if (opt.negation.includes("-") && require_subcommand_router.toCamelCase(opt.negation) === nameOrAlias) return true;
+			}
 		}
 		return false;
 	});
@@ -922,6 +1028,7 @@ function parseCompletionContext(argv, rootCommand) {
 			if (opt) {
 				usedOptions.add(opt.cliName);
 				if (opt.alias) for (const a of opt.alias) usedOptions.add(a);
+				if (opt.negation) usedOptions.add(opt.negation);
 				if (opt.takesValue && !hasInlineValue(word)) i++;
 			}
 			i++;
@@ -1240,11 +1347,14 @@ function availableOptionLines$1(options, fn) {
 	const lines = [];
 	for (const opt of options) {
 		const desc = escapeDesc$1(opt.description ?? "");
+		const negDesc = opt.negationDescription ? escapeDesc$1(opt.negationDescription) : desc;
 		if (opt.valueType === "array") lines.push(`        echo "--${opt.cliName}\t${desc}"`);
 		else {
 			const checks = [`"--${opt.cliName}"`];
 			if (opt.alias) for (const a of opt.alias) checks.push(a.length === 1 ? `"-${a}"` : `"--${a}"`);
+			if (opt.negation) checks.push(`"--${opt.negation}"`);
 			lines.push(`        __${fn}_not_used ${checks.join(" ")}; and echo "--${opt.cliName}\t${desc}"`);
+			if (opt.negation) lines.push(`        __${fn}_not_used ${checks.join(" ")}; and echo "--${opt.negation}\t${negDesc}"`);
 		}
 	}
 	lines.push(`        __${fn}_not_used "--help"; and echo "--help\tShow help"`);
@@ -1314,9 +1424,32 @@ function generateFishCompletion(command, options) {
 	const root = data.command;
 	const visibleSubs = getVisibleSubs(root.subcommands);
 	const lines = [];
-	lines.push(`# Fish completion for ${programName}`);
+	lines.push(...buildHeaderLines({
+		programName,
+		shell: "fish",
+		binPath: options.binPath,
+		programVersion: options.programVersion
+	}));
 	lines.push(`# Generated by politty`);
 	lines.push(``);
+	const sig = computeBinSig(resolveBinPath(programName, options.binPath));
+	const refreshFn = `__${fn}_refresh_completion`;
+	lines.push(`function ${refreshFn} --no-scope-shadowing`);
+	lines.push(`    set -l _bin (command -v ${programName})`);
+	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(`    and source "$_target" 2>/dev/null`);
+	lines.push(`    and return 0`);
+	lines.push(`    return 1`);
+	lines.push(`end`);
+	lines.push(`${refreshFn}`);
+	lines.push(`set -l _politty_refreshed $status`);
+	lines.push(`functions -e ${refreshFn}`);
+	lines.push(`test $_politty_refreshed -eq 0; and return`);
+	lines.push(``);
 	lines.push(`function __${fn}_not_used --no-scope-shadowing`);
 	lines.push(`    for _chk in $argv`);
 	lines.push(`        if contains -- "$_chk" $_used_opts`);
@@ -1442,6 +1575,241 @@ source ~/.config/fish/completions/${programName}.fish`
 	};
 }
 
+//#endregion
+//#region src/completion/loader.ts
+/**
+* Rc-loader generators (bash / zsh).
+*
+* These produce the small snippet a user adds once to `~/.bashrc` or
+* `~/.zshrc`. The snippet:
+*
+*   1. Looks up the binary on $PATH.
+*   2. Reads its mtime.
+*   3. If the on-disk completion cache is missing or its
+*      `# politty-bin-sig:` header differs, regenerates the cache by
+*      spawning the binary once.
+*   4. Sources the cache.
+*
+* All failure modes are silent no-ops so a broken / missing CLI never
+* blocks shell startup.
+*/
+/**
+* Single-quote escape: `'` -> `'\''`. Inside single quotes the shell
+* performs no expansion at all, so `$`, backticks, and `$(...)` are
+* inert. Used for hardcoded paths because callers may sources them
+* from env / config — we must not let metachars in the path execute as
+* commands when the rc snippet is sourced.
+*/
+function shSingleQuote(s) {
+	return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function bashCachePathExpr(programName, cacheDir, shell) {
+	if (cacheDir) return shSingleQuote(`${cacheDir}/completion.${shell}`);
+	return `"\${XDG_CACHE_HOME:-$HOME/.cache}/${programName}/completion.${shell}"`;
+}
+function generateBashLoader(opts) {
+	const fn = sanitize(opts.programName);
+	const cache = bashCachePathExpr(opts.programName, opts.cacheDir, "bash");
+	return `__${fn}_load_completion() {
+    local _bin _cache _sig _hdr
+    _bin=$(type -P ${opts.programName} 2>/dev/null)
+    [[ -n "$_bin" ]] || return 0
+    _cache=${cache}
+    _sig=$(stat -L -c '%Y' "$_bin" 2>/dev/null || stat -L -f '%m' "$_bin" 2>/dev/null) || return 0
+    _hdr="# politty-bin-sig: $_sig"
+    if [[ ! -f "$_cache" ]] || ! head -5 "$_cache" 2>/dev/null | grep -qF "$_hdr"; then
+        # Use the hidden __refresh-completion subcommand instead of
+        # \`$_bin completion bash\`: the foreground completion command
+        # is subject to user setup/cleanup/prompt and required
+        # globalArgs validation, which can silently fail or block when
+        # invoked from rc; runMain bypasses those for __-prefixed
+        # internal subcommands.
+        "$_bin" __refresh-completion bash 2>/dev/null
+    fi
+    # If regen failed but a stale cache survived from a previous run,
+    # source it anyway — a stale completion is preferable to no
+    # completion at all.
+    [[ -f "$_cache" ]] || return 0
+    # shellcheck disable=SC1090
+    source "$_cache"
+}
+__${fn}_load_completion
+unset -f __${fn}_load_completion
+`;
+}
+function generateZshLoader(opts) {
+	const fn = sanitize(opts.programName);
+	const cache = bashCachePathExpr(opts.programName, opts.cacheDir, "zsh");
+	return `__${fn}_load_completion() {
+    emulate -L zsh
+    setopt local_options no_aliases
+    local _bin _cache _sig _hdr
+    _bin=$(whence -p ${opts.programName} 2>/dev/null)
+    [[ -n "$_bin" ]] || return 0
+    _cache=${cache}
+    _sig=$(stat -L -c '%Y' "$_bin" 2>/dev/null || stat -L -f '%m' "$_bin" 2>/dev/null) || return 0
+    _hdr="# politty-bin-sig: $_sig"
+    if [[ ! -f "$_cache" ]] || ! head -5 "$_cache" 2>/dev/null | grep -qF "$_hdr"; then
+        # See bash loader for why we use __refresh-completion instead
+        # of \`$_bin completion zsh\`.
+        "$_bin" __refresh-completion zsh 2>/dev/null
+    fi
+    # See bash loader: keep stale completion over no completion.
+    [[ -f "$_cache" ]] || return 0
+    source "$_cache"
+}
+__${fn}_load_completion
+unfunction __${fn}_load_completion
+`;
+}
+/**
+* Build the rc-loader snippet for bash or zsh. Fish doesn't have an
+* rc-loader; instead, `<program> completion fish --install` writes a
+* self-rewriting autoload file.
+*/
+function generateLoader(opts) {
+	switch (opts.shell) {
+		case "bash": return generateBashLoader(opts);
+		case "zsh": return generateZshLoader(opts);
+		case "fish": throw new Error("fish does not use an rc loader. Run `<program> completion fish --install` to write the self-refreshing autoload file instead.");
+	}
+}
+/**
+* Default cache file path (used by `completion <bash|zsh> --install`
+* and the `__refresh-completion` subcommand). For fish, the install
+* path is `$__fish_config_dir/completions/<program>.fish` and is
+* computed inside `installPath()` instead.
+*/
+function defaultCacheDir(programName) {
+	return `${process.env.XDG_CACHE_HOME ?? `${process.env.HOME ?? ""}/.cache`}/${programName}`;
+}
+
+//#endregion
+//#region src/completion/install.ts
+/**
+* On-disk install + refresh helpers.
+*
+* `install` writes the generated script to its canonical cache /
+* autoload path. `refresh` is the body of the `__refresh-completion`
+* hidden subcommand and the runMain background hook — it regenerates
+* the cache only when the binary's mtime no longer matches the
+* embedded `# politty-bin-sig:` header.
+*
+* All file I/O is best-effort: failures fall through silently. A stale
+* (or missing) cache is preferable to crashing the user's shell.
+*/
+/**
+* Resolve where a script for the given shell should live on disk.
+*
+* - bash/zsh: `<cacheDir>/completion.<shell>` — sourced by the rc loader.
+* - fish:    `$__fish_config_dir/completions/<program>.fish` — autoloaded
+*            by fish on TAB. We approximate `$__fish_config_dir` from
+*            `$XDG_CONFIG_HOME` / `$HOME`.
+*/
+function installPath(programName, shell, cacheDir) {
+	if (shell === "fish") return (0, node_path.join)(process.env.XDG_CONFIG_HOME ?? `${process.env.HOME ?? ""}/.config`, "fish", "completions", `${programName}.fish`);
+	return (0, node_path.join)(cacheDir ?? defaultCacheDir(programName), `completion.${shell}`);
+}
+/** Atomic write: tmp file in the same dir, then rename. */
+function writeAtomic(path, content) {
+	(0, node_fs.mkdirSync)((0, node_path.dirname)(path), { recursive: true });
+	const tmp = `${path}.tmp.${process.pid}`;
+	(0, node_fs.writeFileSync)(tmp, content);
+	(0, node_fs.renameSync)(tmp, path);
+}
+function generateScript(ctx, shell) {
+	return generateCompletion(ctx.rootCommand, {
+		shell,
+		programName: ctx.programName,
+		includeDescriptions: true,
+		...ctx.programVersion !== void 0 && { programVersion: ctx.programVersion },
+		...ctx.binPath !== void 0 && { binPath: ctx.binPath },
+		...ctx.cacheDir !== void 0 && { cacheDir: ctx.cacheDir },
+		...ctx.globalArgsSchema !== void 0 && { globalArgsSchema: ctx.globalArgsSchema }
+	}).script;
+}
+/** Write the script for `shell` to its install path. Returns the path. */
+function install(ctx, shell) {
+	const target = installPath(ctx.programName, shell, ctx.cacheDir);
+	writeAtomic(target, generateScript(ctx, shell));
+	return target;
+}
+/**
+* Read the first ~5 lines of an existing cache file and return its
+* embedded bin-sig. Returns `null` when the file is missing, unreadable,
+* or doesn't have a sig header.
+*/
+function readCachedSig(path) {
+	try {
+		if (!(0, node_fs.existsSync)(path)) return null;
+		const m = (0, node_fs.readFileSync)(path, "utf8").split("\n", 6).join("\n").match(/^# politty-bin-sig: (\S+)/m);
+		return m ? m[1] : null;
+	} catch {
+		return null;
+	}
+}
+/**
+* Rewrite the cache only when stale. Used by:
+*   - `<program> __refresh-completion <shell>` (the hidden subcommand
+*     spawned both by the rc loader and by the runMain background hook)
+*
+* Caller is responsible for gating: the runMain hook (`maybeSpawnRefresh`)
+* checks `hasManagedCache` before spawning so we don't silently create
+* a fish autoload the user never opted into. The rc loader / fish
+* autoload only run after the user has installed completion in the
+* first place, so they're allowed to refresh unconditionally.
+*
+* Must never throw — a stale completion is fine, a crash isn't.
+*/
+function refreshIfStale(ctx, shell) {
+	try {
+		const target = installPath(ctx.programName, shell, ctx.cacheDir);
+		const binPath = resolveBinPath(ctx.programName, ctx.binPath);
+		if (!binPath) return;
+		let currentSig;
+		try {
+			currentSig = Math.floor((0, node_fs.statSync)(binPath).mtimeMs / 1e3).toString();
+		} catch {
+			return;
+		}
+		if (readCachedSig(target) === currentSig) return;
+		writeAtomic(target, generateScript(ctx, shell));
+	} catch {}
+}
+/**
+* Returns true when a politty-managed cache file already exists on disk
+* for the given shell — i.e. the user has installed completion via
+* `<program> completion <shell> --install` or the rc loader has already
+* sourced one. Used by the runMain background hook to avoid spawning
+* the refresher (and thereby silently creating files) on plain CLI runs
+* the user never opted into.
+*/
+function hasManagedCache(ctx, shell) {
+	return readCachedSig(installPath(ctx.programName, shell, ctx.cacheDir)) !== null;
+}
+/**
+* Spawn a detached child process that runs `<program> __refresh-completion <shell>`.
+* The child is fully decoupled (`stdio: "ignore"` + `unref()`), so it
+* outlives the parent without holding any handles.
+*
+* Caller is expected to gate this on the right conditions (interactive
+* shell, not running inside `__complete` itself, etc.).
+*
+* Returns `void` and never throws — even spawn failures are absorbed.
+*/
+function spawnBackgroundRefresh(programArgv0, shell) {
+	try {
+		(0, node_child_process.spawn)(process.execPath, [
+			programArgv0,
+			"__refresh-completion",
+			shell
+		], {
+			detached: true,
+			stdio: "ignore"
+		}).unref();
+	} catch {}
+}
+
 //#endregion
 //#region src/completion/zsh.ts
 function escapeDesc(s) {
@@ -1510,11 +1878,14 @@ function availableOptionLines(options, fn) {
 	const lines = [];
 	for (const opt of options) {
 		const desc = opt.description ? `:${escapeDesc(opt.description)}` : "";
+		const negDesc = opt.negationDescription ? `:${escapeDesc(opt.negationDescription)}` : desc;
 		if (opt.valueType === "array") lines.push(`        _opts+=("--${opt.cliName}${desc}")`);
 		else {
 			const patterns = [`"--${opt.cliName}"`];
 			if (opt.alias) for (const a of opt.alias) patterns.push(a.length === 1 ? `"-${a}"` : `"--${a}"`);
+			if (opt.negation) patterns.push(`"--${opt.negation}"`);
 			lines.push(`        __${fn}_not_used ${patterns.join(" ")} && _opts+=("--${opt.cliName}${desc}")`);
+			if (opt.negation) lines.push(`        __${fn}_not_used ${patterns.join(" ")} && _opts+=("--${opt.negation}${negDesc}")`);
 		}
 	}
 	lines.push(`        __${fn}_not_used "--help" && _opts+=("--help:Show help")`);
@@ -1568,7 +1939,12 @@ function generateZshCompletion(command, options) {
 	const lines = [];
 	lines.push(`#compdef ${programName}`);
 	lines.push(``);
-	lines.push(`# Zsh completion for ${programName}`);
+	lines.push(...buildHeaderLines({
+		programName,
+		shell: "zsh",
+		binPath: options.binPath,
+		programVersion: options.programVersion
+	}));
 	lines.push(`# Generated by politty`);
 	lines.push(``);
 	lines.push(`__${fn}_not_used() {`);
@@ -1764,8 +2140,19 @@ const completionArgsSchema = zod.z.object({
 	instructions: require_subcommand_router.arg(zod.z.boolean().default(false), {
 		alias: "i",
 		description: "Show installation instructions"
-	})
+	}),
+	loader: require_subcommand_router.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_subcommand_router.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_subcommand_router.arg(zod.z.enum([
+	"bash",
+	"zsh",
+	"fish"
+]), {
+	positional: true,
+	description: "Shell to refresh",
+	placeholder: "SHELL"
+}) });
 /**
 * Create a completion subcommand for your CLI
 *
@@ -1781,12 +2168,30 @@ const completionArgsSchema = zod.z.object({
 * });
 * ```
 */
-function createCompletionCommand(rootCommand, programName, globalArgsSchema) {
+function createCompletionCommand(rootCommand, programName, globalArgsSchema, extra = {}) {
 	const resolvedProgramName = programName ?? rootCommand.name;
+	const { cacheDir, programVersion } = extra;
+	const refreshExtra = {
+		...cacheDir !== void 0 && { cacheDir },
+		...programVersion !== void 0 && { programVersion },
+		...globalArgsSchema !== void 0 && { globalArgsSchema }
+	};
+	const installCtxBase = {
+		programName: resolvedProgramName,
+		...refreshExtra
+	};
+	const loaderOptsBase = {
+		programName: resolvedProgramName,
+		...cacheDir !== void 0 && { cacheDir }
+	};
 	if (!rootCommand.subCommands?.__complete) rootCommand.subCommands = {
 		...rootCommand.subCommands,
 		__complete: createDynamicCompleteCommand(rootCommand, resolvedProgramName)
 	};
+	if (!rootCommand.subCommands?.["__refresh-completion"]) rootCommand.subCommands = {
+		...rootCommand.subCommands,
+		"__refresh-completion": createRefreshCompletionCommand(rootCommand, resolvedProgramName, refreshExtra)
+	};
 	return defineCommand({
 		name: "completion",
 		description: "Generate shell completion script",
@@ -1798,11 +2203,43 @@ function createCompletionCommand(rootCommand, programName, globalArgsSchema) {
 				process.exitCode = 1;
 				return;
 			}
+			if (args.install) {
+				let target;
+				try {
+					target = install({
+						rootCommand,
+						...installCtxBase
+					}, shellType);
+				} catch (e) {
+					throw new Error(`install failed: ${e instanceof Error ? e.message : String(e)}`);
+				}
+				console.error(`installed: ${target}`);
+				if (shellType !== "fish") {
+					console.error("");
+					console.error(`Add to your ~/.${shellType}rc:`);
+					console.error("");
+					console.error(generateLoader({
+						...loaderOptsBase,
+						shell: shellType
+					}).trim().replace(/^/gm, "    "));
+				}
+				return;
+			}
+			if (args.loader) {
+				if (shellType === "fish") throw new Error("fish does not use an rc loader. Run `<program> completion fish --install` to write the self-refreshing autoload file instead.");
+				process.stdout.write(generateLoader({
+					...loaderOptsBase,
+					shell: shellType
+				}));
+				return;
+			}
 			const result = generateCompletion(rootCommand, {
 				shell: shellType,
 				programName: resolvedProgramName,
 				includeDescriptions: true,
-				...globalArgsSchema !== void 0 && { globalArgsSchema }
+				...globalArgsSchema !== void 0 && { globalArgsSchema },
+				...programVersion !== void 0 && { programVersion },
+				...cacheDir !== void 0 && { cacheDir }
 			});
 			if (args.instructions) console.log(result.installInstructions);
 			else console.log(result.script);
@@ -1810,6 +2247,25 @@ function createCompletionCommand(rootCommand, programName, globalArgsSchema) {
 	});
 }
 /**
+* Hidden subcommand that the runMain background hook spawns. It does
+* the same stat-compare + atomic rewrite as the rc loader, but in a
+* detached child process so it's invisible to the user.
+*/
+function createRefreshCompletionCommand(rootCommand, programName, extra = {}) {
+	return defineCommand({
+		name: "__refresh-completion",
+		description: "(internal) Refresh the on-disk completion cache if stale.",
+		args: refreshArgsSchema,
+		run(args) {
+			refreshIfStale({
+				rootCommand,
+				programName,
+				...extra
+			}, args.shell);
+		}
+	});
+}
+/**
 * Wrap a command with a completion subcommand
 *
 * This avoids circular references that occur when a command references itself
@@ -1830,15 +2286,53 @@ function createCompletionCommand(rootCommand, programName, globalArgsSchema) {
 * ```
 */
 function withCompletionCommand(command, options) {
-	const { programName, globalArgsSchema } = typeof options === "string" ? { programName: options } : options ?? {};
+	const { programName, globalArgsSchema, cacheDir, programVersion } = typeof options === "string" ? { programName: options } : options ?? {};
+	const resolvedProgramName = programName ?? command.name;
+	const extra = {
+		...cacheDir !== void 0 && { cacheDir },
+		...programVersion !== void 0 && { programVersion },
+		...globalArgsSchema !== void 0 && { globalArgsSchema }
+	};
 	const wrappedCommand = { ...command };
 	wrappedCommand.subCommands = {
 		...command.subCommands,
-		completion: createCompletionCommand(wrappedCommand, programName, globalArgsSchema),
-		__complete: createDynamicCompleteCommand(wrappedCommand, programName)
+		completion: createCompletionCommand(wrappedCommand, programName, globalArgsSchema, extra),
+		__complete: createDynamicCompleteCommand(wrappedCommand, programName),
+		"__refresh-completion": createRefreshCompletionCommand(wrappedCommand, resolvedProgramName, extra)
+	};
+	wrappedCommand.runMainHook = (argv) => {
+		maybeSpawnRefresh(argv, {
+			programName: resolvedProgramName,
+			...cacheDir !== void 0 && { cacheDir }
+		});
 	};
 	return wrappedCommand;
 }
+/**
+* Background-refresh trigger fired from `runMain` via `runMainHook`.
+*
+* Skipped when:
+*   - the user is invoking `__complete` / `__refresh-completion` /
+*     `completion` themselves (avoids loops and double work)
+*   - $SHELL doesn't resolve to a known shell
+*   - the user opted out via $POLITTY_NO_COMPLETION_REFRESH
+*   - process.argv[1] is missing (shouldn't happen for normal CLIs)
+*   - no politty-managed cache exists yet — i.e. the user hasn't
+*     installed completion. Without this gate the detached child would
+*     create a fish autoload (or any cache file) on every CLI run,
+*     even though the user never opted in via `--install` or the rc loader.
+*/
+function maybeSpawnRefresh(argv, ctx) {
+	if (process.env.POLITTY_NO_COMPLETION_REFRESH) return;
+	const firstPositional = argv.find((a) => !a.startsWith("-"));
+	if (firstPositional === "__complete" || firstPositional === "__refresh-completion" || firstPositional === "completion") return;
+	const shell = detectShell();
+	if (!shell) return;
+	const argv0 = process.argv[1];
+	if (!argv0) return;
+	if (!hasManagedCache(ctx, shell)) return;
+	spawnBackgroundRefresh(argv0, shell);
+}
 
 //#endregion
 Object.defineProperty(exports, 'CompletionDirective', {
@@ -1865,6 +2359,12 @@ Object.defineProperty(exports, 'createDynamicCompleteCommand', {
     return createDynamicCompleteCommand;
   }
 });
+Object.defineProperty(exports, 'createRefreshCompletionCommand', {
+  enumerable: true,
+  get: function () {
+    return createRefreshCompletionCommand;
+  }
+});
 Object.defineProperty(exports, 'defineCommand', {
   enumerable: true,
   get: function () {
@@ -1937,4 +2437,4 @@ Object.defineProperty(exports, 'withCompletionCommand', {
     return withCompletionCommand;
   }
 });
-//# sourceMappingURL=completion-B5fgnUGm.cjs.map
+//# sourceMappingURL=completion-BlZxMSeU.cjs.map