politty 0.4.16 → 0.5.1

package/dist/completion-BFOAOg95.cjs

@@ -0,0 +1,4294 @@
+const require_log_collector = require('./log-collector-Cd2_mv87.cjs');
+const require_schema_extractor = require('./schema-extractor-SLPgBNgZ.cjs');
+let zod = require("zod");
+let node_child_process = require("node:child_process");
+let node_fs = require("node:fs");
+let node_path = require("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, `--${require_schema_extractor.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(`--${require_schema_extractor.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(`--${require_schema_extractor.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(`--${require_schema_extractor.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 require_schema_extractor.extractFields(schema).fields.filter((field) => !field.positional).map((field) => {
+		const aliases = require_schema_extractor.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 require_schema_extractor.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 = require_schema_extractor.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 require_schema_extractor.resolveSubCommandMeta(sub);
+	const canonical = require_schema_extractor.resolveSubCommandAlias(command, name);
+	if (canonical) return require_schema_extractor.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 === require_schema_extractor.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("-") && require_schema_extractor.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 (0, node_child_process.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 : require_schema_extractor.resolveSubCommandAlias(context.currentCommand, name);
+		const resolved = direct ?? (aliasCanonical ? subs?.[aliasCanonical] : void 0);
+		const description = resolved ? require_schema_extractor.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 require_schema_extractor.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 = require_schema_extractor.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 ? require_schema_extractor.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(require_schema_extractor.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((0, node_fs.statSync)(binPath).mtimeMs / 1e3).toString();
+	} catch {
+		return "0";
+	}
+}
+/**
+* Walk `$PATH` looking for an executable named `programName`. Returns
+* the first match's full path, or `null` when not found. We mirror the
+* shell's `command -v <prog>` here so the sig embedded in the header
+* (computed by Node) lines up with what the rc loader stat-checks at
+* runtime — including pnpm/npm bin shims that wrap the real entrypoint.
+* Without this alignment, shimmed installs would never match the
+* embedded sig and the cache would regenerate on every shell startup.
+*/
+function findOnPath(programName) {
+	if (!programName || /[/\\\0]/.test(programName)) return null;
+	const path = process.env.PATH ?? "";
+	for (const dir of path.split(":")) {
+		if (!dir) continue;
+		const candidate = (0, node_path.join)(dir, programName);
+		try {
+			if ((0, node_fs.statSync)(candidate).isFile()) return candidate;
+		} catch {}
+	}
+	return null;
+}
+/**
+* Resolve the binary path used for sig computation and stat checks.
+*
+* Order: explicit override → `$PATH` lookup of `programName` → `process.argv[1]`.
+* The `$PATH` lookup keeps Node-side and shell-side stats pointed at the
+* same shim file when the CLI is invoked through a package-manager bin shim.
+*/
+function resolveBinPath(programName, override) {
+	if (override) return override;
+	return findOnPath(programName) ?? process.argv[1] ?? "";
+}
+/**
+* Build the header lines (no trailing blank line). Returned without a
+* leading `#!` so each generator can prepend its own shebang/compdef
+* marker.
+*/
+function buildHeaderLines(opts) {
+	const sig = computeBinSig(resolveBinPath(opts.programName, opts.binPath));
+	const lines = [
+		`# politty-completion-version: ${1}`,
+		`# politty-bin-sig: ${sig}`,
+		`# program: ${opts.programName}`
+	];
+	if (opts.programVersion) lines.push(`# program-version: ${opts.programVersion}`);
+	lines.push(`# shell: ${opts.shell}`);
+	return lines;
+}
+
+//#endregion
+//#region src/completion/self-refresh.ts
+/**
+* Self-refresh guards embedded in generated bash/zsh scripts.
+*
+* These guards make the default `completion <shell>` output safe to
+* save as a static completion file: when the CLI binary changes, the
+* script asks the hidden refresh subcommand to rewrite the sourced
+* file in place, then sources the fresh file and stops executing the
+* stale body.
+*/
+function statSigExpr() {
+	return `$(stat -L -c '%Y' "$_bin" 2>/dev/null || stat -L -f '%m' "$_bin" 2>/dev/null)`;
+}
+function generateBashSelfRefresh(opts) {
+	const { programName, binPath } = opts;
+	const fn = sanitize(programName);
+	const sig = computeBinSig(resolveBinPath(programName, binPath));
+	const refreshFn = `__${fn}_self_refresh`;
+	return [
+		`${refreshFn}() {`,
+		`    local _self _bin _sig`,
+		`    _self=\${BASH_SOURCE[0]:-}`,
+		`    [[ -n "$_self" && -f "$_self" ]] || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# politty-completion-version:" || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# program: ${programName}" || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# shell: bash" || return 1`,
+		`    _bin=$(type -P ${programName} 2>/dev/null)`,
+		`    [[ -n "$_bin" ]] || return 1`,
+		`    _sig=${statSigExpr()} || return 1`,
+		`    [[ "$_sig" != "${sig}" ]] || return 1`,
+		`    "$_bin" __refresh-completion bash "$_self" 2>/dev/null || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# politty-bin-sig: $_sig" || return 1`,
+		`    source "$_self" 2>/dev/null || return 1`,
+		`    return 0`,
+		`}`,
+		`if ${refreshFn}; then`,
+		`    unset -f ${refreshFn}`,
+		`    return 0 2>/dev/null || true`,
+		`else`,
+		`    unset -f ${refreshFn}`,
+		`fi`,
+		``
+	];
+}
+function generateZshSelfRefresh(opts) {
+	const { programName, binPath } = opts;
+	const fn = sanitize(programName);
+	const completionFn = `_${programName}`;
+	const sig = computeBinSig(resolveBinPath(programName, binPath));
+	const refreshFn = `__${fn}_self_refresh`;
+	return [
+		`${refreshFn}() {`,
+		`    emulate -L zsh`,
+		`    setopt local_options no_aliases`,
+		`    local _self _bin _sig`,
+		`    _self="\${(%):-%x}"`,
+		`    [[ -n "$_self" && -f "$_self" ]] || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# politty-completion-version:" || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# program: ${programName}" || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# shell: zsh" || return 1`,
+		`    _bin=$(whence -p ${programName} 2>/dev/null)`,
+		`    [[ -n "$_bin" ]] || return 1`,
+		`    _sig=${statSigExpr()} || return 1`,
+		`    [[ "$_sig" != "${sig}" ]] || return 1`,
+		`    "$_bin" __refresh-completion zsh "$_self" 2>/dev/null || return 1`,
+		`    head -n 8 "$_self" 2>/dev/null | grep -qF "# politty-bin-sig: $_sig" || return 1`,
+		`    source "$_self" 2>/dev/null || return 1`,
+		`    ${completionFn} "$@"`,
+		`    return 0`,
+		`}`,
+		`if ${refreshFn} "$@"; then`,
+		`    unfunction ${refreshFn} 2>/dev/null`,
+		`    return 0 2>/dev/null || true`,
+		`else`,
+		`    unfunction ${refreshFn} 2>/dev/null`,
+		`fi`,
+		``
+	];
+}
+
+//#endregion
+//#region src/completion/bash.ts
+/** Escape a string for use inside bash double-quotes */
+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(``);
+	lines.push(...generateBashSelfRefresh({
+		programName,
+		binPath: options.binPath
+	}));
+	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 auto-refreshing bash completions, add this to your ~/.bashrc:
+eval "$(${programName} completion bash)"
+
+# For faster shell startup, save the script instead:
+mkdir -p ~/.local/share/bash-completion/completions
+${programName} completion bash > ~/.local/share/bash-completion/completions/${programName}
+
+# Then reload your shell or run:
+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 = zod.z.object({
+	shell: require_schema_extractor.arg(zod.z.enum([
+		"bash",
+		"zsh",
+		"fish"
+	]), { description: "Target shell for output formatting" }),
+	args: require_schema_extractor.arg(zod.z.array(zod.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 (status current-filename)`);
+	lines.push(`    test -n "$_target"; and test -f "$_target"; or return 1`);
+	lines.push(`    "$_bin" __refresh-completion fish "$_target" 2>/dev/null`);
+	lines.push(`    and source "$_target" 2>/dev/null`);
+	lines.push(`    and return 0`);
+	lines.push(`    return 1`);
+	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 auto-refreshing fish completions, run:
+${programName} completion fish --install`
+	};
+}
+
+//#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$1(s) {
+	return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function bashCachePathExpr(programName, cacheDir, shell) {
+	if (cacheDir) return shSingleQuote$1(`${cacheDir}/completion.${shell}`);
+	return `"\${XDG_CACHE_HOME:-$HOME/.cache}/${programName}/completion.${shell}"`;
+}
+function generateBashLoader(opts) {
+	const fn = sanitize(opts.programName);
+	const cache = bashCachePathExpr(opts.programName, opts.cacheDir, "bash");
+	return `__${fn}_load_completion() {
+    local _bin _cache _sig _hdr
+    _bin=$(type -P ${opts.programName} 2>/dev/null)
+    [[ -n "$_bin" ]] || return 0
+    _cache=${cache}
+    _sig=$(stat -L -c '%Y' "$_bin" 2>/dev/null || stat -L -f '%m' "$_bin" 2>/dev/null) || return 0
+    _hdr="# politty-bin-sig: $_sig"
+    if [[ ! -f "$_cache" ]] || ! head -5 "$_cache" 2>/dev/null | grep -qF "$_hdr"; then
+        # Use the hidden __refresh-completion subcommand instead of
+        # \`$_bin completion bash\`: the foreground completion command
+        # is subject to user setup/cleanup/prompt and required
+        # globalArgs validation, which can silently fail or block when
+        # invoked from rc; runMain bypasses those for __-prefixed
+        # internal subcommands.
+        "$_bin" __refresh-completion bash 2>/dev/null
+    fi
+    # If regen failed but a stale cache survived from a previous run,
+    # source it anyway — a stale completion is preferable to no
+    # completion at all.
+    [[ -f "$_cache" ]] || return 0
+    # shellcheck disable=SC1090
+    source "$_cache"
+}
+__${fn}_load_completion
+unset -f __${fn}_load_completion
+`;
+}
+function generateZshLoader(opts) {
+	const fn = sanitize(opts.programName);
+	const cache = bashCachePathExpr(opts.programName, opts.cacheDir, "zsh");
+	return `__${fn}_load_completion() {
+    emulate -L zsh
+    setopt local_options no_aliases
+    local _bin _cache _sig _hdr
+    _bin=$(whence -p ${opts.programName} 2>/dev/null)
+    [[ -n "$_bin" ]] || return 0
+    _cache=${cache}
+    _sig=$(stat -L -c '%Y' "$_bin" 2>/dev/null || stat -L -f '%m' "$_bin" 2>/dev/null) || return 0
+    _hdr="# politty-bin-sig: $_sig"
+    if [[ ! -f "$_cache" ]] || ! head -5 "$_cache" 2>/dev/null | grep -qF "$_hdr"; then
+        # See bash loader for why we use __refresh-completion instead
+        # of \`$_bin completion zsh\`.
+        "$_bin" __refresh-completion zsh 2>/dev/null
+    fi
+    # See bash loader: keep stale completion over no completion.
+    [[ -f "$_cache" ]] || return 0
+    source "$_cache"
+}
+__${fn}_load_completion
+unfunction __${fn}_load_completion
+`;
+}
+/**
+* Build the rc-loader snippet for bash or zsh. Fish doesn't have an
+* rc-loader; instead, `<program> completion fish --install` writes a
+* self-rewriting autoload file.
+*/
+function generateLoader(opts) {
+	switch (opts.shell) {
+		case "bash": return generateBashLoader(opts);
+		case "zsh": return generateZshLoader(opts);
+		case "fish": throw new Error("fish does not use an rc loader. Run `<program> completion fish --install` to write the self-refreshing autoload file instead.");
+	}
+}
+/**
+* Default cache file path (used by `completion <bash|zsh> --install`
+* and the `__refresh-completion` subcommand). For fish, the install
+* path is `$__fish_config_dir/completions/<program>.fish` and is
+* computed inside `installPath()` instead.
+*/
+function defaultCacheDir(programName) {
+	return `${process.env.XDG_CACHE_HOME ?? `${process.env.HOME ?? ""}/.cache`}/${programName}`;
+}
+
+//#endregion
+//#region src/completion/install.ts
+/**
+* On-disk install + refresh helpers.
+*
+* `install` writes the generated script to its canonical cache /
+* autoload path. `refresh` is the body of the `__refresh-completion`
+* hidden subcommand and the runMain background hook — it regenerates
+* the cache only when the binary's mtime no longer matches the
+* embedded `# politty-bin-sig:` header.
+*
+* All file I/O is best-effort: failures fall through silently. A stale
+* (or missing) cache is preferable to crashing the user's shell.
+*/
+/**
+* Resolve where a script for the given shell should live on disk.
+*
+* - bash/zsh: `<cacheDir>/completion.<shell>` — sourced by the rc loader.
+* - fish:    `$__fish_config_dir/completions/<program>.fish` — autoloaded
+*            by fish on TAB. We approximate `$__fish_config_dir` from
+*            `$XDG_CONFIG_HOME` / `$HOME`.
+*/
+function installPath(programName, shell, cacheDir) {
+	if (shell === "fish") return (0, node_path.join)(process.env.XDG_CONFIG_HOME ?? `${process.env.HOME ?? ""}/.config`, "fish", "completions", `${programName}.fish`);
+	return (0, node_path.join)(cacheDir ?? defaultCacheDir(programName), `completion.${shell}`);
+}
+/** Atomic write: tmp file in the same dir, then rename. */
+function writeAtomic(path, content) {
+	(0, node_fs.mkdirSync)((0, node_path.dirname)(path), { recursive: true });
+	const tmp = `${path}.tmp.${process.pid}`;
+	(0, node_fs.writeFileSync)(tmp, content);
+	(0, node_fs.renameSync)(tmp, path);
+}
+function generateScript(ctx, shell) {
+	return generateCompletion(ctx.rootCommand, {
+		shell,
+		programName: ctx.programName,
+		includeDescriptions: true,
+		...ctx.programVersion !== void 0 && { programVersion: ctx.programVersion },
+		...ctx.binPath !== void 0 && { binPath: ctx.binPath },
+		...ctx.cacheDir !== void 0 && { cacheDir: ctx.cacheDir },
+		...ctx.globalArgsSchema !== void 0 && { globalArgsSchema: ctx.globalArgsSchema }
+	}).script;
+}
+/** Write the script for `shell` to its install path. Returns the path. */
+function install(ctx, shell) {
+	const target = installPath(ctx.programName, shell, ctx.cacheDir);
+	writeAtomic(target, generateScript(ctx, shell));
+	return target;
+}
+/**
+* Read the first ~5 lines of an existing cache file and return its
+* embedded bin-sig. Returns `null` when the file is missing, unreadable,
+* or doesn't have a sig header.
+*/
+function readCachedSig(path) {
+	try {
+		if (!(0, node_fs.existsSync)(path)) return null;
+		const m = (0, node_fs.readFileSync)(path, "utf8").split("\n", 6).join("\n").match(/^# politty-bin-sig: (\S+)/m);
+		return m ? m[1] : null;
+	} catch {
+		return null;
+	}
+}
+function isManagedTarget(path, programName, shell) {
+	try {
+		if (!(0, node_fs.existsSync)(path)) return false;
+		const head = (0, node_fs.readFileSync)(path, "utf8").split("\n", 8).join("\n");
+		return /^# politty-completion-version: \S+/m.test(head) && head.includes(`# program: ${programName}`) && head.includes(`# shell: ${shell}`);
+	} catch {
+		return false;
+	}
+}
+/**
+* Rewrite the cache only when stale. Used by:
+*   - `<program> __refresh-completion <shell>` (the hidden subcommand
+*     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 = ctx.targetPath ? (0, node_fs.realpathSync)(ctx.targetPath) : installPath(ctx.programName, shell, ctx.cacheDir);
+		if (ctx.targetPath && !isManagedTarget(target, ctx.programName, shell)) return;
+		const binPath = resolveBinPath(ctx.programName, ctx.binPath);
+		if (!binPath) return;
+		let currentSig;
+		try {
+			currentSig = Math.floor((0, node_fs.statSync)(binPath).mtimeMs / 1e3).toString();
+		} catch {
+			return;
+		}
+		if (readCachedSig(target) === currentSig) return;
+		writeAtomic(target, generateScript(ctx, shell));
+	} catch {}
+}
+/**
+* Returns true when a politty-managed cache file already exists on disk
+* for the given shell — i.e. the user has installed completion via
+* `<program> completion <shell> --install` or the rc loader has already
+* sourced one. Used by the runMain background hook to avoid spawning
+* the refresher (and thereby silently creating files) on plain CLI runs
+* the user never opted into.
+*/
+function hasManagedCache(ctx, shell) {
+	return readCachedSig(installPath(ctx.programName, shell, ctx.cacheDir)) !== null;
+}
+/**
+* Spawn a detached child process that runs `<program> __refresh-completion <shell>`.
+* The child is fully decoupled (`stdio: "ignore"` + `unref()`), so it
+* outlives the parent without holding any handles.
+*
+* Caller is expected to gate this on the right conditions (interactive
+* shell, not running inside `__complete` itself, etc.).
+*
+* Returns `void` and never throws — even spawn failures are absorbed.
+*/
+function spawnBackgroundRefresh(programArgv0, shell) {
+	try {
+		(0, node_child_process.spawn)(process.execPath, [
+			programArgv0,
+			"__refresh-completion",
+			shell
+		], {
+			detached: true,
+			stdio: "ignore"
+		}).unref();
+	} catch {}
+}
+
+//#endregion
+//#region src/completion/zsh.ts
+function escapeDesc(s) {
+	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, "\\:");
+}
+/** Escape a string for use inside zsh double-quotes. */
+function escapeZshDQ(s) {
+	return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"").replace(/\$/g, "\\$").replace(/`/g, "\\`");
+}
+/**
+* Generate zsh value completion lines for a ValueCompletion spec.
+* Uses `_vals` array (must be declared in the calling function scope).
+* `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 completionFn = `_${programName}`;
+	const autoloadCheck = `"\${funcstack[1]:-}" == "${escapeZshDQ(completionFn)}"`;
+	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(``);
+	lines.push(...generateZshSelfRefresh({
+		programName,
+		binPath: options.binPath
+	}));
+	for (const spec of expandSpecs) {
+		const varName = expandTableVarName(fn, spec.funcSuffix, spec.fieldName);
+		if (spec.vc.table.length === 0) lines.push(`typeset -gA ${varName}=()`);
+		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(`${completionFn}() {`);
+	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(`if [[ ${autoloadCheck} ]]; then`);
+	lines.push(`    ${completionFn} "$@"`);
+	lines.push(`else`);
+	lines.push(`    compdef ${completionFn} ${programName}`);
+	lines.push(`fi`);
+	lines.push(``);
+	return {
+		script: lines.join("\n"),
+		shell: "zsh",
+		installInstructions: `# To enable auto-refreshing zsh completions, add this to your ~/.zshrc after compinit:
+eval "$(${programName} completion zsh)"
+
+# For faster shell startup, save the script in your fpath:
+mkdir -p ~/.zsh/completions
+${programName} completion zsh > ~/.zsh/completions/_${programName}
+
+# Make sure your ~/.zshrc includes the fpath line before compinit:
+fpath=(~/.zsh/completions $fpath)
+autoload -Uz compinit && compinit
+
+# If ~/.zshrc already calls compinit, add only the fpath line before
+# the existing compinit call.
+
+# Then reload your shell or run:
+source ~/.zshrc`
+	};
+}
+
+//#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"
+	];
+}
+function shSingleQuote(s) {
+	return `'${s.replace(/'/g, "'\\''")}'`;
+}
+function printZshFpathSetup(programName, target) {
+	console.error("");
+	console.error("Configure zsh fpath with:");
+	console.error("");
+	console.error("    mkdir -p ~/.zsh/completions");
+	console.error(`    ln -sf ${shSingleQuote(target)} ~/.zsh/completions/_${programName}`);
+	console.error("");
+	console.error("Add only this block to your ~/.zshrc before compinit:");
+	console.error("");
+	console.error("    fpath=(~/.zsh/completions $fpath)");
+	console.error("    autoload -Uz compinit && compinit");
+}
+/**
+* Detect the current shell from environment
+*/
+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 = zod.z.object({
+	shell: require_schema_extractor.arg(zod.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: require_schema_extractor.arg(zod.z.boolean().default(false), {
+		alias: "i",
+		description: "Show installation instructions"
+	}),
+	loader: require_schema_extractor.arg(zod.z.boolean().default(false), { description: "Print just the rc loader snippet (bash/zsh). Add it to ~/.bashrc or ~/.zshrc; it auto-regenerates the cache when the binary changes." }),
+	install: require_schema_extractor.arg(zod.z.boolean().default(false), { description: "Write the completion script to its on-disk cache (bash/zsh) or autoload location (fish) instead of printing it." })
+});
+const refreshArgsSchema = zod.z.object({
+	shell: require_schema_extractor.arg(zod.z.enum([
+		"bash",
+		"zsh",
+		"fish"
+	]), {
+		positional: true,
+		description: "Shell to refresh",
+		placeholder: "SHELL"
+	}),
+	target: require_schema_extractor.arg(zod.z.string().optional(), {
+		positional: true,
+		description: "Existing politty-generated completion file to refresh",
+		placeholder: "TARGET"
+	})
+});
+/**
+* Create a completion subcommand for your CLI
+*
+* 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 === "bash") {
+					console.error("");
+					console.error(`Add to your ~/.${shellType}rc:`);
+					console.error("");
+					console.error(generateLoader({
+						...loaderOptsBase,
+						shell: shellType
+					}).trim().replace(/^/gm, "    "));
+				} else if (shellType === "zsh") printZshFpathSetup(resolvedProgramName, target);
+				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.target !== void 0 && { targetPath: args.target }
+			}, 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
+Object.defineProperty(exports, 'CompletionDirective', {
+  enumerable: true,
+  get: function () {
+    return CompletionDirective;
+  }
+});
+Object.defineProperty(exports, 'createCompletionCommand', {
+  enumerable: true,
+  get: function () {
+    return createCompletionCommand;
+  }
+});
+Object.defineProperty(exports, 'createDefineCommand', {
+  enumerable: true,
+  get: function () {
+    return createDefineCommand;
+  }
+});
+Object.defineProperty(exports, 'createDynamicCompleteCommand', {
+  enumerable: true,
+  get: function () {
+    return createDynamicCompleteCommand;
+  }
+});
+Object.defineProperty(exports, 'createRefreshCompletionCommand', {
+  enumerable: true,
+  get: function () {
+    return createRefreshCompletionCommand;
+  }
+});
+Object.defineProperty(exports, 'defineCommand', {
+  enumerable: true,
+  get: function () {
+    return defineCommand;
+  }
+});
+Object.defineProperty(exports, 'detectShell', {
+  enumerable: true,
+  get: function () {
+    return detectShell;
+  }
+});
+Object.defineProperty(exports, 'extractCompletionData', {
+  enumerable: true,
+  get: function () {
+    return extractCompletionData;
+  }
+});
+Object.defineProperty(exports, 'extractPositionals', {
+  enumerable: true,
+  get: function () {
+    return extractPositionals;
+  }
+});
+Object.defineProperty(exports, 'formatForShell', {
+  enumerable: true,
+  get: function () {
+    return formatForShell;
+  }
+});
+Object.defineProperty(exports, 'generateCandidates', {
+  enumerable: true,
+  get: function () {
+    return generateCandidates;
+  }
+});
+Object.defineProperty(exports, 'generateCompletion', {
+  enumerable: true,
+  get: function () {
+    return generateCompletion;
+  }
+});
+Object.defineProperty(exports, 'getSupportedShells', {
+  enumerable: true,
+  get: function () {
+    return getSupportedShells;
+  }
+});
+Object.defineProperty(exports, 'hasCompleteCommand', {
+  enumerable: true,
+  get: function () {
+    return hasCompleteCommand;
+  }
+});
+Object.defineProperty(exports, 'parseCompletionContext', {
+  enumerable: true,
+  get: function () {
+    return parseCompletionContext;
+  }
+});
+Object.defineProperty(exports, 'resolveValueCompletion', {
+  enumerable: true,
+  get: function () {
+    return resolveValueCompletion;
+  }
+});
+Object.defineProperty(exports, 'withCompletionCommand', {
+  enumerable: true,
+  get: function () {
+    return withCompletionCommand;
+  }
+});
+//# sourceMappingURL=completion-BFOAOg95.cjs.map