politty 0.4.16 → 0.5.0

package/dist/completion-BA5JMvVG.js

@@ -0,0 +1,4067 @@
+import { a as toCamelCase, h as arg, m as resolveSubCommandMeta, n as getAllAliases, t as extractFields, u as resolveSubCommandAlias } from "./schema-extractor-C50R-1re.js";
+import { z } from "zod";
+import { execSync, spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+//#region src/core/command.ts
+function defineCommand(config) {
+	return {
+		name: config.name,
+		description: config.description,
+		aliases: config.aliases,
+		args: config.args,
+		subCommands: config.subCommands,
+		setup: config.setup,
+		run: config.run,
+		cleanup: config.cleanup,
+		notes: config.notes,
+		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/shell-shared.ts
+/**
+* Helpers shared across the bash/zsh/fish completion generators.
+*
+* The three generators are necessarily distinct (each shell has its own
+* syntax) but they share a handful of building blocks: ANSI-C literal
+* encoding, the `--alias`/`-a` token shape, and the resolved-dep records
+* that drive expand lookups. Keeping these in one place avoids drift
+* when one generator gets a fix that the others should mirror.
+*/
+/**
+* Build the shell-agnostic part of an expand location for an option. Wraps
+* `resolveExpandDepGlobality` so the three generators don't each repeat the
+* `(opt.valueCompletion, opt.isGlobal === true, options, positionals)`
+* incantation.
+*/
+function optionExpandLocation(opt, frameOptions, framePositionals) {
+	return {
+		fieldName: opt.name,
+		isArrayOption: opt.valueType === "array",
+		isGlobal: opt.isGlobal === true,
+		resolvedDeps: resolveExpandDepGlobality(opt.valueCompletion, opt.isGlobal === true, frameOptions, framePositionals)
+	};
+}
+/**
+* Shell-agnostic expand location for a positional. Positionals are never
+* global (the runtime parser does not propagate positionals across frames)
+* and never array-dedup hosts (`key=value` semantics don't apply), so those
+* bits are hard-coded.
+*/
+function positionalExpandLocation(pos, frameOptions, framePositionals) {
+	return {
+		fieldName: pos.name,
+		isArrayOption: false,
+		isGlobal: false,
+		resolvedDeps: resolveExpandDepGlobality(pos.valueCompletion, false, frameOptions, framePositionals)
+	};
+}
+/**
+* Resolve each `dependsOn` entry to its globality at codegen time. A
+* global host's deps all live in the global namespace. A local host
+* may declare deps against a propagated global (its sibling index
+* includes globals); those individual deps must read from the global
+* bucket even when the host itself is local — the tracker only ever
+* writes the global value into \`_global_arg_values_<name>\`, so a
+* lookup against the local bucket would see the empty key.
+*
+* Local-precedence matches `buildSiblingIndex` in `expand-resolver.ts`:
+* a dep name that exists on a local field (option OR positional) at the
+* frame resolves to the local, even if a same-named global also exists.
+* Marking such a dep as global would route the lookup at the wrong
+* bucket and produce no candidates.
+*/
+function resolveExpandDepGlobality(vc, hostIsGlobal, frameOptions, framePositionals = []) {
+	if (vc?.type !== "expand") return [];
+	const globalOptionNames = /* @__PURE__ */ new Set();
+	const localFieldNames = /* @__PURE__ */ new Set();
+	for (const o of frameOptions) if (o.isGlobal === true) globalOptionNames.add(o.name);
+	else localFieldNames.add(o.name);
+	for (const p of framePositionals) localFieldNames.add(p.name);
+	return vc.dependsOn.map((name) => ({
+		name,
+		isGlobal: hostIsGlobal || globalOptionNames.has(name) && !localFieldNames.has(name)
+	}));
+}
+/**
+* Encode a string as an ANSI-C shell literal (`$'…'`) with backslash
+* escapes. Used by bash and zsh to embed expand-table values so newlines,
+* the unit-separator key delimiter, and other control characters survive
+* verbatim.
+*/
+function ansiC(s) {
+	let out = "$'";
+	for (const ch of s) {
+		const code = ch.codePointAt(0);
+		if (ch === "\\") out += "\\\\";
+		else if (ch === "'") out += "\\'";
+		else if (ch === "\n") out += "\\n";
+		else if (ch === "\r") out += "\\r";
+		else if (ch === "	") out += "\\t";
+		else if (code < 32 || code === 127) out += `\\x${code.toString(16).padStart(2, "0")}`;
+		else out += ch;
+	}
+	out += "'";
+	return out;
+}
+/**
+* Render an alias as its CLI token form: single-char aliases become `-x`,
+* multi-char aliases become `--long`. Mirrors the parser's accepted shapes
+* and is the bare-token form (no quoting) used inside generated case
+* patterns.
+*/
+function aliasToken(alias) {
+	return alias.length === 1 ? `-${alias}` : `--${alias}`;
+}
+/**
+* Append every alternate spelling runtime's aliasMap accepts for an alias:
+* `-a` / `--a` for single-char, `--to-be` / `--toBe` for hyphenated.
+* Shared between {@link collectOptionTokens} and {@link localShadowingTokens}.
+*/
+function pushAliasTokens(tokens, a) {
+	pushUnique(tokens, aliasToken(a));
+	if (a.length === 1) pushUnique(tokens, `--${a}`);
+	else if (a.includes("-")) pushUnique(tokens, `--${toCamelCase(a)}`);
+}
+function pushUnique(tokens, t) {
+	if (!tokens.includes(t)) tokens.push(t);
+}
+/**
+* Every CLI spelling the runtime's aliasMap routes to this option:
+*  - `--cliName` (always),
+*  - `-x` when `cliName` is one character,
+*  - `--toCamelCase(cliName)` when `cliName` is hyphenated,
+*  - and the analogous forms for each alias.
+*
+* The order is stable so shell-side case patterns stay diff-friendly.
+*/
+function collectOptionTokens(cliName, aliases) {
+	const tokens = [`--${cliName}`];
+	if (cliName.length === 1) tokens.push(`-${cliName}`);
+	if (cliName.includes("-")) tokens.push(`--${toCamelCase(cliName)}`);
+	for (const a of aliases ?? []) pushAliasTokens(tokens, a);
+	return tokens;
+}
+/**
+* Single-character tokens (`-x`) that global options at this frame own.
+* Shared between availability-guard and value-completion token filtering:
+* both paths must agree on which short forms `separateGlobalArgs` routes
+* to a global rather than a same-letter local.
+*/
+function globalShortTokens(frameOptions) {
+	const out = /* @__PURE__ */ new Set();
+	for (const o of frameOptions) {
+		if (o.isGlobal !== true) continue;
+		if (o.cliName.length === 1) out.add(`-${o.cliName}`);
+		for (const a of o.alias ?? []) if (a.length === 1) out.add(`-${a}`);
+	}
+	return out;
+}
+/**
+* Build the quoted-token list bash/zsh/fish pass to `__<fn>_not_used` to
+* decide whether an option (and its negation form, if any) is still
+* available. Quoting style (`"…"`) is identical across all three shells,
+* so the helper lives here instead of being re-derived per generator.
+*/
+function quotedAvailabilityTokens(cliName, aliases, negation, options) {
+	const tokens = new Set(collectOptionTokens(cliName, aliases));
+	if (negation) {
+		tokens.add(`--${negation}`);
+		if (negation.includes("-")) tokens.add(`--${toCamelCase(negation)}`);
+	}
+	if (options?.frameOptions) if (options.isGlobal === true) for (const o of options.frameOptions) {
+		if (o.isGlobal === true) continue;
+		for (const t of localShadowingTokens(o.cliName, o.alias)) tokens.delete(t);
+	}
+	else {
+		const globalShort = globalShortTokens(options.frameOptions);
+		if (globalShort.size > 0) {
+			const localExplicitShort = new Set((aliases ?? []).filter((a) => a.length === 1).map((a) => `-${a}`));
+			for (const g of globalShort) if (!localExplicitShort.has(g)) tokens.delete(g);
+		}
+	}
+	return [...tokens].map((t) => `"${t}"`);
+}
+/**
+* Tokens the runtime's `separateGlobalArgs` would consider locally
+* owned at the leaf: long-form cliName plus every EXPLICIT alias
+* spelling (in all forms the aliasMap accepts — `-a`/`--a` for short,
+* `--to-be`/`--toBe` for hyphenated). Excludes the auto-derived `-x`
+* for a 1-char cliName because that short form lives in the local
+* aliasMap only when an explicit alias declares it.
+*/
+function localShadowingTokens(cliName, aliases) {
+	const tokens = [`--${cliName}`];
+	if (cliName.includes("-")) tokens.push(`--${toCamelCase(cliName)}`);
+	for (const a of aliases ?? []) pushAliasTokens(tokens, a);
+	return tokens;
+}
+
+//#endregion
+//#region src/completion/value-completion-resolver.ts
+/**
+* Resolve value completion from field metadata.
+*
+* Priority (within `custom`): `expand` > `resolve` > `choices` > `shellCommand`.
+* Specifying more than one of these on the same field throws so the
+* misconfiguration surfaces at command-definition time rather than at
+* completion time. The `expand` variant returns a sentinel — the extractor
+* resolves it against sibling fields and replaces the sentinel with a
+* `{ type: "expand", table, dependsOn }` entry.
+*
+* Outside `custom`: explicit `type` (file/directory/none) > auto-detected
+* enum values from the schema.
+*/
+function resolveValueCompletion(field) {
+	const meta = field.completion;
+	if (meta?.custom) {
+		const c = meta.custom;
+		const definedKeys = [];
+		if (c.expand) definedKeys.push("expand");
+		if (c.resolve) definedKeys.push("resolve");
+		if (c.choices && c.choices.length > 0) definedKeys.push("choices");
+		if (c.shellCommand) definedKeys.push("shellCommand");
+		if (definedKeys.length > 1) throw new Error(`Field "${field.name ?? "<unknown>"}": completion.custom may only specify one of choices, shellCommand, resolve, expand (got ${definedKeys.join(", ")}).`);
+		if (c.expand) return {
+			type: "pending-expand",
+			spec: c.expand
+		};
+		if (c.resolve) return {
+			type: "dynamic",
+			resolve: c.resolve
+		};
+		if (c.choices && c.choices.length > 0) return {
+			type: "choices",
+			choices: c.choices
+		};
+		if (c.shellCommand) return {
+			type: "command",
+			shellCommand: c.shellCommand
+		};
+	}
+	if (meta?.type) {
+		if (meta.type === "file") {
+			if (meta.matcher) return {
+				type: "file",
+				matcher: meta.matcher
+			};
+			if (meta.extensions) return {
+				type: "file",
+				extensions: meta.extensions
+			};
+			return { type: "file" };
+		}
+		if (meta.type === "directory") return { type: "directory" };
+		if (meta.type === "none") return { type: "none" };
+	}
+	if (field.enumValues && field.enumValues.length > 0) return {
+		type: "choices",
+		choices: field.enumValues
+	};
+}
+
+//#endregion
+//#region src/completion/dynamic/context-parser.ts
+/**
+* Parse completion context from partial command line
+*/
+/**
+* The dynamic completion path runs `__complete` at TAB time and never sees
+* "expand" fields (those are handled inline by the static shell script).
+* Strip the transient pending sentinel here so the rest of the runtime path
+* can stay strict about handling only resolved `ValueCompletion` values.
+*/
+function stripPendingExpand(vc) {
+	return vc?.type === "pending-expand" ? void 0 : vc;
+}
+/**
+* Extract options from a command
+*/
+function extractOptions(command) {
+	if (!command.args) return [];
+	return extractOptionsFromSchema(command.args);
+}
+function extractOptionsFromSchema(schema) {
+	return extractFields(schema).fields.filter((field) => !field.positional).map((field) => {
+		const aliases = getAllAliases(field);
+		return {
+			name: field.name,
+			cliName: field.cliName,
+			alias: aliases.length > 0 ? aliases : void 0,
+			negation: field.negationDisplay,
+			negationDescription: field.negationDescription,
+			description: field.description,
+			takesValue: field.type !== "boolean",
+			valueType: field.type,
+			required: field.required,
+			defaultNegationAccepted: field.type === "boolean" && (field.negation === void 0 || field.negation === true),
+			valueCompletion: stripPendingExpand(resolveValueCompletion(field))
+		};
+	});
+}
+/**
+* Build the CLI tokens an option is recognised by (`--cliName`,
+* `--long-alias`, `-x`). Wraps `collectOptionTokens` so collision
+* detection sees every spelling the runtime aliasMap accepts — including
+* the camelCase form of hyphenated names, without which a parent-frame
+* local that intercepts `--toBe` for a global `to-be` would silently
+* skip the migration loop.
+*/
+function optionTokenSet(opt) {
+	return new Set(collectOptionTokens(opt.cliName, opt.alias));
+}
+/**
+* Find a global option whose CLI tokens overlap with `local`'s tokens.
+* Used at subcommand descent to migrate values the runtime's
+* `scanForSubcommand` would have routed to a global field even though
+* the completion parser stored them under a different-named local.
+*/
+function findGlobalByTokenCollision(globals, local) {
+	const localTokens = optionTokenSet(local);
+	for (const g of globals) for (const t of optionTokenSet(g)) if (localTokens.has(t)) return g;
+}
+/**
+* Mirror runtime `scanForSubcommand`: walk a pre-subcommand token slice
+* with the global schema only, populating `globalParsedArgs` with the
+* values the runtime would have routed there before the next subcommand
+* boundary. Runs at every subcommand descent — the runtime invokes
+* `scanForSubcommand` recursively at each frame in `parseArgs`, so the
+* pre-sub global pass applies per descent, not just from root.
+*
+* Returns the set of global option names captured during this pre-scan.
+* Used at descent to skip the local→global token migration for entries
+* whose true value is already known here — a value-taking global
+* aliased the same as a parent-local boolean (e.g. global `--profile`
+* /`-p` and local boolean `alias: "p"`) would otherwise have `true`
+* written over the genuine `"prod"`.
+*/
+function parsePreSubGlobals(tokens, globalOptions, globalParsedArgs) {
+	const captured = /* @__PURE__ */ new Set();
+	if (globalOptions.length === 0) return captured;
+	const arrayWrittenInThisSlice = /* @__PURE__ */ new Set();
+	const writeGlobal = (opt, value) => {
+		writeOptionValue(globalParsedArgs, opt, value, arrayWrittenInThisSlice);
+		captured.add(opt.name);
+	};
+	let i = 0;
+	while (i < tokens.length) {
+		const word = tokens[i];
+		if (word === "--") break;
+		if (!word.startsWith("-")) break;
+		if (!word.startsWith("--") && word.length > 2) {
+			const eqIdx = word.indexOf("=");
+			if ((eqIdx >= 0 ? word.slice(1, eqIdx) : word.slice(1)).length > 1) break;
+		}
+		const parsed = parseOption(word);
+		const opt = findOption(globalOptions, parsed);
+		if (!opt) break;
+		if (opt.takesValue) if (hasInlineValue(word)) {
+			const eqIdx = word.indexOf("=");
+			writeGlobal(opt, word.slice(eqIdx + 1));
+			i++;
+		} else if (i + 1 < tokens.length) {
+			const next = tokens[i + 1];
+			if (next.startsWith("-")) {
+				i++;
+				continue;
+			}
+			writeGlobal(opt, next);
+			i += 2;
+		} else break;
+		else {
+			globalParsedArgs[opt.name] = !isNegationOf(opt, parsed);
+			captured.add(opt.name);
+			i++;
+		}
+	}
+	return captured;
+}
+/**
+* Reshape a value pulled from local storage so it matches the global's
+* declared shape before landing in `globalParsedArgs`. Without this,
+* migrating a local scalar into an array global would expose the
+* resolver to `parsedArgs.tags === "foo"` instead of `["foo"]` — a
+* state the runtime parser never produces.
+*/
+function adaptValueForGlobal(value, global) {
+	if (global.valueType === "array") {
+		if (Array.isArray(value)) return value;
+		return [value];
+	}
+	if (Array.isArray(value)) return value.at(-1);
+	return value;
+}
+/**
+* Append globals to local, preserving local-shadowing by list ORDER rather
+* than by exclusion. Keeping a global in the merged list — even when a
+* local declares the same `cliName` — lets a global's non-colliding tokens
+* (e.g. a `-e` alias the local does not redeclare) still resolve to the
+* global. `findOption` walks the list and returns the first match, so a
+* token the local actually owns still wins.
+*/
+function mergeGlobalOptions(local, globals) {
+	if (globals.length === 0) return local;
+	return [...local, ...globals];
+}
+/**
+* Clamp a positional index against `positionals` so a value past the last
+* declared positional resolves to the trailing variadic slot (if any).
+* Returns `undefined` only when `positionals` is empty — callers can then
+* skip the variadic/previousValues path entirely.
+*/
+function clampToVariadic(positionalIndex, positionals) {
+	const lastIdx = positionals.length - 1;
+	if (lastIdx < 0) return void 0;
+	return positionalIndex > lastIdx ? lastIdx : positionalIndex;
+}
+/**
+* Extract positionals from a command
+*/
+function extractPositionalsForContext(command) {
+	if (!command.args) return [];
+	return extractFields(command.args).fields.filter((field) => field.positional).map((field, index) => ({
+		name: field.name,
+		cliName: field.cliName,
+		position: index,
+		description: field.description,
+		required: field.required,
+		variadic: field.type === "array",
+		valueCompletion: stripPendingExpand(resolveValueCompletion(field))
+	}));
+}
+/**
+* Get subcommand names from a command (including aliases)
+*/
+function getSubcommandNames(command) {
+	if (!command.subCommands) return [];
+	const names = [];
+	for (const [name, subCmd] of Object.entries(command.subCommands)) {
+		if (name.startsWith("__")) continue;
+		names.push(name);
+		const meta = resolveSubCommandMeta(subCmd);
+		if (meta?.aliases) names.push(...meta.aliases);
+	}
+	return names;
+}
+/**
+* Resolve subcommand by name (including alias lookup)
+*/
+function resolveSubcommand(command, name) {
+	if (!command.subCommands) return null;
+	const sub = command.subCommands[name];
+	if (sub) return resolveSubCommandMeta(sub);
+	const canonical = resolveSubCommandAlias(command, name);
+	if (canonical) return resolveSubCommandMeta(command.subCommands[canonical]);
+	return null;
+}
+/**
+* Check if a word is an option (starts with - or --)
+*/
+function isOption(word) {
+	return word.startsWith("-");
+}
+/**
+* Parse option name from word, retaining the form the user typed so the
+* lookup can keep short-form (`-x`) and long-form (`--x`) matches in
+* separate token spaces — runtime negation, cliName, and multi-char
+* aliases only ever appear as long form.
+*/
+function parseOption(word) {
+	if (word.startsWith("--")) {
+		const withoutPrefix = word.slice(2);
+		const eqIndex = withoutPrefix.indexOf("=");
+		return {
+			name: eqIndex >= 0 ? withoutPrefix.slice(0, eqIndex) : withoutPrefix,
+			isLong: true
+		};
+	}
+	if (word.startsWith("-")) return {
+		name: word.slice(1, 2),
+		isLong: false
+	};
+	return {
+		name: word,
+		isLong: true
+	};
+}
+/**
+* Check if option has inline value (e.g., "--foo=bar")
+*/
+function hasInlineValue(word) {
+	return word.includes("=");
+}
+/**
+* For boolean options, the runtime parser accepts the implicit
+* `--no-<cliName>` (and camelCase `--noCliName`) form unless the user
+* opted out via `negation: false` or supplied a custom-string negation
+* (which suppresses the default form). Aliases participate too: a
+* boolean with `alias: "c"` accepts `--no-c` / `--noC` because the
+* runtime resolves the post-`no-` segment through `aliasMap`. Implicit
+* negation is LONG-FORM only — `-no-c` is never an accepted negation —
+* so callers must say so via `isLong` to prevent a short option from
+* being read as a negation.
+*/
+function isImplicitBooleanNegation(opt, name, isLong) {
+	if (!isLong) return false;
+	if (opt.valueType !== "boolean") return false;
+	if (opt.defaultNegationAccepted === false) return false;
+	const candidates = [opt.cliName, ...opt.alias ?? []];
+	for (const c of candidates) {
+		const hyphenated = `no-${c}`;
+		if (name === hyphenated) return true;
+		if (name === toCamelCase(hyphenated)) return true;
+	}
+	return false;
+}
+/** True when `source` is hyphenated and its camelCase form equals `name`. */
+function matchesCamelCase(source, name) {
+	return source !== void 0 && source.includes("-") && toCamelCase(source) === name;
+}
+/**
+* Write `value` into `target[opt.name]` following the runtime's per-frame
+* array semantics: the first write in a frame REPLACES any inherited value
+* (mirroring the runtime's shallow merge of inherited globals), subsequent
+* writes in the same frame APPEND. Scalars overwrite unconditionally.
+* `arraysSeenInFrame` is the frame-scoped seen-set the caller maintains.
+*/
+function writeOptionValue(target, opt, value, arraysSeenInFrame) {
+	if (opt.valueType !== "array") {
+		target[opt.name] = value;
+		return;
+	}
+	if (arraysSeenInFrame.has(opt.name)) {
+		const existing = target[opt.name];
+		target[opt.name] = Array.isArray(existing) ? [...existing, value] : [value];
+	} else {
+		target[opt.name] = [value];
+		arraysSeenInFrame.add(opt.name);
+	}
+}
+/**
+* True when the typed token is the boolean option's negation form — either
+* the explicit `negation` name (or its camelCase variant) or the implicit
+* `--no-<name>` form. Long-form only; short tokens are never negations.
+*/
+function isNegationOf(opt, parsed) {
+	if (!parsed.isLong) return false;
+	if (opt.negation !== void 0 && (opt.negation === parsed.name || matchesCamelCase(opt.negation, parsed.name))) return true;
+	return isImplicitBooleanNegation(opt, parsed.name, parsed.isLong);
+}
+/**
+* Match by cliName, alias, camelCase variants, or an explicit negation
+* name. `isLong` separates the short (`-x`) and long (`--xxx`) token
+* spaces: cliNames and explicit negations are only valid as long form,
+* and aliases match their own length class (a 1-char alias only matches
+* short form because its token is `-x`).
+*/
+function matchesExplicit(opt, name, isLong) {
+	if (opt.cliName === name && (isLong || opt.cliName.length === 1)) return true;
+	if (opt.alias) {
+		for (const a of opt.alias) if (a === name && (isLong || a.length === 1)) return true;
+	}
+	if (isLong && opt.negation === name) return true;
+	if (!isLong || name.length <= 1) return false;
+	if (matchesCamelCase(opt.cliName, name)) return true;
+	if (opt.alias?.some((a) => matchesCamelCase(a, name))) return true;
+	return matchesCamelCase(opt.negation, name);
+}
+/**
+* Find option by name or alias. Tried in two passes so that a real field
+* literally named `noFoo` always wins over `--no-foo` being interpreted as
+* the implicit negation of a sibling `foo` field — the runtime parser
+* resolves the explicit field first as well.
+*
+* Short-form precedence mirrors runtime's `separateGlobalArgs`: when a
+* global owns the `-x` alias and the local does NOT explicitly declare
+* `alias: "x"`, the global wins (a bare local `cliName: "x"` does not
+* register `x` in the local aliasMap). Long form keeps the local-first
+* order via the unshadowed merged list.
+*/
+function findOption(options, parsed) {
+	if (!parsed.isLong) {
+		const localWithExplicitAlias = options.find((opt) => opt.isGlobal !== true && opt.alias?.includes(parsed.name) === true);
+		if (localWithExplicitAlias) return localWithExplicitAlias;
+		const global = options.find((opt) => opt.isGlobal === true && matchesExplicit(opt, parsed.name, parsed.isLong));
+		if (global) return global;
+	}
+	const explicit = options.find((opt) => matchesExplicit(opt, parsed.name, parsed.isLong));
+	if (explicit) return explicit;
+	return options.find((opt) => isImplicitBooleanNegation(opt, parsed.name, parsed.isLong));
+}
+/**
+* Parse completion context from command line arguments
+*
+* @param argv - Arguments after the program name (e.g., ["build", "--fo"])
+* @param rootCommand - The root command
+* @param globalArgsSchema - Optional global args. When provided, options
+*   derived from this schema are merged into every command level so dynamic
+*   resolvers attached to global options can be reached from any subcommand.
+* @returns Completion context
+*/
+function parseCompletionContext(argv, rootCommand, globalArgsSchema) {
+	let currentCommand = rootCommand;
+	const subcommandPath = [];
+	const globalOptions = globalArgsSchema ? extractOptionsFromSchema(globalArgsSchema).map((o) => ({
+		...o,
+		isGlobal: true
+	})) : [];
+	const usedOptions = /* @__PURE__ */ new Set();
+	let positionalCount = 0;
+	let parsedArgs = {};
+	let positionalValues = [];
+	const globalParsedArgs = {};
+	const globalsCapturedByPreSubScan = /* @__PURE__ */ new Set();
+	let frameStartIdx = 0;
+	let arraysSetInCurrentFrame = /* @__PURE__ */ new Set();
+	/**
+	* Mark the option's cliName plus every alias and (if present) negation
+	* form as consumed. The negation shares the field's "used" slot so
+	* typing either form filters both from subsequent suggestions.
+	*/
+	const markUsed = (opt) => {
+		usedOptions.add(opt.cliName);
+		for (const a of opt.alias ?? []) usedOptions.add(a);
+		if (opt.negation) usedOptions.add(opt.negation);
+	};
+	const recordOptionValue = (opt, value) => {
+		writeOptionValue(opt.isGlobal === true ? globalParsedArgs : parsedArgs, opt, value, arraysSetInCurrentFrame);
+	};
+	/**
+	* Record a boolean flag the user typed. The positive form sets `true`;
+	* the negation form (`--no-foo` or a custom `negationDisplay`) sets
+	* `false`. Dynamic resolvers depend on these values to switch candidates
+	* based on flag state, so the absence of a writer here used to hide
+	* boolean siblings entirely.
+	*/
+	const recordBooleanFlag = (opt, parsed) => {
+		const target = opt.isGlobal === true ? globalParsedArgs : parsedArgs;
+		target[opt.name] = !isNegationOf(opt, parsed);
+	};
+	let i = 0;
+	let options = mergeGlobalOptions(extractOptions(currentCommand), globalOptions);
+	let afterDoubleDash = false;
+	while (i < argv.length - 1) {
+		const word = argv[i];
+		if (!afterDoubleDash && word === "--") {
+			afterDoubleDash = true;
+			i++;
+			continue;
+		}
+		if (!afterDoubleDash && word.startsWith("-") && !word.startsWith("--") && word.length > 2 && !word.includes("=")) {
+			const chars = Array.from(word.slice(1));
+			const localOptions = options.filter((o) => o.isGlobal !== true);
+			for (const c of chars) {
+				const o = findOption(localOptions, {
+					name: c,
+					isLong: false
+				});
+				if (!o || o.takesValue) continue;
+				markUsed(o);
+				recordBooleanFlag(o, {
+					name: c,
+					isLong: false
+				});
+			}
+			i++;
+			continue;
+		}
+		if (!afterDoubleDash && isOption(word)) {
+			const parsed = parseOption(word);
+			const opt = findOption(options, parsed);
+			if (opt) {
+				markUsed(opt);
+				if (opt.takesValue) {
+					if (hasInlineValue(word)) {
+						const eqIdx = word.indexOf("=");
+						recordOptionValue(opt, word.slice(eqIdx + 1));
+					} else if (i + 1 < argv.length - 1) {
+						const next = argv[i + 1];
+						if (!isOption(next)) {
+							recordOptionValue(opt, next);
+							i++;
+						}
+					}
+				} else recordBooleanFlag(opt, parsed);
+			}
+			i++;
+			continue;
+		}
+		const subcommand = afterDoubleDash ? null : resolveSubcommand(currentCommand, word);
+		if (subcommand) {
+			subcommandPath.push(word);
+			const parentLocalOptions = extractOptions(currentCommand);
+			const preSubSlice = argv.slice(frameStartIdx, i);
+			for (const name of parsePreSubGlobals(preSubSlice, globalOptions, globalParsedArgs)) globalsCapturedByPreSubScan.add(name);
+			currentCommand = subcommand;
+			options = mergeGlobalOptions(extractOptions(currentCommand), globalOptions);
+			for (const key of Object.keys(parsedArgs)) {
+				const localOpt = parentLocalOptions.find((o) => o.name === key);
+				const tokenCollidingGlobal = globalOptions.find((g) => g.name === key) ?? (localOpt ? findGlobalByTokenCollision(globalOptions, localOpt) : void 0);
+				if (!tokenCollidingGlobal) continue;
+				if (globalsCapturedByPreSubScan.has(tokenCollidingGlobal.name)) continue;
+				globalParsedArgs[tokenCollidingGlobal.name] = adaptValueForGlobal(parsedArgs[key], tokenCollidingGlobal);
+			}
+			usedOptions.clear();
+			positionalCount = 0;
+			parsedArgs = {};
+			positionalValues = [];
+			arraysSetInCurrentFrame = /* @__PURE__ */ new Set();
+			frameStartIdx = i + 1;
+			i++;
+			continue;
+		}
+		positionalValues.push(word);
+		positionalCount++;
+		i++;
+	}
+	const currentWord = argv[argv.length - 1] ?? "";
+	const previousWord = argv[argv.length - 2] ?? "";
+	const positionals = extractPositionalsForContext(currentCommand);
+	const subcommands = getSubcommandNames(currentCommand);
+	for (let p = 0; p < positionals.length; p++) {
+		const pos = positionals[p];
+		if (pos.variadic) {
+			parsedArgs[pos.name] = positionalValues.slice(p);
+			break;
+		}
+		if (p < positionalValues.length) parsedArgs[pos.name] = positionalValues[p];
+	}
+	let completionType;
+	let targetOption;
+	let positionalIndex;
+	if (!afterDoubleDash && previousWord && isOption(previousWord) && !hasInlineValue(previousWord)) {
+		const opt = findOption(options, parseOption(previousWord));
+		if (opt && opt.takesValue) {
+			completionType = "option-value";
+			targetOption = opt;
+		} else if (currentWord.startsWith("-")) completionType = "option-name";
+		else {
+			completionType = determineDefaultCompletionType(currentWord, subcommands, positionals, positionalCount);
+			if (completionType === "positional") positionalIndex = positionalCount;
+		}
+	} else if (!afterDoubleDash && currentWord.startsWith("-") && hasInlineValue(currentWord)) {
+		const opt = findOption(options, parseOption(currentWord));
+		if (opt && opt.takesValue) {
+			completionType = "option-value";
+			targetOption = opt;
+		} else completionType = "option-name";
+	} else if (!afterDoubleDash && currentWord.startsWith("-")) completionType = "option-name";
+	else {
+		completionType = determineDefaultCompletionType(currentWord, subcommands, positionals, positionalCount, afterDoubleDash);
+		if (completionType === "positional") positionalIndex = positionalCount;
+	}
+	let previousValues = [];
+	if (targetOption) {
+		if (targetOption.valueType === "array") {
+			const stored = (targetOption.isGlobal === true ? globalParsedArgs : parsedArgs)[targetOption.name];
+			previousValues = Array.isArray(stored) ? stored.filter((v) => typeof v === "string") : [];
+		}
+	} else if (completionType === "positional" && positionalIndex !== void 0) {
+		const clampedIdx = clampToVariadic(positionalIndex, positionals);
+		if (clampedIdx !== void 0 && positionals[clampedIdx]?.variadic) previousValues = positionalValues.slice(clampedIdx);
+	}
+	const mergedParsedArgs = {
+		...globalParsedArgs,
+		...parsedArgs
+	};
+	return {
+		subcommandPath,
+		currentCommand,
+		currentWord,
+		previousWord,
+		completionType,
+		targetOption,
+		positionalIndex,
+		options,
+		subcommands,
+		positionals,
+		usedOptions,
+		providedPositionalCount: positionalCount,
+		parsedArgs: mergedParsedArgs,
+		previousValues
+	};
+}
+/**
+* Determine default completion type when not completing an option
+*/
+function determineDefaultCompletionType(currentWord, subcommands, positionals, positionalCount, afterDoubleDash) {
+	if (afterDoubleDash) return "positional";
+	if (subcommands.length > 0) {
+		if (subcommands.filter((s) => s.startsWith(currentWord)).length > 0 || currentWord === "") return "subcommand";
+	}
+	if (positionalCount < positionals.length) return "positional";
+	if (positionals.length > 0 && positionals[positionals.length - 1].variadic) return "positional";
+	return "subcommand";
+}
+
+//#endregion
+//#region src/completion/dynamic/candidate-generator.ts
+/**
+* Generate completion candidates based on context
+*/
+/**
+* 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
+};
+/**
+* Detect an inline `--opt=` prefix on an option-value `currentWord`.
+* Mirrors what the shell scripts already strip via `_inline_prefix`, so
+* resolvers see only the value portion (e.g. `foo` for `--field=foo`).
+* Positional words are excluded: `cli -- --foo=bar` is a legitimate
+* positional value, not an inline option assignment.
+*/
+function detectInlineOptionPrefix(currentWord) {
+	if (!currentWord.startsWith("-")) return void 0;
+	const eqIdx = currentWord.indexOf("=");
+	if (eqIdx <= 0) return void 0;
+	return currentWord.slice(0, eqIdx + 1);
+}
+/**
+* Generate completion candidates based on context.
+*
+* Async because dynamic resolvers may return promises. Sync completion
+* sources (choices/file/directory/command/none, subcommand, option name)
+* still resolve synchronously and the await is a no-op for them.
+*
+* Inline option-value prefixes (`--field=foo`) on the option-value path
+* are stripped here so resolvers and post-processing always see the
+* value portion regardless of whether the caller pre-normalized.
+*/
+async function generateCandidates(context, options) {
+	switch (context.completionType) {
+		case "subcommand": return generateSubcommandCandidates(context);
+		case "option-name": return generateOptionNameCandidates(context);
+		case "option-value": {
+			const opt = context.targetOption;
+			const inlinePrefix = opt ? detectInlineOptionPrefix(context.currentWord) : void 0;
+			return generateValueCandidates(inlinePrefix ? {
+				...context,
+				currentWord: context.currentWord.slice(inlinePrefix.length)
+			} : context, options, opt?.name, opt?.valueCompletion);
+		}
+		case "positional": {
+			const positional = resolvePositionalTarget(context);
+			return generateValueCandidates(context, options, positional?.name, positional?.valueCompletion, positional?.description);
+		}
+	}
+}
+/**
+* Pick the positional whose `valueCompletion` should drive the current
+* cursor. Clamps to the trailing variadic positional so a value beyond
+* the schema's positional count still resolves to the variadic slot —
+* but only when that slot IS variadic; otherwise a non-variadic last
+* positional must not greedily absorb the extra value.
+*/
+function resolvePositionalTarget(context) {
+	const requestedIdx = context.positionalIndex ?? 0;
+	const clampedIdx = clampToVariadic(requestedIdx, context.positionals);
+	if (clampedIdx === void 0) return void 0;
+	const candidate = context.positionals[clampedIdx];
+	if (!candidate) return void 0;
+	return clampedIdx === requestedIdx || candidate.variadic ? candidate : void 0;
+}
+/**
+* Execute a shell command and return results as candidates
+*/
+function executeShellCommand(command) {
+	try {
+		return execSync(command, {
+			encoding: "utf-8",
+			timeout: 5e3
+		}).split("\n").map((line) => line.trim()).filter((line) => line.length > 0).map((line) => ({
+			value: line,
+			type: "value"
+		}));
+	} catch {
+		return [];
+	}
+}
+/**
+* Two-stage `key=value` post-processing. Returns the transformed candidate
+* list plus whether it contains a bare `key=` entry so the caller can flip
+* NoSpace and let the user keep typing past the first TAB.
+*
+* Key stage (`=` not yet typed): collapse every `key=value` candidate to a
+* unique `key=` entry so the first TAB picks the key.
+*
+* Value stage (`=` typed): drop only the bare `<key>=` candidate that
+* echoes the prefix the user already typed. A blanket `endsWith("=")`
+* filter would also remove legitimate values such as base64 `key=YWJj=` or
+* value-only `YWJj=` (padding), so match the candidate string exactly
+* against the typed key prefix.
+*/
+function applyKeyValuePostProcessing(candidates, currentWord) {
+	const keyStage = !currentWord.includes("=");
+	const processed = keyStage ? collapseToKeys(candidates) : dropBareKeyEcho(candidates, currentWord);
+	return {
+		candidates: processed,
+		hasEqSuffix: keyStage && processed.some((c) => c.value.endsWith("="))
+	};
+}
+function collapseToKeys(candidates) {
+	const seen = /* @__PURE__ */ new Set();
+	const out = [];
+	for (const c of candidates) {
+		const eqIdx = c.value.indexOf("=");
+		if (eqIdx <= 0) {
+			out.push(c);
+			continue;
+		}
+		const keyPart = c.value.slice(0, eqIdx + 1);
+		if (seen.has(keyPart)) continue;
+		seen.add(keyPart);
+		out.push({
+			...c,
+			value: keyPart
+		});
+	}
+	return out;
+}
+function dropBareKeyEcho(candidates, currentWord) {
+	const keyPrefix = currentWord.slice(0, currentWord.indexOf("=") + 1);
+	return candidates.filter((c) => c.value !== keyPrefix);
+}
+/**
+* Resolve value completion, executing shell commands and file lookups in JS
+*/
+async function resolveValueCandidates(vc, ctx, description) {
+	const candidates = [];
+	let directive = CompletionDirective.FilterPrefix;
+	let fileExtensions;
+	let fileMatchers;
+	switch (vc.type) {
+		case "choices":
+			if (vc.choices) for (const choice of vc.choices) candidates.push({
+				value: choice,
+				description,
+				type: "value"
+			});
+			directive |= CompletionDirective.NoFileCompletion;
+			break;
+		case "file":
+			if (vc.matcher && vc.matcher.length > 0) {
+				fileMatchers = vc.matcher.filter((m) => m.trim().length > 0);
+				if (fileMatchers.length === 0) {
+					fileMatchers = void 0;
+					directive |= CompletionDirective.FileCompletion;
+				}
+			} else if (vc.extensions && vc.extensions.length > 0) {
+				fileExtensions = Array.from(new Set(vc.extensions.map((ext) => ext.trim().replace(/^\./, "")).filter((ext) => ext.length > 0)));
+				if (fileExtensions.length === 0) {
+					fileExtensions = void 0;
+					directive |= CompletionDirective.FileCompletion;
+				}
+			} else directive |= CompletionDirective.FileCompletion;
+			break;
+		case "directory":
+			directive |= CompletionDirective.DirectoryCompletion;
+			break;
+		case "command":
+			if (vc.shellCommand) candidates.push(...executeShellCommand(vc.shellCommand));
+			directive |= CompletionDirective.NoFileCompletion;
+			break;
+		case "none":
+			directive |= CompletionDirective.NoFileCompletion;
+			break;
+		case "dynamic":
+			try {
+				const result = await vc.resolve(ctx);
+				for (const c of result.candidates) {
+					const normalized = typeof c === "string" ? { value: c } : c;
+					candidates.push({
+						...normalized,
+						type: "value"
+					});
+				}
+				directive = result.directive ?? CompletionDirective.FilterPrefix | CompletionDirective.NoFileCompletion;
+			} catch {
+				directive = CompletionDirective.NoFileCompletion | CompletionDirective.Error;
+			}
+			break;
+		case "expand":
+			directive |= CompletionDirective.NoFileCompletion;
+			break;
+	}
+	if (vc.type === "dynamic" || vc.type === "expand") {
+		const processed = applyKeyValuePostProcessing(candidates, ctx.currentWord);
+		if (processed.hasEqSuffix) directive |= CompletionDirective.NoSpace;
+		return {
+			candidates: processed.candidates,
+			directive,
+			fileExtensions,
+			fileMatchers
+		};
+	}
+	return {
+		candidates,
+		directive,
+		fileExtensions,
+		fileMatchers
+	};
+}
+/**
+* Generate subcommand candidates
+*/
+function generateSubcommandCandidates(context) {
+	const candidates = [];
+	for (const name of context.subcommands) {
+		const subs = context.currentCommand.subCommands;
+		const direct = subs?.[name];
+		const aliasCanonical = direct ? void 0 : resolveSubCommandAlias(context.currentCommand, name);
+		const resolved = direct ?? (aliasCanonical ? subs?.[aliasCanonical] : void 0);
+		const description = resolved ? resolveSubCommandMeta(resolved)?.description : void 0;
+		candidates.push({
+			value: name,
+			description,
+			type: "subcommand"
+		});
+	}
+	if (candidates.length === 0 || context.currentWord.startsWith("-")) {
+		const optionResult = generateOptionNameCandidates(context);
+		candidates.push(...optionResult.candidates);
+	}
+	return {
+		candidates,
+		directive: CompletionDirective.FilterPrefix
+	};
+}
+/**
+* Generate option name candidates
+*/
+function generateOptionNameCandidates(context) {
+	const candidates = [];
+	const availableOptions = context.options.filter((opt) => {
+		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"
+		});
+		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",
+		type: "option"
+	});
+	return {
+		candidates,
+		directive: CompletionDirective.FilterPrefix
+	};
+}
+/**
+* Build the resolver-invocation slice of CompletionContext.
+* `currentWord` reaches resolvers normalized by `generateCandidates` —
+* the option-value path strips any inline `--field=` prefix first, so
+* resolvers and the key=value post-processing only ever see the value
+* portion. The target field is dropped from `parsedArgs` so resolvers
+* can treat it as "other args": for repeatable options and variadic
+* positionals the parser already stages already-typed values under the
+* same key, and exposing them under both `parsedArgs` and `previousValues`
+* would let a resolver mistake the in-flight field for a fully-supplied
+* sibling.
+*/
+function resolverContext(context, options, targetFieldName) {
+	return {
+		currentWord: context.currentWord,
+		shell: options.shell,
+		parsedArgs: parsedArgsWithoutTarget(context.parsedArgs, targetFieldName),
+		previousValues: context.previousValues,
+		subcommandPath: context.subcommandPath
+	};
+}
+function parsedArgsWithoutTarget(parsedArgs, key) {
+	if (key === void 0 || !(key in parsedArgs)) return parsedArgs;
+	const next = { ...parsedArgs };
+	delete next[key];
+	return next;
+}
+/**
+* Generate value candidates for either an option or a positional. Both paths
+* resolve the same way once their target field is identified. `description`
+* is propagated to choices candidates (positional path supplies it; option
+* path does not, mirroring the prior split implementations).
+*/
+async function generateValueCandidates(context, options, targetFieldName, vc, description) {
+	if (!vc) return {
+		candidates: [],
+		directive: CompletionDirective.FilterPrefix
+	};
+	return resolveValueCandidates(vc, resolverContext(context, options, targetFieldName), description);
+}
+
+//#endregion
+//#region src/completion/expand-resolver.ts
+/**
+* Resolve every pending `expand` spec on a subcommand. The static extractor
+* collects pending targets while building options/positionals (it sees the
+* sentinel via `resolveValueCompletion`) and passes them here once siblings
+* are known.
+*/
+function resolveExpandTargets(sub, targets, globalOptions = []) {
+	if (targets.length === 0) return;
+	const siblingIndex = buildSiblingIndex(sub, globalOptions);
+	for (const target of targets) target.set(resolveOne(target, siblingIndex));
+}
+/**
+* Build a name → static-values map for siblings, using each field's already
+* resolved `valueCompletion`. Only `choices`-typed completions count;
+* referencing anything else from `dependsOn` is reported as a clean error
+* in {@link resolveOne}. Global options with static choices are merged in
+* so a local expand can declare `dependsOn: ["env"]` against a global
+* \`env\` field — runtime propagates the global value to every frame, so
+* the resolved table must cover those combinations too.
+*/
+function buildSiblingIndex(sub, globalOptions) {
+	const index = /* @__PURE__ */ new Map();
+	const claimedByLocal = /* @__PURE__ */ new Set();
+	for (const field of [...sub.options, ...sub.positionals]) claimedByLocal.add(field.name);
+	const visit = (fields, fromGlobal) => {
+		for (const field of fields) {
+			if (index.has(field.name)) continue;
+			if (fromGlobal && claimedByLocal.has(field.name)) continue;
+			const vc = field.valueCompletion;
+			if (vc?.type === "choices" && vc.choices && vc.choices.length > 0) index.set(field.name, vc.choices);
+		}
+	};
+	visit([...sub.options, ...sub.positionals], false);
+	visit(globalOptions, true);
+	return index;
+}
+function resolveOne(target, siblings) {
+	const { spec } = target;
+	const deps = spec.dependsOn;
+	if (deps.length === 0) throw new Error(`Field "${target.describe}": completion.custom.expand.dependsOn must list at least one sibling arg.`);
+	const valueLists = [];
+	for (const dep of deps) {
+		if (dep === target.name) throw new Error(`Field "${target.describe}": completion.custom.expand.dependsOn cannot reference the field itself ("${dep}").`);
+		const values = siblings.get(dep);
+		if (!values) throw new Error(`Field "${target.describe}": completion.custom.expand.dependsOn references "${dep}", which is not a sibling arg with a static \`choices\`/enum schema on the same command. Chaining expand specs is not supported.`);
+		valueLists.push([...values]);
+	}
+	const table = [];
+	for (const combo of cartesian(valueLists)) {
+		const depsRecord = {};
+		deps.forEach((name, idx) => {
+			depsRecord[name] = combo[idx];
+		});
+		let raw;
+		try {
+			raw = spec.enumerate(depsRecord);
+		} catch (err) {
+			const cause = err instanceof Error ? err.message : String(err);
+			throw new Error(`Field "${target.describe}": completion.custom.expand.enumerate threw for deps=${JSON.stringify(depsRecord)}: ${cause}`);
+		}
+		const candidates = normaliseCandidates(raw);
+		if (candidates.length === 0) continue;
+		table.push({
+			key: combo,
+			candidates
+		});
+	}
+	return {
+		type: "expand",
+		dependsOn: deps,
+		table
+	};
+}
+function normaliseCandidates(raw) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const item of raw) {
+		const value = typeof item === "string" ? item : item.value;
+		if (seen.has(value)) continue;
+		seen.add(value);
+		const entry = { value };
+		if (typeof item !== "string" && item.description !== void 0) entry.description = item.description;
+		out.push(entry);
+	}
+	return out;
+}
+function* cartesian(lists) {
+	if (lists.length === 0) {
+		yield [];
+		return;
+	}
+	const indices = Array.from({ length: lists.length }).fill(0);
+	while (true) {
+		yield indices.map((i, dim) => lists[dim][i]);
+		let dim = lists.length - 1;
+		while (dim >= 0) {
+			indices[dim]++;
+			if (indices[dim] < lists[dim].length) break;
+			indices[dim] = 0;
+			dim--;
+		}
+		if (dim < 0) return;
+	}
+}
+
+//#endregion
+//#region src/completion/extractor.ts
+/**
+* Extract completion data from commands
+*/
+/**
+* Resolve and assign value completion to a field. Pending expand sentinels
+* are stashed in `pending`; the eventual `resolveExpandTargets` pass replaces
+* the sentinel with a fully-resolved `{ type: "expand", ... }` via `set`.
+*/
+function assignValueCompletion(field, pending, describe, set) {
+	const raw = resolveValueCompletion(field);
+	if (raw?.type === "pending-expand") {
+		pending.push({
+			name: field.name,
+			describe,
+			set,
+			spec: raw.spec
+		});
+		return;
+	}
+	if (raw !== void 0) set(raw);
+}
+/**
+* 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, "_");
+}
+/**
+* Build the override env-var name shells inspect to pick a different
+* binary (`<NAME>_BIN`). Shell parameter names cannot begin with a
+* digit, so prepend an underscore when the upper-cased function name
+* starts with one — e.g. `2fa` ⇒ `_2FA_BIN`.
+*/
+function binEnvVarName(fn) {
+	const upper = fn.toUpperCase();
+	return /^[A-Z_]/.test(upper) ? `${upper}_BIN` : `_${upper}_BIN`;
+}
+/**
+* Hoisted expand-table variable name for a (funcSuffix, fieldName) at frame
+* scope. Bash uses indirect expansion `${!var}` on per-entry scalars, zsh
+* uses associative-array subscripts on this same base — the identifier
+* shape is identical, so both generators share this helper.
+*/
+function expandTableVarName(fn, funcSuffix, fieldName) {
+	return `__${fn}_expand_${funcSuffix}__${sanitize(fieldName)}`;
+}
+/**
+* Body of the `__<fn>_invoke_complete` wrapper that bash and zsh emit when
+* any field uses an in-process JS resolver. Bytes are identical between the
+* two shells — both use `local`, `shift`, and the `<NAME>_BIN`-override
+* lookup — so the helper lives here. Fish has a different `function`
+* syntax (no `local`, `set -l` instead) and emits its own version inline.
+*/
+function dynamicInvokeCompleteLines(fn, programName) {
+	return [
+		`__${fn}_invoke_complete() {`,
+		`    local _shell="$1"; shift`,
+		`    "\${${binEnvVarName(fn)}:-${programName}}" __complete --shell "$_shell" -- "$@" 2>/dev/null`,
+		`}`
+	];
+}
+/**
+* Filter subcommands to only visible (non-internal) ones.
+* Internal subcommands start with "__" and are hidden from completion/help.
+*/
+function getVisibleSubs(subs) {
+	return subs.filter((s) => !s.name.startsWith("__"));
+}
+/**
+* Get all completable subcommand names including aliases.
+* Returns an array of { name, description } for all visible subcommands
+* and their aliases.
+*/
+function getSubNamesWithAliases(subs) {
+	const result = [];
+	for (const sub of getVisibleSubs(subs)) {
+		result.push({
+			name: sub.name,
+			description: sub.description
+		});
+		if (sub.aliases) for (const alias of sub.aliases) result.push({
+			name: alias,
+			description: sub.description
+		});
+	}
+	return result;
+}
+/**
+* Convert a resolved field to a completable option. Pending expand specs
+* are stashed in `pending` and patched onto the returned object after
+* sibling choices are known.
+*/
+function fieldToOption(field, pending) {
+	const defaultNegationAccepted = field.type === "boolean" && (field.negation === void 0 || field.negation === true);
+	const opt = {
+		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,
+		required: field.required,
+		defaultNegationAccepted
+	};
+	assignValueCompletion(field, pending, `--${field.cliName}`, (next) => {
+		opt.valueCompletion = next;
+	});
+	return opt;
+}
+/**
+* Extract positional arguments from a command
+*/
+function extractPositionals(command) {
+	if (!command.args) return [];
+	return extractFields(command.args).fields.filter((field) => field.positional);
+}
+/** Convert pre-extracted fields to options. */
+function fieldsToOptions(fields, pending) {
+	return fields.filter((field) => !field.positional).map((field) => fieldToOption(field, pending));
+}
+/** Convert pre-extracted fields to positionals. */
+function fieldsToPositionals(fields, pending) {
+	return fields.filter((field) => field.positional).map((field, index) => {
+		const pos = {
+			name: field.name,
+			cliName: field.cliName,
+			position: index,
+			description: field.description,
+			required: field.required,
+			variadic: field.type === "array"
+		};
+		assignValueCompletion(field, pending, `<${field.cliName}>`, (next) => {
+			pos.valueCompletion = next;
+		});
+		return pos;
+	});
+}
+/**
+* Extract a completable subcommand from a command
+*/
+function extractSubcommand(name, command, globalOptions = []) {
+	const subcommands = [];
+	if (command.subCommands) for (const [subName, subCommand] of Object.entries(command.subCommands)) {
+		const resolved = resolveSubCommandMeta(subCommand);
+		if (resolved) subcommands.push(extractSubcommand(subName, resolved, globalOptions));
+		else subcommands.push({
+			name: subName,
+			description: "(lazy loaded)",
+			subcommands: [],
+			options: [],
+			positionals: []
+		});
+	}
+	const pending = [];
+	const fields = command.args ? extractFields(command.args).fields : [];
+	const node = {
+		name,
+		description: command.description,
+		aliases: command.aliases,
+		subcommands,
+		options: fieldsToOptions(fields, pending),
+		positionals: fieldsToPositionals(fields, pending)
+	};
+	resolveExpandTargets(node, pending, globalOptions);
+	return node;
+}
+/** Join parent and child with a separator, omitting separator when parent is empty. */
+function joinPrefix(parent, child, sep) {
+	return parent ? `${parent}${sep}${child}` : child;
+}
+/**
+* Expand each parent pathStr by joining every child name (canonical plus
+* aliases) with `:`. Used to keep alias-expanded path variants in lockstep
+* across walkers that need to reach the same node from any path the
+* runtime scanner can produce.
+*/
+function expandChildPathStrs(pathStrs, child) {
+	const childNames = [child.name, ...child.aliases ?? []];
+	return pathStrs.flatMap((p) => childNames.map((n) => joinPrefix(p, n, ":")));
+}
+/**
+* Walk the subcommand tree and yield a row per value-taking option, with
+* the path-aware token set the runtime would actually route here. Used by
+* all three shell generators — bash/zsh format these as `|`-joined case
+* patterns, fish wraps each pattern in a quoted glob.
+*
+* At ANCESTOR frames (those with further subcommand children) the runtime's
+* `scanForSubcommand` consults globals only — local-precedence does NOT
+* apply, so a global value option keeps every alias even when a local at
+* the frame claims the same short token. At LEAF frames, the leaf parser's
+* `separateGlobalArgs` applies local-precedence so `effectiveOptionTokens`
+* is the correct filter.
+*/
+function walkOptTakesValueRows(sub, parentPath) {
+	const rows = [];
+	const isAncestor = getVisibleSubs(sub.subcommands).length > 0;
+	for (const opt of sub.options) {
+		if (!opt.takesValue) continue;
+		const tokens = isAncestor && opt.isGlobal === true ? collectOptionTokens(opt.cliName, opt.alias) : effectiveOptionTokens(opt, sub.options);
+		if (tokens.length === 0) continue;
+		rows.push({
+			parentPath,
+			tokens
+		});
+	}
+	for (const child of getVisibleSubs(sub.subcommands)) for (const name of [child.name, ...child.aliases ?? []]) rows.push(...walkOptTakesValueRows(child, joinPrefix(parentPath, name, ":")));
+	return rows;
+}
+/**
+* Collect opt-takes-value case entries for a subcommand tree.
+* 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, parentPath) {
+	return walkOptTakesValueRows(sub, parentPath).map((row) => {
+		return `        ${row.tokens.map((t) => `${row.parentPath}:${t}`).join("|")}) return 0 ;;`;
+	});
+}
+/**
+* Recursively collect all subcommand route entries.
+* Returns entries used by all shell generators for both dispatch routing
+* and subcommand lookup (is_subcmd) tables.
+* Aliases are mapped to the same handler as the canonical name.
+*/
+function collectRouteEntries(sub, parentPath = "", parentFunc = "") {
+	const entries = [];
+	for (const child of getVisibleSubs(sub.subcommands)) {
+		const funcSuffix = joinPrefix(parentFunc, sanitize(child.name), "_");
+		for (const name of [child.name, ...child.aliases ?? []]) {
+			const pathStr = joinPrefix(parentPath, name, ":");
+			entries.push(...collectRouteEntries(child, pathStr, funcSuffix));
+			entries.push({
+				pathStr,
+				funcSuffix,
+				lookupPattern: `${parentPath}:${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 ;;`);
+}
+/**
+* Subcommand-dispatch case body lines for bash/zsh: each route forwards
+* `$_subcmd` to its handler function. Identical emission between shells.
+*/
+function subDispatchCaseLines(routeEntries, fn) {
+	return routeEntries.map((r) => `        ${r.pathStr}) __${fn}_complete_${r.funcSuffix} ;;`);
+}
+/**
+* Per-shell `_arg_values` write expression. zsh uses an associative-array
+* subscript; bash uses prefix-scalar variables so the generated script
+* runs on bash 3.2 (macOS default `/bin/bash`), which lacks associative
+* arrays. The `isGlobal` flag picks the bucket (`_global_arg_values_*`
+* survives subcommand descent; `_arg_values_*` does not).
+*/
+function trackedFieldAssign(t, shell) {
+	const prefix = t.isGlobal ? `_global_arg_values` : `_arg_values`;
+	return shell === "bash" ? `${prefix}_${sanitize(t.fieldName)}="$3"` : `${prefix}[${t.fieldName}]="$3"`;
+}
+/**
+* Case-statement body lines for `__track_opt` — capture option values into
+* the per-frame state. See {@link trackedFieldAssign} for the per-shell
+* assignment shape.
+*/
+function trackOptCaseLines(trackedFields, shell) {
+	const lines = [];
+	for (const t of trackedFields) {
+		if (t.isPositional || !t.optionTokens || t.optionTokens.length === 0) continue;
+		const joined = t.pathStrs.flatMap((p) => t.optionTokens.map((n) => `${p}:${n}`)).join("|");
+		lines.push(`        ${joined}) ${trackedFieldAssign(t, shell)} ;;`);
+	}
+	return lines;
+}
+/**
+* Case-statement body lines for `__track_pos` — capture positional values
+* by `(subcmd, positional-index)`. See {@link trackedFieldAssign} for the
+* per-shell assignment shape.
+*/
+function trackPosCaseLines(trackedFields, shell) {
+	const lines = [];
+	for (const t of trackedFields) {
+		if (!t.isPositional) continue;
+		const joined = t.pathStrs.map((p) => `${p}:${t.position}`).join("|");
+		lines.push(`        ${joined}) ${trackedFieldAssign(t, shell)} ;;`);
+	}
+	return lines;
+}
+/**
+* Case-statement body lines for `__track_array_expand` — record each `key=`
+* slot the user has typed so the candidate loop can skip already-consumed
+* entries. The first write to a global array in a frame replaces the
+* inherited bucket (mirroring the runtime's per-frame array merge);
+* subsequent writes append. zsh uses associative arrays; bash uses
+* prefix-scalar variables (see {@link trackOptCaseLines}).
+*/
+function trackArrayExpandCaseLines(arrayExpandSpecs, shell) {
+	const lines = [];
+	for (const spec of arrayExpandSpecs) {
+		if (spec.optionTokens.length === 0) continue;
+		const joined = spec.pathStrs.flatMap((p) => spec.optionTokens.map((tok) => `${p}:${tok}`)).join("|");
+		const bucket = sanitize(spec.fieldName);
+		const bucketPrefix = spec.isGlobal ? `_global_used_field_keys` : `_used_field_keys`;
+		const bucketRef = shell === "bash" ? `${bucketPrefix}_${bucket}` : `${bucketPrefix}[${bucket}]`;
+		const seenRef = shell === "bash" ? `_global_arr_seen_${bucket}` : `_global_arr_seen[${bucket}]`;
+		const assignFirst = `${bucketRef}=" $_k "`;
+		const assignAppend = `${bucketRef}+=" $_k "`;
+		const seenSet = `${seenRef}=1`;
+		lines.push(`        ${joined})`);
+		lines.push(`            if [[ "$3" == *=* ]]; then`);
+		lines.push(`                local _k="\${3%%=*}"`);
+		if (spec.isGlobal) {
+			lines.push(`                if [[ -n "$_k" ]]; then`);
+			lines.push(`                    if [[ -z "\${${seenRef}:-}" ]]; then`);
+			lines.push(`                        ${assignFirst}`);
+			lines.push(`                        ${seenSet}`);
+			lines.push(`                    else`);
+			lines.push(`                        ${assignAppend}`);
+			lines.push(`                    fi`);
+			lines.push(`                fi`);
+		} else lines.push(`                [[ -n "$_k" ]] && ${assignAppend}`);
+		lines.push(`            fi`);
+		lines.push(`            ;;`);
+	}
+	return lines;
+}
+/**
+* Compute the option token set the runtime would actually route to
+* `opt` at the given frame. Globals shadow LOCAL short tokens of the
+* same letter (runtime's `separateGlobalArgs` harvests `-x` for the
+* global unless the local explicitly declares `alias: "x"`), so a
+* local cliName `x` with no alias must NOT emit `-x` in its
+* tracker / value-completion / takes-value cases when a global at the
+* frame owns that token. Long forms are unaffected — precedence is
+* scoped to short aliases.
+*/
+function effectiveOptionTokens(opt, frameOptions) {
+	const all = collectOptionTokens(opt.cliName, opt.alias);
+	if (opt.isGlobal === true) {
+		const localClaimed = /* @__PURE__ */ new Set();
+		for (const o of frameOptions) {
+			if (o.isGlobal === true) continue;
+			for (const t of localShadowingTokens(o.cliName, o.alias)) localClaimed.add(t);
+		}
+		return all.filter((t) => !localClaimed.has(t));
+	}
+	const globalShort = globalShortTokens(frameOptions);
+	if (globalShort.size === 0) return all;
+	return all.filter((t) => {
+		if (!t.startsWith("-") || t.startsWith("--")) return true;
+		if (!globalShort.has(t)) return true;
+		return opt.alias?.includes(t.slice(1)) === true;
+	});
+}
+/**
+* Walk the subcommand tree and return every resolved expand spec along
+* with where it lives. The order is deterministic (DFS, root → leaves;
+* options before positionals within a node).
+*/
+function collectExpandSpecs(root) {
+	const out = [];
+	walk(root, [], [""], [], "root", out);
+	return out;
+}
+function walk(node, path, pathStrs, intermediatePathStrs, funcSuffix, out) {
+	const pathStr = pathStrs[0];
+	for (const opt of node.options) {
+		const vc = opt.valueCompletion;
+		if (vc?.type === "expand") {
+			const isArrayOption = opt.valueType === "array";
+			out.push({
+				path,
+				pathStr,
+				pathStrs,
+				intermediatePathStrs,
+				funcSuffix,
+				fieldName: opt.name,
+				isGlobal: opt.isGlobal === true,
+				isPositional: false,
+				isArrayOption,
+				optionTokens: isArrayOption ? effectiveOptionTokens(opt, node.options) : [],
+				vc
+			});
+		}
+	}
+	for (const pos of node.positionals) {
+		const vc = pos.valueCompletion;
+		if (vc?.type === "expand") out.push({
+			path,
+			pathStr,
+			pathStrs,
+			intermediatePathStrs,
+			funcSuffix,
+			fieldName: pos.name,
+			isGlobal: false,
+			isPositional: true,
+			isArrayOption: false,
+			optionTokens: [],
+			vc
+		});
+	}
+	for (const child of getVisibleSubs(node.subcommands)) walk(child, [...path, child.name], expandChildPathStrs(pathStrs, child), [...intermediatePathStrs, ...pathStrs], funcSuffix === "root" ? sanitize(child.name) : `${funcSuffix}_${sanitize(child.name)}`, out);
+}
+/**
+* For every expand spec, find each `dependsOn` sibling field at the same
+* path and return enough metadata for the shell generator to emit tracker
+* cases. Fields that cannot be resolved are silently skipped — the static
+* extractor already validated `dependsOn` upstream in
+* `resolveExpandTargets`, so unresolved siblings here would indicate a
+* programming error and would simply yield no tracker entries.
+*/
+function collectTrackedFields(root, specs, globalOptions = []) {
+	const nodeByPath = indexNodesByPath(root);
+	const buckets = /* @__PURE__ */ new Map();
+	const addPath = (key, ref, paths) => {
+		let bucket = buckets.get(key);
+		if (!bucket) {
+			bucket = {
+				ref,
+				pathStrs: [],
+				seen: /* @__PURE__ */ new Set()
+			};
+			buckets.set(key, bucket);
+		}
+		for (const p of paths) {
+			if (bucket.seen.has(p)) continue;
+			bucket.seen.add(p);
+			bucket.pathStrs.push(p);
+		}
+	};
+	/**
+	* Group spec frames by the per-leaf surviving-token set for a global option.
+	* The runtime scanner at a LEAF frame drops global tokens that a local
+	* option already claims (via `localShadowingTokens`); at ANCESTOR frames it
+	* sees only globals so every token survives. Grouping by token-set keeps the
+	* generated tracker case body minimal — one branch per unique frame group.
+	*/
+	const groupGlobalFramesByTokenSet = (optTokens, leafPaths, ancestorPaths) => {
+		const groups = /* @__PURE__ */ new Map();
+		const recordLeaf = (path, tokens) => {
+			if (tokens.length === 0) return;
+			const tokenKey = tokens.join(" ");
+			let group = groups.get(tokenKey);
+			if (!group) {
+				group = {
+					tokens,
+					paths: []
+				};
+				groups.set(tokenKey, group);
+			}
+			group.paths.push(path);
+		};
+		for (const p of leafPaths) {
+			const n = nodeByPath.get(p);
+			if (!n) continue;
+			const claimed = /* @__PURE__ */ new Set();
+			for (const o of n.options) {
+				if (o.isGlobal === true) continue;
+				for (const t of localShadowingTokens(o.cliName, o.alias)) claimed.add(t);
+			}
+			recordLeaf(p, optTokens.filter((t) => !claimed.has(t)));
+		}
+		for (const p of ancestorPaths) recordLeaf(p, optTokens);
+		return groups;
+	};
+	const addGlobalDepTracker = (dep, opt, spec) => {
+		const groups = groupGlobalFramesByTokenSet(collectOptionTokens(opt.cliName, opt.alias), spec.pathStrs, spec.intermediatePathStrs);
+		for (const [tokenKey, group] of groups) addPath(`g::${dep}::${tokenKey}`, {
+			fieldName: dep,
+			isGlobal: true,
+			isPositional: false,
+			optionTokens: group.tokens
+		}, group.paths);
+	};
+	for (const spec of specs) {
+		const node = nodeByPath.get(spec.pathStr);
+		if (!node) continue;
+		for (const dep of spec.vc.dependsOn) {
+			if (spec.isGlobal) {
+				const globalOpt = globalOptions.find((o) => o.name === dep);
+				if (!globalOpt) continue;
+				addGlobalDepTracker(dep, globalOpt, spec);
+				continue;
+			}
+			const posIndex = node.positionals.findIndex((p) => p.name === dep);
+			if (posIndex >= 0) {
+				addPath(`lp::${spec.pathStr}::${dep}`, {
+					fieldName: dep,
+					isGlobal: false,
+					isPositional: true,
+					position: posIndex
+				}, spec.pathStrs);
+				continue;
+			}
+			const opt = node.options.find((o) => o.name === dep);
+			if (!opt) continue;
+			if (opt.isGlobal === true) {
+				addGlobalDepTracker(dep, opt, spec);
+				continue;
+			}
+			addPath(`lo::${spec.pathStr}::${dep}`, {
+				fieldName: dep,
+				isGlobal: false,
+				isPositional: false,
+				optionTokens: effectiveOptionTokens(opt, node.options)
+			}, spec.pathStrs);
+		}
+	}
+	const out = [];
+	for (const bucket of buckets.values()) {
+		if (bucket.pathStrs.length === 0) continue;
+		out.push({
+			...bucket.ref,
+			pathStr: bucket.pathStrs[0],
+			pathStrs: bucket.pathStrs
+		});
+	}
+	return out;
+}
+function indexNodesByPath(root) {
+	const map = /* @__PURE__ */ new Map();
+	const recurse = (node, pathStrs) => {
+		for (const p of pathStrs) map.set(p, node);
+		for (const child of getVisibleSubs(node.subcommands)) recurse(child, expandChildPathStrs(pathStrs, child));
+	};
+	recurse(root, [""]);
+	return map;
+}
+/**
+* Walk a CompletableSubcommand tree and return true when any option or
+* positional uses an in-process dynamic resolver. Used by shell generators
+* to decide whether to emit `__<fn>_invoke_complete` delegate helpers.
+*/
+function hasDynamicCompletion(sub) {
+	for (const opt of sub.options) if (opt.valueCompletion?.type === "dynamic") return true;
+	for (const pos of sub.positionals) if (pos.valueCompletion?.type === "dynamic") return true;
+	for (const child of sub.subcommands) if (hasDynamicCompletion(child)) return true;
+	return false;
+}
+/**
+* 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, globalArgsSchema) {
+	let globalOptions = [];
+	if (globalArgsSchema) {
+		const globalPending = [];
+		globalOptions = fieldsToOptions(extractFields(globalArgsSchema).fields, globalPending).map((opt) => {
+			opt.isGlobal = true;
+			return opt;
+		});
+		resolveExpandTargets({
+			name: programName,
+			subcommands: [],
+			options: globalOptions,
+			positionals: []
+		}, globalPending);
+	}
+	const rootSubcommand = extractSubcommand(programName, command, globalOptions);
+	if (globalArgsSchema) propagateGlobalOptions(rootSubcommand, globalOptions);
+	else globalOptions = rootSubcommand.options;
+	return {
+		command: rootSubcommand,
+		programName,
+		globalOptions
+	};
+}
+
+//#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 */
+function escapeBashDQ(s) {
+	return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\$/g, "\\$").replace(/`/g, "\\`");
+}
+/**
+* Hex-encode the UTF-8 byte representation of `s` so the resulting
+* string is safe as a suffix of a bash identifier. Each non-alnum byte
+* becomes `_HH` (exactly 2 hex digits, always upper-case). `_` is also
+* encoded (as `_5F`) to keep the join separator between encoded dep
+* values unambiguous — without that, `(v1="-", v2="")` and
+* `(v1="_2D", v2="")` would both render `_2D_`.
+*
+* Per-byte fixed-width encoding avoids the variable-length codepoint
+* collision where `-A` (codepoint 0x2D + literal `A`) and `˚` (codepoint
+* 0x02DA) would both produce `_2DA` under the previous scheme. Mirrors
+* the runtime `__<fn>_enc` helper emitted alongside expand tables; the
+* helper forces `LC_ALL=C` so its `${var:i:1}` iterates over the same
+* UTF-8 bytes this encoder emits.
+*/
+function bashEncodeKey(s) {
+	let out = "";
+	const bytes = new TextEncoder().encode(s);
+	for (const byte of bytes) if (byte >= 48 && byte <= 57 || byte >= 65 && byte <= 90 || byte >= 97 && byte <= 122) out += String.fromCharCode(byte);
+	else out += `_${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+	return out;
+}
+/**
+* Generate bash value completion code for a ValueCompletion spec.
+* `location` is required when `vc.type === "expand"` (otherwise unused).
+*/
+function bashValueLines(vc, inline, fn, location) {
+	if (!vc) return [];
+	switch (vc.type) {
+		case "expand": {
+			if (!location) throw new Error("bashValueLines: expand variant requires a location");
+			const varName = expandTableVarName(fn, location.funcSuffix, location.fieldName);
+			const encLines = [`local _enc_key='' _enc_v`];
+			location.resolvedDeps.forEach((d, i) => {
+				const safe = sanitize(d.name);
+				const varRef = d.isGlobal ? `_global_arg_values_${safe}` : `_arg_values_${safe}`;
+				encLines.push(`_enc_v="\${${varRef}:-}"`);
+				encLines.push(i === 0 ? `_enc_key="$(__${fn}_enc "$_enc_v")"` : `_enc_key+="_$(__${fn}_enc "$_enc_v")"`);
+			});
+			const inlineExpr = inline ? `"\${_inline_prefix}\${_c}"` : `"$_c"`;
+			const bucketRef = location.isGlobal ? `\${_global_used_field_keys_${sanitize(location.fieldName)}:-}` : `\${_used_field_keys_${sanitize(location.fieldName)}:-}`;
+			const arrayDedupLines = location.isArrayOption ? [`            if [[ -n "$_ck" && " ${bucketRef} " == *" $_ck "* ]]; then continue; fi`] : [];
+			return [
+				`compopt +o default 2>/dev/null`,
+				...encLines,
+				`local _varname=${varName}__\${_enc_key}`,
+				`local _raw="\${!_varname:-}"`,
+				`if [[ -n "$_raw" ]]; then`,
+				`    local -a _vals=()`,
+				`    local _line`,
+				`    while IFS= read -r _line; do _vals+=("$_line"); done <<< "$_raw"`,
+				`    local _c _ck _seen_keys=" " _had_key=0`,
+				`    for _c in "\${_vals[@]}"; do`,
+				`        [[ -z "$_c" ]] && continue`,
+				`        if [[ "$_c" == *=* ]]; then`,
+				`            _ck="\${_c%%=*}"`,
+				...arrayDedupLines,
+				`            if [[ "$_cur" != *=* ]]; then`,
+				`                [[ "$_seen_keys" == *" $_ck "* ]] && continue`,
+				`                _seen_keys+="$_ck "`,
+				`                _c="\${_ck}="`,
+				`                _had_key=1`,
+				`            elif [[ "$_c" != *=?* ]]; then`,
+				`                continue`,
+				`            fi`,
+				`        fi`,
+				`        [[ "$_c" == "$_cur"* ]] && COMPREPLY+=(${inlineExpr})`,
+				`    done`,
+				`    if (( _had_key )); then compopt -o nospace 2>/dev/null; fi`,
+				`fi`,
+				`if (( \${#COMPREPLY[@]} == 0 )); then COMPREPLY=( "" ); fi`
+			];
+		}
+		case "dynamic": return [
+			`local _dyn_out`,
+			`_dyn_out=$(__${fn}_invoke_complete bash "\${_words[@]}")`,
+			`__${fn}_apply_dynamic_output "$_dyn_out"`
+		];
+		case "choices": {
+			const lines = [
+				`local -a _choices=(${vc.choices.map((c) => `"${escapeBashDQ(c)}"`).join(" ")})`,
+				`COMPREPLY=()`,
+				`local _c; for _c in "\${_choices[@]}"; do [[ "$_c" == "$_cur"* ]] && COMPREPLY+=("\${_inline_prefix}\${_c}"); done`
+			];
+			if (inline) lines.push(`compopt -o nospace`);
+			lines.push(`compopt +o default 2>/dev/null`);
+			return lines;
+		}
+		case "file":
+			if (vc.matcher?.length) return bashFileFilter(vc.matcher.map((p) => `[[ "\${_f##*/}" == ${p} ]]`).join(" || "));
+			if (vc.extensions?.length) return bashFileFilter(vc.extensions.map((ext) => `[[ "$_f" == *".${ext}" ]]`).join(" || "));
+			return [`COMPREPLY=($(compgen -P "$_inline_prefix" -f -- "$_cur"))`, `compopt -o filenames`];
+		case "directory": return [`COMPREPLY=($(compgen -P "$_inline_prefix" -d -- "$_cur"))`, `compopt -o filenames`];
+		case "command": return [`COMPREPLY=($(compgen -P "$_inline_prefix" -W "$(${vc.shellCommand})" -- "$_cur"))`];
+		case "none": return [`compopt +o default 2>/dev/null`];
+	}
+}
+/**
+* Snippet that unsets every shell variable matching `<prefix>*`. Bash 3.2
+* has no associative arrays, so the trackers use one variable per field;
+* the per-invocation reset clears them by enumerating with `compgen -v
+* <prefix>` and feeding the names to `unset`. `2>/dev/null` is paired both
+* sides so an empty enumeration result (no variables yet) doesn't print
+* the `unset:` usage line.
+*/
+function unsetPrefixed(prefix) {
+	return `unset $(compgen -v ${prefix} 2>/dev/null) 2>/dev/null`;
+}
+function bashFileFilter(checks) {
+	return [
+		`local -a _all_entries=($(compgen -f -- "$_cur"))`,
+		`for _f in "\${_all_entries[@]}"; do`,
+		`    if [[ -d "$_f" ]]; then`,
+		`        COMPREPLY+=("\${_inline_prefix}$_f")`,
+		`    elif ${checks}; then`,
+		`        COMPREPLY+=("\${_inline_prefix}$_f")`,
+		`    fi`,
+		`done`,
+		`compopt -o filenames`,
+		`compopt +o default 2>/dev/null`
+	];
+}
+/** Collect value-taking option patterns for case matching */
+function optionValueCases$2(options, positionals, inline, fn, funcSuffix) {
+	const lines = [];
+	for (const opt of options) {
+		if (!opt.takesValue || !opt.valueCompletion) continue;
+		const valLines = bashValueLines(opt.valueCompletion, inline, fn, {
+			funcSuffix,
+			...optionExpandLocation(opt, options, positionals)
+		});
+		if (valLines.length === 0) continue;
+		const patterns = effectiveOptionTokens(opt, options);
+		if (patterns.length === 0) continue;
+		lines.push(`            ${patterns.join("|")})`);
+		for (const vl of valLines) lines.push(`                ${vl}`);
+		lines.push(`                return ;;`);
+	}
+	return lines;
+}
+/** Generate positional completion block */
+function positionalBlock$2(positionals, fn, funcSuffix, options = []) {
+	if (positionals.length === 0) return [];
+	const lines = [];
+	lines.push(`    case "$_pos_count" in`);
+	for (const pos of positionals) {
+		if (pos.variadic) lines.push(`        ${pos.position}|*)`);
+		else lines.push(`        ${pos.position})`);
+		for (const vl of bashValueLines(pos.valueCompletion, false, fn, {
+			funcSuffix,
+			...positionalExpandLocation(pos, options, positionals)
+		})) lines.push(`            ${vl}`);
+		lines.push(`            ;;`);
+	}
+	lines.push(`    esac`);
+	return lines;
+}
+/** Generate prev/inline value completion blocks for options */
+function valueCompletionBlocks(options, positionals, fn, funcSuffix) {
+	if (!options.some((o) => o.takesValue && o.valueCompletion)) return [];
+	const lines = [];
+	const prevCases = optionValueCases$2(options, positionals, false, fn, funcSuffix);
+	if (prevCases.length > 0) {
+		lines.push(`    if [[ -z "$_inline_prefix" ]]; then`);
+		lines.push(`        case "$_prev" in`);
+		lines.push(...prevCases);
+		lines.push(`        esac`);
+		lines.push(`    fi`);
+	}
+	const inlineCases = optionValueCases$2(options, positionals, true, fn, funcSuffix);
+	if (inlineCases.length > 0) {
+		lines.push(`    if [[ -n "$_inline_prefix" ]]; then`);
+		lines.push(`        case "\${_inline_prefix%=}" in`);
+		lines.push(...inlineCases);
+		lines.push(`        esac`);
+		lines.push(`    fi`);
+	}
+	return lines;
+}
+/** Generate available-options list lines */
+function availableOptionLines$2(options, fn) {
+	const lines = [];
+	for (const opt of options) {
+		if (opt.valueType === "array") {
+			lines.push(`        _avail+=(--${opt.cliName})`);
+			continue;
+		}
+		const patterns = quotedAvailabilityTokens(opt.cliName, opt.alias, opt.negation, {
+			isGlobal: opt.isGlobal === true,
+			frameOptions: options
+		});
+		const guard = `__${fn}_not_used ${patterns.join(" ")}`;
+		const emitNames = opt.negation ? [opt.cliName, opt.negation] : [opt.cliName];
+		for (const name of emitNames) {
+			if (!patterns.includes(`"--${name}"`)) continue;
+			lines.push(`        ${guard} && _avail+=(--${name})`);
+		}
+	}
+	lines.push(`        __${fn}_not_used "--help" && _avail+=(--help)`);
+	return lines;
+}
+/**
+* Generate a per-subcommand completion function.
+* Recursively generates functions for nested subcommands.
+*/
+function generateSubHandler$2(sub, fn, path) {
+	const fullPath = [...path, sub.name];
+	const funcSuffix = fullPath.map(sanitize).join("_");
+	const funcName = `__${fn}_complete_${funcSuffix}`;
+	const visibleSubs = getVisibleSubs(sub.subcommands);
+	const lines = [];
+	for (const child of visibleSubs) lines.push(...generateSubHandler$2(child, fn, fullPath));
+	lines.push(`${funcName}() {`);
+	lines.push(...valueCompletionBlocks(sub.options, sub.positionals, fn, funcSuffix));
+	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, fn, funcSuffix, sub.options).map((l) => `    ${l}`));
+		lines.push(`        return`);
+		lines.push(`    fi`);
+	} else lines.push(`    if (( _after_dd )); then return; fi`);
+	lines.push(`    if [[ "$_cur" == -* ]]; then`);
+	lines.push(`        local -a _avail=()`);
+	lines.push(...availableOptionLines$2(sub.options, fn));
+	lines.push(`        COMPREPLY=($(compgen -W "\${_avail[*]}" -- "$_cur"))`);
+	lines.push(`        compopt +o default 2>/dev/null`);
+	lines.push(`        return`);
+	lines.push(`    fi`);
+	if (visibleSubs.length > 0) {
+		const subNames = getSubNamesWithAliases(sub.subcommands).map((s) => s.name).join(" ");
+		lines.push(`    COMPREPLY=($(compgen -W "${subNames}" -- "$_cur"))`);
+		lines.push(`    compopt +o default 2>/dev/null`);
+	} else if (sub.positionals.length > 0) lines.push(...positionalBlock$2(sub.positionals, fn, funcSuffix, sub.options));
+	lines.push(`}`);
+	lines.push(``);
+	return lines;
+}
+function generateBashCompletion(command, options) {
+	const { programName } = options;
+	const data = extractCompletionData(command, programName, options.globalArgsSchema);
+	const fn = sanitize(programName);
+	const root = data.command;
+	const visibleSubs = getVisibleSubs(root.subcommands);
+	const expandSpecs = collectExpandSpecs(root);
+	const trackedFields = collectTrackedFields(root, expandSpecs, data.globalOptions);
+	const lines = [];
+	lines.push(...buildHeaderLines({
+		programName,
+		shell: "bash",
+		binPath: options.binPath,
+		programVersion: options.programVersion
+	}));
+	lines.push(`# Generated by politty`);
+	lines.push(``);
+	const hasExpand = expandSpecs.length > 0;
+	const arrayExpandSpecs = expandSpecs.filter((s) => s.isArrayOption);
+	const hasArrayExpand = arrayExpandSpecs.length > 0;
+	if (hasExpand) {
+		lines.push(`__${fn}_enc() {`);
+		lines.push(`    local LC_ALL=C`);
+		lines.push(`    local _s=$1 _r='' _c _i`);
+		lines.push(`    for (( _i=0; _i<\${#_s}; _i++ )); do`);
+		lines.push(`        _c=\${_s:_i:1}`);
+		lines.push(`        case "$_c" in`);
+		lines.push(`            [a-zA-Z0-9]) _r+="$_c" ;;`);
+		lines.push(`            *) printf -v _r '%s_%02X' "$_r" "'$_c" ;;`);
+		lines.push(`        esac`);
+		lines.push(`    done`);
+		lines.push(`    printf '%s' "$_r"`);
+		lines.push(`}`);
+		lines.push(``);
+	}
+	for (const spec of expandSpecs) {
+		const varName = expandTableVarName(fn, spec.funcSuffix, spec.fieldName);
+		for (const entry of spec.vc.table) {
+			const encKey = entry.key.map(bashEncodeKey).join("_");
+			const value = entry.candidates.map((c) => c.value).join("\n");
+			lines.push(`${varName}__${encKey}=${ansiC(value)}`);
+		}
+		lines.push(``);
+	}
+	if (hasDynamicCompletion(root)) {
+		lines.push(...dynamicInvokeCompleteLines(fn, programName));
+		lines.push(``);
+		lines.push(`__${fn}_apply_dynamic_output() {`);
+		lines.push(`    local _raw="$1"`);
+		lines.push(`    COMPREPLY=()`);
+		lines.push(`    local _directive=0`);
+		lines.push(`    local -a _lines=()`);
+		lines.push(`    local _line`);
+		lines.push(`    while IFS= read -r _line; do _lines+=("$_line"); done <<< "$_raw"`);
+		lines.push(`    local _last=$((\${#_lines[@]} - 1))`);
+		lines.push(`    if (( _last >= 0 )) && [[ "\${_lines[$_last]}" =~ ^:[0-9]+$ ]]; then`);
+		lines.push(`        _directive="\${_lines[$_last]#:}"`);
+		lines.push(`        unset '_lines[_last]'`);
+		lines.push(`    fi`);
+		lines.push(`    for _line in "\${_lines[@]}"; do`);
+		lines.push(`        [[ -z "$_line" ]] && continue`);
+		lines.push(`        COMPREPLY+=("$_line")`);
+		lines.push(`    done`);
+		lines.push(`    local _ip="\${_inline_prefix:-}"`);
+		lines.push(`    if (( _directive & ${CompletionDirective.DirectoryCompletion} )); then`);
+		lines.push(`        compopt +o default 2>/dev/null`);
+		lines.push(`        compopt -o filenames 2>/dev/null`);
+		lines.push(`        local _d`);
+		lines.push(`        while IFS= read -r _d; do COMPREPLY+=("\${_ip}\${_d}"); done < <(compgen -d -- "$_cur")`);
+		lines.push(`        if (( \${#COMPREPLY[@]} == 0 )); then COMPREPLY=( "" ); fi`);
+		lines.push(`    elif (( _directive & ${CompletionDirective.FileCompletion} )); then`);
+		lines.push(`        if (( \${#COMPREPLY[@]} > 0 )) || [[ -n "$_ip" ]]; then`);
+		lines.push(`            compopt -o filenames 2>/dev/null`);
+		lines.push(`            local _f`);
+		lines.push(`            while IFS= read -r _f; do COMPREPLY+=("\${_ip}\${_f}"); done < <(compgen -f -- "$_cur")`);
+		lines.push(`        else`);
+		lines.push(`            compopt -o default 2>/dev/null`);
+		lines.push(`        fi`);
+		lines.push(`    else`);
+		lines.push(`        if (( _directive & ${CompletionDirective.NoFileCompletion} )); then`);
+		lines.push(`            compopt +o default 2>/dev/null`);
+		lines.push(`            if (( \${#COMPREPLY[@]} == 0 )); then COMPREPLY=( "" ); fi`);
+		lines.push(`        fi`);
+		lines.push(`    fi`);
+		lines.push(`    if (( _directive & ${CompletionDirective.NoSpace} )); then`);
+		lines.push(`        compopt -o nospace 2>/dev/null`);
+		lines.push(`    fi`);
+		lines.push(`}`);
+		lines.push(``);
+	}
+	lines.push(`__${fn}_not_used() {`);
+	lines.push(`    for _u in "\${_used_opts[@]}"; do`);
+	lines.push(`        for _chk in "$@"; do`);
+	lines.push(`            [[ "$_u" == "$_chk" ]] && return 1`);
+	lines.push(`        done`);
+	lines.push(`    done`);
+	lines.push(`    return 0`);
+	lines.push(`}`);
+	lines.push(``);
+	lines.push(`__${fn}_opt_takes_value() {`);
+	lines.push(`    case "$1:$2" in`);
+	lines.push(...optTakesValueEntries(root, ""));
+	lines.push(`    esac`);
+	lines.push(`    return 1`);
+	lines.push(`}`);
+	lines.push(``);
+	if (hasExpand) {
+		lines.push(`__${fn}_track_opt() {`);
+		lines.push(`    case "$1:$2" in`);
+		lines.push(...trackOptCaseLines(trackedFields, "bash"));
+		lines.push(`    esac`);
+		lines.push(`}`);
+		lines.push(``);
+		lines.push(`__${fn}_track_pos() {`);
+		lines.push(`    case "$1:$2" in`);
+		lines.push(...trackPosCaseLines(trackedFields, "bash"));
+		lines.push(`    esac`);
+		lines.push(`}`);
+		lines.push(``);
+	}
+	if (hasArrayExpand) {
+		lines.push(`__${fn}_track_array_expand() {`);
+		lines.push(`    case "$1:$2" in`);
+		lines.push(...trackArrayExpandCaseLines(arrayExpandSpecs, "bash"));
+		lines.push(`    esac`);
+		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, root.positionals, fn, "root"));
+	lines.push(`    if [[ -z "$_inline_prefix" ]] && __${fn}_opt_takes_value "" "$_prev"; then return; fi`);
+	lines.push(`    if [[ -n "$_inline_prefix" ]] && __${fn}_opt_takes_value "" "\${_inline_prefix%=}"; then return; fi`);
+	if (root.positionals.length > 0) {
+		lines.push(`    if (( _after_dd )); then`);
+		lines.push(...positionalBlock$2(root.positionals, fn, "root", root.options).map((l) => `    ${l}`));
+		lines.push(`        return`);
+		lines.push(`    fi`);
+	} else lines.push(`    if (( _after_dd )); then return; fi`);
+	lines.push(`    if [[ "$_cur" == -* ]]; then`);
+	lines.push(`        local -a _avail=()`);
+	lines.push(...availableOptionLines$2(root.options, fn));
+	lines.push(`        COMPREPLY=($(compgen -W "\${_avail[*]}" -- "$_cur"))`);
+	lines.push(`        compopt +o default 2>/dev/null`);
+	if (visibleSubs.length > 0) {
+		lines.push(`    else`);
+		const subNames = getSubNamesWithAliases(root.subcommands).map((s) => s.name).join(" ");
+		lines.push(`        COMPREPLY=($(compgen -W "${subNames}" -- "$_cur"))`);
+		lines.push(`        compopt +o default 2>/dev/null`);
+	} else if (root.positionals.length > 0) {
+		lines.push(`    else`);
+		lines.push(...positionalBlock$2(root.positionals, fn, "root", root.options).map((l) => `    ${l}`));
+	}
+	lines.push(`    fi`);
+	lines.push(`}`);
+	lines.push(``);
+	const subRouting = subDispatchCaseLines(routeEntries, fn).join("\n");
+	lines.push(`_${fn}_completions() {`);
+	lines.push(`    COMPREPLY=()`);
+	lines.push(``);
+	lines.push(`    # Rejoin words split by '=' in COMP_WORDBREAKS`);
+	lines.push(`    local -a _words=()`);
+	lines.push(`    local _i=1`);
+	lines.push(`    while (( _i <= COMP_CWORD )); do`);
+	lines.push(`        if [[ "\${COMP_WORDS[_i]}" == "=" && \${#_words[@]} -gt 0 ]]; then`);
+	lines.push(`            _words[\${#_words[@]}-1]+="=\${COMP_WORDS[_i+1]:-}"`);
+	lines.push(`            (( _i += 2 ))`);
+	lines.push(`        else`);
+	lines.push(`            _words+=("\${COMP_WORDS[_i]}")`);
+	lines.push(`            (( _i++ ))`);
+	lines.push(`        fi`);
+	lines.push(`    done`);
+	lines.push(``);
+	lines.push(`    local _cur=""`);
+	lines.push(`    (( \${#_words[@]} > 0 )) && _cur="\${_words[\${#_words[@]}-1]}"`);
+	lines.push(`    local _inline_prefix=""`);
+	lines.push(``);
+	lines.push(`    local _prev=""`);
+	lines.push(`    (( \${#_words[@]} > 1 )) && _prev="\${_words[\${#_words[@]}-2]}"`);
+	lines.push(``);
+	lines.push(`    local _subcmd="" _after_dd=0 _pos_count=0 _skip_next=0`);
+	lines.push(`    local -a _used_opts=()`);
+	if (hasExpand) {
+		lines.push(`    ${unsetPrefixed("_arg_values_")}`);
+		lines.push(`    ${unsetPrefixed("_global_arg_values_")}`);
+	}
+	if (hasArrayExpand) {
+		lines.push(`    ${unsetPrefixed("_used_field_keys_")}`);
+		lines.push(`    ${unsetPrefixed("_global_used_field_keys_")}`);
+		lines.push(`    ${unsetPrefixed("_global_arr_seen_")}`);
+	}
+	lines.push(``);
+	lines.push(`    local _j=0`);
+	lines.push(`    while (( _j < \${#_words[@]} - 1 )); do`);
+	lines.push(`        local _w="\${_words[_j]}"`);
+	lines.push(`        if (( _skip_next )); then _skip_next=0; (( _j++ )); continue; fi`);
+	lines.push(`        if [[ "$_w" == "--" ]]; then _after_dd=1; (( _j++ )); continue; fi`);
+	const afterDdTrack = hasExpand ? `__${fn}_track_pos "$_subcmd" "$_pos_count" "$_w"; ` : "";
+	lines.push(`        if (( _after_dd )); then ${afterDdTrack}(( _pos_count++ )); (( _j++ )); continue; fi`);
+	lines.push(`        if [[ "$_w" == -*=* ]]; then`);
+	lines.push(`            _used_opts+=("\${_w%%=*}")`);
+	if (hasExpand) {
+		lines.push(`            __${fn}_track_opt "$_subcmd" "\${_w%%=*}" "\${_w#*=}"`);
+		if (hasArrayExpand) lines.push(`            __${fn}_track_array_expand "$_subcmd" "\${_w%%=*}" "\${_w#*=}"`);
+	}
+	lines.push(`            (( _j++ )); continue`);
+	lines.push(`        fi`);
+	lines.push(`        if [[ "$_w" == -* ]]; then`);
+	lines.push(`            _used_opts+=("$_w")`);
+	lines.push(`            if __${fn}_opt_takes_value "$_subcmd" "$_w"; then`);
+	lines.push(`                local _next="\${_words[_j+1]:-}"`);
+	lines.push(`                if [[ -n "$_next" && "$_next" != -* ]]; then _skip_next=1; fi`);
+	if (hasExpand) {
+		lines.push(`                if (( _skip_next )); then`);
+		lines.push(`                    __${fn}_track_opt "$_subcmd" "$_w" "$_next"`);
+		if (hasArrayExpand) {
+			lines.push(`                    if (( _j + 2 < \${#_words[@]} )); then`);
+			lines.push(`                        __${fn}_track_array_expand "$_subcmd" "$_w" "$_next"`);
+			lines.push(`                    fi`);
+		}
+		lines.push(`                fi`);
+	}
+	lines.push(`            fi`);
+	lines.push(`            (( _j++ )); continue`);
+	lines.push(`        fi`);
+	const clearState = hasArrayExpand ? `; ${unsetPrefixed("_arg_values_")}; ${unsetPrefixed("_used_field_keys_")}; ${unsetPrefixed("_global_arr_seen_")}` : hasExpand ? `; ${unsetPrefixed("_arg_values_")}` : "";
+	const posTrack = hasExpand ? `__${fn}_track_pos "$_subcmd" "$_pos_count" "$_w"; ` : "";
+	if (routeEntries.length > 0) lines.push(`        if __${fn}_is_subcmd "$_subcmd" "$_w"; then _subcmd="\${_subcmd:+\${_subcmd}:}$_w"; _used_opts=(); _pos_count=0${clearState}; else ${posTrack}(( _pos_count++ )); fi`);
+	else {
+		if (hasExpand) lines.push(`        __${fn}_track_pos "$_subcmd" "$_pos_count" "$_w"`);
+		lines.push(`        (( _pos_count++ ))`);
+	}
+	lines.push(`        (( _j++ ))`);
+	lines.push(`    done`);
+	lines.push(``);
+	lines.push(`    if (( ! _after_dd )) && [[ "$_cur" == -*=* ]]; then`);
+	lines.push(`        _inline_prefix="\${_cur%%=*}="`);
+	lines.push(`        _cur="\${_cur#*=}"`);
+	lines.push(`    fi`);
+	lines.push(``);
+	lines.push(`    case "$_subcmd" in`);
+	lines.push(subRouting);
+	lines.push(`        *) __${fn}_complete_root ;;`);
+	lines.push(`    esac`);
+	lines.push(`}`);
+	lines.push(``);
+	lines.push(`complete -o default -F _${fn}_completions ${programName}`);
+	lines.push(``);
+	return {
+		script: lines.join("\n"),
+		shell: "bash",
+		installInstructions: `# To enable completions, add the following to your ~/.bashrc:
+
+# Option 1: Source directly
+eval "$(${programName} completion bash)"
+
+# Option 2: Save to a file
+${programName} completion bash > ~/.local/share/bash-completion/completions/${programName}
+
+# Then reload your shell or run:
+source ~/.bashrc`
+	};
+}
+
+//#endregion
+//#region src/completion/dynamic/shell-formatter.ts
+/**
+* Format completion candidates for the specified shell
+*
+* @returns Shell-ready output string (lines separated by newline, last line is :directive)
+*/
+function formatForShell(result, options) {
+	switch (options.shell) {
+		case "bash": return formatForBash(result, options);
+		case "zsh": return formatForZsh(result, options);
+		case "fish": return formatForFish(result, options);
+	}
+}
+/**
+* Append extension metadata and directive to output lines
+*/
+function appendMetadata(lines, result) {
+	if (result.fileExtensions && result.fileExtensions.length > 0) lines.push(`@ext:${result.fileExtensions.join(",")}`);
+	if (result.fileMatchers && result.fileMatchers.length > 0) lines.push(`@matcher:${result.fileMatchers.join(",")}`);
+	lines.push(`:${result.directive}`);
+}
+/**
+* Format for bash
+*
+* - Pre-filters candidates by currentWord prefix (replaces compgen -W)
+* - Handles --opt=value inline values by prepending prefix
+* - Outputs plain values only (no descriptions - bash COMPREPLY doesn't support them)
+* - Last line: :directive
+*/
+function formatForBash(result, options) {
+	const lines = ((result.directive & CompletionDirective.FilterPrefix) !== 0 && options.currentWord ? result.candidates.filter((c) => c.value.startsWith(options.currentWord)) : result.candidates).map((c) => options.inlinePrefix ? `${options.inlinePrefix}${c.value}` : c.value);
+	appendMetadata(lines, result);
+	return lines.join("\n");
+}
+/**
+* Format for zsh
+*
+* - Outputs value:description pairs for _describe
+* - Colons in values/descriptions are escaped with backslash
+* - Last line: :directive
+*/
+function formatForZsh(result, _options) {
+	const lines = result.candidates.map((c) => {
+		const escapedValue = c.value.replace(/:/g, "\\:");
+		if (c.description) return `${escapedValue}:${c.description.replace(/:/g, "\\:")}`;
+		return escapedValue;
+	});
+	appendMetadata(lines, result);
+	return lines.join("\n");
+}
+/**
+* Format for fish
+*
+* - Outputs value\tdescription pairs
+* - Last line: :directive
+*/
+function formatForFish(result, _options) {
+	const lines = result.candidates.map((c) => {
+		if (c.description) return `${c.value}\t${c.description}`;
+		return c.value;
+	});
+	appendMetadata(lines, result);
+	return lines.join("\n");
+}
+
+//#endregion
+//#region src/completion/dynamic/complete-command.ts
+/**
+* Dynamic completion command implementation
+*
+* This creates a hidden `__complete` command that outputs completion candidates
+* for shell scripts to consume. Usage:
+*
+*   mycli __complete --shell bash -- build --fo
+*   mycli __complete --shell zsh -- plugin add
+*
+* Output format depends on the target shell:
+*   bash: plain values (pre-filtered by prefix), last line :directive
+*   zsh:  value:description pairs, last line :directive
+*   fish: value\tdescription pairs, last line :directive
+*/
+/**
+* Schema for the __complete command
+*/
+const completeArgsSchema = z.object({
+	shell: arg(z.enum([
+		"bash",
+		"zsh",
+		"fish"
+	]), { description: "Target shell for output formatting" }),
+	args: arg(z.array(z.string()).default([]), {
+		positional: true,
+		description: "Arguments to complete",
+		variadic: true
+	})
+});
+/**
+* Create the dynamic completion command
+*
+* @param rootCommand - The root command to generate completions for
+* @param programName - The program name (optional, defaults to rootCommand.name)
+* @param globalArgsSchema - Global args schema. Forwarded to
+*   `parseCompletionContext` so resolvers attached to global options remain
+*   reachable at every subcommand level.
+* @returns A command that outputs completion candidates
+*/
+function createDynamicCompleteCommand(rootCommand, _programName, globalArgsSchema) {
+	return defineCommand({
+		name: "__complete",
+		args: completeArgsSchema,
+		async run(args) {
+			const context = parseCompletionContext(args.args, rootCommand, globalArgsSchema);
+			const inlinePrefix = context.completionType === "option-value" && context.targetOption ? detectInlineOptionPrefix(context.currentWord) : void 0;
+			const effectiveWord = inlinePrefix ? context.currentWord.slice(inlinePrefix.length) : context.currentWord;
+			const output = formatForShell(await generateCandidates(context, { shell: args.shell }), {
+				shell: args.shell,
+				currentWord: effectiveWord,
+				inlinePrefix
+			});
+			console.log(output);
+		}
+	});
+}
+/**
+* Check if a command tree contains the __complete command
+*/
+function hasCompleteCommand(command) {
+	return Boolean(command.subCommands?.["__complete"]);
+}
+
+//#endregion
+//#region src/completion/fish.ts
+/** Escape shell-special characters for fish double-quoted strings */
+function escapeDesc$1(s) {
+	return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\$/g, "\\$");
+}
+/**
+* Escape a fish `switch` case pattern. Fish's `case` interprets its
+* arguments as globs even when double-quoted, so glob metacharacters
+* (`*`, `?`, `[`, `]`) must be backslash-escaped to keep the comparison
+* literal — otherwise a key like `prod*` would also match a runtime
+* value of `production`. Quote/dollar/backslash are escaped first so the
+* resulting string remains valid inside a double-quoted literal.
+*/
+function fishCaseEscape(s) {
+	return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\$/g, "\\$").replace(/\*/g, "\\*").replace(/\?/g, "\\?").replace(/\[/g, "\\[").replace(/]/g, "\\]");
+}
+/**
+* Generate fish value completion lines for a ValueCompletion spec.
+* Each line outputs candidates via echo (tab-separated value\tdescription).
+*
+* `location` is required for the expand variant (carries fieldName +
+* isArrayOption); other variants ignore it.
+*/
+function fishValueLines(vc, fn, location) {
+	if (!vc) return [];
+	switch (vc.type) {
+		case "expand": {
+			if (!location) throw new Error("fishValueLines: expand variant requires a location");
+			const depExpr = (d) => {
+				const safe = sanitize(d.name);
+				return d.isGlobal ? `$_global_arg_values_${safe}` : `$_arg_values_${safe}`;
+			};
+			const depKey = location.resolvedDeps.map((d) => `"${depExpr(d)}"`).join(`\\x1f`);
+			const bucket = sanitize(location.fieldName);
+			const bucketList = location.isGlobal ? `$_global_used_field_keys_${bucket}` : `$_used_field_keys_${bucket}`;
+			const out = [`switch ${depKey}`];
+			for (const entry of vc.table) {
+				const casePattern = entry.key.map((k) => `"${fishCaseEscape(k)}"`).join(`\\x1f`);
+				out.push(`    case ${casePattern}`);
+				const keyOnlyLines = [];
+				const fullLines = [];
+				const seenKeys = /* @__PURE__ */ new Set();
+				const printfLine = (value, description) => description ? `printf '%s\\t%s\\n' "${escapeDesc$1(value)}" "${escapeDesc$1(description)}"` : `printf '%s\\n' "${escapeDesc$1(value)}"`;
+				const wrapWithDedup = (echoLine, keyPart) => location.isArrayOption && keyPart.length > 0 ? [
+					`        if not contains -- "${escapeDesc$1(keyPart)}" ${bucketList}`,
+					`            ${echoLine}`,
+					`        end`
+				] : [`        ${echoLine}`];
+				for (const c of entry.candidates) {
+					const eqIdx = c.value.indexOf("=");
+					const keyPart = eqIdx > 0 ? c.value.slice(0, eqIdx) : "";
+					const echoLine = printfLine(c.value, c.description);
+					if (!(keyPart.length > 0 && c.value.length === eqIdx + 1)) fullLines.push(...wrapWithDedup(echoLine, keyPart));
+					if (keyPart.length === 0) keyOnlyLines.push(`        ${echoLine}`);
+					else if (!seenKeys.has(keyPart)) {
+						seenKeys.add(keyPart);
+						keyOnlyLines.push(...wrapWithDedup(printfLine(`${keyPart}=`, c.description), keyPart));
+					}
+				}
+				if (fullLines.length !== keyOnlyLines.length || fullLines.some((l, i) => l !== keyOnlyLines[i])) {
+					out.push(`        if string match -q '*=*' -- "$_cur"`);
+					out.push(...fullLines);
+					out.push(`        else`);
+					out.push(...keyOnlyLines);
+					out.push(`        end`);
+				} else out.push(...fullLines);
+			}
+			out.push(`end`);
+			return out;
+		}
+		case "dynamic": return [`__${fn}_invoke_complete fish $_args | __${fn}_apply_dynamic_output "$_cur"`];
+		case "choices": return vc.choices.map((c) => `echo "${escapeDesc$1(c)}"`);
+		case "file":
+			if (vc.matcher?.length) return fishMatcherLines(vc.matcher);
+			if (vc.extensions?.length) return fishExtensionLines(vc.extensions);
+			return [`__fish_complete_path "$_cur"`];
+		case "directory": return [`__fish_complete_directories "$_cur"`];
+		case "command": return [
+			`for _v in (${vc.shellCommand})`,
+			`    echo "$_v"`,
+			`end`
+		];
+		case "none": return [];
+	}
+}
+/** Generate fish matcher-filtered file completion */
+function fishMatcherLines(patterns) {
+	return [
+		`__fish_complete_directories "$_cur"`,
+		`set -l _dir ""`,
+		`if string match -q '*/*' "$_cur"`,
+		`    set _dir (string replace -r '[^/]*$' '' "$_cur")`,
+		`end`,
+		...patterns.flatMap((p) => [
+			`for _f in "$_dir"${p}`,
+			`    test -f "$_f"; and string match -q "$_cur*" "$_f"; and echo "$_f"`,
+			`end`
+		])
+	];
+}
+/** Generate fish extension-filtered file completion */
+function fishExtensionLines(extensions) {
+	const lines = [];
+	lines.push(`__fish_complete_directories "$_cur"`);
+	for (const ext of extensions) {
+		lines.push(`for _f in "$_cur"*.${ext}`);
+		lines.push(`    test -f "$_f"; and echo "$_f"`);
+		lines.push(`end`);
+	}
+	return lines;
+}
+/** Generate option-value switch cases for fish */
+function optionValueCases$1(options, positionals, fn) {
+	const lines = [];
+	for (const opt of options) {
+		if (!opt.takesValue || !opt.valueCompletion) continue;
+		const valLines = fishValueLines(opt.valueCompletion, fn, optionExpandLocation(opt, options, positionals));
+		if (valLines.length === 0) continue;
+		const tokens = effectiveOptionTokens(opt, options);
+		if (tokens.length === 0) continue;
+		const cond = tokens.map((t) => `test "$_prev" = "${t}"`).join("; or ");
+		lines.push(`    if ${cond}`);
+		for (const vl of valLines) lines.push(`        ${vl}`);
+		lines.push(`        return`);
+		lines.push(`    end`);
+	}
+	return lines;
+}
+/** Generate positional completion block for fish */
+function positionalBlock$1(positionals, fn, options = []) {
+	if (positionals.length === 0) return [];
+	const lines = [];
+	for (const pos of positionals) {
+		const valLines = fishValueLines(pos.valueCompletion, fn, positionalExpandLocation(pos, options, positionals));
+		if (valLines.length === 0) continue;
+		if (pos.variadic) lines.push(`    if test $_pos_count -ge ${pos.position}`);
+		else lines.push(`    if test $_pos_count -eq ${pos.position}`);
+		for (const vl of valLines) lines.push(`        ${vl}`);
+		lines.push(`        return`);
+		lines.push(`    end`);
+	}
+	return lines;
+}
+/** Generate available-option echo lines for fish */
+function availableOptionLines$1(options, fn) {
+	const lines = [];
+	for (const opt of options) {
+		const desc = escapeDesc$1(opt.description ?? "");
+		if (opt.valueType === "array") {
+			lines.push(`        echo "--${opt.cliName}\t${desc}"`);
+			continue;
+		}
+		const checks = quotedAvailabilityTokens(opt.cliName, opt.alias, opt.negation, {
+			isGlobal: opt.isGlobal === true,
+			frameOptions: options
+		});
+		const guard = `__${fn}_not_used ${checks.join(" ")}`;
+		const negDesc = opt.negationDescription ? escapeDesc$1(opt.negationDescription) : desc;
+		const entries = [{
+			name: opt.cliName,
+			desc
+		}];
+		if (opt.negation) entries.push({
+			name: opt.negation,
+			desc: negDesc
+		});
+		for (const e of entries) {
+			if (!checks.includes(`"--${e.name}"`)) continue;
+			lines.push(`        ${guard}; and echo "--${e.name}\t${e.desc}"`);
+		}
+	}
+	lines.push(`        __${fn}_not_used "--help"; and echo "--help\tShow help"`);
+	return lines;
+}
+/**
+* Generate a per-subcommand completion function for fish.
+* Recursively generates functions for nested subcommands.
+*/
+function generateSubHandler$1(sub, fn, path) {
+	const fullPath = [...path, sub.name];
+	const funcName = `__${fn}_complete_${fullPath.map(sanitize).join("_")}`;
+	const visibleSubs = getVisibleSubs(sub.subcommands);
+	const lines = [];
+	for (const child of visibleSubs) lines.push(...generateSubHandler$1(child, fn, fullPath));
+	lines.push(`function ${funcName} --no-scope-shadowing`);
+	lines.push(...optionValueCases$1(sub.options, sub.positionals, fn));
+	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, fn, sub.options).map((l) => `    ${l}`));
+		lines.push(`        return`);
+		lines.push(`    end`);
+	} else lines.push(`    if test $_after_dd -eq 1; return; end`);
+	lines.push(`    if string match -q -- '-*' "$_cur"`);
+	lines.push(...availableOptionLines$1(sub.options, fn));
+	lines.push(`        return`);
+	lines.push(`    end`);
+	if (visibleSubs.length > 0) for (const s of getSubNamesWithAliases(sub.subcommands)) {
+		const desc = escapeDesc$1(s.description ?? "");
+		lines.push(`    echo "${s.name}\t${desc}"`);
+	}
+	else if (sub.positionals.length > 0) lines.push(...positionalBlock$1(sub.positionals, fn, sub.options));
+	lines.push(`end`);
+	lines.push(``);
+	return lines;
+}
+/** Generate opt-takes-value entries for fish switch cases */
+function optTakesValueCases(sub, parentPath) {
+	const lines = [];
+	for (const row of walkOptTakesValueRows(sub, parentPath)) {
+		const patterns = row.tokens.map((t) => `"${row.parentPath}:${t}"`);
+		lines.push(`        case ${patterns.join(" ")}`);
+		lines.push(`            return 0`);
+	}
+	return lines;
+}
+function generateFishCompletion(command, options) {
+	const { programName } = options;
+	const data = extractCompletionData(command, programName, options.globalArgsSchema);
+	const fn = sanitize(programName);
+	const root = data.command;
+	const visibleSubs = getVisibleSubs(root.subcommands);
+	const expandSpecs = collectExpandSpecs(root);
+	const trackedFields = collectTrackedFields(root, expandSpecs, data.globalOptions);
+	const hasExpand = expandSpecs.length > 0;
+	const arrayExpandSpecs = expandSpecs.filter((s) => s.isArrayOption);
+	const hasArrayExpand = arrayExpandSpecs.length > 0;
+	const lines = [];
+	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(``);
+	if (hasDynamicCompletion(root)) {
+		lines.push(`function __${fn}_invoke_complete`);
+		lines.push(`    set -l _shell $argv[1]`);
+		lines.push(`    set -l _argv $argv[2..]`);
+		lines.push(`    set -l _bin ${programName}`);
+		lines.push(`    if set -q ${binEnvVarName(fn)}`);
+		lines.push(`        set _bin $${binEnvVarName(fn)}`);
+		lines.push(`    end`);
+		lines.push(`    $_bin __complete --shell $_shell -- $_argv 2>/dev/null`);
+		lines.push(`end`);
+		lines.push(``);
+		lines.push(`function __${fn}_apply_dynamic_output`);
+		lines.push(`    set -l _cur $argv[1]`);
+		lines.push(`    set -l _directive 0`);
+		lines.push(`    set -l _emitted 0`);
+		lines.push(`    set -l _prev ""`);
+		lines.push(`    set -l _has_prev 0`);
+		lines.push(`    while read -l _l`);
+		lines.push(`        if test $_has_prev -eq 1`);
+		lines.push(`            if test -n "$_prev"`);
+		lines.push(`                printf '%s\\n' "$_prev"`);
+		lines.push(`                set _emitted 1`);
+		lines.push(`            end`);
+		lines.push(`        end`);
+		lines.push(`        set _prev $_l`);
+		lines.push(`        set _has_prev 1`);
+		lines.push(`    end`);
+		lines.push(`    if test $_has_prev -eq 1`);
+		lines.push(`        if string match -qr '^:[0-9]+$' -- $_prev`);
+		lines.push(`            set _directive (string sub -s 2 -- $_prev)`);
+		lines.push(`        else`);
+		lines.push(`            if test -n "$_prev"`);
+		lines.push(`                printf '%s\\n' "$_prev"`);
+		lines.push(`                set _emitted 1`);
+		lines.push(`            end`);
+		lines.push(`        end`);
+		lines.push(`    end`);
+		lines.push(`    if test (math "bitand($_directive, ${CompletionDirective.DirectoryCompletion})") -ne 0`);
+		lines.push(`        __fish_complete_directories "$_cur"`);
+		lines.push(`    else if test (math "bitand($_directive, ${CompletionDirective.FileCompletion})") -ne 0`);
+		lines.push(`        __fish_complete_path "$_cur"`);
+		lines.push(`    else if test $_emitted -eq 0; and test (math "bitand($_directive, ${CompletionDirective.NoFileCompletion})") -eq 0`);
+		lines.push(`        __fish_complete_path "$_cur"`);
+		lines.push(`    end`);
+		lines.push(`end`);
+		lines.push(``);
+	}
+	lines.push(`function __${fn}_not_used --no-scope-shadowing`);
+	lines.push(`    for _chk in $argv`);
+	lines.push(`        if contains -- "$_chk" $_used_opts`);
+	lines.push(`            return 1`);
+	lines.push(`        end`);
+	lines.push(`    end`);
+	lines.push(`    return 0`);
+	lines.push(`end`);
+	lines.push(``);
+	lines.push(`function __${fn}_opt_takes_value`);
+	lines.push(`    switch "$argv[1]:$argv[2]"`);
+	lines.push(...optTakesValueCases(root, ""));
+	lines.push(`    end`);
+	lines.push(`    return 1`);
+	lines.push(`end`);
+	lines.push(``);
+	if (hasExpand) {
+		const trackerVar = (t) => `${t.isGlobal ? "_global_arg_values_" : "_arg_values_"}${sanitize(t.fieldName)}`;
+		lines.push(`function __${fn}_track_opt --no-scope-shadowing`);
+		lines.push(`    switch "$argv[1]:$argv[2]"`);
+		for (const t of trackedFields) {
+			if (t.isPositional || !t.optionTokens || t.optionTokens.length === 0) continue;
+			const cases = t.pathStrs.flatMap((p) => t.optionTokens.map((n) => `"${p}:${n}"`)).join(" ");
+			lines.push(`        case ${cases}`);
+			lines.push(`            set -g ${trackerVar(t)} "$argv[3]"`);
+		}
+		lines.push(`    end`);
+		lines.push(`end`);
+		lines.push(``);
+		lines.push(`function __${fn}_track_pos --no-scope-shadowing`);
+		lines.push(`    switch "$argv[1]:$argv[2]"`);
+		for (const t of trackedFields) {
+			if (!t.isPositional) continue;
+			const cases = t.pathStrs.map((p) => `"${p}:${t.position}"`).join(" ");
+			lines.push(`        case ${cases}`);
+			lines.push(`            set -g ${trackerVar(t)} "$argv[3]"`);
+		}
+		lines.push(`    end`);
+		lines.push(`end`);
+		lines.push(``);
+	}
+	if (hasArrayExpand) {
+		lines.push(`function __${fn}_track_array_expand --no-scope-shadowing`);
+		lines.push(`    switch "$argv[1]:$argv[2]"`);
+		for (const spec of arrayExpandSpecs) {
+			if (spec.optionTokens.length === 0) continue;
+			const cases = spec.pathStrs.flatMap((p) => spec.optionTokens.map((tok) => `"${p}:${tok}"`)).join(" ");
+			const bucket = sanitize(spec.fieldName);
+			const bucketVar = spec.isGlobal ? `_global_used_field_keys_` : `_used_field_keys_`;
+			lines.push(`        case ${cases}`);
+			lines.push(`            if string match -q '*=*' -- "$argv[3]"`);
+			lines.push(`                set -l _k (string replace -r '=.*' '' -- "$argv[3]")`);
+			lines.push(`                if test -n "$_k"`);
+			if (spec.isGlobal) {
+				lines.push(`                    if not set -q _global_arr_seen_${bucket}`);
+				lines.push(`                        set -g ${bucketVar}${bucket} "$_k"`);
+				lines.push(`                        set -g _global_arr_seen_${bucket} 1`);
+				lines.push(`                    else if not contains -- "$_k" $${bucketVar}${bucket}`);
+				lines.push(`                        set -ga ${bucketVar}${bucket} "$_k"`);
+				lines.push(`                    end`);
+			} else {
+				lines.push(`                    if not contains -- "$_k" $${bucketVar}${bucket}`);
+				lines.push(`                        set -ga ${bucketVar}${bucket} "$_k"`);
+				lines.push(`                    end`);
+			}
+			lines.push(`                end`);
+			lines.push(`            end`);
+		}
+		lines.push(`    end`);
+		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(...optionValueCases$1(root.options, root.positionals, fn));
+	lines.push(`    if __${fn}_opt_takes_value "" "$_prev"; return; end`);
+	if (root.positionals.length > 0) {
+		lines.push(`    if test $_after_dd -eq 1`);
+		lines.push(...positionalBlock$1(root.positionals, fn, root.options).map((l) => `    ${l}`));
+		lines.push(`        return`);
+		lines.push(`    end`);
+	} else lines.push(`    if test $_after_dd -eq 1; return; end`);
+	lines.push(`    if string match -q -- '-*' "$_cur"`);
+	lines.push(...availableOptionLines$1(root.options, fn));
+	if (visibleSubs.length > 0) {
+		lines.push(`    else`);
+		for (const s of getSubNamesWithAliases(root.subcommands)) {
+			const desc = escapeDesc$1(s.description ?? "");
+			lines.push(`        echo "${s.name}\t${desc}"`);
+		}
+	} else if (root.positionals.length > 0) {
+		lines.push(`    else`);
+		lines.push(...positionalBlock$1(root.positionals, fn, root.options));
+	}
+	lines.push(`    end`);
+	lines.push(`end`);
+	lines.push(``);
+	lines.push(`function __fish_${fn}_complete`);
+	lines.push(`    set -l _args (commandline -opc)`);
+	lines.push(`    set -e _args[1]`);
+	lines.push(``);
+	lines.push(`    set -l _ct (commandline -ct)`);
+	lines.push(`    if test (count $_ct) -eq 0`);
+	lines.push(`        set -a _args ""`);
+	lines.push(`    else`);
+	lines.push(`        set -a _args $_ct`);
+	lines.push(`    end`);
+	lines.push(``);
+	lines.push(`    set -l _cur ""`);
+	lines.push(`    if test (count $_args) -gt 0`);
+	lines.push(`        set _cur "$_args[-1]"`);
+	lines.push(`    end`);
+	lines.push(``);
+	lines.push(`    set -l _prev ""`);
+	lines.push(`    if test (count $_args) -gt 1`);
+	lines.push(`        set _prev "$_args[-2]"`);
+	lines.push(`    end`);
+	lines.push(``);
+	lines.push(`    set -l _subcmd "" ; set -l _after_dd 0 ; set -l _pos_count 0 ; set -l _skip_next 0`);
+	lines.push(`    set -l _used_opts`);
+	lines.push(``);
+	if (hasExpand) for (const t of trackedFields) {
+		lines.push(`    set -e _arg_values_${sanitize(t.fieldName)}`);
+		lines.push(`    set -e _global_arg_values_${sanitize(t.fieldName)}`);
+	}
+	if (hasArrayExpand) for (const spec of arrayExpandSpecs) {
+		lines.push(`    set -e _used_field_keys_${sanitize(spec.fieldName)}`);
+		lines.push(`    set -e _global_used_field_keys_${sanitize(spec.fieldName)}`);
+		lines.push(`    set -e _global_arr_seen_${sanitize(spec.fieldName)}`);
+	}
+	lines.push(`    set -l _j 1`);
+	lines.push(`    set -l _limit (math (count $_args) - 1)`);
+	lines.push(`    while test $_j -le $_limit`);
+	lines.push(`        set -l _w "$_args[$_j]"`);
+	lines.push(`        if test $_skip_next -eq 1; set _skip_next 0; set _j (math $_j + 1); continue; end`);
+	lines.push(`        if test "$_w" = "--"; set _after_dd 1; set _j (math $_j + 1); continue; end`);
+	const afterDdTrack = hasExpand ? `__${fn}_track_pos "$_subcmd" "$_pos_count" "$_w"; ` : "";
+	lines.push(`        if test $_after_dd -eq 1; ${afterDdTrack}set _pos_count (math $_pos_count + 1); set _j (math $_j + 1); continue; end`);
+	lines.push(`        if string match -q -- '-*=*' "$_w"`);
+	lines.push(`            set -l _opt (string replace -r '=.*' '' -- "$_w")`);
+	lines.push(`            set -a _used_opts "$_opt"`);
+	if (hasExpand) {
+		lines.push(`            set -l _val (string replace -r '^[^=]*=' '' -- "$_w")`);
+		lines.push(`            __${fn}_track_opt "$_subcmd" "$_opt" "$_val"`);
+		if (hasArrayExpand) lines.push(`            __${fn}_track_array_expand "$_subcmd" "$_opt" "$_val"`);
+	}
+	lines.push(`            set _j (math $_j + 1); continue`);
+	lines.push(`        end`);
+	lines.push(`        if string match -q -- '-*' "$_w"`);
+	lines.push(`            set -a _used_opts "$_w"`);
+	lines.push(`            if __${fn}_opt_takes_value "$_subcmd" "$_w"`);
+	lines.push(`                set -l _next ""`);
+	lines.push(`                set -l _next_idx (math $_j + 1)`);
+	lines.push(`                if test $_next_idx -le (count $_args)`);
+	lines.push(`                    set _next "$_args[$_next_idx]"`);
+	lines.push(`                end`);
+	lines.push(`                if test -n "$_next"; and not string match -q -- '-*' "$_next"`);
+	lines.push(`                    set _skip_next 1`);
+	if (hasExpand) {
+		lines.push(`                    __${fn}_track_opt "$_subcmd" "$_w" "$_next"`);
+		if (hasArrayExpand) {
+			lines.push(`                    if test $_j -lt $_limit`);
+			lines.push(`                        __${fn}_track_array_expand "$_subcmd" "$_w" "$_next"`);
+			lines.push(`                    end`);
+		}
+	}
+	lines.push(`                end`);
+	lines.push(`            end`);
+	lines.push(`            set _j (math $_j + 1); continue`);
+	lines.push(`        end`);
+	if (routeEntries.length > 0) {
+		lines.push(`        if __${fn}_is_subcmd "$_subcmd" "$_w"`);
+		lines.push(`            test -n "$_subcmd"; and set _subcmd "$_subcmd:$_w"; or set _subcmd "$_w"`);
+		lines.push(`            set _used_opts; set _pos_count 0`);
+		if (hasExpand) {
+			for (const t of trackedFields) lines.push(`            set -e _arg_values_${sanitize(t.fieldName)}`);
+			if (hasArrayExpand) for (const spec of arrayExpandSpecs) {
+				lines.push(`            set -e _used_field_keys_${sanitize(spec.fieldName)}`);
+				lines.push(`            set -e _global_arr_seen_${sanitize(spec.fieldName)}`);
+			}
+		}
+		lines.push(`        else`);
+		if (hasExpand) lines.push(`            __${fn}_track_pos "$_subcmd" "$_pos_count" "$_w"`);
+		lines.push(`            set _pos_count (math $_pos_count + 1)`);
+		lines.push(`        end`);
+	} else {
+		if (hasExpand) lines.push(`        __${fn}_track_pos "$_subcmd" "$_pos_count" "$_w"`);
+		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 r of routeEntries) lines.push(`        case "${r.pathStr}"; __${fn}_complete_${r.funcSuffix}`);
+	lines.push(`        case '*'; __${fn}_complete_root`);
+	lines.push(`    end`);
+	lines.push(`end`);
+	lines.push(``);
+	lines.push(`# Clear existing completions`);
+	lines.push(`complete -e -c ${programName}`);
+	lines.push(``);
+	lines.push(`# Register completion`);
+	lines.push(`complete -c ${programName} -f -a '(__fish_${fn}_complete)'`);
+	lines.push(``);
+	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`
+	};
+}
+
+//#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) {
+	return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\$/g, "\\$").replace(/`/g, "\\`").replace(/:/g, "\\:");
+}
+/**
+* Escape a candidate value for use inside a `_describe` spec. `_describe`
+* splits each spec on the first unescaped `:` to separate value from
+* description, so any literal `:` in the value (URLs, namespaced ids) must
+* be backslash-escaped — and the escape itself must double up so the final
+* string interprets `\:` as a single literal.
+*/
+function escapeDescribeValue(s) {
+	return s.replace(/\\/g, "\\\\").replace(/:/g, "\\:");
+}
+/**
+* Generate zsh value completion lines for a ValueCompletion spec.
+* Uses `_vals` array (must be declared in the calling function scope).
+* `location` is required when `vc.type === "expand"`.
+*/
+function zshValueLines(vc, fn, location) {
+	if (!vc) return [];
+	switch (vc.type) {
+		case "expand": {
+			if (!location) throw new Error("zshValueLines: expand variant requires a location");
+			const varName = expandTableVarName(fn, location.funcSuffix, location.fieldName);
+			const depKey = location.resolvedDeps.map((d) => d.isGlobal ? `"\${_global_arg_values[${d.name}]:-}"` : `"\${_arg_values[${d.name}]:-}"`).join(`$'\\x1f'`);
+			const bucket = sanitize(location.fieldName);
+			const bucketRef = location.isGlobal ? `\${_global_used_field_keys[${bucket}]:-}` : `\${_used_field_keys[${bucket}]:-}`;
+			const arrayDedupLines = location.isArrayOption ? [`            if [[ -n "$_ck" && " ${bucketRef} " == *" $_ck "* ]]; then continue; fi`] : [];
+			return [
+				`local _key=${depKey}`,
+				`local _raw="\${${varName}[$_key]:-}"`,
+				`if [[ -n "$_raw" ]]; then`,
+				`    local -a _candidates=("\${(@f)_raw}")`,
+				`    _vals=()`,
+				`    local _c _ck _cke _vp _seen_keys=" " _desc _has_eq=0 _tmp`,
+				`    for _c in "\${_candidates[@]}"; do`,
+				`        _tmp="\${_c//\\\\:/$'\\x01'}"`,
+				`        _vp="\${_tmp%%:*}"`,
+				`        if [[ "$_vp" == *=* ]]; then`,
+				`            _cke="\${_c%%=*}"`,
+				`            _ck="\${_cke//\\\\:/:}"`,
+				...arrayDedupLines,
+				`            if [[ "\${words[CURRENT]}" != *=* ]]; then`,
+				`                [[ "$_seen_keys" == *" $_ck "* ]] && continue`,
+				`                _seen_keys+="$_ck "`,
+				`                if [[ "$_tmp" == *:* ]]; then`,
+				`                    _desc="\${\${_tmp#*:}//$'\\x01'/\\\\:}"`,
+				`                    _c="\${_cke}=:$_desc"`,
+				`                else`,
+				`                    _c="\${_cke}="`,
+				`                fi`,
+				`                _has_eq=1`,
+				`            else`,
+				`                [[ "$_vp" == *=?* ]] || continue`,
+				`            fi`,
+				`        fi`,
+				`        _vals+=("$_c")`,
+				`    done`,
+				`    if (( _has_eq )); then`,
+				`        __${fn}_cdescribe 'completions' _vals -S ''`,
+				`    else`,
+				`        __${fn}_cdescribe 'completions' _vals`,
+				`    fi`,
+				`fi`
+			];
+		}
+		case "dynamic": return [`__${fn}_apply_dynamic_output "$(__${fn}_invoke_complete zsh "\${(@)words[2,CURRENT]}")"`];
+		case "choices": return [`_vals=(${vc.choices.map((c) => `"${escapeDesc(c)}"`).join(" ")})`, `__${fn}_cdescribe 'completions' _vals`];
+		case "file":
+			if (vc.matcher?.length) return vc.matcher.map((p) => `_files -g "${p}"`);
+			if (vc.extensions?.length) return vc.extensions.map((ext) => `_files -g "*.${ext}"`);
+			return [`_files`];
+		case "directory": return [`_files -/`];
+		case "command": return [`_vals=("\${(@f)$(${vc.shellCommand})}")`, `__${fn}_cdescribe 'completions' _vals`];
+		case "none": return [];
+	}
+}
+/** Generate option-value case branches */
+function optionValueCases(options, positionals, fn, funcSuffix) {
+	const lines = [];
+	for (const opt of options) {
+		if (!opt.takesValue || !opt.valueCompletion) continue;
+		const valLines = zshValueLines(opt.valueCompletion, fn, {
+			funcSuffix,
+			...optionExpandLocation(opt, options, positionals)
+		});
+		if (valLines.length === 0) continue;
+		const patterns = effectiveOptionTokens(opt, options);
+		if (patterns.length === 0) continue;
+		lines.push(`            ${patterns.join("|")})`);
+		for (const vl of valLines) lines.push(`                ${vl}`);
+		lines.push(`                return 0 ;;`);
+	}
+	return lines;
+}
+/** Generate positional completion block */
+function positionalBlock(positionals, fn, funcSuffix, options = []) {
+	if (positionals.length === 0) return [];
+	const lines = [];
+	lines.push(`    case "$_pos_count" in`);
+	for (const pos of positionals) {
+		if (pos.variadic) lines.push(`        ${pos.position}|*)`);
+		else lines.push(`        ${pos.position})`);
+		const valLines = zshValueLines(pos.valueCompletion, fn, {
+			funcSuffix,
+			...positionalExpandLocation(pos, options, positionals)
+		});
+		for (const vl of valLines) lines.push(`            ${vl}`);
+		lines.push(`            ;;`);
+	}
+	lines.push(`    esac`);
+	return lines;
+}
+/** Generate prev-word value completion case block */
+function valueCompletionBlock(options, positionals, fn, funcSuffix) {
+	if (!options.some((o) => o.takesValue && o.valueCompletion)) return [];
+	const prevCases = optionValueCases(options, positionals, fn, funcSuffix);
+	if (prevCases.length === 0) return [];
+	return [
+		`    case "\${words[CURRENT-1]}" in`,
+		...prevCases,
+		`    esac`
+	];
+}
+/** Generate available-options list lines */
+function availableOptionLines(options, fn) {
+	const lines = [];
+	for (const opt of options) {
+		const desc = opt.description ? `:${escapeDesc(opt.description)}` : "";
+		if (opt.valueType === "array") {
+			lines.push(`        _opts+=("--${opt.cliName}${desc}")`);
+			continue;
+		}
+		const patterns = quotedAvailabilityTokens(opt.cliName, opt.alias, opt.negation, {
+			isGlobal: opt.isGlobal === true,
+			frameOptions: options
+		});
+		const guard = `__${fn}_not_used ${patterns.join(" ")}`;
+		const negDesc = opt.negationDescription ? `:${escapeDesc(opt.negationDescription)}` : desc;
+		const entries = [{
+			name: opt.cliName,
+			desc
+		}];
+		if (opt.negation) entries.push({
+			name: opt.negation,
+			desc: negDesc
+		});
+		for (const e of entries) {
+			if (!patterns.includes(`"--${e.name}"`)) continue;
+			lines.push(`        ${guard} && _opts+=("--${e.name}${e.desc}")`);
+		}
+	}
+	lines.push(`        __${fn}_not_used "--help" && _opts+=("--help:Show help")`);
+	return lines;
+}
+/**
+* Generate a per-subcommand completion function.
+* Recursively generates functions for nested subcommands.
+*/
+function generateSubHandler(sub, fn, path) {
+	const fullPath = [...path, sub.name];
+	const funcSuffix = fullPath.map(sanitize).join("_");
+	const funcName = `__${fn}_complete_${funcSuffix}`;
+	const visibleSubs = getVisibleSubs(sub.subcommands);
+	const lines = [];
+	for (const child of visibleSubs) lines.push(...generateSubHandler(child, fn, fullPath));
+	lines.push(`${funcName}() {`);
+	lines.push(`    local -a _vals=()`);
+	lines.push(...valueCompletionBlock(sub.options, sub.positionals, fn, funcSuffix));
+	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, funcSuffix, sub.options).map((l) => `    ${l}`));
+		lines.push(`        return 0`);
+		lines.push(`    fi`);
+	} else lines.push(`    if (( _after_dd )); then return 0; fi`);
+	lines.push(`    if [[ "\${words[CURRENT]}" == -* ]]; then`);
+	lines.push(`        local -a _opts=()`);
+	lines.push(...availableOptionLines(sub.options, fn));
+	lines.push(`        __${fn}_cdescribe 'options' _opts`);
+	lines.push(`        return 0`);
+	lines.push(`    fi`);
+	if (visibleSubs.length > 0) {
+		const subItems = getSubNamesWithAliases(sub.subcommands).map((s) => {
+			const desc = s.description ? `:${escapeDesc(s.description)}` : "";
+			return `"${s.name}${desc}"`;
+		}).join(" ");
+		lines.push(`    local -a _subs=(${subItems})`);
+		lines.push(`    __${fn}_cdescribe 'subcommands' _subs`);
+	} else if (sub.positionals.length > 0) lines.push(...positionalBlock(sub.positionals, fn, funcSuffix, sub.options));
+	lines.push(`}`);
+	lines.push(``);
+	return lines;
+}
+function generateZshCompletion(command, options) {
+	const { programName } = options;
+	const data = extractCompletionData(command, programName, options.globalArgsSchema);
+	const fn = sanitize(programName);
+	const root = data.command;
+	const visibleSubs = getVisibleSubs(root.subcommands);
+	const expandSpecs = collectExpandSpecs(root);
+	const trackedFields = collectTrackedFields(root, expandSpecs, data.globalOptions);
+	const hasExpand = expandSpecs.length > 0;
+	const arrayExpandSpecs = expandSpecs.filter((s) => s.isArrayOption);
+	const hasArrayExpand = arrayExpandSpecs.length > 0;
+	const lines = [];
+	lines.push(`#compdef ${programName}`);
+	lines.push(``);
+	lines.push(...buildHeaderLines({
+		programName,
+		shell: "zsh",
+		binPath: options.binPath,
+		programVersion: options.programVersion
+	}));
+	lines.push(`# Generated by politty`);
+	lines.push(``);
+	for (const spec of expandSpecs) {
+		const varName = expandTableVarName(fn, spec.funcSuffix, spec.fieldName);
+		if (spec.vc.table.length === 0) lines.push(`typeset -gA ${varName}=()`);
+		else {
+			lines.push(`typeset -gA ${varName}=(`);
+			for (const entry of spec.vc.table) {
+				const key = entry.key.join("");
+				const value = entry.candidates.map((c) => {
+					const escapedValue = escapeDescribeValue(c.value);
+					return c.description ? `${escapedValue}:${c.description}` : escapedValue;
+				}).join("\n");
+				lines.push(`    ${ansiC(key)} ${ansiC(value)}`);
+			}
+			lines.push(`)`);
+		}
+		lines.push(``);
+	}
+	if (hasDynamicCompletion(root)) {
+		lines.push(...dynamicInvokeCompleteLines(fn, programName));
+		lines.push(``);
+		lines.push(`__${fn}_apply_dynamic_output() {`);
+		lines.push(`    local _raw="$1"`);
+		lines.push(`    local _directive=0`);
+		lines.push(`    local -a _vals _lines`);
+		lines.push(`    _lines=("\${(@f)_raw}")`);
+		lines.push(`    local _last=$#_lines`);
+		lines.push(`    if (( _last >= 1 )) && [[ "\${_lines[$_last]}" == :<-> ]]; then`);
+		lines.push(`        _directive="\${_lines[$_last]#:}"`);
+		lines.push(`        _lines[$_last]=()`);
+		lines.push(`    fi`);
+		lines.push(`    local _l`);
+		lines.push(`    for _l in "\${_lines[@]}"; do`);
+		lines.push(`        [[ -z "$_l" ]] && continue`);
+		lines.push(`        _vals+=("$_l")`);
+		lines.push(`    done`);
+		lines.push(`    if (( \${#_vals[@]} > 0 )); then`);
+		lines.push(`        if (( _directive & ${CompletionDirective.NoSpace} )); then`);
+		lines.push(`            __${fn}_cdescribe 'completions' _vals -S ''`);
+		lines.push(`        else`);
+		lines.push(`            __${fn}_cdescribe 'completions' _vals`);
+		lines.push(`        fi`);
+		lines.push(`    fi`);
+		lines.push(`    if (( _directive & ${CompletionDirective.DirectoryCompletion} )); then`);
+		lines.push(`        _files -/`);
+		lines.push(`    elif (( _directive & ${CompletionDirective.FileCompletion} )); then`);
+		lines.push(`        _files`);
+		lines.push(`    elif (( \${#_vals[@]} == 0 )) && ! (( _directive & ${CompletionDirective.NoFileCompletion} )); then`);
+		lines.push(`        _files`);
+		lines.push(`    fi`);
+		lines.push(`}`);
+		lines.push(``);
+	}
+	lines.push(`__${fn}_not_used() {`);
+	lines.push(`    local _u _chk`);
+	lines.push(`    for _u in "\${_used_opts[@]}"; do`);
+	lines.push(`        for _chk in "$@"; do`);
+	lines.push(`            [[ "$_u" == "$_chk" ]] && return 1`);
+	lines.push(`        done`);
+	lines.push(`    done`);
+	lines.push(`    return 0`);
+	lines.push(`}`);
+	lines.push(``);
+	lines.push(`__${fn}_cdescribe() {`);
+	lines.push(`    _describe "$@" 2>/dev/null && return 0`);
+	lines.push(`    shift`);
+	lines.push(`    local _cd_arr="$1"`);
+	lines.push(`    shift`);
+	lines.push(`    local -a _cd_vals=("\${(@)\${(P)_cd_arr}%%:*}")`);
+	lines.push(`    compadd "$@" -a _cd_vals 2>/dev/null`);
+	lines.push(`    return 0`);
+	lines.push(`}`);
+	lines.push(``);
+	lines.push(`__${fn}_opt_takes_value() {`);
+	lines.push(`    case "$1:$2" in`);
+	lines.push(...optTakesValueEntries(root, ""));
+	lines.push(`    esac`);
+	lines.push(`    return 1`);
+	lines.push(`}`);
+	lines.push(``);
+	if (hasExpand) {
+		lines.push(`__${fn}_track_opt() {`);
+		lines.push(`    case "$1:$2" in`);
+		lines.push(...trackOptCaseLines(trackedFields, "zsh"));
+		lines.push(`    esac`);
+		lines.push(`}`);
+		lines.push(``);
+		lines.push(`__${fn}_track_pos() {`);
+		lines.push(`    case "$1:$2" in`);
+		lines.push(...trackPosCaseLines(trackedFields, "zsh"));
+		lines.push(`    esac`);
+		lines.push(`}`);
+		lines.push(``);
+	}
+	if (hasArrayExpand) {
+		lines.push(`__${fn}_track_array_expand() {`);
+		lines.push(`    case "$1:$2" in`);
+		lines.push(...trackArrayExpandCaseLines(arrayExpandSpecs, "zsh"));
+		lines.push(`    esac`);
+		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=()`);
+	lines.push(...valueCompletionBlock(root.options, root.positionals, fn, "root"));
+	lines.push(`    if __${fn}_opt_takes_value "" "\${words[CURRENT-1]}"; then return 0; fi`);
+	if (root.positionals.length > 0) {
+		lines.push(`    if (( _after_dd )); then`);
+		lines.push(...positionalBlock(root.positionals, fn, "root", root.options).map((l) => `    ${l}`));
+		lines.push(`        return 0`);
+		lines.push(`    fi`);
+	} else lines.push(`    if (( _after_dd )); then return 0; fi`);
+	lines.push(`    if [[ "\${words[CURRENT]}" == -* ]]; then`);
+	lines.push(`        local -a _opts=()`);
+	lines.push(...availableOptionLines(root.options, fn));
+	lines.push(`        __${fn}_cdescribe 'options' _opts`);
+	if (visibleSubs.length > 0) {
+		lines.push(`    else`);
+		const subItems = getSubNamesWithAliases(root.subcommands).map((s) => {
+			const desc = s.description ? `:${escapeDesc(s.description)}` : "";
+			return `"${s.name}${desc}"`;
+		}).join(" ");
+		lines.push(`        local -a _subs=(${subItems})`);
+		lines.push(`        __${fn}_cdescribe 'subcommands' _subs`);
+	} else if (root.positionals.length > 0) {
+		lines.push(`    else`);
+		lines.push(...positionalBlock(root.positionals, fn, "root", root.options).map((l) => `    ${l}`));
+	}
+	lines.push(`    fi`);
+	lines.push(`}`);
+	lines.push(``);
+	const subRouting = subDispatchCaseLines(routeEntries, fn).join("\n");
+	lines.push(`_${fn}() {`);
+	lines.push(`    (( CURRENT )) || CURRENT=\${#words}`);
+	lines.push(``);
+	lines.push(`    local _subcmd="" _after_dd=0 _pos_count=0 _skip_next=0`);
+	lines.push(`    local -a _used_opts=()`);
+	if (hasExpand) {
+		lines.push(`    local -A _arg_values=()`);
+		lines.push(`    local -A _global_arg_values=()`);
+	}
+	if (hasArrayExpand) {
+		lines.push(`    local -A _used_field_keys=()`);
+		lines.push(`    local -A _global_used_field_keys=()`);
+		lines.push(`    local -A _global_arr_seen=()`);
+	}
+	lines.push(``);
+	lines.push(`    local _j=2`);
+	lines.push(`    while (( _j < CURRENT )); do`);
+	lines.push(`        local _w="\${words[_j]}"`);
+	lines.push(`        if (( _skip_next )); then _skip_next=0; (( _j++ )); continue; fi`);
+	lines.push(`        if [[ "$_w" == "--" ]]; then _after_dd=1; (( _j++ )); continue; fi`);
+	const afterDdTrack = hasExpand ? `__${fn}_track_pos "$_subcmd" "$_pos_count" "$_w"; ` : "";
+	lines.push(`        if (( _after_dd )); then ${afterDdTrack}(( _pos_count++ )); (( _j++ )); continue; fi`);
+	lines.push(`        if [[ "$_w" == -*=* ]]; then`);
+	lines.push(`            _used_opts+=("\${_w%%=*}")`);
+	if (hasExpand) {
+		lines.push(`            __${fn}_track_opt "$_subcmd" "\${_w%%=*}" "\${_w#*=}"`);
+		if (hasArrayExpand) lines.push(`            __${fn}_track_array_expand "$_subcmd" "\${_w%%=*}" "\${_w#*=}"`);
+	}
+	lines.push(`            (( _j++ )); continue`);
+	lines.push(`        fi`);
+	lines.push(`        if [[ "$_w" == -* ]]; then`);
+	lines.push(`            _used_opts+=("$_w")`);
+	lines.push(`            if __${fn}_opt_takes_value "$_subcmd" "$_w"; then`);
+	lines.push(`                local _next="\${words[_j+1]:-}"`);
+	lines.push(`                if [[ -n "$_next" && "$_next" != -* ]]; then _skip_next=1; fi`);
+	if (hasExpand) {
+		lines.push(`                if (( _skip_next )); then`);
+		lines.push(`                    __${fn}_track_opt "$_subcmd" "$_w" "$_next"`);
+		if (hasArrayExpand) {
+			lines.push(`                    if (( _j + 1 < CURRENT )); then`);
+			lines.push(`                        __${fn}_track_array_expand "$_subcmd" "$_w" "$_next"`);
+			lines.push(`                    fi`);
+		}
+		lines.push(`                fi`);
+	}
+	lines.push(`            fi`);
+	lines.push(`            (( _j++ )); continue`);
+	lines.push(`        fi`);
+	const clearState = hasArrayExpand ? `; _arg_values=(); _used_field_keys=(); _global_arr_seen=()` : hasExpand ? `; _arg_values=()` : "";
+	const posTrack = hasExpand ? `__${fn}_track_pos "$_subcmd" "$_pos_count" "$_w"; ` : "";
+	if (routeEntries.length > 0) lines.push(`        if __${fn}_is_subcmd "$_subcmd" "$_w"; then _subcmd="\${_subcmd:+\${_subcmd}:}$_w"; _used_opts=(); _pos_count=0${clearState}; else ${posTrack}(( _pos_count++ )); fi`);
+	else {
+		if (hasExpand) lines.push(`        __${fn}_track_pos "$_subcmd" "$_pos_count" "$_w"`);
+		lines.push(`        (( _pos_count++ ))`);
+	}
+	lines.push(`        (( _j++ ))`);
+	lines.push(`    done`);
+	lines.push(``);
+	lines.push(`    case "$_subcmd" in`);
+	lines.push(subRouting);
+	lines.push(`        *) __${fn}_complete_root ;;`);
+	lines.push(`    esac`);
+	lines.push(`}`);
+	lines.push(``);
+	lines.push(`zstyle ':completion:*:*:${programName}:*' file-patterns '%p:globbed-files *(-/):directories'`);
+	lines.push(``);
+	lines.push(`compdef _${fn} ${programName}`);
+	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)
+eval "$(${programName} completion zsh)"
+
+# Option 2: Save to a file in your fpath
+${programName} completion zsh > ~/.zsh/completions/_${programName}
+
+# Make sure your fpath includes the completions directory:
+# fpath=(~/.zsh/completions $fpath)
+# autoload -Uz compinit && compinit
+
+# Then reload your shell or run:
+source ~/.zshrc`
+	};
+}
+
+//#endregion
+//#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"
+	}),
+	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
+*
+* 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, 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, globalArgsSchema)
+	};
+	if (!rootCommand.subCommands?.["__refresh-completion"]) rootCommand.subCommands = {
+		...rootCommand.subCommands,
+		"__refresh-completion": createRefreshCompletionCommand(rootCommand, resolvedProgramName, refreshExtra)
+	};
+	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;
+			}
+			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 },
+				...programVersion !== void 0 && { programVersion },
+				...cacheDir !== void 0 && { cacheDir }
+			});
+			if (args.instructions) console.log(result.installInstructions);
+			else console.log(result.script);
+		}
+	});
+}
+/**
+* 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
+* 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, 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, extra),
+		__complete: createDynamicCompleteCommand(wrappedCommand, programName, globalArgsSchema),
+		"__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 { defineCommand as _, getSupportedShells as a, hasCompleteCommand as c, extractPositionals as d, CompletionDirective as f, createDefineCommand as g, resolveValueCompletion as h, generateCompletion as i, formatForShell as l, parseCompletionContext as m, createRefreshCompletionCommand as n, withCompletionCommand as o, generateCandidates as p, detectShell as r, createDynamicCompleteCommand as s, createCompletionCommand as t, extractCompletionData as u };
+//# sourceMappingURL=completion-BA5JMvVG.js.map