politty 0.4.15 → 0.4.16

package/dist/{completion-Ca5ESJlG.js → completion-B04iiki9.js}

@@ -1,6 +1,8 @@
-import { c as resolveSubCommandMeta, h as arg, i as resolveSubCommandAlias, l as extractFields, p as toCamelCase } from "./subcommand-router-ENeCymvX.js";
+import { c as resolveSubCommandMeta, h as arg, i as resolveSubCommandAlias, l as extractFields, p as toCamelCase } from "./subcommand-router-XZBWe8HN.js";
 import { z } from "zod";
-import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { execSync, spawn } from "node:child_process";
 
 //#region src/core/command.ts
 function defineCommand(config) {
@@ -138,6 +140,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,
@@ -289,6 +293,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(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 = join(dir, programName);
+		try {
+			if (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 */
@@ -416,7 +493,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;
@@ -465,7 +544,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() {`);
@@ -604,13 +688,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
 };
 /**
@@ -736,13 +828,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",
@@ -808,6 +908,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,
@@ -889,6 +991,10 @@ function findOption(options, nameOrAlias) {
 		if (nameOrAlias.length > 1) {
 			if (opt.cliName.includes("-") && toCamelCase(opt.cliName) === nameOrAlias) return true;
 			if (opt.alias?.some((a) => a.includes("-") && toCamelCase(a) === nameOrAlias)) return true;
+			if (opt.negation) {
+				if (opt.negation === nameOrAlias) return true;
+				if (opt.negation.includes("-") && toCamelCase(opt.negation) === nameOrAlias) return true;
+			}
 		}
 		return false;
 	});
@@ -921,6 +1027,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++;
@@ -1239,11 +1346,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"`);
@@ -1313,9 +1423,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`);
@@ -1441,6 +1574,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 join(process.env.XDG_CONFIG_HOME ?? `${process.env.HOME ?? ""}/.config`, "fish", "completions", `${programName}.fish`);
+	return join(cacheDir ?? defaultCacheDir(programName), `completion.${shell}`);
+}
+/** Atomic write: tmp file in the same dir, then rename. */
+function writeAtomic(path, content) {
+	mkdirSync(dirname(path), { recursive: true });
+	const tmp = `${path}.tmp.${process.pid}`;
+	writeFileSync(tmp, content);
+	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 (!existsSync(path)) return null;
+		const m = 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(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 {
+		spawn(process.execPath, [
+			programArgv0,
+			"__refresh-completion",
+			shell
+		], {
+			detached: true,
+			stdio: "ignore"
+		}).unref();
+	} catch {}
+}
+
 //#endregion
 //#region src/completion/zsh.ts
 function escapeDesc(s) {
@@ -1509,11 +1877,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")`);
@@ -1567,7 +1938,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() {`);
@@ -1763,8 +2139,19 @@ const completionArgsSchema = z.object({
 	instructions: arg(z.boolean().default(false), {
 		alias: "i",
 		description: "Show installation instructions"
-	})
+	}),
+	loader: arg(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: arg(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 = z.object({ shell: arg(z.enum([
+	"bash",
+	"zsh",
+	"fish"
+]), {
+	positional: true,
+	description: "Shell to refresh",
+	placeholder: "SHELL"
+}) });
 /**
 * Create a completion subcommand for your CLI
 *
@@ -1780,12 +2167,30 @@ const completionArgsSchema = 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",
@@ -1797,11 +2202,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);
@@ -1809,6 +2246,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
@@ -1829,16 +2285,54 @@ 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
-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-Ca5ESJlG.js.map
+export { defineCommand as _, getSupportedShells as a, hasCompleteCommand as c, CompletionDirective as d, generateCandidates as f, createDefineCommand as g, resolveValueCompletion as h, generateCompletion as i, formatForShell as l, extractPositionals as m, createRefreshCompletionCommand as n, withCompletionCommand as o, extractCompletionData as p, detectShell as r, createDynamicCompleteCommand as s, createCompletionCommand as t, parseCompletionContext as u };
+//# sourceMappingURL=completion-B04iiki9.js.map