@crustjs/core 0.0.18 → 0.2.0

package/dist/invocation-DcA5FqF7.js

@@ -0,0 +1,1875 @@
+import { writeFile } from "node:fs/promises";
+import { dirname, join, posix, resolve, win32 } from "node:path";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { Writable } from "node:stream";
+import { parseArgs } from "node:util";
+import { isPromise } from "node:util/types";
+import { homedir } from "node:os";
+//#region src/errors.ts
+/**
+* A typed error for runtime recipe, Extension, Context, documentation, argv, and validation failures.
+*
+* Every `CrustError` carries a {@link CrustErrorCode} that identifies the specific
+* failure, enabling programmatic error handling without fragile message parsing.
+*
+* @example
+* ```ts
+* import { CrustError } from "@crustjs/core";
+*
+* const outcome = await app.run(["deploy"], { args: { target: "prod" } });
+* if (outcome.status === "failed") {
+*   const err = outcome.error;
+*   if (err instanceof CrustError) {
+*     console.error(`[${err.code}] ${err.message}`);
+*   }
+* }
+* ```
+*/
+var CrustError = class extends Error {
+	/** Machine-readable error code for programmatic handling */
+	code;
+	/** Structured payload for programmatic handling */
+	details;
+	/** Optional wrapped original error/value */
+	cause;
+	constructor(code, message, ...details) {
+		super(message);
+		this.name = "CrustError";
+		this.code = code;
+		this.details = details[0];
+	}
+	is(code) {
+		return Object.is(this.code, code);
+	}
+	withCause(cause) {
+		this.cause = cause;
+		return this;
+	}
+	toJSON() {
+		return {
+			code: this.code,
+			message: this.message,
+			details: this.details
+		};
+	}
+};
+//#endregion
+//#region src/parsing/spellings.ts
+function assertUsableSpelling(spelling, kind) {
+	if (spelling === "") throw new CrustError("DEFINITION", `Flag ${kind} spellings must be non-empty`, {
+		subject: "flag",
+		name: spelling,
+		reason: "empty-spelling"
+	});
+	if (kind !== "short" && spelling.startsWith("no-")) throw new CrustError("DEFINITION", `Flag ${kind} "${spelling}" must not start with "no-"; the prefix is reserved for boolean negation`, {
+		subject: "flag",
+		name: spelling,
+		reason: "reserved-no-prefix"
+	});
+	if (spelling === "__proto__") throw new CrustError("DEFINITION", `Flag ${kind} "__proto__" is a reserved spelling`, {
+		subject: "flag",
+		name: spelling,
+		reason: "reserved-spelling"
+	});
+}
+/** All canonical, short, and alias spellings carried by a flag definition. */
+function flagSpellings(name, def) {
+	return [
+		name,
+		...def.short === void 0 ? [] : [def.short],
+		...def.aliases ?? []
+	];
+}
+/** Whether a flag accepts generated `--no-` spellings. */
+function isFlagNegatable(def) {
+	return def.type === "boolean" && def.noNegate !== true;
+}
+/** Convert named authoring definitions to the runtime flag record. */
+function toFlagsRecord(definitions, initial = {}) {
+	const flags = { ...initial };
+	const seen = new Set(Object.entries(initial).flatMap(([name, def]) => flagSpellings(name, def)));
+	for (const definition of definitions) {
+		const { name, ...flag } = definition;
+		const normalized = normalizeFlag(name, flag);
+		for (const spelling of flagSpellings(name, normalized)) {
+			if (seen.has(spelling)) throw new CrustError("DEFINITION", `Flag "${name}" collides with an existing flag`, {
+				subject: "flag",
+				name,
+				reason: "flag-collision"
+			});
+			seen.add(spelling);
+		}
+		flags[name] = normalized;
+	}
+	return flags;
+}
+/** Copy only definition-owned collections, not JSON/URL/schema payloads. */
+function ownDefinition(def) {
+	if (def.choices && def.default !== void 0) {
+		const values = "multiple" in def && def.multiple ? def.default : [def.default];
+		for (const value of values) if (!def.choices.includes(value)) throw new CrustError("DEFINITION", "default must be one of choices");
+	}
+	return Object.freeze({
+		...def,
+		..."aliases" in def && def.aliases ? { aliases: Object.freeze([...def.aliases]) } : {},
+		...def.choices ? { choices: Object.freeze([...def.choices]) } : {},
+		..."multiple" in def && def.multiple && Array.isArray(def.default) ? { default: Object.freeze([...def.default]) } : {}
+	});
+}
+function normalizeFlag(name, def) {
+	assertUsableSpelling(name, "canonical");
+	if (def.short !== void 0) assertUsableSpelling(def.short, "short");
+	for (const alias of def.aliases ?? []) assertUsableSpelling(alias, "alias");
+	const spellings = flagSpellings(name, def);
+	if (new Set(spellings).size !== spellings.length) throw new CrustError("DEFINITION", `Flag "${name}" repeats one of its own spellings`, {
+		subject: "flag",
+		name,
+		reason: "flag-collision"
+	});
+	if (def.short !== void 0 && def.short.length !== 1) throw new CrustError("DEFINITION", "Short flags must be one character");
+	return ownDefinition(def);
+}
+function normalizeArg(def) {
+	if (def.name === "") throw new CrustError("DEFINITION", "Argument names must be non-empty", {
+		subject: "argument",
+		name: def.name,
+		reason: "empty-name"
+	});
+	return ownDefinition(def);
+}
+//#endregion
+//#region src/api/context.ts
+const defining = Symbol("crust.defining");
+/** @internal */
+function definingOf(value) {
+	return value[defining];
+}
+/** @internal */
+function seal(value) {
+	return Object.freeze(Object.assign(value, { [defining]: value }));
+}
+/** Check only declared availability; setup, callback values, and cycles belong to invocation. */
+function validateContextAvailability(contexts, sources) {
+	const names = new Set(contexts.map((instance) => instance.name));
+	const visited = /* @__PURE__ */ new Set();
+	const visit = (source) => {
+		if (visited.has(source)) return;
+		visited.add(source);
+		const name = "contextName" in source ? source.contextName : source.name;
+		if (!names.has(name)) throw new CrustError("DEFINITION", `No provider for Context "${name}"`, {
+			subject: "context",
+			name,
+			reason: "missing-context"
+		});
+		for (const dependency of source.uses) visit(dependency);
+	};
+	for (const source of sources) visit(source);
+}
+function isContextSetup(value) {
+	return typeof value === "function";
+}
+function defineContext(name, configOrSetup, maybeSetup) {
+	const hasConfig = !isContextSetup(configOrSetup);
+	const config = hasConfig ? configOrSetup : {};
+	const setup = hasConfig ? maybeSetup : configOrSetup;
+	const ownedFlags = Object.freeze(toFlagsRecord(config.flags ?? []));
+	const uses = Object.freeze((config.uses ?? []).map(definingOf));
+	const instance = (instanceUses, run) => {
+		return seal({
+			name,
+			ownedFlags,
+			uses: instanceUses,
+			setup: run
+		});
+	};
+	const factory = (options) => instance(uses, (input) => {
+		return setup({
+			options,
+			...input
+		});
+	});
+	factory.contextName = name;
+	factory.uses = uses;
+	factory.of = (value) => instance(Object.freeze([]), () => value);
+	return seal(factory);
+}
+function isDisposeCallback(value) {
+	return typeof value === "function";
+}
+/**
+* Minimal `AsyncDisposableStack` stand-in for runtimes without the global
+* (Node 22): LIFO disposal of used resources and deferred callbacks,
+* preferring `Symbol.asyncDispose` over `Symbol.dispose`.
+*
+* ponytail: multiple disposal errors aggregate as `AggregateError` instead of
+* the native `SuppressedError` chain; delete this class when Node 22 leaves
+* the support floor.
+*
+* @internal Exported for unit testing and invocation wiring.
+*/
+var FallbackAsyncDisposableStack = class {
+	#entries = [];
+	#disposed = false;
+	#assertPending() {
+		if (this.#disposed) throw new ReferenceError("AsyncDisposableStack is already disposed");
+	}
+	use(value) {
+		this.#assertPending();
+		const dispose = hasAsyncDispose(value) ? value[Symbol.asyncDispose] : value[Symbol.dispose];
+		this.#entries.push(() => dispose.call(value));
+		return value;
+	}
+	defer(onDisposeAsync) {
+		this.#assertPending();
+		if (!isDisposeCallback(onDisposeAsync)) throw new TypeError("defer callback is not callable");
+		this.#entries.push(onDisposeAsync);
+	}
+	async [Symbol.asyncDispose]() {
+		this.#disposed = true;
+		const errors = [];
+		for (let index = this.#entries.length - 1; index >= 0; index--) try {
+			await this.#entries[index]();
+		} catch (error) {
+			errors.push(error);
+		}
+		if (errors.length === 1) throw errors[0];
+		if (errors.length > 1) throw new AggregateError(errors, "Disposal failed");
+	}
+};
+const DisposalStack = globalThis.AsyncDisposableStack ?? FallbackAsyncDisposableStack;
+function hasAsyncDispose(value) {
+	return typeof value[Symbol.asyncDispose] === "function";
+}
+function isDisposableValue(value) {
+	if (value === null || typeof value !== "object" && typeof value !== "function") return false;
+	const candidate = value;
+	return typeof candidate[Symbol.asyncDispose] === "function" || typeof candidate[Symbol.dispose] === "function";
+}
+function registerDisposable(value, disposal, registered) {
+	if (!isDisposableValue(value) || registered.has(value)) return;
+	registered.add(value);
+	disposal.use(value);
+}
+/** Internal lazy invocation container. Public consumers receive scoped Context bags. */
+function createContextResolver(contexts, io, disposal) {
+	const byName = new Map(contexts.map((context) => [context.name, context]));
+	const entries = /* @__PURE__ */ new Map();
+	const registered = /* @__PURE__ */ new WeakSet();
+	let validatedFlags;
+	let disposed = false;
+	disposal.defer(() => {
+		disposed = true;
+	});
+	const pathTo = (from, target, visited = /* @__PURE__ */ new Set()) => {
+		if (from.name === target) return [from.name];
+		if (visited.has(from.name)) return void 0;
+		visited.add(from.name);
+		for (const name of from.waitingOn) {
+			const next = entries.get(name);
+			if (!next) continue;
+			const path = pathTo(next, target, visited);
+			if (path) return [from.name, ...path];
+		}
+	};
+	const isFlagValidationError = (error) => {
+		try {
+			const seen = /* @__PURE__ */ new Set();
+			for (let e = error; e != null && !seen.has(e); e = e.cause) {
+				seen.add(e);
+				if (e instanceof CrustError && e.code === "DEFINITION" && e.details?.reason === "flags-before-validation") return true;
+			}
+			return false;
+		} catch {
+			return false;
+		}
+	};
+	function handledRejection(reason) {
+		const rejection = Promise.reject(reason);
+		rejection.catch(() => {});
+		return rejection;
+	}
+	const makePull = (origin) => (name) => {
+		const originSuffix = origin ? ` (pulled while constructing Context "${origin.name}")` : "";
+		if (disposed) return handledRejection(new CrustError("DEFINITION", `Context "${name}" cannot be pulled from onError because invocation Contexts have already been disposed.`, {
+			subject: "context",
+			name,
+			reason: "context-after-disposal"
+		}));
+		const context = byName.get(name);
+		if (!context) return handledRejection(new CrustError("DEFINITION", `No provider for Context "${name}". Add .provide(${name}(...)) to the app or an ancestor command.${originSuffix}`, {
+			subject: "context",
+			name,
+			reason: "missing-context"
+		}));
+		if (validatedFlags === void 0 && Object.keys(context.ownedFlags).length > 0) return handledRejection(new CrustError("DEFINITION", `Context "${name}" owns flags and cannot be pulled before flag validation${originSuffix}. Pull it from an action or a postRun hook after a validated invocation.`, {
+			subject: "context",
+			name,
+			reason: "flags-before-validation"
+		}));
+		let entry = entries.get(name);
+		if (!entry) {
+			const deferred = Promise.withResolvers();
+			deferred.promise.catch(() => {});
+			entry = {
+				name,
+				promise: deferred.promise,
+				resolve: deferred.resolve,
+				reject: deferred.reject,
+				waitingOn: /* @__PURE__ */ new Set(),
+				settled: false
+			};
+			entries.set(name, entry);
+			const current = entry;
+			(async () => {
+				try {
+					const ownedFlags = Object.fromEntries(Object.keys(context.ownedFlags).map((flag) => [flag, validatedFlags?.[flag]]));
+					const value = await context.setup({
+						...io,
+						flags: ownedFlags,
+						ctx: makeBag(context.uses, current),
+						defer(cleanup) {
+							if (current.settled) throw new CrustError("DEFINITION", `Context "${name}" cannot register cleanup after its setup has finished.`, {
+								subject: "context",
+								name,
+								reason: "context-defer-after-setup"
+							});
+							disposal.defer(cleanup);
+						}
+					});
+					registerDisposable(value, disposal, registered);
+					current.resolve(value);
+				} catch (error) {
+					if (isFlagValidationError(error)) entries.delete(name);
+					current.reject(error);
+				} finally {
+					current.settled = true;
+				}
+			})();
+		}
+		if (origin && !entry.settled) {
+			const path = pathTo(entry, origin.name);
+			if (path) return handledRejection(new CrustError("DEFINITION", `Context dependency cycle: ${[origin.name, ...path].map((part) => `"${part}"`).join(" -> ")}`, {
+				subject: "context",
+				name: origin.name,
+				reason: "context-cycle"
+			}));
+			origin.waitingOn.add(name);
+			return entry.promise.finally(() => origin.waitingOn.delete(name));
+		}
+		return entry.promise;
+	};
+	const makeBag = (sources, origin) => {
+		const bag = {};
+		const add = (source) => {
+			const name = "contextName" in source ? source.contextName : source.name;
+			if (Object.hasOwn(bag, name)) return;
+			Object.defineProperty(bag, name, {
+				enumerable: true,
+				get: () => makePull(origin)(name)
+			});
+			for (const dependency of source.uses ?? []) add(dependency);
+		};
+		for (const source of sources) add(source);
+		return Object.freeze(bag);
+	};
+	return {
+		bag: (sources) => makeBag(sources, null),
+		setValidatedFlags(flags) {
+			validatedFlags = flags;
+		},
+		async settle() {
+			for (;;) {
+				const pending = [...entries.values()].filter((entry) => !entry.settled);
+				if (pending.length === 0) return;
+				await Promise.allSettled(pending.map((entry) => entry.promise));
+			}
+		}
+	};
+}
+//#endregion
+//#region src/api/extension.ts
+const FINISHED = Object.freeze({ [Symbol("crust.finished")]: true });
+/** @internal */
+function finishInvocation() {
+	return FINISHED;
+}
+function isExtensionFactory(value) {
+	return typeof value === "function";
+}
+function defineExtension(id, config = {}) {
+	if (id === void 0) return defineExtension;
+	if (isExtensionFactory(config)) return Object.assign((...args) => defineExtension(id, config(...args)), { id });
+	const ownedFlags = Object.freeze(toFlagsRecord(config.flags ?? []));
+	toFlagsRecord((config.provides ?? []).flatMap((instance) => Object.entries(definingOf(instance).ownedFlags).map(([name, def]) => ({
+		...def,
+		name
+	}))), ownedFlags);
+	return seal({
+		...config,
+		uses: Object.freeze((config.uses ?? []).map(definingOf)),
+		...config.provides ? { provides: Object.freeze(config.provides.map(definingOf)) } : {},
+		...config.commands ? { commands: Object.freeze([...config.commands]) } : {},
+		id,
+		...config.flags === void 0 ? {} : { flags: ownedFlags }
+	});
+}
+//#endregion
+//#region src/command/node.ts
+/**
+* Creates a new `CommandNode` with all fields initialized to defaults.
+*
+* @param name - The command name.
+* @returns A fresh `CommandNode` with empty flags, no args, no subcommands,
+*          no extensions, and no action.
+*/
+function createCommandNode(name) {
+	return {
+		meta: { name },
+		localFlags: {},
+		ownedFlags: {},
+		effectiveFlags: {},
+		flagSpellings: /* @__PURE__ */ new Map(),
+		args: [],
+		subCommands: {},
+		contexts: [],
+		demands: [],
+		extensions: [],
+		run: void 0
+	};
+}
+/** Register one effective flag and its source-owned state with a single collision policy. */
+function registerFlag(node, name, def, source) {
+	def = normalizeFlag(name, def);
+	const incomingSpellings = flagSpellings(name, def);
+	const existingName = Object.hasOwn(node.effectiveFlags, name) ? name : incomingSpellings.map((spelling) => node.flagSpellings.get(spelling)?.canonicalName).find((existing) => existing !== void 0);
+	if (existingName !== void 0) throw new CrustError("DEFINITION", `Flag "${name}" collides with existing flag "${existingName}" on command "${node.meta.name}"`, {
+		subject: "flag",
+		name,
+		reason: "flag-collision"
+	});
+	(source === "local" ? node.localFlags : node.ownedFlags)[name] = def;
+	node.effectiveFlags[name] = def;
+	const entry = {
+		canonicalName: name,
+		def,
+		negatable: isFlagNegatable(def)
+	};
+	node.flagSpellings.set(name, {
+		...entry,
+		kind: "canonical"
+	});
+	if (def.short !== void 0) node.flagSpellings.set(def.short, {
+		...entry,
+		kind: "short"
+	});
+	for (const alias of def.aliases ?? []) node.flagSpellings.set(alias, {
+		...entry,
+		kind: "alias"
+	});
+}
+//#endregion
+//#region src/command/extensions-install.ts
+/** Inject an Extension-owned flag into a node and, when recursive, its descendants. */
+function injectExtensionFlag(node, name, def, recursive) {
+	registerFlag(node, name, def, "owned");
+	if (!recursive) return;
+	for (const sub of Object.values(node.subCommands)) injectExtensionFlag(sub, name, def, true);
+}
+/** Attach one Extension's owned root commands to a cloned tree. */
+function applyExtensionCommands(root, extension, materializeCommandDefinition) {
+	for (const definition of extension.commands ?? []) root.subCommands[definition.name] = materializeCommandDefinition(definition, root, extension.id);
+}
+/** Inject one Extension's owned flags across a cloned tree. */
+function applyExtensionFlags(root, extension) {
+	for (const [name, defWithScope] of Object.entries(extension.flags ?? {})) {
+		const { recursive = true, ...def } = defWithScope;
+		injectExtensionFlag(root, name, def, recursive);
+	}
+}
+/** Deep-clone a command subtree without mutating the builder graph. */
+function cloneCommandNode(node) {
+	const subCommands = {};
+	for (const [name, sub] of Object.entries(node.subCommands)) subCommands[name] = cloneCommandNode(sub);
+	return {
+		...node,
+		meta: { ...node.meta },
+		localFlags: { ...node.localFlags },
+		ownedFlags: { ...node.ownedFlags },
+		effectiveFlags: { ...node.effectiveFlags },
+		flagSpellings: new Map([...node.flagSpellings].map(([spelling, entry]) => [spelling, {
+			...entry,
+			def: node.effectiveFlags[entry.canonicalName]
+		}])),
+		args: [...node.args],
+		subCommands,
+		contexts: node.contexts.map((context) => ({ ...context })),
+		demands: [...node.demands],
+		extensions: [...node.extensions],
+		run: node.run
+	};
+}
+function invalidSections({ subject, name }) {
+	return new CrustError("DEFINITION", `${subject === "command" ? "Command" : "Extension"} "${name}" contains invalid documentation sections`, {
+		subject,
+		name,
+		reason: "invalid-sections"
+	});
+}
+function normalizeSection(section, owner) {
+	const { title, body, only, except } = section;
+	if (!title.trim() || /[\r\n]/.test(title) || !body.trim() || only?.length === 0 || except?.length === 0 || only !== void 0 && except !== void 0) throw invalidSections(owner);
+	const audience = (ids) => {
+		return Object.freeze(ids.map((consumer) => typeof consumer === "string" ? consumer : consumer.id));
+	};
+	return Object.freeze({
+		title,
+		body,
+		...only ? { only: audience(only) } : except ? { except: audience(except) } : {}
+	});
+}
+function validateCommandSections(name, sections) {
+	return sections.map((section) => normalizeSection(section, {
+		subject: "command",
+		name
+	}));
+}
+function contributionTarget(root, command, extension) {
+	let target = root;
+	for (const segment of command) {
+		const next = Object.hasOwn(target.subCommands, segment) ? target.subCommands[segment] : void 0;
+		if (!next) throw new CrustError("DEFINITION", `Extension "${extension.id}" section target "${command.join(" ")}" is not a canonical command path`, {
+			subject: "extension",
+			name: extension.id,
+			reason: "invalid-section-path"
+		});
+		target = next;
+	}
+	return target;
+}
+function applyExtensionSections(root, extension, snapshot) {
+	if (!extension.sections) return;
+	const owner = {
+		subject: "extension",
+		name: extension.id
+	};
+	const contributions = extension.sections(snapshot);
+	for (const contribution of contributions) {
+		const section = normalizeSection(contribution, owner);
+		const target = contributionTarget(root, contribution.command, extension);
+		target.meta.sections = [...target.meta.sections ?? [], section];
+	}
+}
+function installExtensionContexts(node, extensions, reRegisteredIds) {
+	const cloned = cloneCommandNode(node);
+	const kept = new Set(extensions.flatMap((e) => !reRegisteredIds.has(e.id) && node.extensions.includes(e) ? [e.id] : []));
+	const prune = (target) => {
+		target.contexts = target.contexts.filter((context) => context.extensionId === void 0 || kept.has(context.extensionId));
+		const effectiveNames = Object.keys(target.effectiveFlags);
+		const localFlags = target.localFlags;
+		const ownedFlags = {};
+		for (const { instance } of target.contexts) Object.assign(ownedFlags, instance.ownedFlags);
+		target.localFlags = {};
+		target.ownedFlags = {};
+		target.effectiveFlags = {};
+		target.flagSpellings = /* @__PURE__ */ new Map();
+		for (const name of effectiveNames) {
+			const source = Object.hasOwn(ownedFlags, name) ? "owned" : "local";
+			const flags = source === "owned" ? ownedFlags : localFlags;
+			if (Object.hasOwn(flags, name)) registerFlag(target, name, flags[name], source);
+		}
+		for (const child of Object.values(target.subCommands)) prune(child);
+	};
+	prune(cloned);
+	for (const extension of extensions) {
+		if (kept.has(extension.id)) continue;
+		const instances = extension.provides ?? [];
+		if (instances.length === 0) continue;
+		const walk = (target, skip) => {
+			const installed = instances.filter((instance) => !skip.has(instance.name));
+			const registrations = installed.map((instance) => ({
+				instance,
+				extensionId: extension.id
+			}));
+			target.contexts.push(...registrations);
+			for (const instance of installed) for (const [name, def] of Object.entries(instance.ownedFlags)) registerFlag(target, name, def, "owned");
+			const inherited = new WeakSet(target.contexts.map(({ instance }) => instance));
+			for (const child of Object.values(target.subCommands)) {
+				const childSkip = new Set(skip);
+				for (const { instance } of child.contexts) if (!inherited.has(instance)) childSkip.add(instance.name);
+				walk(child, childSkip);
+			}
+		};
+		walk(cloned, /* @__PURE__ */ new Set());
+	}
+	return cloned;
+}
+//#endregion
+//#region ../utils/src/terminal.ts
+const STORAGE_KEY = Symbol.for("crustjs.terminal.io");
+const AMBIENT_CALLBACKS_KEY = Symbol.for("crustjs.terminal.ambient-callbacks");
+const globalWithStorage = globalThis;
+const globalWithAmbientCallbacks = globalThis;
+/** Bundled copies in Core, Prompts, and Progress share process-wide terminal state. */
+const storage = globalWithStorage[STORAGE_KEY] ??= new AsyncLocalStorage();
+const ambientCallbacks = globalWithAmbientCallbacks[AMBIENT_CALLBACKS_KEY] ??= /* @__PURE__ */ new WeakMap();
+/** Run a function with terminal streams available in its async scope. */
+function withTerminalIO(io, fn) {
+	const current = storage.getStore();
+	return storage.run({
+		input: io.input ?? current?.input,
+		output: io.output ?? current?.output
+	}, fn);
+}
+function lineBufferedOutput(io) {
+	let pending = "";
+	const output = new Writable({
+		decodeStrings: false,
+		write(chunk, _encoding, callback) {
+			pending += chunk.toString();
+			let newline = pending.indexOf("\n");
+			while (newline !== -1) {
+				io.stderr(pending.slice(0, newline));
+				pending = pending.slice(newline + 1);
+				newline = pending.indexOf("\n");
+			}
+			callback();
+		}
+	});
+	ambientCallbacks.set(output, io);
+	return output;
+}
+/** Run a function with Core's line-oriented output bridged into the terminal stream scope. */
+function withAmbientTerminalIO(io, fn) {
+	const current = storage.getStore();
+	return withTerminalIO({
+		input: current?.input,
+		output: current?.output && !ambientCallbacks.has(current.output) ? current.output : lineBufferedOutput(io)
+	}, fn);
+}
+//#endregion
+//#region ../utils/src/primitive.ts
+/**
+* Attempts to coerce a string to a number, returning `undefined` only when the
+* result is `NaN`. Callers decide whether `undefined` means throw or fallback.
+*
+* @example
+* ```ts
+* tryCoerceNumber("42"); // 42
+* tryCoerceNumber("abc"); // undefined
+* tryCoerceNumber(""); // 0
+* ```
+*/
+function tryCoerceNumber(raw) {
+	const num = Number(raw);
+	return Number.isNaN(num) ? void 0 : num;
+}
+/**
+* Coerces Crust boolean strings using the existing strict truthy spellings.
+*
+* @example
+* ```ts
+* coerceBooleanString("true"); // true
+* coerceBooleanString("1"); // true
+* coerceBooleanString("false"); // false
+* ```
+*/
+function coerceBooleanString(raw) {
+	return raw === "true" || raw === "1";
+}
+//#endregion
+//#region src/parsing/coercers.ts
+/**
+* Coerce a raw argv string into a {@link URL} instance via the WHATWG
+* `URL` parser. Any protocol accepted by `new URL()` (https, http, file,
+* ftp, …) is allowed.
+*
+* Throws `CrustError("PARSE", …)` when the input is not a valid URL.
+* The original input is echoed in the message. When the input clearly
+* lacks a URL scheme, we append a hint reminding the user to include
+* one — a common foot-gun on the command line.
+*/
+function coerceUrl(raw) {
+	try {
+		return new URL(raw);
+	} catch {
+		throw new CrustError("PARSE", `Invalid URL "${raw}"${/^[a-z][a-z0-9+.-]*:/i.test(raw) ? "" : " (missing protocol — e.g. https://example.com)"}`);
+	}
+}
+/**
+* Coerce a raw argv string into an absolute filesystem path.
+*
+* Steps:
+* 1. Reject empty input.
+* 2. Expand a leading `~` (followed by `/` or end-of-string) to the user's
+*    home directory. `~username` is intentionally NOT expanded.
+* 3. Resolve against `process.cwd()` so the result is always absolute.
+*
+* Path-traversal (`..`) is allowed — coercion does not sandbox.
+*/
+function coercePath(raw) {
+	if (raw === "") throw new CrustError("PARSE", "Path cannot be empty");
+	const expanded = raw.replace(/^~(?=\/|$)/, homedir());
+	return resolve(process.cwd(), expanded);
+}
+/**
+* Coerce a raw argv string into a parsed JSON value (`JsonValue`) via
+* `JSON.parse`. Any valid JSON document is accepted — objects, arrays,
+* strings, numbers, booleans, null.
+*
+* Throws `CrustError("PARSE", …)` when the input is not valid JSON.
+* The original `SyntaxError.message` is included plus a shell-quoting
+* hint, since unquoted JSON on the command line is a common foot-gun.
+*
+* Note: `JSON.parse` loses precision on integers above `Number.MAX_SAFE_INTEGER`.
+*/
+function coerceJson(raw) {
+	try {
+		return JSON.parse(raw);
+	} catch (err) {
+		throw new CrustError("PARSE", `Invalid JSON: ${err instanceof Error ? err.message : String(err)}. Tip: wrap JSON in single quotes on the command line, e.g. --flag '{"k":1}'`);
+	}
+}
+//#endregion
+//#region src/parsing/parser.ts
+/**
+* Build the options config for `util.parseArgs` from the shared spelling table.
+* Also returns a reverse alias→name mapping for resolving parsed results.
+*/
+function buildParseArgsOptionDescriptor(spellings) {
+	const options = {};
+	const aliasToName = {};
+	for (const [spelling, entry] of spellings) {
+		const descriptor = { type: entry.def.type === "boolean" ? "boolean" : "string" };
+		if (entry.def.multiple) descriptor.multiple = true;
+		if (entry.kind === "canonical") {
+			if (entry.def.short) descriptor.short = entry.def.short;
+			options[spelling] = descriptor;
+			continue;
+		}
+		aliasToName[spelling] = entry.canonicalName;
+		if (entry.kind === "alias") options[spelling] = descriptor;
+	}
+	return {
+		options,
+		aliasToName
+	};
+}
+/**
+* Coerce a string value to the expected type based on the type literal.
+*/
+function coerceValue(value, type, label) {
+	if (type === "number") {
+		const num = tryCoerceNumber(value);
+		if (num === void 0) throw new CrustError("PARSE", `Expected number for ${label}, got "${value}"`);
+		return num;
+	}
+	if (type === "boolean") return coerceBooleanString(value);
+	if (type === "url") return coerceUrl(value);
+	if (type === "path") return coercePath(value);
+	if (type === "json") return coerceJson(value);
+	return value;
+}
+/**
+* Validate a raw argv string against a flag/arg `choices` list. Throws
+* `CrustError("PARSE", …)` when the value is not in the allowed set.
+*
+* Runs *before* any `parse` transform so the user-facing comparison is on
+* the raw token, not the post-`parse` value.
+*/
+function validateChoice(raw, choices, label) {
+	if (!choices.includes(raw)) throw new CrustError("PARSE", `Invalid value "${raw}" for ${label}. Expected one of: ${choices.join(", ")}`);
+}
+/** Invoke a user `parse` function on a raw token, wrapping errors. */
+function invokeParse(parse, raw, label, index) {
+	const location = index === void 0 ? label : `${label} element [${index}]`;
+	let result;
+	try {
+		result = parse(raw);
+		if (isPromise(result)) {
+			result.catch(() => {});
+			throw new Error("parse must be synchronous");
+		}
+	} catch (err) {
+		throw new CrustError("PARSE", `Failed to parse ${location}: ${err instanceof Error ? err.message : String(err)}`).withCause(err);
+	}
+	return result;
+}
+/**
+* Resolve a flag/arg default to its runtime value, mirroring the argv-side
+* coercion pipeline so omitted-flag behavior matches user-supplied behavior:
+*
+*   raw default → parse | coerce → result
+*
+* Without this, `{ type: "path", default: "./dist" }` returns the raw
+* relative string while `--out ./dist` returns an absolute path.
+*
+* `parse` is preferred when present (matches the escape-hatch contract).
+* `type: "path"` defaults are coerced through `coercePath` because their
+* default field is a raw string per `PathFlagDef`/`PathArgDef`. `url` and
+* `json` defaults are already in their resolved form (`URL` / `unknown`)
+* per the variant interfaces, so they pass through unchanged.
+*/
+function resolveDefault(def, label) {
+	const { default: defaultValue, parse } = def;
+	if (defaultValue === void 0) return void 0;
+	if (parse) {
+		if (Array.isArray(defaultValue)) return defaultValue.map((v, i) => invokeParse(parse, String(v), label, i));
+		return invokeParse(parse, String(defaultValue), label);
+	}
+	if (def.type === "path") {
+		if (Array.isArray(defaultValue)) return defaultValue.map((v) => coercePath(String(v)));
+		return coercePath(String(defaultValue));
+	}
+	return "multiple" in def && def.multiple && Array.isArray(defaultValue) ? [...defaultValue] : defaultValue;
+}
+/**
+* Coerce a single flag's parsed value to its target type.
+*
+* Order on string-typed flags with `choices` and/or `parse`:
+*   raw token → choices validation → parse transform (if set) → result.
+* For multi-value flags both steps run per element.
+*/
+function coerceFlagValue(name, def, parsed) {
+	if (parsed.kind === "boolean") return parsed.value;
+	const label = `--${name}`;
+	const coerce = (value, index) => {
+		if (def.choices) validateChoice(value, def.choices, label);
+		if (def.parse) return invokeParse(def.parse, value, label, index);
+		return coerceValue(value, def.type, label);
+	};
+	return Array.isArray(parsed.value) ? parsed.value.map(coerce) : coerce(parsed.value);
+}
+/**
+* Resolve parsed option tokens to canonical flag names, in argv order.
+*
+* Works from `parsed.tokens` rather than `parsed.values` because
+* `util.parseArgs` groups values by option key: with aliases, the last *key*
+* would win instead of the last *token* (`--verbose --no-loud --verbose`
+* must be `true`), and `multiple` flags spread across aliases would lose
+* their interleaved argv order.
+*/
+function resolveAliases(tokens, aliasToName, flagsDef) {
+	const canonical = {};
+	for (const token of tokens) {
+		if (token.kind !== "option") continue;
+		const canonicalName = aliasToName[token.name] ?? token.name;
+		const def = flagsDef[canonicalName];
+		const existing = canonical[canonicalName];
+		if (def.type === "boolean") {
+			const value = !token.rawName.startsWith("--no-");
+			if (def.multiple && existing?.kind === "boolean" && Array.isArray(existing.value)) existing.value.push(value);
+			else canonical[canonicalName] = {
+				kind: "boolean",
+				value: def.multiple ? [value] : value
+			};
+		} else {
+			const value = token.value;
+			if (def.multiple && existing?.kind === "string" && Array.isArray(existing.value)) existing.value.push(value);
+			else canonical[canonicalName] = {
+				kind: "string",
+				value: def.multiple ? [value] : value
+			};
+		}
+	}
+	return canonical;
+}
+/**
+* Resolve all flag definitions against the canonical parsed values.
+* Handles coercion and default values.
+*/
+function resolveFlags(flagsDef, values, coerce) {
+	const resolved = {};
+	for (const name of Object.keys(values)) if (!Object.hasOwn(flagsDef, name) && values[name] !== void 0) throw new CrustError("PARSE", `Unknown flag "--${name}"`, {
+		flag: name,
+		reason: "unknown-flag"
+	});
+	for (const [name, def] of Object.entries(flagsDef)) {
+		const parsedValue = Object.hasOwn(values, name) ? values[name] : void 0;
+		if (!(parsedValue === void 0 || def.multiple && Array.isArray(parsedValue) && parsedValue.length === 0)) {
+			resolved[name] = coerce(name, def, parsedValue);
+			continue;
+		}
+		resolved[name] = resolveDefault(def, `--${name}`);
+	}
+	return resolved;
+}
+/**
+* Validate required flags against already-resolved flag values.
+*/
+function validateRequiredFlags(flagsDef, resolvedFlags) {
+	for (const [name, def] of Object.entries(flagsDef)) if (def.required === true && def.default === void 0) {
+		if (resolvedFlags[name] === void 0) throw new CrustError("VALIDATION", `Missing required flag "--${name}"`);
+	}
+}
+function coerceArgToken(def, raw, label, index) {
+	if (def.schema) return raw;
+	if (def.choices) validateChoice(raw, def.choices, label);
+	if (def.parse) return invokeParse(def.parse, raw, label, index);
+	return coerceValue(raw, def.type, label);
+}
+function resolveArgs(argsDef, positionals, coerce) {
+	const resolved = {};
+	let index = 0;
+	for (const def of argsDef) {
+		const { name } = def;
+		const label = `<${name}>`;
+		if (def.variadic) {
+			resolved[name] = positionals.slice(index).map((v, i) => coerce(def, v, label, i));
+			index = positionals.length;
+		} else if (index < positionals.length) {
+			resolved[name] = coerce(def, positionals[index], label);
+			index++;
+		} else resolved[name] = resolveDefault(def, label);
+	}
+	return {
+		args: resolved,
+		consumed: index
+	};
+}
+/**
+* Enforce `noNegate` at parse time.
+*
+* `--no-<spelling>` works for the canonical name and every long alias
+* (an alias is a perfect synonym), but a boolean that
+* opted out via `noNegate` rejects every negated spelling. Without this
+* pre-scan, `util.parseArgs` (`allowNegative`) would silently accept it.
+*/
+function validateNoNegateUsage(argv, spellings) {
+	for (const arg of argv) {
+		if (arg === "--") return;
+		if (!arg.startsWith("--no-")) continue;
+		const assignmentIndex = arg.indexOf("=");
+		const rawName = assignmentIndex === -1 ? arg.slice(5) : arg.slice(5, assignmentIndex);
+		const spelling = spellings.get(rawName);
+		if (!spelling || spelling.def.type !== "boolean" || spelling.negatable) continue;
+		throw new CrustError("PARSE", `Flag "--${spelling.canonicalName}" does not support negation ("--no-${rawName}")`);
+	}
+}
+function tokenizeArgv(command, argv) {
+	const spellings = command.flagSpellings;
+	const { options: parseOptions, aliasToName } = buildParseArgsOptionDescriptor(spellings);
+	validateNoNegateUsage(argv, spellings);
+	let parsed;
+	try {
+		parsed = parseArgs({
+			args: argv,
+			options: parseOptions,
+			strict: true,
+			allowPositionals: true,
+			allowNegative: true,
+			tokens: true
+		});
+	} catch (error) {
+		if (error instanceof Error) {
+			const unknownMatch = error.message.match(/Unknown option '(.+?)'/);
+			if (unknownMatch) throw new CrustError("PARSE", `Unknown flag "${unknownMatch[1]}"`).withCause(error);
+			if ("code" in error && error.code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE" && error.message.length > 0) throw new CrustError("PARSE", error.message).withCause(error);
+		}
+		throw new CrustError("PARSE", "Failed to parse command arguments").withCause(error);
+	}
+	const rawArgs = [];
+	const preSeparatorPositionals = [];
+	let afterSeparator = false;
+	for (const token of parsed.tokens) {
+		if (token.kind === "option-terminator") {
+			afterSeparator = true;
+			continue;
+		}
+		if (token.kind === "positional") (afterSeparator ? rawArgs : preSeparatorPositionals).push(token.value);
+	}
+	return {
+		positionals: preSeparatorPositionals,
+		flagValues: resolveAliases(parsed.tokens, aliasToName, command.effectiveFlags),
+		rawArgs
+	};
+}
+function validateStructuredValue(def, value, label) {
+	const type = def.schema ? def.type === "boolean" ? "boolean" : "string" : def.type;
+	let valid;
+	if (type === "url") valid = value instanceof URL;
+	else if (type === "json") {
+		const pending = [value];
+		const seen = /* @__PURE__ */ new Set();
+		valid = true;
+		while (pending.length > 0) {
+			const item = pending.pop();
+			if (item instanceof URL) {
+				valid = false;
+				break;
+			}
+			if (Array.isArray(item) && !seen.has(item)) {
+				seen.add(item);
+				pending.push(...item);
+			}
+		}
+	} else valid = typeof value === (type === "path" ? "string" : type);
+	if (!valid) throw new CrustError("PARSE", `Expected ${type} for ${label}`);
+	if (value === false && "noNegate" in def && def.noNegate) throw new CrustError("PARSE", `Flag "${label}" does not support negation`);
+}
+/** Validate supplied structured values before applying transforms. */
+function coerceStructuredValue(def, value, label, index) {
+	validateStructuredValue(def, value, label);
+	if (def.choices) validateChoice(String(value), def.choices, label);
+	if (def.parse) return invokeParse(def.parse, String(value), label, index);
+	if (def.type === "path") return coercePath(String(value));
+	return value;
+}
+function coerceStructuredFlag(name, def, value) {
+	const label = `--${name}`;
+	if (def.multiple) {
+		if (!Array.isArray(value)) throw new CrustError("PARSE", `Expected an occurrence array for ${label}`);
+		return value.map((item, i) => coerceStructuredValue(def, item, label, i));
+	}
+	return coerceStructuredValue(def, value, label);
+}
+/** Both front doors share binding, defaults, and canonical flag validation. */
+function bind(command, positionals, flagValues, coerceArg, coerceFlag) {
+	const flags = resolveFlags(command.effectiveFlags, flagValues, coerceFlag);
+	return {
+		...resolveArgs(command.args, positionals, coerceArg),
+		flags
+	};
+}
+/**
+* Parse argv against a command's arg/flag definitions.
+*
+* Wraps Node's `util.parseArgs` with Crust's enhanced semantics:
+* positional arg mapping, type coercion, alias expansion, default values,
+* variadic args, and strict mode.
+*
+* This is a pure parse+coerce function — it never throws for missing required
+* values. Use {@link validateParsed} to enforce required constraints after
+* extensions have had a chance to finish an invocation (e.g. `--help`).
+*
+* @param command - The command whose arg/flag definitions drive the parsing
+* @param argv - The argv array to parse (typically `process.argv.slice(2)`)
+* @returns Parsed args, flags, excessArgs (positionals before `--` not consumed by a declared argument), and rawArgs (everything after `--`)
+* @throws {CrustError} On unknown flags or type coercion failure
+*/
+function parseArgs$1(command, argv) {
+	const { positionals, flagValues, rawArgs } = tokenizeArgv(command, argv);
+	const { args, flags, consumed } = bind(command, positionals, flagValues, coerceArgToken, coerceFlagValue);
+	return {
+		args,
+		flags,
+		excessArgs: positionals.slice(consumed),
+		rawArgs
+	};
+}
+/** Bind typed input without producing argv; the path alone selects the command. */
+function parseStructured(command, input) {
+	const { args: inputArgs, flags: inputFlags, raw } = input;
+	const positionals = [];
+	let omittedArgument;
+	for (const definition of command.args) {
+		const value = inputArgs && Object.hasOwn(inputArgs, definition.name) ? inputArgs[definition.name] : void 0;
+		if (value === void 0) {
+			omittedArgument = definition.name;
+			continue;
+		}
+		if (omittedArgument !== void 0) throw new CrustError("PARSE", `Argument <${definition.name}> cannot be provided after omitted argument <${omittedArgument}>`, {
+			argument: definition.name,
+			reason: "positional-gap"
+		});
+		if (definition.variadic) {
+			if (!Array.isArray(value)) throw new CrustError("PARSE", `Expected an occurrence array for <${definition.name}>`);
+			positionals.push(...value);
+		} else positionals.push(value);
+	}
+	for (const name of Object.keys(inputArgs ?? {})) if (!command.args.some((definition) => definition.name === name) && inputArgs?.[name] !== void 0) throw new CrustError("PARSE", `Unknown argument "${name}"`, {
+		argument: name,
+		reason: "unknown-argument"
+	});
+	const { args, flags } = bind(command, positionals, inputFlags ?? {}, coerceStructuredValue, coerceStructuredFlag);
+	return {
+		args,
+		flags,
+		excessArgs: [],
+		rawArgs: [...raw ?? []]
+	};
+}
+/**
+* Validate a parse result against its command's required-value constraints.
+*
+* Separated from {@link parseArgs} so that middleware (e.g. `--help`) can
+* inspect the parse result before validation errors are surfaced.
+*
+* @param command - The command whose definitions drive the validation
+* @param parsed - The parse result from {@link parseArgs}
+* @throws {CrustError} On missing required args or flags
+*/
+function validateParsed(command, parsed) {
+	const argsDef = command.args;
+	const flagsDef = command.effectiveFlags;
+	const args = parsed.args;
+	const flags = parsed.flags;
+	if (parsed.excessArgs.length > 0) throw new CrustError("VALIDATION", `Unexpected positional argument${parsed.excessArgs.length === 1 ? "" : "s"}: ${parsed.excessArgs.map((arg) => JSON.stringify(arg)).join(", ")}`);
+	for (const def of argsDef) {
+		const { name } = def;
+		const label = `argument "<${name}>"`;
+		const value = args[name];
+		if (def.required === true && def.default === void 0) {
+			if (def.variadic) {
+				if (!Array.isArray(value) || value.length === 0) throw new CrustError("VALIDATION", `Missing required ${label}`);
+			} else if (value === void 0) throw new CrustError("VALIDATION", `Missing required ${label}`);
+		}
+	}
+	validateRequiredFlags(flagsDef, flags);
+}
+//#endregion
+//#region ../utils/src/schema.ts
+/**
+* Format an issue path into a dot-path string.
+*
+* - Numeric keys (array indexes) are rendered with bracket notation: `items[0]`
+* - String/symbol keys are joined with dots: `flags.verbose`
+* - An empty path array produces an empty string (root-level issue)
+*
+* @example
+* ```ts
+* formatPath(["flags", "verbose"]);
+* // => "flags.verbose"
+*
+* formatPath(["args", 0]);
+* // => "args[0]"
+*
+* formatPath([]);
+* // => ""
+* ```
+*/
+function isNumericPathSegment(segment) {
+	return typeof segment === "number";
+}
+function formatPath(path) {
+	return path.map((segment, index) => isNumericPathSegment(segment) ? `[${segment}]` : index > 0 ? `.${String(segment)}` : String(segment)).join("");
+}
+/**
+* Normalize a Standard Schema issue path to an array of `PropertyKey`.
+*
+* Standard Schema paths contain either bare `PropertyKey` values or
+* `{ key: PropertyKey }` segment objects; both forms are flattened to
+* plain `PropertyKey`. Returns an empty array for a root-level issue
+* (`undefined`).
+*/
+function isStandardPathSegment(segment) {
+	return typeof segment === "object" && segment !== null && "key" in segment;
+}
+function normalizeStandardPath(path) {
+	if (!path) return [];
+	return path.map((segment) => isStandardPathSegment(segment) ? segment.key : segment);
+}
+/**
+* Normalize Standard Schema issues into canonical `ValidationIssue` objects.
+*
+* Applies an optional prefix (e.g. `["flags", "verbose"]`) to each issue
+* path, then formats each path to its canonical dot-path string.
+*
+* @param issues — Raw Standard Schema issues from a failed validation
+* @param prefix — Optional path segments prepended to each issue path
+*/
+function normalizeStandardIssues(issues, prefix = []) {
+	return issues.map((issue) => {
+		const resolvedPath = normalizeStandardPath(issue.path);
+		const fullPath = [...prefix, ...resolvedPath];
+		return {
+			message: issue.message,
+			path: formatPath(fullPath)
+		};
+	});
+}
+//#endregion
+//#region src/parsing/schema.ts
+async function runSchema(schema, raw, path, issues) {
+	let result = schema["~standard"].validate(raw);
+	if (result instanceof Promise) result = await result;
+	if (result.issues) {
+		issues.push(...normalizeStandardIssues(result.issues, path));
+		return { ok: false };
+	}
+	return {
+		ok: true,
+		value: result.value
+	};
+}
+/**
+* Apply Standard Schemas declared on arg/flag definitions.
+*
+* Runs after syntax parsing and structural validation: each schema receives
+* the raw parsed value (`string | undefined` for args, the raw token value
+* for flags, arrays for variadic/multiple) and exclusively owns coercion,
+* defaults, requiredness, and validation. Returns transformed copies of
+* `args`/`flags`; definitions without a schema pass through unchanged.
+*
+* @throws {CrustError} `VALIDATION` aggregating every schema issue
+*/
+async function applySchemas(node, parsed) {
+	const issues = [];
+	const args = new Map(Object.entries(parsed.args));
+	const flags = new Map(Object.entries(parsed.flags));
+	for (const def of node.args) {
+		if (def.schema === void 0) continue;
+		const result = await runSchema(def.schema, args.get(def.name), ["args", def.name], issues);
+		if (result.ok) args.set(def.name, result.value);
+	}
+	for (const [name, def] of Object.entries(node.effectiveFlags)) {
+		if (def.schema === void 0) continue;
+		const result = await runSchema(def.schema, flags.get(name), ["flags", name], issues);
+		if (result.ok) flags.set(name, result.value);
+	}
+	if (issues.length > 0) throw new CrustError("VALIDATION", `Invalid input:\n${issues.map((issue) => `  - ${issue.path}: ${issue.message}`).join("\n")}`, { issues });
+	return {
+		args: Object.fromEntries(args),
+		flags: Object.fromEntries(flags)
+	};
+}
+//#endregion
+//#region src/sections.ts
+/** Whether a command belongs in user-facing listings. */
+function isListed(command) {
+	return command.meta.hidden !== true;
+}
+/** Select and merge sections visible to the given consumer. */
+function sectionsFor(sections, consumer) {
+	const visible = (sections ?? []).filter((section) => {
+		if (section.only) return section.only.includes(consumer);
+		if (section.except) return !section.except.includes(consumer);
+		return true;
+	});
+	const merged = /* @__PURE__ */ new Map();
+	for (const section of visible) {
+		const existing = merged.get(section.title);
+		merged.set(section.title, existing ? {
+			title: section.title,
+			body: `${existing.body}\n${section.body}`
+		} : section);
+	}
+	return [...merged.values()];
+}
+/** Collect section-bearing visible commands in canonical path order. The root path is `[]`. */
+function visibleSectionsFor(snapshot, consumer) {
+	const groups = [];
+	function visit(command, path) {
+		const sections = sectionsFor(command.meta.sections, consumer);
+		if (sections.length > 0) groups.push({
+			path,
+			sections
+		});
+		for (const [name, child] of Object.entries(command.subCommands).sort(([a], [b]) => a.localeCompare(b))) if (isListed(child)) visit(child, [...path, name]);
+	}
+	visit(snapshot, []);
+	return groups;
+}
+//#endregion
+//#region src/command/snapshot.ts
+/** Drop keys with `undefined` values so snapshots serialize cleanly, then freeze. */
+function freezeCompact(obj) {
+	for (const key of Object.keys(obj)) if (obj[key] === void 0) delete obj[key];
+	return Object.freeze(obj);
+}
+function serializableDefault(value) {
+	if (value instanceof URL) return value.href;
+	if (Array.isArray(value)) return Object.freeze(value.map(serializableDefault));
+	return value;
+}
+function snapshotArg(def) {
+	return freezeCompact({
+		name: def.name,
+		type: def.type,
+		description: def.description,
+		required: def.required,
+		variadic: def.variadic,
+		choices: def.choices ? Object.freeze([...def.choices]) : void 0,
+		default: serializableDefault(def.default)
+	});
+}
+function snapshotFlag(def) {
+	return freezeCompact({
+		type: def.type,
+		description: def.description,
+		short: def.short,
+		aliases: def.aliases ? Object.freeze([...def.aliases]) : void 0,
+		required: def.required,
+		multiple: def.multiple,
+		negatable: isFlagNegatable(def),
+		noNegate: "noNegate" in def ? def.noNegate : void 0,
+		choices: def.choices ? Object.freeze([...def.choices]) : void 0,
+		default: serializableDefault(def.default)
+	});
+}
+/**
+* Project an internal command node (and its whole subtree) into a
+* {@link CommandSnapshot}.
+*/
+function snapshotCommand(node) {
+	const flags = {};
+	for (const [name, def] of Object.entries(node.effectiveFlags)) flags[name] = snapshotFlag(def);
+	const subCommands = {};
+	for (const [name, sub] of Object.entries(node.subCommands)) subCommands[name] = snapshotCommand(sub);
+	return Object.freeze({
+		meta: freezeCompact({
+			name: node.meta.name,
+			description: node.meta.description,
+			version: node.meta.version,
+			usage: node.meta.usage,
+			sections: node.meta.sections ? Object.freeze(node.meta.sections.map((section) => Object.freeze({ ...section }))) : void 0,
+			aliases: node.meta.aliases ? Object.freeze([...node.meta.aliases]) : void 0,
+			hidden: node.meta.hidden
+		}),
+		hasAction: node.run !== void 0,
+		args: Object.freeze(node.args.map(snapshotArg)),
+		flags: Object.freeze(flags),
+		subCommands: Object.freeze(subCommands)
+	});
+}
+//#endregion
+//#region src/command/router.ts
+/**
+* Find a sibling whose `meta.aliases` contains the given candidate. Returns
+* the canonical sibling key and node when matched, otherwise `null`.
+*
+* Resolution intentionally records the **canonical** key on the
+* `CommandRoute.commandPath`, never the alias the user typed. This is
+* load-bearing: error messages, help titles, and downstream extensions read
+* `commandPath` and assume canonical names.
+*/
+function findAliasMatch(subCommands, candidate) {
+	for (const [name, node] of Object.entries(subCommands)) {
+		const aliases = node.meta.aliases;
+		if (!aliases) continue;
+		if (aliases.includes(candidate)) return {
+			canonicalName: name,
+			node
+		};
+	}
+	return null;
+}
+/**
+* Match a dash token against the parser's shared spelling table.
+*
+* The token walk stays here because routing stops at unknown flags while
+* parsing reports them as errors; only spelling and negation policy is shared.
+*/
+function matchKnownFlagToken(spellings, token) {
+	if (token === "--") return null;
+	if (token.startsWith("--")) {
+		const eq = token.indexOf("=");
+		const spelling = eq === -1 ? token.slice(2) : token.slice(2, eq);
+		const entry = spellings.get(spelling);
+		if (entry) return { consumesValue: entry.def.type !== "boolean" && eq === -1 };
+		if (spelling.startsWith("no-")) {
+			if (spellings.get(spelling.slice(3))?.negatable) return { consumesValue: false };
+		}
+		return null;
+	}
+	const chars = token.slice(1);
+	if (chars.length === 0) return null;
+	for (let index = 0; index < chars.length; index++) {
+		const entry = spellings.get(chars[index]);
+		if (!entry) return null;
+		if (entry.def.type !== "boolean") return { consumesValue: index === chars.length - 1 };
+	}
+	return { consumesValue: false };
+}
+/**
+* Resolve a command from an argv array by walking the subcommand tree.
+*
+* Subcommand matching happens BEFORE flag parsing, so:
+* `crust build --entry src/cli.ts` first resolves "build" as a subcommand,
+* then passes `["--entry", "src/cli.ts"]` to the build command's parser.
+*
+* Resolution rules:
+* 1. If `argv[0]` matches a subcommand key, recurse into that subcommand
+* 2. If `argv[0]` matches a sibling's `meta.aliases` entry, recurse into
+*    that sibling and record the **canonical** name in `commandPath`
+* 3. If no match and the current command has `run()`, return it (args passed to parser)
+* 3a. Known flags encountered before a subcommand name are set aside and
+*     re-prepended for the resolved command's parser — but only if every
+*     command routing descends into recognizes them with the same token
+*     shape. A flag the subcommand cannot parse (e.g. a parent-local flag)
+*     is a PARSE error at the descend, never a silent forward-then-fail.
+* 4. If no match and the current command has NO `run()`, it signals the caller
+*    should show help (the `showHelp` flag is set in the result)
+* 5. Unknown subcommands produce a structured COMMAND_NOT_FOUND error whose
+*    `details.available` lists visible canonical sibling names (aliases are
+*    discoverable via `details.parentCommand.subCommands[name].meta.aliases`)
+*
+* Implementation: linear scan over siblings on miss. Command trees are small
+* and resolution runs once per invocation, so the cost is negligible compared
+* to building/freezing a parallel alias→canonical map. The scan does NOT
+* mutate `CommandNode`.
+*
+* @param command - The root command to resolve from
+* @param argv - The argv array to resolve against
+* @returns The resolved command, argv, and the command path
+* @throws {CrustError} COMMAND_NOT_FOUND when an unknown subcommand is given and the parent has no run()
+* @throws {CrustError} PARSE when a flag set aside during routing is not parseable by the subcommand being descended into
+*/
+function resolveCommand(command, argv) {
+	const path = [command.meta.name];
+	let current = command;
+	let routedArgv = argv;
+	const skippedFlagTokens = [];
+	const skippedFlagChecks = [];
+	const assertFlagsForwardable = (child, candidate) => {
+		if (skippedFlagChecks.length === 0) return;
+		const childSpellings = child.flagSpellings;
+		for (const { token, consumesValue } of skippedFlagChecks) {
+			const match = matchKnownFlagToken(childSpellings, token);
+			if (match !== null && match.consumesValue === consumesValue) continue;
+			throw new CrustError("PARSE", `Flag "${token}" cannot be used before subcommand "${candidate}" because "${candidate}" does not accept it.`, {
+				flag: token,
+				reason: "flag-not-forwardable"
+			});
+		}
+	};
+	while (routedArgv.length > 0) {
+		const subCommands = current.subCommands;
+		if (Object.keys(subCommands).length === 0) break;
+		const candidate = routedArgv[0];
+		if (!candidate) break;
+		if (candidate.startsWith("-")) {
+			const match = matchKnownFlagToken(current.flagSpellings, candidate);
+			if (!match) break;
+			skippedFlagTokens.push(candidate);
+			skippedFlagChecks.push({
+				token: candidate,
+				consumesValue: match.consumesValue
+			});
+			routedArgv = routedArgv.slice(1);
+			const value = routedArgv[0];
+			if (match.consumesValue && value !== void 0) {
+				skippedFlagTokens.push(value);
+				routedArgv = routedArgv.slice(1);
+			}
+			continue;
+		}
+		if (Object.hasOwn(subCommands, candidate) && subCommands[candidate]) {
+			assertFlagsForwardable(subCommands[candidate], candidate);
+			current = subCommands[candidate];
+			path.push(candidate);
+			routedArgv = routedArgv.slice(1);
+			continue;
+		}
+		const aliasMatch = findAliasMatch(subCommands, candidate);
+		if (aliasMatch) {
+			assertFlagsForwardable(aliasMatch.node, candidate);
+			current = aliasMatch.node;
+			path.push(aliasMatch.canonicalName);
+			routedArgv = routedArgv.slice(1);
+			continue;
+		}
+		if (current.run) break;
+		const parentCommand = snapshotCommand(current);
+		throw new CrustError("COMMAND_NOT_FOUND", `Unknown command "${candidate}".`, {
+			input: candidate,
+			available: Object.entries(parentCommand.subCommands).flatMap(([name, child]) => isListed(child) ? [name] : []),
+			commandPath: [...path],
+			parentCommand
+		});
+	}
+	return {
+		command: current,
+		argv: [...skippedFlagTokens, ...routedArgv],
+		commandPath: path
+	};
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.148.0/helpers/esm/usingCtx.js
+function _usingCtx() {
+	var r = "function" == typeof SuppressedError ? SuppressedError : function(r, e) {
+		var n = Error();
+		return n.name = "SuppressedError", n.error = r, n.suppressed = e, n;
+	}, e = {}, n = [];
+	function using(r, e) {
+		if (null != e) {
+			if (Object(e) !== e) throw new TypeError("using declarations can only be used with objects, functions, null, or undefined.");
+			if (r) var o = e[Symbol.asyncDispose || Symbol["for"]("Symbol.asyncDispose")];
+			if (void 0 === o && (o = e[Symbol.dispose || Symbol["for"]("Symbol.dispose")], r)) var t = o;
+			if ("function" != typeof o) throw new TypeError("Object is not disposable.");
+			t && (o = function o() {
+				try {
+					t.call(e);
+				} catch (r) {
+					return Promise.reject(r);
+				}
+			}), n.push({
+				v: e,
+				d: o,
+				a: r
+			});
+		} else r && n.push({
+			d: e,
+			a: r
+		});
+		return e;
+	}
+	return {
+		e,
+		u: using.bind(null, !1),
+		a: using.bind(null, !0),
+		d: function d() {
+			var o, t = this.e, s = 0;
+			function next() {
+				for (; o = n.pop();) try {
+					if (!o.a && 1 === s) return s = 0, n.push(o), Promise.resolve().then(next);
+					if (o.d) {
+						var r = o.d.call(o.v);
+						if (o.a) return s |= 2, Promise.resolve(r).then(next, err);
+					} else s |= 1;
+				} catch (r) {
+					return err(r);
+				}
+				if (1 === s) return t !== e ? Promise.reject(t) : Promise.resolve();
+				if (t !== e) throw t;
+			}
+			function err(n) {
+				return t = t !== e ? new r(n, t) : n, next();
+			}
+			return next();
+		}
+	};
+}
+//#endregion
+//#region src/command/invocation.ts
+/** Terminal defaults: line-oriented writes to the process streams. */
+const DEFAULT_IO = {
+	stdout: (text) => console.log(text),
+	stderr: (text) => console.error(text)
+};
+/**
+* Snapshot subprocess protocol used by first-party build tooling.
+*
+* When set to a non-empty file path, `.execute()` prepares the command tree,
+* validates its documentation sections, optionally runs Extension build hooks when the
+* build output directory is set, writes its final JSON snapshot and Build Report, and exits
+* without dispatching a Command Action. In-process callers use `Crust.snapshot()`.
+*/
+const SNAPSHOT_PATH_ENV = "CRUST_INTERNAL_SNAPSHOT_PATH";
+const BUILD_OUT_DIR_ENV = "CRUST_INTERNAL_BUILD_OUT_DIR";
+const EXIT_CODE_CANCELLED = 130;
+function isAbortError(error) {
+	if (!(error instanceof Error)) return false;
+	return error.name === "AbortError";
+}
+function freezeTree(node) {
+	Object.freeze(node);
+	Object.freeze(node.localFlags);
+	Object.freeze(node.ownedFlags);
+	Object.freeze(node.effectiveFlags);
+	if (node.meta.sections) Object.freeze(node.meta.sections);
+	Object.freeze(node.meta);
+	Object.freeze(node.contexts);
+	Object.freeze(node.extensions);
+	Object.freeze(node.args);
+	for (const sub of Object.values(node.subCommands)) freezeTree(sub);
+	Object.freeze(node.subCommands);
+}
+function isSymbol(value) {
+	return typeof value === "symbol";
+}
+function normalizeArtifactPath(path) {
+	const normalized = posix.normalize(path.replaceAll("\\", "/"));
+	const drivePrefix = /^[A-Za-z]:/;
+	if (posix.isAbsolute(normalized) || win32.isAbsolute(path) || win32.isAbsolute(normalized) || drivePrefix.test(path) || drivePrefix.test(normalized)) throw new Error(`Artifact path "${path}" must be relative to outDir.`);
+	if (normalized === ".." || normalized.startsWith("../")) throw new Error(`Artifact path "${path}" escapes outDir.`);
+	if (normalized === "." || normalized === "./") throw new Error(`Artifact path "${path}" must name a file inside outDir.`);
+	return normalized;
+}
+const preparedInvocations = /* @__PURE__ */ new WeakMap();
+/** Clone and apply Extension commands and flags; recipes run exactly once here. */
+function buildExtensionTree(node, materializeCommandDefinition) {
+	const rootNode = cloneCommandNode(node);
+	const extensions = Object.freeze([...node.extensions]);
+	for (const extension of extensions) applyExtensionCommands(rootNode, extension, materializeCommandDefinition);
+	for (const extension of extensions) applyExtensionFlags(rootNode, extension);
+	return {
+		rootNode,
+		extensions
+	};
+}
+/** Evaluate Extension section callbacks against current state and freeze the tree. */
+function applySectionsAndFreeze(rootNode, extensions) {
+	const authoredSnapshot = snapshotCommand(rootNode);
+	for (const extension of extensions) applyExtensionSections(rootNode, extension, authoredSnapshot);
+	freezeTree(rootNode);
+	return rootNode;
+}
+/** Clone, apply Extensions and sections, freeze, and cache ordinary invocation preparation. */
+function prepareInvocation(node, materializeCommandDefinition) {
+	const cached = preparedInvocations.get(node);
+	if (cached) return cached;
+	const prepared = buildExtensionTree(node, materializeCommandDefinition);
+	applySectionsAndFreeze(prepared.rootNode, prepared.extensions);
+	preparedInvocations.set(node, prepared);
+	return prepared;
+}
+function resolveArgvInput(root, argv) {
+	const route = resolveCommand(root, [...argv]);
+	return {
+		argv,
+		route,
+		parsed: parseArgs$1(route.command, route.argv)
+	};
+}
+function resolveStructuredInput(root, path, input) {
+	const route = resolveCommand(root, [...path]);
+	if (route.argv.length > 0) {
+		const candidate = route.argv[0];
+		const parentCommand = snapshotCommand(route.command);
+		throw new CrustError("COMMAND_NOT_FOUND", `Unknown command "${candidate}".`, {
+			input: candidate,
+			available: Object.entries(parentCommand.subCommands).flatMap(([name, child]) => isListed(child) ? [name] : []),
+			commandPath: route.commandPath,
+			parentCommand
+		});
+	}
+	return {
+		argv: path,
+		route,
+		parsed: parseStructured(route.command, input)
+	};
+}
+/** Resolve, parse, and run one invocation without rendering failures. */
+async function dispatch(input, prepared, io, onExtensionContext, onFailure) {
+	try {
+		var _usingCtx$1 = _usingCtx();
+		const { rootNode, extensions } = prepared;
+		const { argv, route, parsed } = "argv" in input ? resolveArgvInput(rootNode, input.argv) : resolveStructuredInput(rootNode, input.path, input.input);
+		const resolvedNode = route.command;
+		const disposal = _usingCtx$1.a(new DisposalStack());
+		const contexts = resolvedNode.contexts.map(({ instance }) => instance);
+		const resolver = createContextResolver(contexts, io, disposal);
+		const rootSnapshot = snapshotCommand(rootNode);
+		const extensionContext = Object.freeze({
+			argv: [...argv],
+			rootCommand: rootSnapshot,
+			command: resolvedNode === rootNode ? rootSnapshot : snapshotCommand(resolvedNode),
+			commandPath: Object.freeze([...route.commandPath]),
+			args: parsed.args,
+			flags: parsed.flags,
+			rawArgs: parsed.rawArgs,
+			ctx: resolver.bag(extensions.flatMap((extension) => extension.uses ?? [])),
+			finish: finishInvocation,
+			stdout: io.stdout,
+			stderr: io.stderr
+		});
+		onExtensionContext?.(extensionContext);
+		const terminal = async () => {
+			validateParsed(resolvedNode, parsed);
+			const validated = await applySchemas(resolvedNode, parsed);
+			resolver.setValidatedFlags(validated.flags);
+			if (!resolvedNode.run) return;
+			const context = {
+				args: validated.args,
+				flags: validated.flags,
+				ctx: resolver.bag(contexts),
+				rawArgs: parsed.rawArgs,
+				command: extensionContext.command,
+				rootCommand: rootSnapshot,
+				stdout: io.stdout,
+				stderr: io.stderr
+			};
+			return await resolvedNode.run(context);
+		};
+		let result;
+		let outcome = { status: "completed" };
+		try {
+			try {
+				for (const extension of extensions) if (await extension.hooks?.preRun?.(extensionContext) === finishInvocation()) {
+					outcome = {
+						status: "finished",
+						by: extension.id
+					};
+					break;
+				}
+				if (outcome.status !== "finished") result = await terminal();
+			} catch (error) {
+				const by = await onFailure?.(error, extensionContext);
+				outcome = {
+					status: "failed",
+					error,
+					...by === void 0 ? {} : { by }
+				};
+			}
+			Object.freeze(outcome);
+			let postRunFailed = false;
+			let postRunError;
+			for (const extension of extensions.toReversed()) try {
+				await extension.hooks?.postRun?.(extensionContext, outcome);
+			} catch (error) {
+				if (outcome.status !== "failed" && !postRunFailed) {
+					postRunFailed = true;
+					postRunError = error;
+				}
+			}
+			if (outcome.status === "failed") throw outcome.error;
+			if (postRunFailed) throw postRunError;
+		} finally {
+			await resolver.settle();
+		}
+		return outcome.status === "finished" ? {
+			status: "finished",
+			by: outcome.by
+		} : {
+			status: "completed",
+			result
+		};
+	} catch (_) {
+		_usingCtx$1.e = _;
+	} finally {
+		await _usingCtx$1.d();
+	}
+}
+/** Render one failure through Extension onError hooks, ending in Core's default renderer. */
+async function renderFailure(error, argv, prepared, io, extensionContext, silentDefault = false) {
+	const renderDefault = () => {
+		if (silentDefault) return;
+		const message = error instanceof Error ? error.message : String(error);
+		io.stderr(`Error: ${message}`);
+	};
+	function unavailable(property) {
+		return Promise.reject(new CrustError("DEFINITION", `Context "${String(property)}" cannot be pulled from onError because invocation Contexts have already been disposed.`, {
+			subject: "context",
+			name: String(property),
+			reason: "context-after-disposal"
+		}));
+	}
+	const unavailableContext = new Proxy({}, { get: (_, property) => property === "then" || isSymbol(property) ? void 0 : unavailable(property) });
+	const context = extensionContext ?? Object.freeze({
+		argv: [...argv],
+		rootCommand: snapshotCommand(prepared.rootNode),
+		command: snapshotCommand(prepared.rootNode),
+		commandPath: Object.freeze([prepared.rootNode.meta.name]),
+		args: Object.freeze({}),
+		flags: Object.freeze({}),
+		rawArgs: [],
+		finish: finishInvocation,
+		stdout: io.stdout,
+		stderr: io.stderr,
+		ctx: unavailableContext
+	});
+	try {
+		for (const extension of prepared.extensions) if (await extension.hooks?.onError?.(error, context)) return extension.id;
+	} catch {}
+	renderDefault();
+}
+/** Explicitly injected IO opts an invocation into the ambient terminal scope. */
+function hasInjectedIO(io) {
+	return io !== void 0 && Object.keys(io).length > 0;
+}
+/** Quiet programmatic boundary: capture output and the failure escaping the complete lifecycle. */
+async function runInvocation(node, input, io, materializeCommandDefinition) {
+	const stdout = [];
+	const stderr = [];
+	try {
+		const sinks = { ...io };
+		const resolvedIO = {
+			stdout(text) {
+				stdout.push(text);
+				sinks.stdout?.(text);
+			},
+			stderr(text) {
+				stderr.push(text);
+				sinks.stderr?.(text);
+			}
+		};
+		return {
+			...await withAmbientTerminalIO(resolvedIO, async () => {
+				return await dispatch(input, prepareInvocation(node, materializeCommandDefinition), resolvedIO);
+			}),
+			stdout: stdout.join("\n"),
+			stderr: stderr.join("\n")
+		};
+	} catch (error) {
+		return {
+			status: "failed",
+			error,
+			stdout: stdout.join("\n"),
+			stderr: stderr.join("\n")
+		};
+	}
+}
+/** Terminal CLI boundary: render failures and set the process exit status. */
+async function executeInvocation(node, options, materializeCommandDefinition) {
+	const argv = options?.argv ?? process.argv.slice(2);
+	const io = {
+		...DEFAULT_IO,
+		...options?.io
+	};
+	const snapshotPath = process.env[SNAPSHOT_PATH_ENV];
+	if (snapshotPath) {
+		try {
+			const base = buildExtensionTree(node, materializeCommandDefinition);
+			const takeSnapshot = () => snapshotCommand(applySectionsAndFreeze(cloneCommandNode(base.rootNode), base.extensions));
+			let snapshot = takeSnapshot();
+			const buildOutDir = process.env[BUILD_OUT_DIR_ENV];
+			if (buildOutDir) {
+				const extensions = [];
+				for (const extension of base.extensions) {
+					if (!extension.build) continue;
+					try {
+						const artifacts = await extension.build({
+							snapshot,
+							outDir: buildOutDir
+						});
+						extensions.push({
+							id: extension.id,
+							files: artifacts === void 0 ? "unknown" : artifacts.map(normalizeArtifactPath)
+						});
+					} catch (error) {
+						const message = error instanceof Error ? error.message : String(error);
+						throw new Error(`Extension "${extension.id}" build failed: ${message}`, { cause: error });
+					}
+					snapshot = takeSnapshot();
+				}
+				await writeFile(join(dirname(snapshotPath), "build-report.json"), JSON.stringify({ extensions }));
+			}
+			await writeFile(snapshotPath, JSON.stringify(snapshot));
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			console.error(message);
+			return process.exit(1);
+		}
+		return process.exit(0);
+	}
+	const invoke = async () => {
+		let prepared;
+		try {
+			prepared = prepareInvocation(node, materializeCommandDefinition);
+		} catch (error) {
+			if (isAbortError(error)) {
+				process.exitCode = EXIT_CODE_CANCELLED;
+				return EXIT_CODE_CANCELLED;
+			}
+			const message = error instanceof Error ? error.message : String(error);
+			io.stderr(`Error: ${message}`);
+			process.exitCode = 1;
+			return 1;
+		}
+		let extensionContext;
+		let renderedInDispatch = false;
+		try {
+			await dispatch({ argv }, prepared, io, (context) => {
+				extensionContext = context;
+			}, async (error, context) => {
+				renderedInDispatch = true;
+				const cancelled = isAbortError(error);
+				process.exitCode = cancelled ? EXIT_CODE_CANCELLED : 1;
+				return renderFailure(error, argv, prepared, io, context, cancelled);
+			});
+		} catch (error) {
+			if (isAbortError(error)) {
+				if (!renderedInDispatch) await renderFailure(error, argv, prepared, io, extensionContext, true);
+				process.exitCode = EXIT_CODE_CANCELLED;
+				return EXIT_CODE_CANCELLED;
+			}
+			process.exitCode = 1;
+			if (!renderedInDispatch) await renderFailure(error, argv, prepared, io, extensionContext);
+			return 1;
+		}
+		return 0;
+	};
+	return await (hasInjectedIO(options?.io) ? withAmbientTerminalIO(io, invoke) : invoke());
+}
+//#endregion
+export { definingOf as _, runInvocation as a, normalizeFlag as b, sectionsFor as c, installExtensionContexts as d, validateCommandSections as f, defineContext as g, defineExtension as h, prepareInvocation as i, visibleSectionsFor as l, registerFlag as m, SNAPSHOT_PATH_ENV as n, snapshotCommand as o, createCommandNode as p, executeInvocation as r, isListed as s, BUILD_OUT_DIR_ENV as t, cloneCommandNode as u, validateContextAvailability as v, CrustError as x, normalizeArg as y };