@crustjs/extensions 0.2.0

package/dist/index.js

@@ -0,0 +1,1857 @@
+import { mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { CrustError, defineCommand, defineExtension, defineExtensionId } from "@crustjs/core";
+import { buildCommandDocumentation, formatDescription, isListed, sectionsFor } from "@crustjs/core/tooling";
+import { stripVTControlCharacters } from "node:util";
+import { bold, cyan, dim, green, padEnd, stringWidth, yellow } from "@crustjs/style";
+//#region src/completion/escape.ts
+/**
+* Per-shell quoting and validation helpers used by the completion
+* templates and by the extension's output-path handling.
+*
+* Why this exists: the completion templates inline a lot of CLI-author
+* provided text — command names, flag names, descriptions, choice values,
+* `binName`, `version` — into emitted shell scripts. Those scripts are
+* routinely installed via `eval "$(mycli completion bash)"` (it is the
+* documented install path), so any unsanitised interpolation is at
+* minimum a foot-gun and at worst arbitrary code execution at install
+* time. Centralising the escaping rules in one module keeps the templates
+* pure rendering code and gives us a single place to test the adversarial
+* inputs.
+*
+* Two complementary strategies are used:
+*
+* 1. **Validate identifiers** — command/flag/alias/bin names are
+*    programmer-controlled identifiers in the source CLI definition.
+*    They have no business containing whitespace, quotes, semicolons, or
+*    control characters. We reject those at spec/render time with a
+*    clear error rather than try to escape them through three different
+*    shell grammars.
+* 2. **Escape free-form text** — descriptions, choice values, version
+*    strings, and the embedded comment headers are user-facing prose.
+*    Those go through per-shell escape helpers so the templates can
+*    interpolate them safely.
+*/
+/**
+* Choice-value shape accepted for `flags[].choices` and `args[].choices`.
+*
+* Looser than {@link IDENT_PATTERN} so legitimate enumerated values like
+* `us-east-1`, `1.0`, `text/plain`, or `node@20` flow through unchanged,
+* but still excludes whitespace, quotes, and shell metacharacters that
+* would force per-shell escaping inside the emitted action lists
+* (`compgen -W`, zsh `(...)` action, fish `-a`).
+*
+* If a CLI legitimately needs choice values containing whitespace or
+* shell-special characters, we'd need a richer per-shell escaping scheme;
+* that's out of scope for v1. We fail fast with a clear message rather
+* than silently mis-quote.
+*/
+const CHOICE_VALUE_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.+:@/-]*$/;
+function assertSafeChoiceValue(value) {
+	if (!CHOICE_VALUE_PATTERN.test(value)) throw new Error(`completion extension: unsupported choice value ${JSON.stringify(value)} — must match /^[A-Za-z0-9_.+:@/-]+$/. Whitespace and shell metacharacters are not supported in v1.`);
+	return value;
+}
+/**
+* Identifier shape accepted for command names, flag names, flag aliases,
+* short flags, and arg names.
+*
+* - First char must be alphanumeric (avoids leading `-` which `complete`
+*   would interpret as an option in bash/fish).
+* - Subsequent chars: alphanumeric, `_`, `.`, or `-`.
+* - Single-character names are allowed (covers single-char short flags).
+*
+* This is deliberately conservative. CLI authors who want a command
+* named `foo:bar` or `it's` are out of scope for v1 — every shell would
+* need bespoke escaping for `case` patterns, `compdef`, and fish
+* predicate code.
+*/
+const IDENT_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]*)?$/;
+/** Throw if `name` is not a safe identifier; otherwise return it. */
+function assertSafeIdentifier(name, kind) {
+	if (!IDENT_PATTERN.test(name)) throw new Error(`completion extension: invalid ${kind} ${JSON.stringify(name)} — must match /^[A-Za-z0-9][A-Za-z0-9._-]*$/. Whitespace, quotes, and shell metacharacters are not supported.`);
+	return name;
+}
+/** Map a validated CLI identifier to a shell function identifier. */
+function toShellIdent(name) {
+	return name.replace(/[^A-Za-z0-9_]/g, "_");
+}
+/**
+* Validate `binName` for use as the program name in generated scripts and
+* as a filesystem basename when `--output-dir` is set.
+*
+* Stricter than {@link assertSafeIdentifier} because `binName` also
+* becomes a filename and a `complete -F`/`compdef` argument that's
+* easier to break than option names.
+*/
+function assertSafeBinName(binName) {
+	if (binName.length === 0) throw new Error("completion extension: binName must not be empty");
+	if (binName.includes("/") || binName.includes("\\") || binName === ".." || binName === ".") throw new Error(`completion extension: invalid binName ${JSON.stringify(binName)} — path separators and "."/".." are not allowed (used as a filename in --output-dir mode).`);
+	return assertSafeIdentifier(binName, "binName");
+}
+/**
+* Strip control characters from `value` so it can be safely embedded in
+* a shell comment line or shell-quoted string without smuggling a
+* newline that would terminate the comment / break the quote nesting.
+*
+* Replaces NUL, CR, LF, vertical-tab, form-feed, and other C0/C1 controls
+* with a single space. We keep horizontal tab as-is (descriptions
+* occasionally use it for alignment).
+*/
+function sanitizeFreeText(value) {
+	return value.replace(/[\x00-\x08\x0A-\x1F\x7F]/g, " ");
+}
+/**
+* Wrap `value` as a bash single-quoted shell word.
+*
+* Single quotes have no escape sequence in bash, so embedded single quotes
+* close-and-reopen the quote: `'foo'\''bar'`. This is the canonical
+* `printf %q`-style safe form: the result is always exactly one shell
+* token regardless of the input bytes (after sanitisation).
+*
+* Callers should pass values that have already had control characters
+* scrubbed via {@link sanitizeFreeText} when the value is free-form
+* (description, version, choice value).
+*/
+function bashSingleQuote(value) {
+	return `'${value.replace(/'/g, "'\\''")}'`;
+}
+/**
+* Escape a single value for inclusion as a literal-matched key in a bash
+* `case` pattern, when the entire pattern is wrapped in double quotes.
+*
+* Inside `"..."` quotes, bash treats `*?[]{}|()` as literals, so the only
+* remaining concern is the double-quote characters in the active set:
+* `\`, `$`, `` ` ``, `"`. We escape those.
+*
+* The result is meant to be placed inside `"..."`; callers add the outer
+* quotes themselves so they can build patterns like
+* `"<path>|<word>"` from multiple escaped pieces.
+*/
+function bashDoubleQuoteInner(value) {
+	return value.replace(/[\\$`"]/g, "\\$&");
+}
+/**
+* Escape free-form text for use inside the `[...]` description bracket of
+* a zsh `_arguments` spec.
+*
+* `_arguments` parses spec strings with `:` as the field separator and
+* `[...]` as the description bracket; backslash escapes both. We also
+* scrub newlines (descriptions are one-liners in completion menus) and
+* single quotes (the spec is wrapped in single quotes by the caller).
+*/
+function zshArgsDescription(value) {
+	return value.replace(/\\/g, "\\\\").replace(/\[/g, "\\[").replace(/]/g, "\\]").replace(/:/g, "\\:").replace(/'/g, "'\\''").replace(/[\r\n]+/g, " ");
+}
+/**
+* Escape a value for inclusion as the **name** field of a `_describe`
+* item (the part before the `:` description separator). `_describe`
+* splits each item on the first un-escaped `:`, so embedded colons
+* must be escaped. Backslashes also need escaping because they're the
+* escape character.
+*
+* The result is meant to be placed inside zsh single quotes by the
+* caller (we do NOT include outer quotes); call {@link bashSingleQuote}
+* on the assembled `name:desc` string when emitting.
+*/
+function zshDescribeField(value) {
+	return value.replace(/\\/g, "\\\\").replace(/:/g, "\\:").replace(/[\r\n]+/g, " ");
+}
+/**
+* Wrap `value` as a fish single-quoted shell word. Fish single quotes
+* only escape `\\` and `\'`; everything else is literal.
+*/
+function fishSingleQuote(value) {
+	return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+}
+//#endregion
+//#region src/completion/templates/bash.ts
+/**
+* Pure-static bash completion script renderer.
+*
+* Strategy: at generation time we walk the command tree and emit a
+* self-contained bash function that performs the full completion logic
+* locally — no `__complete` subprocess shell-out, no runtime callbacks.
+*
+* The generated script:
+*
+* 1. Defines a Cobra-style fallback init shim
+*    (`__<bin>_init_completion`) so the script works even when the
+*    `bash-completion` package is not installed (macOS default bash,
+*    Alpine, NixOS without the package).
+* 2. Walks `COMP_WORDS` left-to-right, advancing a `cmd_path` through
+*    the static command tree. Stops walking at the `--` end-of-options
+*    terminator and skips value-taking flag pairs so we don't mistake a
+*    flag value for a subcommand.
+* 3. Once the path is resolved, picks completion candidates:
+*    - if the user is mid-`--name=value`, splits on `=` and offers the
+*      static value list (or files) for that flag,
+*    - else if the previous token is a known flag-with-choices, offers
+*      the static value list,
+*    - else if the previous token is a known free-form value flag,
+*      falls back to file completion,
+*    - else if the current token starts with `-`, offers the flag set,
+*    - else offers the subcommand list and the resolved command's
+*      positional choices (or files for free-form positionals).
+* 4. Registers via `complete -F _<bin> <bin>` with the bin name passed
+*    through {@link bashSingleQuote}.
+*/
+/**
+* Render the wordlist of subcommand candidates for a single command —
+* each candidate as a bash-quoted shell word so values containing
+* spaces (theoretical: identifier validation rejects them) or shell
+* metacharacters (theoretical: same) survive `compgen -W` splitting.
+*
+* Includes canonical names and any declared aliases.
+*/
+function subcmdWordlist(node) {
+	const words = [];
+	for (const sub of node.subCommands) {
+		words.push(sub.name);
+		if (sub.aliases !== void 0) for (const alias of sub.aliases) words.push(alias);
+	}
+	return words.join(" ");
+}
+/**
+* Render the wordlist of flag candidates for a single command. Includes
+* long names, short alias, extra long aliases, and `--no-<name>` for
+* boolean flags whose snapshot marks them as negatable.
+*/
+function flagWordlist(node) {
+	const words = [];
+	for (const flag of node.flags) {
+		words.push(`--${flag.name}`);
+		if (flag.short !== void 0) words.push(`-${flag.short}`);
+		if (flag.aliases !== void 0) for (const alias of flag.aliases) words.push(`--${alias}`);
+		if (flag.negatable) {
+			words.push(`--no-${flag.name}`);
+			if (flag.aliases !== void 0) for (const alias of flag.aliases) words.push(`--no-${alias}`);
+		}
+	}
+	return words.join(" ");
+}
+/**
+* Recursively collect every (parent-path, child-word) edge in the command
+* tree as a `case` branch the dispatch loop can consume. Aliases are
+* surfaced as additional `case` keys that resolve to the same `cmd_path`,
+* matching the router's alias-aware behaviour.
+*/
+function collectPathCases(parentPath, parent, out) {
+	for (const sub of parent.subCommands) {
+		const newPath = parentPath === "" ? sub.name : `${parentPath}:${sub.name}`;
+		const subcmds = subcmdWordlist(sub);
+		const flags = flagWordlist(sub);
+		const valueFlags = valueFlagWordlist(sub);
+		out.push({
+			key: `${parentPath}|${sub.name}`,
+			cmdPath: newPath,
+			subcmds,
+			flags,
+			valueFlags
+		});
+		if (sub.aliases !== void 0) for (const alias of sub.aliases) out.push({
+			key: `${parentPath}|${alias}`,
+			cmdPath: newPath,
+			subcmds,
+			flags,
+			valueFlags
+		});
+		collectPathCases(newPath, sub, out);
+	}
+}
+/**
+* Walk every flag at every depth and emit one {@link ValueTypeCase} per
+* spelling for flags that declared `type: "path"` (file completion) or
+* `type: "url" | "json"` (suppress file fallback).
+*/
+function collectValueTypeCases(cmdPath, node, out) {
+	for (const flag of node.flags) {
+		if (flag.valueCompletion === void 0) continue;
+		const kind = flag.valueCompletion === "files" ? "path" : "suppress";
+		for (const spelling of flagSpellings(flag)) out.push({
+			key: `${cmdPath}|${spelling}`,
+			kind
+		});
+	}
+	for (const sub of node.subCommands) collectValueTypeCases(cmdPath === "" ? sub.name : `${cmdPath}:${sub.name}`, sub, out);
+}
+/**
+* For every flag at every command depth that declares `choices`, emit a
+* `case` branch mapping `<path>|<flag-spelling>` → values. Each spelling
+* (long, short, alias) gets its own branch so the lookup is constant-time
+* regardless of how the user wrote the flag.
+*/
+function collectChoiceCases(cmdPath, node, out) {
+	for (const flag of node.flags) {
+		if (flag.choices === void 0) continue;
+		const values = flag.choices.join(" ");
+		const spellings = flagSpellings(flag);
+		for (const spelling of spellings) out.push({
+			key: `${cmdPath}|${spelling}`,
+			values
+		});
+	}
+	for (const sub of node.subCommands) collectChoiceCases(cmdPath === "" ? sub.name : `${cmdPath}:${sub.name}`, sub, out);
+}
+/**
+* Collect per-command positional suppression entries. Each url/json
+* positional contributes one slot index; a variadic url/json positional
+* also sets `variadicFrom` so suppression extends past the declared slot.
+*/
+function collectArgSuppressCases(cmdPath, node, out) {
+	const slots = [];
+	let variadicFrom;
+	node.args.forEach((arg, idx) => {
+		if (arg.valueCompletion !== "none") return;
+		if (arg.variadic) variadicFrom = idx;
+		else slots.push(idx);
+	});
+	if (slots.length > 0 || variadicFrom !== void 0) out.push({
+		cmdPath,
+		slots,
+		variadicFrom
+	});
+	for (const sub of node.subCommands) collectArgSuppressCases(cmdPath === "" ? sub.name : `${cmdPath}:${sub.name}`, sub, out);
+}
+/**
+* Collect per-command positional choice entries, recursively. Returns
+* one {@link ArgChoiceEntry} per command that has at least one positional
+* arg with a `choices` list (variadic or otherwise). Commands with no
+* positional choices are omitted so the rendered case-block stays
+* tight.
+*/
+function collectArgChoiceCases(cmdPath, node, out) {
+	const bySlot = [];
+	let variadicFrom;
+	let variadicValues;
+	let hasAny = false;
+	node.args.forEach((arg, idx) => {
+		if (arg.variadic) {
+			if (arg.choices !== void 0) {
+				variadicFrom = idx;
+				variadicValues = arg.choices.join(" ");
+				hasAny = true;
+			}
+			return;
+		}
+		if (arg.choices !== void 0) {
+			bySlot[idx] = arg.choices.join(" ");
+			hasAny = true;
+		} else bySlot[idx] = void 0;
+	});
+	if (hasAny) out.push({
+		cmdPath,
+		bySlot,
+		variadicFrom,
+		variadicValues
+	});
+	for (const sub of node.subCommands) collectArgChoiceCases(cmdPath === "" ? sub.name : `${cmdPath}:${sub.name}`, sub, out);
+}
+function flagSpellings(flag) {
+	const out = [`--${flag.name}`];
+	if (flag.short !== void 0) out.push(`-${flag.short}`);
+	if (flag.aliases !== void 0) for (const alias of flag.aliases) out.push(`--${alias}`);
+	return out;
+}
+/**
+* Render the wordlist of *value-taking* flag spellings for a single
+* command. Used to drive both flag-value context (after `--target`) and
+* the path walker's "skip the next token" heuristic.
+*/
+function valueFlagWordlist(node) {
+	const words = [];
+	for (const flag of node.flags) {
+		if (!flag.takesValue) continue;
+		for (const spelling of flagSpellings(flag)) words.push(spelling);
+	}
+	return words.join(" ");
+}
+/**
+* Render a self-contained bash completion script for the given spec.
+*
+* @param spec     The walker output describing the command tree.
+* @param binName  The user-facing binary name. Validated via
+*                 {@link assertSafeBinName} upstream.
+* @param version  Free-form version string for the header comment;
+*                 control characters are stripped before emission.
+*/
+function renderBash(spec, binName, version) {
+	const ident = toShellIdent(binName);
+	const fnName = `_${ident}`;
+	const initFn = `__${ident}_init_completion`;
+	const rootSubcmds = subcmdWordlist(spec);
+	const rootFlags = flagWordlist(spec);
+	const rootValueFlags = valueFlagWordlist(spec);
+	const pathCases = [];
+	collectPathCases("", spec, pathCases);
+	const choiceCases = [];
+	collectChoiceCases("", spec, choiceCases);
+	const valueTypeCases = [];
+	collectValueTypeCases("", spec, valueTypeCases);
+	const argChoiceEntries = [];
+	collectArgChoiceCases("", spec, argChoiceEntries);
+	const argSuppressEntries = [];
+	collectArgSuppressCases("", spec, argSuppressEntries);
+	const lines = [];
+	lines.push(`# completion script for ${binName} v${version} — regenerate with: ${binName} completion bash`);
+	lines.push("");
+	lines.push(`${initFn}() {`);
+	lines.push("	COMPREPLY=()");
+	lines.push("	cur=\"${COMP_WORDS[COMP_CWORD]}\"");
+	lines.push("	if (( COMP_CWORD > 0 )); then prev=\"${COMP_WORDS[COMP_CWORD-1]}\"; else prev=\"\"; fi");
+	lines.push("	words=(\"${COMP_WORDS[@]}\")");
+	lines.push("	cword=$COMP_CWORD");
+	lines.push("}");
+	lines.push("");
+	lines.push(`__${ident}_prev_is_value_flag() {`);
+	lines.push("	local candidate");
+	lines.push("	for candidate in $valueFlags; do");
+	lines.push("		if [[ \"$candidate\" == \"$prev\" ]]; then return 0; fi");
+	lines.push("	done");
+	lines.push("	return 1");
+	lines.push("}");
+	lines.push("");
+	lines.push(`${fnName}() {`);
+	lines.push("	local cur prev words cword");
+	lines.push("	if declare -F _init_completion >/dev/null 2>&1; then");
+	lines.push("		_init_completion -n \"=\" || return");
+	lines.push("	else");
+	lines.push(`\t\t${initFn} || return`);
+	lines.push("	fi");
+	lines.push("");
+	lines.push("	local cmd_path=\"\"");
+	lines.push(`\tlocal subcmds="${bashDoubleQuoteInner(rootSubcmds)}"`);
+	lines.push(`\tlocal flags="${bashDoubleQuoteInner(rootFlags)}"`);
+	lines.push(`\tlocal valueFlags="${bashDoubleQuoteInner(rootValueFlags)}"`);
+	lines.push("	local i=1");
+	lines.push("	local end_of_options=0");
+	lines.push("");
+	lines.push("	while (( i < cword )); do");
+	lines.push("		local w=\"${words[$i]}\"");
+	lines.push("		if [[ \"$w\" == \"--\" ]]; then");
+	lines.push("			end_of_options=1");
+	lines.push("			((i++)); break");
+	lines.push("		fi");
+	lines.push("		if [[ \"$w\" == --*=* ]]; then");
+	lines.push("			((i++)); continue");
+	lines.push("		fi");
+	lines.push("		if [[ \"$w\" == -* ]]; then");
+	lines.push("			local candidate");
+	lines.push("			local _was_value_flag=0");
+	lines.push("			for candidate in $valueFlags; do");
+	lines.push("				if [[ \"$candidate\" == \"$w\" ]]; then _was_value_flag=1; break; fi");
+	lines.push("			done");
+	lines.push("			if (( _was_value_flag )); then ((i+=2)); else ((i++)); fi");
+	lines.push("			continue");
+	lines.push("		fi");
+	lines.push("		case \"$cmd_path|$w\" in");
+	for (const c of pathCases) {
+		lines.push(`\t\t\t"${bashDoubleQuoteInner(c.key)}")`);
+		lines.push(`\t\t\t\tcmd_path="${bashDoubleQuoteInner(c.cmdPath)}"`);
+		lines.push(`\t\t\t\tsubcmds="${bashDoubleQuoteInner(c.subcmds)}"`);
+		lines.push(`\t\t\t\tflags="${bashDoubleQuoteInner(c.flags)}"`);
+		lines.push(`\t\t\t\tvalueFlags="${bashDoubleQuoteInner(c.valueFlags)}"`);
+		lines.push("				;;");
+	}
+	lines.push("			*) break ;;");
+	lines.push("		esac");
+	lines.push("		((i++))");
+	lines.push("	done");
+	lines.push("");
+	lines.push("	if (( end_of_options )); then");
+	lines.push("		return");
+	lines.push("	fi");
+	lines.push("");
+	lines.push("	if [[ \"$cur\" == --*=* ]]; then");
+	lines.push("		local _flag=\"${cur%%=*}\"");
+	lines.push("		local _value=\"${cur#*=}\"");
+	if (choiceCases.length > 0) {
+		lines.push("		case \"$cmd_path|$_flag\" in");
+		for (const c of choiceCases) {
+			lines.push(`\t\t\t"${bashDoubleQuoteInner(c.key)}")`);
+			lines.push(`\t\t\t\tCOMPREPLY=( $(compgen -P "\${_flag}=" -W "${bashDoubleQuoteInner(c.values)}" -- "$_value") )`);
+			lines.push("				return");
+			lines.push("				;;");
+		}
+		lines.push("		esac");
+	}
+	if (valueTypeCases.length > 0) {
+		lines.push("		case \"$cmd_path|$_flag\" in");
+		for (const c of valueTypeCases) {
+			lines.push(`\t\t\t"${bashDoubleQuoteInner(c.key)}")`);
+			if (c.kind === "path") lines.push("				COMPREPLY=( $(compgen -P \"${_flag}=\" -f -- \"$_value\") )");
+			else lines.push("				compopt +o default 2>/dev/null");
+			lines.push("				return");
+			lines.push("				;;");
+		}
+		lines.push("		esac");
+	}
+	lines.push("		return");
+	lines.push("	fi");
+	lines.push("");
+	if (choiceCases.length > 0) {
+		lines.push("	case \"$cmd_path|$prev\" in");
+		for (const c of choiceCases) {
+			lines.push(`\t\t"${bashDoubleQuoteInner(c.key)}")`);
+			lines.push(`\t\t\tCOMPREPLY=( $(compgen -W "${bashDoubleQuoteInner(c.values)}" -- "$cur") )`);
+			lines.push("			return");
+			lines.push("			;;");
+		}
+		lines.push("	esac");
+		lines.push("");
+	}
+	if (valueTypeCases.length > 0) {
+		lines.push("	case \"$cmd_path|$prev\" in");
+		for (const c of valueTypeCases) {
+			lines.push(`\t\t"${bashDoubleQuoteInner(c.key)}")`);
+			if (c.kind === "path") lines.push("			COMPREPLY=( $(compgen -f -- \"$cur\") )");
+			else lines.push("			compopt +o default 2>/dev/null");
+			lines.push("			return");
+			lines.push("			;;");
+		}
+		lines.push("	esac");
+		lines.push("");
+	}
+	lines.push(`\tif __${ident}_prev_is_value_flag; then`);
+	lines.push("		return");
+	lines.push("	fi");
+	lines.push("");
+	lines.push("	if [[ \"$cur\" == -* ]]; then");
+	lines.push("		COMPREPLY=( $(compgen -W \"$flags\" -- \"$cur\") )");
+	lines.push("	else");
+	if (argChoiceEntries.length > 0 || argSuppressEntries.length > 0) {
+		lines.push("		local pos_idx=0");
+		lines.push("		local _pidx_j=$i");
+		lines.push("		local _pidx_skip_next=0");
+		lines.push("		while (( _pidx_j < cword )); do");
+		lines.push("			local _pidx_w=\"${words[$_pidx_j]}\"");
+		lines.push("			if (( _pidx_skip_next )); then");
+		lines.push("				_pidx_skip_next=0");
+		lines.push("				((_pidx_j++)); continue");
+		lines.push("			fi");
+		lines.push("			if [[ \"$_pidx_w\" == \"--\" ]]; then");
+		lines.push("				((_pidx_j++)); continue");
+		lines.push("			fi");
+		lines.push("			if [[ \"$_pidx_w\" == --*=* ]]; then");
+		lines.push("				((_pidx_j++)); continue");
+		lines.push("			fi");
+		lines.push("			if [[ \"$_pidx_w\" == -* ]]; then");
+		lines.push("				local _pidx_cand");
+		lines.push("				for _pidx_cand in $valueFlags; do");
+		lines.push("					if [[ \"$_pidx_cand\" == \"$_pidx_w\" ]]; then _pidx_skip_next=1; break; fi");
+		lines.push("				done");
+		lines.push("				((_pidx_j++)); continue");
+		lines.push("			fi");
+		lines.push("			pos_idx=$((pos_idx + 1))");
+		lines.push("			((_pidx_j++))");
+		lines.push("		done");
+		lines.push("		local pos_choices=\"\"");
+		lines.push("		case \"$cmd_path\" in");
+		for (const entry of argChoiceEntries) {
+			lines.push(`\t\t\t"${bashDoubleQuoteInner(entry.cmdPath)}")`);
+			lines.push("				case \"$pos_idx\" in");
+			entry.bySlot.forEach((values, idx) => {
+				if (values === void 0) return;
+				lines.push(`\t\t\t\t\t${idx})`);
+				lines.push(`\t\t\t\t\t\tpos_choices="${bashDoubleQuoteInner(values)}"`);
+				lines.push("						;;");
+			});
+			if (entry.variadicFrom !== void 0 && entry.variadicValues !== void 0) {
+				lines.push("					*)");
+				lines.push(`\t\t\t\t\t\tif (( pos_idx >= ${entry.variadicFrom} )); then pos_choices="${bashDoubleQuoteInner(entry.variadicValues)}"; fi`);
+				lines.push("						;;");
+			}
+			lines.push("				esac");
+			lines.push("				;;");
+		}
+		lines.push("		esac");
+		if (argSuppressEntries.length > 0) {
+			lines.push("		case \"$cmd_path\" in");
+			for (const entry of argSuppressEntries) {
+				lines.push(`\t\t\t"${bashDoubleQuoteInner(entry.cmdPath)}")`);
+				lines.push("				case \"$pos_idx\" in");
+				for (const slot of entry.slots) {
+					lines.push(`\t\t\t\t\t${slot})`);
+					lines.push("						compopt +o default 2>/dev/null");
+					lines.push("						;;");
+				}
+				if (entry.variadicFrom !== void 0) {
+					lines.push("					*)");
+					lines.push(`\t\t\t\t\t\tif (( pos_idx >= ${entry.variadicFrom} )); then compopt +o default 2>/dev/null; fi`);
+					lines.push("						;;");
+				}
+				lines.push("				esac");
+				lines.push("				;;");
+			}
+			lines.push("		esac");
+		}
+		lines.push("		if (( pos_idx == 0 )); then");
+		lines.push("			COMPREPLY=( $(compgen -W \"$pos_choices $subcmds\" -- \"$cur\") )");
+		lines.push("		else");
+		lines.push("			COMPREPLY=( $(compgen -W \"$pos_choices\" -- \"$cur\") )");
+		lines.push("		fi");
+	} else lines.push("		COMPREPLY=( $(compgen -W \"$subcmds\" -- \"$cur\") )");
+	lines.push("	fi");
+	lines.push("}");
+	lines.push("");
+	lines.push(`complete -o default -F ${fnName} ${bashSingleQuote(binName)}`);
+	return `${lines.join("\n")}\n`;
+}
+//#endregion
+//#region src/completion/templates/fish.ts
+/**
+* Pure-static fish completion script renderer.
+*
+* Strategy: emit declarative `complete -c <bin>` rules — one per
+* subcommand candidate, one per flag of every reachable command. Fish
+* accumulates rules into an in-memory table at `source` time and consults
+* them on every TAB; there's no entry-point function, no subprocess, and
+* no shell state to manage.
+*
+* **Subcommand routing.** We emit a single helper per script —
+* `__<ident>_path_at_arg` — that walks `commandline -opc` left-to-right,
+* skips flags and the `--` end-of-options terminator, and verifies that
+* each consumed positional matches the expected canonical-or-alias set
+* for its depth in order. This replaces the stock
+* `__fish_seen_subcommand_from` chain (which is order-insensitive and
+* misroutes when the same name appears at different depths).
+*/
+/** Build the space-joined spelling list for a command (canonical + aliases). */
+function spellingsOf(node) {
+	return [node.name, ...node.aliases ?? []].join(" ");
+}
+/** Build the space-joined "block" list — direct children of `node`. */
+function childSpellings(node) {
+	const out = [];
+	for (const sub of node.subCommands) {
+		out.push(sub.name);
+		if (sub.aliases !== void 0) out.push(...sub.aliases);
+	}
+	return out.join(" ");
+}
+/**
+* Render a single `complete -c <bin> ...` rule line.
+*
+* `binName` was validated upstream via `assertSafeBinName`, but we still
+* single-quote it as defence-in-depth so the line works even if a future
+* caller bypasses validation.
+*/
+function renderRule(binName, parts) {
+	const segments = [`complete -c ${fishSingleQuote(binName)}`];
+	if (parts.condition !== void 0) segments.push(`-n ${fishSingleQuote(parts.condition)}`);
+	if (parts.exclusive) segments.push("-x");
+	else if (parts.requireParameter) segments.push("-r");
+	else if (parts.noFiles) segments.push("-f");
+	if (parts.short !== void 0) segments.push(`-s ${fishSingleQuote(parts.short)}`);
+	if (parts.long !== void 0) segments.push(`-l ${fishSingleQuote(parts.long)}`);
+	if (parts.arguments !== void 0) segments.push(`-a ${parts.arguments}`);
+	if (parts.description !== void 0) segments.push(`-d ${fishSingleQuote(parts.description)}`);
+	return segments.join(" ");
+}
+/**
+* Build the `-n` path and positional-argument predicate.
+*
+* Calls `__<ident>_path_at_arg <spellings...> <pos_spec> <block>` where
+* `pos_spec` is either `<N>` (exact: completion fires when exactly N
+* positionals have been consumed past the path) or `*<N>` (fires when
+* N-or-more positionals have been consumed).
+*/
+function posPredicate(ident, path, leaf, posSpec) {
+	const args = [];
+	for (const node of path) args.push(fishSingleQuote(spellingsOf(node)));
+	args.push(fishSingleQuote(posSpec));
+	args.push(fishSingleQuote(childSpellings(leaf)));
+	return `__${ident}_path_at_arg ${args.join(" ")}`;
+}
+/**
+* Recursively walk the command tree and emit:
+*   1. one subcommand-listing rule per child of the current node, gated
+*      on the path predicate — these surface child names + aliases with
+*      descriptions in the completion menu;
+*   2. one rule per flag of the current node;
+*   3. one rule per positional arg that declares choices (only the first
+*      slot — fish's `complete -a` model is best at offering a single
+*      candidate set; further slots fall through to filename completion
+*      via `-r` on the rule).
+*/
+function emitRules(binName, ident, path, current, out) {
+	const condition = posPredicate(ident, path, current, "*0");
+	for (const sub of current.subCommands) {
+		const desc = sub.description ?? "";
+		const spellings = [sub.name, ...sub.aliases ?? []];
+		for (const spelling of spellings) out.push(renderRule(binName, {
+			condition,
+			arguments: fishSingleQuote(spelling),
+			description: desc,
+			noFiles: true
+		}));
+	}
+	/**
+	* Emit choice values as a separate rule per candidate. See the note
+	* on {@link renderRule}'s `arguments` handling for why we don't
+	* pack them into one space-joined list.
+	*/
+	const emitChoiceFlag = (rule, choices) => {
+		for (const choice of choices) out.push(renderRule(binName, {
+			...rule,
+			exclusive: true,
+			arguments: fishSingleQuote(choice)
+		}));
+	};
+	for (const flag of current.flags) {
+		const desc = flag.description ?? "";
+		const baseRule = {
+			condition,
+			long: flag.name,
+			description: desc
+		};
+		if (flag.short !== void 0) baseRule.short = flag.short;
+		const emitValueRule = (rule) => {
+			if (flag.choices !== void 0 && flag.choices.length > 0) {
+				emitChoiceFlag(rule, flag.choices);
+				return;
+			}
+			if (flag.valueCompletion === "files") {
+				out.push(renderRule(binName, {
+					...rule,
+					requireParameter: true,
+					arguments: fishSingleQuote("(__fish_complete_path)")
+				}));
+				return;
+			}
+			out.push(renderRule(binName, {
+				...rule,
+				requireParameter: true
+			}));
+		};
+		if (flag.takesValue) emitValueRule(baseRule);
+		else out.push(renderRule(binName, baseRule));
+		if (flag.aliases !== void 0) for (const alias of flag.aliases) {
+			const aliasRule = {
+				condition,
+				long: alias,
+				description: desc
+			};
+			if (flag.takesValue) emitValueRule(aliasRule);
+			else out.push(renderRule(binName, aliasRule));
+		}
+		if (flag.negatable) {
+			const negDesc = `disable: ${desc}`.trim();
+			out.push(renderRule(binName, {
+				condition,
+				long: `no-${flag.name}`,
+				description: negDesc
+			}));
+			if (flag.aliases !== void 0) for (const alias of flag.aliases) out.push(renderRule(binName, {
+				condition,
+				long: `no-${alias}`,
+				description: negDesc
+			}));
+		}
+	}
+	current.args.forEach((arg, idx) => {
+		const posSpec = arg.variadic ? `*${idx}` : String(idx);
+		if (arg.choices !== void 0 && arg.choices.length > 0) {
+			const posCondition = posPredicate(ident, path, current, posSpec);
+			for (const choice of arg.choices) out.push(renderRule(binName, {
+				condition: posCondition,
+				arguments: fishSingleQuote(choice),
+				description: arg.description ?? "",
+				noFiles: true
+			}));
+			return;
+		}
+		if (arg.valueCompletion === "files") {
+			const posCondition = posPredicate(ident, path, current, posSpec);
+			out.push(renderRule(binName, {
+				condition: posCondition,
+				arguments: fishSingleQuote("(__fish_complete_path)"),
+				description: arg.description ?? ""
+			}));
+		}
+	});
+	for (const sub of current.subCommands) emitRules(binName, ident, [...path, sub], sub, out);
+}
+/**
+* Emit the per-script `__<ident>_path_at_arg` helper. It takes a
+* `pos_spec` argument before the block list. `pos_spec` is `<N>` (fires
+* when exactly N positionals have
+* been consumed past the path — the cursor is filling slot N) or
+* `*<N>` (variadic; fires when N-or-more positionals have been
+* consumed, used for variadic-with-choices args and path matching).
+*/
+function emitPosHelper(ident) {
+	const fn = `__${ident}_path_at_arg`;
+	const lines = [];
+	lines.push(`function ${fn}`);
+	lines.push("	set -l total_argv (count $argv)");
+	lines.push("	set -l block (string split \" \" -- $argv[$total_argv])");
+	lines.push("	set -l pos_spec $argv[(math $total_argv - 1)]");
+	lines.push("	set -l n (math $total_argv - 2)");
+	lines.push("	set -l variadic 0");
+	lines.push("	set -l target $pos_spec");
+	lines.push("	if string match -q -- '\\**' $pos_spec");
+	lines.push("		set variadic 1");
+	lines.push("		set target (string sub --start 2 -- $pos_spec)");
+	lines.push("	end");
+	lines.push("	set -l tokens (commandline -opc)");
+	lines.push("	set -l total (count $tokens)");
+	lines.push("	set -l j 2");
+	lines.push("	set -l consumed 0");
+	lines.push("	set -l end_of_options 0");
+	lines.push("	while test $j -le $total");
+	lines.push("		set -l t $tokens[$j]");
+	lines.push("		if test \"$t\" = \"--\"");
+	lines.push("			set end_of_options 1");
+	lines.push("			set j (math $j + 1)");
+	lines.push("			continue");
+	lines.push("		end");
+	lines.push("		if test $end_of_options -eq 0; and string match -q -- '-*' $t");
+	lines.push("			set j (math $j + 1)");
+	lines.push("			continue");
+	lines.push("		end");
+	lines.push("		if test $consumed -lt $n");
+	lines.push("			set -l alts (string split \" \" -- $argv[(math $consumed + 1)])");
+	lines.push("			if not contains -- $t $alts");
+	lines.push("				return 1");
+	lines.push("			end");
+	lines.push("			set consumed (math $consumed + 1)");
+	lines.push("		else");
+	lines.push("			if contains -- $t $block");
+	lines.push("				return 1");
+	lines.push("			end");
+	lines.push("			set consumed (math $consumed + 1)");
+	lines.push("		end");
+	lines.push("		set j (math $j + 1)");
+	lines.push("	end");
+	lines.push("	set -l beyond (math $consumed - $n)");
+	lines.push("	if test $variadic -eq 1");
+	lines.push("		test $beyond -ge $target");
+	lines.push("	else");
+	lines.push("		test $beyond -eq $target");
+	lines.push("	end");
+	lines.push("end");
+	return lines;
+}
+/**
+* Render a self-contained fish completion script for the given spec.
+*
+* The script is safe to drop into `~/.config/fish/completions/<bin>.fish`
+* (auto-loaded the first time the user types `<bin>`) AND safe to source
+* inline via `mycli completion fish | source` — both paths just register
+* `complete` rules.
+*
+* @param spec     Walker output.
+* @param binName  User-facing binary name; validated upstream.
+* @param version  Free-form version string for the header comment.
+*/
+function renderFish(spec, binName, version) {
+	const ident = toShellIdent(binName);
+	const lines = [];
+	lines.push(`# completion script for ${binName} v${version} — regenerate with: ${binName} completion fish`);
+	lines.push("");
+	lines.push(...emitPosHelper(ident));
+	lines.push("");
+	lines.push(`complete -c ${fishSingleQuote(binName)} -f`);
+	lines.push("");
+	const rules = [];
+	emitRules(binName, ident, [], spec, rules);
+	lines.push(...rules);
+	return `${lines.join("\n")}\n`;
+}
+//#endregion
+//#region src/completion/templates/zsh.ts
+/**
+* Pure-static zsh completion script renderer.
+*
+* Strategy: emit one `_<bin>_<path>` helper per command in the tree.
+* Helpers for non-leaf commands declare an `_arguments -C` spec with
+* `1: :->cmds` and `*::arg:->args`, then dispatch via `case "$line[1]"`
+* into the child helper — the canonical `->state` routing pattern from
+* `man zshcompsys` (and used by oclif's `ZshCompWithSpaces`).
+*
+* The first line is `#compdef <bin>` (required by zsh's autoload mechanism)
+* and the entry-point function is invoked with `"$@"` at the end so the
+* script works both when dropped into `$fpath` and when sourced directly
+* (e.g. via `eval "$(mycli completion zsh)"`).
+*
+* **Quoting model.** Every spec string is wrapped via {@link bashSingleQuote}
+* so it survives any character (description text, choice values) by going
+* through the standard `'foo'\''bar'` close-and-reopen idiom. The spec
+* **contents** are independently escaped via {@link zshArgsDescription}
+* (for `_arguments` description brackets) and {@link zshDescribeField}
+* (for the colon-separated `_describe` items).
+*/
+function flagSpecs(flag) {
+	const desc = flag.description ?? "";
+	const descPart = `[${zshArgsDescription(desc)}]`;
+	let valueSuffix = "";
+	if (flag.takesValue) {
+		const valueLabel = flag.name;
+		if (flag.choices !== void 0 && flag.choices.length > 0) valueSuffix = `:${valueLabel}:(${flag.choices.join(" ")})`;
+		else if (flag.valueCompletion === "files") valueSuffix = `:${valueLabel}:_files`;
+		else if (flag.valueCompletion === "none") valueSuffix = `:${valueLabel}: `;
+		else if (flag.type === "string") valueSuffix = `:${valueLabel}:_files`;
+		else valueSuffix = `:${valueLabel}: `;
+	}
+	const repeat = flag.multiple === true ? "*" : "";
+	const allLong = [flag.name, ...flag.aliases ?? []];
+	const allShort = flag.short !== void 0 ? [flag.short] : [];
+	const specs = [];
+	if (allShort.length === 0 && allLong.length === 1) {
+		const eq = flag.takesValue ? "=" : "";
+		const body = `${repeat}--${flag.name}${eq}${descPart}${valueSuffix}`;
+		specs.push(bashSingleQuote(body));
+	} else {
+		const mutex = [...allShort.map((s) => `-${s}`), ...allLong.map((l) => `--${l}`)].join(" ");
+		const altGroup = [...allShort.map((s) => `-${s}`), ...allLong.map((l) => `--${l}${flag.takesValue ? "=" : ""}`)].join(",");
+		const headPrefix = flag.multiple === true ? "" : `(${mutex})`;
+		const repeatBrace = flag.multiple === true ? "*" : "";
+		const fragments = [
+			bashSingleQuote(headPrefix),
+			`${repeatBrace}{${altGroup}}`,
+			bashSingleQuote(`${descPart}${valueSuffix}`)
+		];
+		specs.push(fragments.join(""));
+	}
+	if (flag.negatable) {
+		const negDesc = `[${zshArgsDescription(`disable: ${desc}`.trim())}]`;
+		const negNames = allLong.map((l) => `--no-${l}`);
+		if (negNames.length === 1) specs.push(bashSingleQuote(`${repeat}${negNames[0]}${negDesc}`));
+		else {
+			const negMutex = negNames.join(" ");
+			const negAlt = negNames.join(",");
+			const headPrefix = flag.multiple === true ? "" : `(${negMutex})`;
+			const repeatBrace = flag.multiple === true ? "*" : "";
+			specs.push([
+				bashSingleQuote(headPrefix),
+				`${repeatBrace}{${negAlt}}`,
+				bashSingleQuote(negDesc)
+			].join(""));
+		}
+	}
+	return specs;
+}
+/**
+* Render the positional-argument specs for a single command.
+*
+* Uses the same `'<idx>:NAME:<action>'` shape across leaf and non-leaf
+* helpers. Variadic args expand the `<idx>` to `*` and run the action
+* for every remaining word. Branches mirror {@link flagSpecs}:
+*   - choices                       → `(a b c)`
+*   - valueCompletion === "files"   → `_files`
+*   - valueCompletion === "none"    → ` ` (noop — url/json are not paths)
+*   - free-form string              → `_files`
+*   - number/bool                   → ` ` (noop — rare positional case)
+*/
+function renderArgSpecs(node) {
+	const specs = [];
+	node.args.forEach((arg, idx) => {
+		const idxToken = arg.variadic ? "*" : String(idx + 1);
+		const label = arg.name;
+		let action;
+		if (arg.choices !== void 0 && arg.choices.length > 0) action = `(${arg.choices.join(" ")})`;
+		else if (arg.valueCompletion === "none") action = " ";
+		else if (arg.valueCompletion === "files" || arg.type === "string") action = "_files";
+		else action = " ";
+		specs.push(bashSingleQuote(`${idxToken}:${label}:${action}`));
+	});
+	return specs;
+}
+/**
+* Build the function name for the helper that handles a given command
+* path. The root is `_<ident>`; nested children append `_<segment>` for
+* each step.
+*/
+function helperName(rootIdent, path) {
+	if (path.length === 0) return `_${rootIdent}`;
+	return `_${rootIdent}_${path.map(toShellIdent).join("_")}`;
+}
+/**
+* Render a single command's helper function.
+*
+* - Leaf commands: declare flag specs and any positional arg specs.
+* - Non-leaf commands: add the standard `->state` routing and a `case`
+*   over `$line[1]` (the first non-option positional) that dispatches to
+*   each child helper. Aliases reuse the same helper as their canonical
+*   sibling.
+*
+* Non-leaf commands with positional args are uncommon but supported:
+* the routing emits `'1: :->cmds'` so the first slot is treated as a
+* subcommand, plus any *additional* positional specs (slots 2+) for the
+* declared args. If a CLI uses arg slot 1 AND has subcommands, the
+* subcommand wins for that slot — matches the parser's behaviour where
+* a known subcommand takes precedence over a positional value.
+*/
+function renderHelper(rootIdent, path, node, out) {
+	const fnName = helperName(rootIdent, path);
+	const flagSpecLines = node.flags.flatMap(flagSpecs);
+	const argSpecLines = renderArgSpecs(node);
+	const hasChildren = node.subCommands.length > 0;
+	out.push(`${fnName}() {`);
+	if (hasChildren) {
+		out.push("	local context state state_descr line");
+		out.push("	typeset -A opt_args");
+		out.push("");
+		out.push("	_arguments -C \\");
+		for (const spec of flagSpecLines) out.push(`\t\t${spec} \\`);
+		out.push("		'1: :->cmds' \\");
+		out.push("		'*::arg:->args'");
+		out.push("");
+		out.push("	case \"$state\" in");
+		out.push("		cmds)");
+		out.push("			local -a subcmds");
+		out.push("			subcmds=(");
+		for (const sub of node.subCommands) {
+			const desc = zshDescribeField(sub.description ?? "");
+			out.push(`\t\t\t\t${bashSingleQuote(`${zshDescribeField(sub.name)}:${desc}`)}`);
+			if (sub.aliases !== void 0) for (const alias of sub.aliases) out.push(`\t\t\t\t${bashSingleQuote(`${zshDescribeField(alias)}:${desc}`)}`);
+		}
+		out.push("			)");
+		out.push("			_describe 'subcommand' subcmds");
+		out.push("			;;");
+		out.push("		args)");
+		out.push("			case \"$line[1]\" in");
+		for (const sub of node.subCommands) {
+			const childFn = helperName(rootIdent, [...path, sub.name]);
+			const alts = [sub.name, ...sub.aliases ?? []].map(bashSingleQuote).join("|");
+			out.push(`\t\t\t\t${alts})`);
+			out.push(`\t\t\t\t\t${childFn}`);
+			out.push("					;;");
+		}
+		out.push("			esac");
+		out.push("			;;");
+		out.push("	esac");
+	} else if (flagSpecLines.length === 0 && argSpecLines.length === 0) out.push("	:");
+	else {
+		out.push("	_arguments \\");
+		const allSpecs = [...flagSpecLines, ...argSpecLines];
+		allSpecs.forEach((spec, idx) => {
+			const trailing = idx === allSpecs.length - 1 ? "" : " \\";
+			out.push(`\t\t${spec}${trailing}`);
+		});
+	}
+	out.push("}");
+	out.push("");
+	for (const sub of node.subCommands) renderHelper(rootIdent, [...path, sub.name], sub, out);
+}
+/**
+* Render a self-contained zsh completion script for the given spec.
+*
+* The script is safe to drop into `$fpath` as `_<bin>` (autoloaded via the
+* `#compdef` magic line) AND safe to source inline via
+* `eval "$(mycli completion zsh)"` — the trailing `_<bin> "$@"` makes the
+* inline form actually invoke completion when the file is sourced.
+*
+* @param spec     Walker output.
+* @param binName  User-facing binary name; validated upstream via
+*                 {@link assertSafeBinName}.
+* @param version  Free-form version string for the header comment.
+*/
+function renderZsh(spec, binName, version) {
+	const ident = toShellIdent(binName);
+	const lines = [];
+	lines.push(`#compdef ${binName}`);
+	lines.push(`# completion script for ${binName} v${version} — regenerate with: ${binName} completion zsh`);
+	lines.push("");
+	const helpers = [];
+	renderHelper(ident, [], spec, helpers);
+	lines.push(...helpers);
+	lines.push(`if [ "$funcstack[1]" = "_${ident}" ]; then`);
+	lines.push(`\t_${ident} "$@"`);
+	lines.push("else");
+	lines.push(`\tcompdef _${ident} ${bashSingleQuote(binName)}`);
+	lines.push("fi");
+	return `${lines.join("\n")}\n`;
+}
+//#endregion
+//#region src/completion/walker.ts
+/**
+* Normalise an optional description: strip ANSI, then drop empty results.
+* Returning `undefined` (rather than `""`) makes templates' presence checks
+* easy and keeps generated scripts tidy.
+*/
+function normaliseDescription(value) {
+	if (value === void 0) return void 0;
+	const stripped = sanitizeFreeText(stripVTControlCharacters(value)).trim();
+	return stripped.length === 0 ? void 0 : stripped;
+}
+/**
+* Project a single documentation flag onto a `CompletionFlag`.
+*/
+function walkFlag(def) {
+	assertSafeIdentifier(def.name, "flag name");
+	const aliases = def.aliases.filter((alias) => alias.length > 0);
+	for (const alias of aliases) assertSafeIdentifier(alias, "flag alias");
+	if (def.short !== void 0 && def.short.length > 0) assertSafeIdentifier(def.short, "flag short alias");
+	const description = normaliseDescription(def.description);
+	const common = {
+		name: def.name,
+		...def.short !== void 0 && def.short.length > 0 ? { short: def.short } : {},
+		...aliases.length > 0 ? { aliases } : {},
+		...description === void 0 ? {} : { description },
+		...def.multiple ? { multiple: true } : {},
+		negatable: def.negatable
+	};
+	if (def.type === "boolean") return {
+		...common,
+		type: "boolean",
+		takesValue: false
+	};
+	if (def.type === "number") return {
+		...common,
+		type: "number",
+		takesValue: true
+	};
+	if (def.type === "path") return {
+		...common,
+		type: "string",
+		takesValue: true,
+		valueCompletion: "files"
+	};
+	if (def.type === "url" || def.type === "json") return {
+		...common,
+		type: "string",
+		takesValue: true,
+		valueCompletion: "none"
+	};
+	const choices = def.choices;
+	if (choices !== void 0 && choices.length > 0) return {
+		...common,
+		type: "string",
+		takesValue: true,
+		choices: choices.map(assertSafeChoiceValue)
+	};
+	return {
+		...common,
+		type: "string",
+		takesValue: true
+	};
+}
+/** Project a single documentation argument onto a `CompletionArg`. */
+function walkArg(def) {
+	assertSafeIdentifier(def.name, "arg name");
+	const description = normaliseDescription(def.description);
+	const common = {
+		name: def.name,
+		required: def.required,
+		variadic: def.variadic,
+		...description === void 0 ? {} : { description }
+	};
+	if (def.type === "number" || def.type === "boolean") return {
+		...common,
+		type: def.type
+	};
+	if (def.type === "path") return {
+		...common,
+		type: "string",
+		valueCompletion: "files"
+	};
+	if (def.type === "url" || def.type === "json") return {
+		...common,
+		type: "string",
+		valueCompletion: "none"
+	};
+	const choices = def.type === "string" ? def.choices : void 0;
+	if (choices !== void 0 && choices.length > 0) return {
+		...common,
+		type: "string",
+		choices: choices.map(assertSafeChoiceValue)
+	};
+	return {
+		...common,
+		type: "string"
+	};
+}
+/**
+* Build a completion command from the shared documentation model.
+*/
+function walkCommandNode(node) {
+	assertSafeIdentifier(node.name, "command name");
+	for (const alias of node.aliases) assertSafeIdentifier(alias, "command alias");
+	const flags = node.flags.map(walkFlag);
+	const args = node.args.map(walkArg);
+	const subCommands = node.children.map(walkCommandNode);
+	const result = {
+		name: node.name,
+		flags,
+		args,
+		subCommands
+	};
+	if (node.aliases.length > 0) result.aliases = node.aliases;
+	const description = normaliseDescription(node.description);
+	if (description !== void 0) result.description = description;
+	return result;
+}
+//#endregion
+//#region src/completion/index.ts
+const COMPLETION = defineExtensionId("crust:completion");
+const SUPPORTED_SHELLS = [
+	"bash",
+	"zsh",
+	"fish"
+];
+/** Filename convention for each shell's drop-in completion file. */
+function filenameForShell(shell, binName) {
+	switch (shell) {
+		case "bash": return binName;
+		case "zsh": return `_${binName}`;
+		case "fish": return `${binName}.fish`;
+	}
+}
+const SHELL_RENDERERS = {
+	bash: renderBash,
+	zsh: renderZsh,
+	fish: renderFish
+};
+function prepareRender(root, options) {
+	const binName = assertSafeBinName(options.binName ?? root.meta.name);
+	const version = options.version ?? root.meta.version;
+	if (version === void 0) throw new CrustError("DEFINITION", "The completion extension requires a version in new Crust(name, { version }) or completion({ version })");
+	return {
+		spec: walkCommandNode(buildCommandDocumentation(root)),
+		binName,
+		version: sanitizeFreeText(version)
+	};
+}
+async function writeCompletionFiles(dir, root, options) {
+	const { spec, binName, version } = prepareRender(root, options);
+	await mkdir(dir, { recursive: true });
+	const filenames = [];
+	for (const shell of SUPPORTED_SHELLS) {
+		const filename = filenameForShell(shell, binName);
+		const script = SHELL_RENDERERS[shell](spec, binName, version);
+		await writeFile(join(dir, filename), script, "utf8");
+		filenames.push(filename);
+	}
+	return filenames;
+}
+function renderCompletionScript(shell, root, options = {}) {
+	const { spec, binName, version } = prepareRender(root, options);
+	return SHELL_RENDERERS[shell](spec, binName, version);
+}
+/** Render a bash completion script from a prepared root Command Snapshot. */
+function renderBashCompletion(root, options) {
+	return renderCompletionScript("bash", root, options);
+}
+/** Render a zsh completion script from a prepared root Command Snapshot. */
+function renderZshCompletion(root, options) {
+	return renderCompletionScript("zsh", root, options);
+}
+/** Render a fish completion script from a prepared root Command Snapshot. */
+function renderFishCompletion(root, options) {
+	return renderCompletionScript("fish", root, options);
+}
+/**
+* Build an Extension that contributes a `completion <shell>` command
+* which emits a tab-completion script for bash, zsh, or fish.
+*
+* **Strategy: pure-static.** The action walks the final root snapshot, so
+* registration order is irrelevant — any commands or recursive flags added
+* by other Extensions are visible by the time we generate the script. The
+* walker projects Core's documentation model to a small completion model; per-shell
+* renderers turn that into a self-contained shell script with no runtime
+* callbacks.
+*
+* **Print vs `--output-dir`.**
+* - With no `--output-dir`: print the script for the requested `<shell>`
+*   to stdout (the install pattern is
+*   `mycli completion bash > ~/.local/share/...`).
+* - With `--output-dir <path>`: write **all** supported shells' files
+*   into the directory using the canonical per-shell filename
+*   (`<bin>` for bash, `_<bin>` for zsh, `<bin>.fish` for fish). This
+*   is the artifact-generation path used by Homebrew, Nix, and similar
+*   distribution channels — distributors run it once at packaging time
+*   and the resulting files become drop-ins.
+*
+* **Build hook.** `crust build` writes the same three files under
+* `<outDir>/completions/`; `--package` stages that directory. The binary name
+* defaults to the snapshot's `meta.name`, unless `options.binName` is set.
+*/
+const completion = defineExtension(COMPLETION, (options = {}) => {
+	const subcommandName = options.command ?? "completion";
+	return {
+		commands: [defineCommand(subcommandName, { description: "Generate shell tab-completion scripts" }, (cmd) => cmd.args({
+			name: "shell",
+			type: "string",
+			required: true,
+			description: "Shell to generate completion for",
+			choices: SUPPORTED_SHELLS
+		}).flags({
+			name: "output-dir",
+			type: "string",
+			description: "Write all supported shells' scripts into this directory instead of printing to stdout"
+		}).action(async (context) => {
+			const outputDir = context.flags["output-dir"];
+			if (outputDir === void 0) {
+				context.stdout(renderCompletionScript(context.args.shell, context.rootCommand, options));
+				return;
+			}
+			await writeCompletionFiles(resolve(outputDir), context.rootCommand, options);
+		}))],
+		build: async ({ snapshot, outDir }) => {
+			const dir = join(outDir, "completions");
+			await mkdir(outDir, { recursive: true });
+			const stagedDir = await mkdtemp(join(outDir, ".completions-"));
+			try {
+				const filenames = await writeCompletionFiles(stagedDir, snapshot, options);
+				await rm(dir, {
+					recursive: true,
+					force: true
+				});
+				await rename(stagedDir, dir);
+				return filenames.map((filename) => join("completions", filename));
+			} finally {
+				await rm(stagedDir, {
+					recursive: true,
+					force: true
+				});
+			}
+		}
+	};
+});
+//#endregion
+//#region src/help.ts
+const FLAG_COLUMN_WIDTH = 28;
+const ARG_COLUMN_WIDTH = 18;
+const COMMAND_COLUMN_WIDTH = 10;
+const HELP = defineExtensionId("crust:help");
+function formatArgToken(arg) {
+	return arg.required ? yellow(arg.token) : dim(yellow(arg.token));
+}
+function formatUsageSegment(segment) {
+	switch (segment.kind) {
+		case "path":
+		case "custom": return green(segment.text);
+		case "command":
+		case "options": return cyan(segment.text);
+		case "arg": return segment.required ? yellow(segment.text) : dim(yellow(segment.text));
+	}
+}
+function formatFlagsSection(flags) {
+	if (flags.length === 0) return [];
+	const lines = [bold(cyan("Options:"))];
+	for (const flag of flags) {
+		const rendered = `${padEnd(cyan(flag.spellings.join(", ")), FLAG_COLUMN_WIDTH, " ")} `;
+		lines.push(`  ${rendered}${formatDescription(flag.description, flag.default, flag.choices, dim)}`.trimEnd());
+	}
+	return lines;
+}
+function formatArgsSection(command) {
+	if (command.args.length === 0) return [];
+	const lines = [bold(cyan("Arguments:"))];
+	for (const arg of command.args) {
+		const rendered = `${padEnd(formatArgToken(arg), ARG_COLUMN_WIDTH, " ")} `;
+		lines.push(`  ${rendered}${formatDescription(arg.description, arg.default, arg.choices, dim)}`.trimEnd());
+	}
+	return lines;
+}
+function formatCommandLabel(command) {
+	const name = green(command.name);
+	return command.aliases.length === 0 ? name : `${name} (${command.aliases.join(", ")})`;
+}
+function formatCommandsSection(command) {
+	if (command.children.length === 0) return [];
+	const lines = [bold(cyan("Commands:"))];
+	for (const child of command.children) {
+		const rendered = `${padEnd(formatCommandLabel(child), COMMAND_COLUMN_WIDTH, " ")} `;
+		lines.push(`  ${rendered}${child.description ?? ""}`.trimEnd());
+	}
+	return lines;
+}
+function renderHelp(command, path) {
+	const model = buildCommandDocumentation(command, path);
+	const heading = model.path.join(" ");
+	const lines = [
+		model.description ? `${bold(heading)} - ${dim(model.description)}` : bold(heading),
+		"",
+		bold(cyan("Usage:")),
+		`  ${model.usageSegments.map(formatUsageSegment).join(" ")}`
+	];
+	for (const section of [
+		formatCommandsSection(model),
+		formatArgsSection(model),
+		formatFlagsSection(model.flags)
+	]) if (section.length > 0) lines.push("", ...section);
+	for (const section of sectionsFor(model.sections, HELP)) lines.push("", bold(cyan(`${section.title}:`)), ...section.body.split("\n").map((l) => `  ${l}`));
+	return lines.join("\n");
+}
+const helpFlags = [{
+	name: "help",
+	type: "boolean",
+	short: "h",
+	noNegate: true,
+	description: "Show help"
+}];
+const help = defineExtension(HELP, () => ({
+	flags: helpFlags,
+	hooks: { preRun(context) {
+		if (context.flags.help !== true && context.command.hasAction) return;
+		context.stdout(renderHelp(context.command, context.commandPath));
+		return context.finish();
+	} }
+}));
+//#endregion
+//#region src/did-you-mean.ts
+const DID_YOU_MEAN = defineExtensionId("crust:did-you-mean");
+function levenshtein(a, b) {
+	const aLen = a.length;
+	const bLen = b.length;
+	if (aLen === 0) return bLen;
+	if (bLen === 0) return aLen;
+	const row = Uint32Array.from({ length: bLen + 1 }, (_, i) => i);
+	for (let i = 1; i <= aLen; i++) {
+		let prev = i;
+		for (let j = 1; j <= bLen; j++) {
+			const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+			const val = Math.min(row[j] + 1, prev + 1, row[j - 1] + cost);
+			row[j - 1] = prev;
+			prev = val;
+		}
+		row[bLen] = prev;
+	}
+	return row[bLen];
+}
+/**
+* Find canonical-name suggestions for `input` by matching against every
+* sibling's canonical name **and** any aliases declared on each sibling.
+*
+* Matched aliases are mapped back to their canonical, so suggestions only
+* ever report canonical names — mirroring `router.ts`, which records
+* canonicals on `commandPath`. When both a canonical and its alias score
+* within threshold, the better score wins for that command (a short alias
+* cannot lose to a more-distant canonical, and vice-versa).
+*
+* Subcommands marked `meta.hidden: true` are excluded from the candidate
+* set so internal commands (e.g. `__complete`) cannot leak into
+* user-facing typo suggestions. They remain invocable by direct name —
+* routing does not consult `meta.hidden`.
+*
+* The matching is limited to: (a) `candidate.startsWith(input)` (a
+* forward-completion hint, useful when the user typed a prefix) and
+* (b) Levenshtein distance ≤ 3. The reverse `input.startsWith(candidate)`
+* shortcut is intentionally omitted: with aliases in the candidate set,
+* any 1–2 char alias would falsely match every typo as distance 0.
+*/
+function findSuggestions(input, subCommands) {
+	const best = /* @__PURE__ */ new Map();
+	const score = (text) => {
+		if (text.startsWith(input)) return 0;
+		const d = levenshtein(input, text);
+		return d <= 3 ? d : null;
+	};
+	const record = (canonical, distance) => {
+		const prev = best.get(canonical);
+		if (prev === void 0 || distance < prev) best.set(canonical, distance);
+	};
+	for (const [name, node] of Object.entries(subCommands)) {
+		if (!isListed(node)) continue;
+		const d = score(name);
+		if (d !== null) record(name, d);
+		for (const alias of node.meta.aliases ?? []) {
+			const da = score(alias);
+			if (da !== null) record(name, da);
+		}
+	}
+	return [...best.entries()].sort(([aName, aDist], [bName, bDist]) => aDist !== bDist ? aDist - bDist : aName.localeCompare(bName)).map(([name]) => name);
+}
+const didYouMean = defineExtension(DID_YOU_MEAN, (options = {}) => {
+	const mode = options.mode ?? "error";
+	return { hooks: { onError(error, context) {
+		if (!(error instanceof CrustError) || !error.is("COMMAND_NOT_FOUND")) return;
+		const details = error.details;
+		const suggestions = findSuggestions(details.input, details.parentCommand.subCommands);
+		let message = `Unknown command "${details.input}".`;
+		if (suggestions.length > 0) message += ` Did you mean "${suggestions[0]}"?`;
+		if (mode === "help") {
+			context.stdout(message);
+			context.stdout("");
+			context.stdout(renderHelp(details.parentCommand, details.commandPath));
+			return true;
+		}
+		if (details.available.length > 0) message += `\n\nAvailable commands: ${details.available.join(", ")}`;
+		context.stderr(message);
+		return true;
+	} } };
+});
+//#endregion
+//#region src/no-color.ts
+const NO_COLOR = defineExtensionId("crust:no-color");
+let activeRuns = 0;
+let baseForceColor;
+let baseNoColor;
+const colorRuns = /* @__PURE__ */ new WeakSet();
+const colorFlags = [{
+	name: "color",
+	type: "boolean",
+	description: "Enable colored output"
+}];
+/**
+* Adds a recursive `--color` / `--no-color` flag pair that scopes the
+* standard color environment variables around command execution:
+*
+* - `--color` sets `FORCE_COLOR=3` (and clears `NO_COLOR`, so strict
+*   no-color.org-only child processes also comply) — forces all ANSI on
+*   (truecolor), overriding non-TTY detection. Any color library that
+*   honors `FORCE_COLOR` (including `@crustjs/style` and chalk) obeys it,
+*   and child processes inherit it.
+* - `--no-color` sets `NO_COLOR=1` (and clears `FORCE_COLOR` so the flag
+*   wins over ambient env) — suppresses colors while non-color modifiers
+*   and hyperlinks keep following TTY detection, per
+*   [no-color.org](https://no-color.org/).
+*
+* Previous values are restored after the command finishes. When overlapping
+* programmatic runs in one process use opposite flags, the later run wins
+* mid-flight (the env is process-global); the ambient values are restored
+* once all runs finish.
+*/
+const noColor = defineExtension(NO_COLOR, () => ({
+	flags: colorFlags,
+	hooks: {
+		preRun(context) {
+			const flagValue = context.flags.color;
+			if (flagValue !== true && flagValue !== false) return;
+			if (activeRuns === 0) {
+				baseForceColor = process.env.FORCE_COLOR;
+				baseNoColor = process.env.NO_COLOR;
+			}
+			activeRuns++;
+			colorRuns.add(context);
+			if (flagValue) {
+				delete process.env.NO_COLOR;
+				process.env.FORCE_COLOR = "3";
+			} else {
+				delete process.env.FORCE_COLOR;
+				process.env.NO_COLOR = "1";
+			}
+		},
+		postRun(context) {
+			if (!colorRuns.has(context)) return;
+			colorRuns.delete(context);
+			activeRuns--;
+			if (activeRuns === 0) {
+				if (baseForceColor === void 0) delete process.env.FORCE_COLOR;
+				else process.env.FORCE_COLOR = baseForceColor;
+				if (baseNoColor === void 0) delete process.env.NO_COLOR;
+				else process.env.NO_COLOR = baseNoColor;
+			}
+		}
+	}
+}));
+//#endregion
+//#region ../utils/src/process.ts
+/** Parse the package manager from npm's user-agent environment value. */
+function packageManagerFromUserAgent(userAgent) {
+	if (userAgent?.startsWith("bun")) return "bun";
+	if (userAgent?.startsWith("pnpm")) return "pnpm";
+	if (userAgent?.startsWith("yarn")) return "yarn";
+	if (userAgent?.startsWith("npm")) return "npm";
+	return null;
+}
+//#endregion
+//#region src/update-notifier.ts
+const UPDATE_NOTIFIER = defineExtensionId("crust:update-notifier");
+/** Default check interval: 24 hours. */
+const DEFAULT_INTERVAL_MS = 864e5;
+/** Default network timeout: 5 seconds. */
+const DEFAULT_TIMEOUT_MS = 5e3;
+/** Default npm registry URL. */
+const DEFAULT_REGISTRY_URL = "https://registry.npmjs.org";
+function compareSemver(left, right) {
+	const parse = (version) => {
+		const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(version);
+		if (!match) throw new TypeError(`Invalid semantic version: ${version}`);
+		return {
+			core: match.slice(1, 4).map(Number),
+			prerelease: match[4]?.split(".") ?? []
+		};
+	};
+	const a = parse(left);
+	const b = parse(right);
+	for (let index = 0; index < 3; index++) if (a.core[index] !== b.core[index]) return a.core[index] < b.core[index] ? -1 : 1;
+	if (a.prerelease.length === 0 || b.prerelease.length === 0) return a.prerelease.length === b.prerelease.length ? 0 : a.prerelease.length === 0 ? 1 : -1;
+	for (let index = 0; index < Math.max(a.prerelease.length, b.prerelease.length); index++) {
+		const x = a.prerelease[index];
+		const y = b.prerelease[index];
+		if (x === void 0 || y === void 0) return x === void 0 ? -1 : 1;
+		if (x === y) continue;
+		const xNumeric = /^\d+$/.test(x);
+		const yNumeric = /^\d+$/.test(y);
+		if (xNumeric && yNumeric) return Number(x) < Number(y) ? -1 : 1;
+		if (xNumeric !== yNumeric) return xNumeric ? -1 : 1;
+		return x < y ? -1 : 1;
+	}
+	return 0;
+}
+/**
+* Returns whether `latest` is newer, or false when either version is invalid.
+*
+* @internal
+*/
+function isNewerVersion(current, latest) {
+	try {
+		return compareSemver(latest, current) === 1;
+	} catch {
+		return false;
+	}
+}
+function hasLatestDistTag(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value) || !("dist-tags" in value)) return false;
+	const tags = value["dist-tags"];
+	return typeof tags === "object" && tags !== null && !Array.isArray(tags) && "latest" in tags && typeof tags.latest === "string" && tags.latest.length > 0;
+}
+/**
+* Fetch the `dist-tags.latest` version string for a package from an npm
+* registry.
+*
+* Uses the platform timeout signal so network stalls cannot hang the CLI process.
+*
+* Returns `null` on any failure (network error, timeout, non-OK status,
+* missing/malformed response body).
+*
+* @internal
+*/
+async function fetchLatestVersion(packageName, registryUrl, timeoutMs) {
+	try {
+		const url = `${registryUrl.replace(/\/+$/, "")}/${encodeURIComponent(packageName)}`;
+		const response = await fetch(url, {
+			signal: AbortSignal.timeout(timeoutMs),
+			headers: { Accept: "application/vnd.npm.install-v1+json" }
+		});
+		if (!response.ok) return null;
+		const data = await response.json();
+		if (!hasLatestDistTag(data)) return null;
+		return data["dist-tags"].latest;
+	} catch {
+		return null;
+	}
+}
+function normalizeNotifierState(input) {
+	if (!input) return { lastCheckedAt: 0 };
+	return {
+		lastCheckedAt: Number.isFinite(input.lastCheckedAt) ? input.lastCheckedAt : 0,
+		latestVersion: input.latestVersion?.length ? input.latestVersion : void 0,
+		lastNotifiedVersion: input.lastNotifiedVersion?.length ? input.lastNotifiedVersion : void 0
+	};
+}
+const NO_CACHE_ADAPTER = {
+	read: async () => null,
+	write: async () => {}
+};
+/** @internal */
+async function createStoreCacheAdapter(packageName, registryUrl) {
+	const { createStore, stateDir } = await import("@crustjs/store");
+	const store = createStore({
+		dirPath: stateDir(encodeURIComponent(packageName)),
+		name: "update-notifier",
+		fields: {
+			lastCheckedAt: {
+				type: "number",
+				default: 0
+			},
+			latestVersion: { type: "string" },
+			lastNotifiedVersion: { type: "string" },
+			registryUrl: { type: "string" }
+		}
+	});
+	return {
+		read: async () => {
+			const state = await store.read();
+			if (state.registryUrl !== registryUrl) return null;
+			return {
+				lastCheckedAt: state.lastCheckedAt,
+				latestVersion: state.latestVersion,
+				lastNotifiedVersion: state.lastNotifiedVersion
+			};
+		},
+		write: async (state) => {
+			await store.write({
+				lastCheckedAt: state.lastCheckedAt,
+				latestVersion: state.latestVersion,
+				lastNotifiedVersion: state.lastNotifiedVersion,
+				registryUrl
+			});
+		}
+	};
+}
+function detectPackageManager() {
+	const detectedFromUserAgent = packageManagerFromUserAgent(process.env.npm_config_user_agent);
+	if (detectedFromUserAgent) return detectedFromUserAgent;
+	const detectedFromExecPath = detectPackageManagerFromExecPath(process.env.npm_execpath);
+	if (detectedFromExecPath) return detectedFromExecPath;
+	const detectedFromRuntime = detectPackageManagerFromExecPath(process.execPath);
+	if (detectedFromRuntime) return detectedFromRuntime;
+	return "npm";
+}
+function detectPackageManagerFromExecPath(execPath) {
+	if (!execPath) return null;
+	const executable = basename(execPath).toLowerCase();
+	if (executable === "bun" || executable.startsWith("bun-")) return "bun";
+	if (executable === "pnpm" || executable.startsWith("pnpm-")) return "pnpm";
+	if (executable === "yarn" || executable.startsWith("yarn-")) return "yarn";
+	if (executable === "npm" || executable.startsWith("npm-")) return "npm";
+	return null;
+}
+function defaultUpdateCommand(packageName, packageManager, scope) {
+	if (packageManager === "pnpm") return scope === "global" ? `pnpm add -g ${packageName}@latest` : `pnpm add ${packageName}@latest`;
+	if (packageManager === "yarn") return scope === "global" ? `npm install -g ${packageName}@latest` : `yarn add ${packageName}@latest`;
+	if (packageManager === "bun") return scope === "global" ? `bun add -g ${packageName}@latest` : `bun add ${packageName}@latest`;
+	return scope === "global" ? `npm install -g ${packageName}@latest` : `npm install ${packageName}@latest`;
+}
+function resolveUpdateCommand(packageName, updateCommand) {
+	if (updateCommand === void 0 || typeof updateCommand === "string") return updateCommand;
+	const packageManager = detectPackageManager();
+	if (typeof updateCommand === "function") return updateCommand({
+		packageName,
+		packageManager
+	});
+	return defaultUpdateCommand(packageName, packageManager, updateCommand.scope);
+}
+/**
+* Creates an update notifier extension that checks the npm registry after a
+* successful command action and displays a notice when a newer version is available.
+*
+* **Behavior:**
+* - By default, checks are cached for 24 hours in the package's state directory.
+* - `cache: false` disables cross-run persistence.
+* - A custom cache adapter can override the built-in persistence.
+* - The notice is command-less unless `updateCommand` is configured.
+* - The postRun hook awaits the network check and cache reads and writes,
+*   delaying invocation completion after the action.
+* - `timeoutMs` bounds only the network request, defaulting to 5 seconds.
+* - Network, cache, and parsing errors are silently swallowed. A missing
+*   current version throws a DEFINITION error before that recovery block.
+* - Update notices are intentionally written to the invocation's stderr callback.
+* - Duplicate notifications for the same version are suppressed.
+*
+* @param options - Extension configuration. `packageName` is required.
+* @returns An Extension registered with `.extend()`.
+*
+* @example
+* ```ts
+* import { Crust } from "@crustjs/core";
+* import { updateNotifier } from "@crustjs/extensions";
+*
+* const app = new Crust("my-cli", { description: "My awesome CLI", version: "1.2.3" })
+*   .extend(updateNotifier({ packageName: "my-cli" }))
+*   .action(() => {
+*     console.log("Hello!");
+*   });
+*
+* await app.execute();
+* ```
+*/
+const updateNotifier = defineExtension(UPDATE_NOTIFIER, (options) => {
+	const { currentVersion, packageName, timeoutMs = DEFAULT_TIMEOUT_MS, registryUrl = DEFAULT_REGISTRY_URL, updateCommand, updateDocsUrl, cache } = options;
+	const intervalMs = (cache === false ? void 0 : cache?.intervalMs) ?? DEFAULT_INTERVAL_MS;
+	return { hooks: { async postRun(context, outcome) {
+		if (outcome.status !== "completed") return;
+		const resolvedCurrentVersion = currentVersion ?? context.rootCommand.meta.version;
+		if (resolvedCurrentVersion === void 0) throw new CrustError("DEFINITION", "The update notifier extension requires a version in new Crust(name, { version }) or currentVersion");
+		try {
+			let cacheAdapter = NO_CACHE_ADAPTER;
+			if (cache !== false) {
+				if (cache?.adapter) cacheAdapter = cache.adapter;
+				else cacheAdapter = await createStoreCacheAdapter(packageName, registryUrl);
+			}
+			const state = normalizeNotifierState(await cacheAdapter.read().catch(() => null));
+			const resolvedUpdateCommand = resolveUpdateCommand(packageName, updateCommand);
+			const now = Date.now();
+			const elapsed = now - state.lastCheckedAt;
+			if (cache !== false && elapsed >= 0 && elapsed < intervalMs) {
+				if (state.latestVersion && isNewerVersion(resolvedCurrentVersion, state.latestVersion) && state.lastNotifiedVersion !== state.latestVersion) {
+					emitUpdateNotice(resolvedCurrentVersion, state.latestVersion, resolvedUpdateCommand, updateDocsUrl, context.stderr);
+					await cacheAdapter.write({
+						...state,
+						lastNotifiedVersion: state.latestVersion
+					});
+				}
+				return;
+			}
+			const latestVersion = await fetchLatestVersion(packageName, registryUrl, timeoutMs);
+			if (latestVersion === null) {
+				await cacheAdapter.write({
+					...state,
+					lastCheckedAt: now
+				});
+				return;
+			}
+			const nextState = {
+				...state,
+				lastCheckedAt: now,
+				latestVersion
+			};
+			if (isNewerVersion(resolvedCurrentVersion, latestVersion) && state.lastNotifiedVersion !== latestVersion) {
+				emitUpdateNotice(resolvedCurrentVersion, latestVersion, resolvedUpdateCommand, updateDocsUrl, context.stderr);
+				nextState.lastNotifiedVersion = latestVersion;
+			}
+			await cacheAdapter.write(nextState);
+		} catch {}
+	} } };
+});
+/**
+* Emits a styled, boxed update notice to stderr.
+*
+* Uses stderr so the notice does not interfere with piped stdout.
+*
+* The notice uses rounded-corner box-drawing characters and ANSI colors:
+* - Yellow box border
+* - Dim current version, bold green latest version
+* - Optional cyan update command and documentation URL
+*
+* @internal
+*/
+function emitUpdateNotice(currentVersion, latestVersion, updateCommand, updateDocsUrl, stderr) {
+	const PADDING = 3;
+	const contentLines = [
+		`Update available  ${dim(currentVersion)} ${yellow("→")} ${bold(green(latestVersion))}`,
+		...updateCommand !== void 0 ? [`Run ${cyan(updateCommand)}`] : [],
+		...updateDocsUrl !== void 0 ? [`See ${cyan(updateDocsUrl)} to update`] : []
+	];
+	const contentWidth = Math.max(...contentLines.map((line) => stringWidth(line)));
+	const innerWidth = contentWidth + 6;
+	const border = "─".repeat(innerWidth);
+	const pad = " ".repeat(PADDING);
+	const emptyLine = `${yellow("│")}${" ".repeat(innerWidth)}${yellow("│")}`;
+	stderr([
+		"",
+		`${yellow("╭")}${yellow(border)}${yellow("╮")}`,
+		emptyLine,
+		...contentLines.map((line) => `${yellow("│")}${pad}${padEnd(line, contentWidth)}${pad}${yellow("│")}`),
+		emptyLine,
+		`${yellow("╰")}${yellow(border)}${yellow("╯")}`,
+		""
+	].join("\n"));
+}
+//#endregion
+//#region src/version.ts
+const VERSION = defineExtensionId("crust:version");
+const versionFlags = [{
+	name: "version",
+	type: "boolean",
+	short: "v",
+	noNegate: true,
+	description: "Show version number",
+	recursive: false
+}];
+function makeVersion(resolve, options) {
+	const { format } = options;
+	return defineExtension()(VERSION, {
+		flags: versionFlags,
+		hooks: { preRun(context) {
+			if (context.commandPath.length !== 1 || context.flags.version !== true) return;
+			const resolvedVersion = resolve(context);
+			const line = format === "plain" ? resolvedVersion : format ? format(resolvedVersion, context) : `${context.rootCommand.meta.name} v${resolvedVersion}`;
+			context.stdout(line);
+			return context.finish();
+		} }
+	});
+}
+function createVersion(value, options = {}) {
+	if (value === void 0) return makeVersion((context) => context.rootCommand.meta.version, options);
+	return makeVersion(() => {
+		return typeof value === "function" ? value() : value;
+	}, options);
+}
+const version = Object.assign(createVersion, { id: VERSION });
+//#endregion
+export { completion, didYouMean, help, noColor, renderBashCompletion, renderFishCompletion, renderHelp, renderZshCompletion, updateNotifier, version };