@optique/discover 1.2.0-dev.2169 → 1.2.0-dev.2179

package/dist/src-Ci75oZo-.js

@@ -0,0 +1,754 @@
+import { isCommand } from "./command-DO5zgkvS.js";
+import { longestMatch, or } from "@optique/core/constructs";
+import { map } from "@optique/core/modifiers";
+import { command } from "@optique/core/primitives";
+import { runAsync } from "@optique/run";
+import process from "node:process";
+import { readdir, realpath, stat } from "node:fs/promises";
+import { posix, relative, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { dispatchByMode, inheritAnnotations, mapModeValue, wrapForMode } from "@optique/core/extension";
+import { mergeHidden } from "@optique/core/usage";
+
+//#region src/index.ts
+/**
+* Returns runtime-aware command module suffixes.
+*
+* @param options Runtime detection overrides for testing or custom launchers.
+* @returns File suffixes to scan.
+* @since 1.1.0
+*/
+function getDefaultExtensions(options = {}) {
+	const runtime = options.runtime ?? getRuntime();
+	if (runtime === "deno" || runtime === "bun") return [
+		".ts",
+		".mts",
+		".js",
+		".mjs"
+	];
+	const extensions = [
+		".js",
+		".mjs",
+		".cjs"
+	];
+	if (hasNodeTypeScriptLoader(options.execArgv ?? process.execArgv, options.nodeOptions ?? process.env.NODE_OPTIONS ?? "", options.nodeTypeScriptSupport ?? hasNativeNodeTypeScriptSupport())) extensions.push(".ts", ".mts", ".cts");
+	return extensions;
+}
+/**
+* Discovers command modules under a directory.
+*
+* @param options Discovery options.
+* @returns Discovered commands sorted by command path.
+* @throws {TypeError} If options are invalid, discovery finds no commands,
+*         command paths are duplicated, or a module does not default-export
+*         a command created with `defineCommand()`.
+* @since 1.1.0
+*/
+async function discoverCommands(options) {
+	const dir = pathFromDir(options.dir);
+	const extensions = normalizeExtensions(options.extensions ?? getDefaultExtensions());
+	const entryFileName = normalizeEntryFileName(options.entryFileName);
+	const files = await collectCommandFiles(dir, extensions);
+	if (files.length < 1) throw new TypeError(`No command modules found in ${dir}.`);
+	const seen = /* @__PURE__ */ new Map();
+	const discovered = [];
+	for (const filePath of files) {
+		const path = commandPathFromFile(dir, filePath, extensions, entryFileName);
+		const key = commandPathKey(path);
+		const previous = seen.get(key);
+		if (previous != null) {
+			const displayPath = displayCommandPath(path);
+			throw new TypeError(`Duplicate command path "${displayPath}" from ${previous} and ${filePath}.`);
+		}
+		seen.set(key, filePath);
+		const mod = await import(pathToFileURL(filePath).href);
+		const commandDefinition = commandFromModuleExport(filePath, mod.default);
+		validateDeclaredCommandPath(commandDefinition, path, filePath, "file path");
+		discovered.push({
+			path,
+			filePath,
+			command: commandDefinition
+		});
+	}
+	return sortCommands(discovered);
+}
+/**
+* Converts a static module map into command entries.
+*
+* This is useful for bundlers and single-file packagers that can statically
+* see module maps, such as `import.meta.glob(..., { eager: true })`, while
+* still deriving command paths from file-like module keys.
+*
+* @param modules Static module map keyed by module path.
+* @param options Module path derivation options.
+* @returns Command entries sorted by command path.
+* @throws {TypeError} If options are invalid, no command modules are found,
+*         command paths are duplicated, a module does not default-export a
+*         command created with `defineCommand()`, or an explicit command
+*         `path` does not match the module-derived path.
+* @since 1.2.0
+*/
+function commandsFromModules(modules, options = {}) {
+	if (modules == null || typeof modules !== "object") throw new TypeError("commandsFromModules() requires a module map object.");
+	const base = normalizeModuleBase(options.base);
+	const extensions = normalizeExtensions(options.extensions ?? getDefaultExtensions());
+	const entryFileName = normalizeEntryFileName(options.entryFileName);
+	const modulePaths = Object.keys(modules).toSorted((a, b) => a.localeCompare(b));
+	const seen = /* @__PURE__ */ new Map();
+	const discovered = [];
+	for (const modulePath of modulePaths) {
+		if (isDeclarationFile(posix.basename(modulePath)) || !extensions.some((ext) => modulePath.endsWith(ext))) continue;
+		const path = commandPathFromModulePath(base, modulePath, extensions, entryFileName);
+		const key = commandPathKey(path);
+		const previous = seen.get(key);
+		if (previous != null) {
+			const displayPath = displayCommandPath(path);
+			throw new TypeError(`Duplicate command path "${displayPath}" from ${previous} and ${modulePath}.`);
+		}
+		seen.set(key, modulePath);
+		const commandDefinition = commandFromModuleExport(modulePath, modules[modulePath]);
+		validateDeclaredCommandPath(commandDefinition, path, modulePath, "module path");
+		discovered.push({
+			path,
+			modulePath,
+			command: commandDefinition
+		});
+	}
+	if (discovered.length < 1) throw new TypeError("No command modules found in module map.");
+	return sortCommands(discovered);
+}
+/**
+* Builds a parser that dispatches to discovered command handlers.
+*
+* @param commands Commands to compose.
+* @param metadata Optional root documentation metadata.
+* @returns A parser that resolves to an internal command invocation.
+* @throws {TypeError} If no commands are provided or command paths are
+*         duplicated.
+* @since 1.1.0
+*/
+function createProgramParser(commands, metadata = {}) {
+	if (commands.length < 1) throw new TypeError("createProgramParser() requires at least one command.");
+	const sortedCommands = sortCommands(commands);
+	rejectDuplicatePaths(sortedCommands.map((entry) => ({
+		path: entry.path,
+		filePath: displayCommandPath(entry.path)
+	})));
+	const rootNode = buildCommandTree(sortedCommands);
+	const parser = buildNodeParser(rootNode);
+	return withRootDocs(parser, sortedCommands, metadata);
+}
+/**
+* Discovers and runs a command program.
+*
+* @param options Program options.
+* @returns A promise that resolves after the selected command handler
+*          completes.
+* @throws {TypeError} If discovery or command loading fails.
+* @since 1.1.0
+*/
+async function runProgram(options) {
+	let commands;
+	if (isStaticRunProgramOptions(options)) commands = staticCommandsToEntries(options.commands);
+	else commands = await discoverCommands({
+		dir: options.dir,
+		extensions: options.extensions,
+		entryFileName: options.entryFileName
+	});
+	const parser = createProgramParser(commands, options.metadata);
+	const invocation = await runAsync(parser, buildRunOptions(options));
+	await invocation.handler(invocation.value);
+}
+function getRuntime() {
+	if ("Deno" in globalThis) return "deno";
+	if ("Bun" in globalThis) return "bun";
+	return "node";
+}
+function hasNodeTypeScriptLoader(execArgv, nodeOptions, nativeSupport) {
+	const haystack = [...execArgv, nodeOptions].join(" ");
+	return nativeSupport || /\b(?:tsx|ts-node|tsimp|jiti)\b/.test(haystack) || /--(?:experimental-)?transform-types\b/.test(haystack) || /--experimental-strip-types\b/.test(haystack);
+}
+function hasNativeNodeTypeScriptSupport() {
+	const features = process.features;
+	return features?.typescript === "strip" || features?.typescript === "transform";
+}
+function pathFromDir(dir) {
+	return typeof dir === "string" ? resolve(dir) : fileURLToPath(dir);
+}
+function normalizeExtensions(extensions) {
+	if (extensions.length < 1) throw new TypeError("At least one command file extension is required.");
+	const normalized = [];
+	for (const extension of extensions) {
+		if (!extension.startsWith(".") || extension.length < 2) throw new TypeError(`Command file extension must start with a dot: ${extension}`);
+		if (!normalized.includes(extension)) normalized.push(extension);
+	}
+	return normalized.toSorted((a, b) => b.length - a.length || a.localeCompare(b));
+}
+function normalizeEntryFileName(entryFileName) {
+	if (entryFileName === void 0) return "index";
+	if (entryFileName === false) return false;
+	if (typeof entryFileName !== "string") throw new TypeError(`Command entry file name must be a non-empty file name: ${entryFileName}`);
+	const normalized = entryFileName;
+	if (normalized.length < 1 || normalized.includes("/") || normalized.includes("\\")) throw new TypeError(`Command entry file name must be a non-empty file name: ${normalized}`);
+	return normalized;
+}
+function normalizeModuleBase(base) {
+	if (base === void 0) return ".";
+	if (typeof base !== "string" || base.length < 1) throw new TypeError(`Module base path must be a non-empty string: ${base}`);
+	return normalizeModulePath(base);
+}
+async function collectCommandFiles(dir, extensions, activeDirs = /* @__PURE__ */ new Set()) {
+	const canonicalDir = await realpath(dir);
+	if (activeDirs.has(canonicalDir)) return [];
+	const nextActiveDirs = new Set(activeDirs);
+	nextActiveDirs.add(canonicalDir);
+	const entries = await readdir(dir, { withFileTypes: true });
+	const files = [];
+	for (const entry of entries.toSorted((a, b) => a.name.localeCompare(b.name))) {
+		const path = resolve(dir, entry.name);
+		const entryType = await getCommandFileEntryType(path, entry);
+		if (entryType === "directory") files.push(...await collectCommandFiles(path, extensions, nextActiveDirs));
+		else if (entryType === "file" && !isDeclarationFile(entry.name) && extensions.some((ext) => entry.name.endsWith(ext))) files.push(path);
+	}
+	return files;
+}
+async function getCommandFileEntryType(path, entry) {
+	if (entry.isDirectory()) return "directory";
+	if (entry.isFile()) return "file";
+	if (!entry.isSymbolicLink()) return void 0;
+	try {
+		const target = await stat(path);
+		if (target.isDirectory()) return "directory";
+		if (target.isFile()) return "file";
+		return void 0;
+	} catch {
+		return void 0;
+	}
+}
+function isDeclarationFile(fileName) {
+	return /\.d\.[cm]?ts$/.test(fileName);
+}
+function commandPathFromFile(rootDir, filePath, extensions, entryFileName) {
+	const withoutExtension = stripCommandExtension(filePath, extensions);
+	const relativePath = relative(rootDir, withoutExtension);
+	const path = relativePath.split(sep).filter((segment) => segment.length > 0);
+	return commandPathFromSegments(path, filePath, entryFileName);
+}
+function commandPathFromModulePath(base, modulePath, extensions, entryFileName) {
+	const withoutExtension = stripCommandExtension(modulePath, extensions);
+	const relativePath = relativeModulePath(base, withoutExtension, modulePath);
+	const path = relativePath.split("/").filter((segment) => segment.length > 0);
+	return commandPathFromSegments(path, modulePath, entryFileName);
+}
+function stripCommandExtension(path, extensions) {
+	const matchedExtension = extensions.find((ext) => path.endsWith(ext));
+	if (matchedExtension == null) throw new TypeError(`No configured extension matches ${path}.`);
+	return path.slice(0, -matchedExtension.length);
+}
+function relativeModulePath(base, modulePath, originalModulePath) {
+	const normalizedPath = normalizeModulePath(modulePath);
+	const relativePath = posix.relative(base, normalizedPath);
+	if (relativePath.length < 1 || relativePath === ".." || relativePath.startsWith("../") || posix.isAbsolute(relativePath)) throw new TypeError(`Module path ${originalModulePath} is not under base path ${base}.`);
+	return relativePath;
+}
+function normalizeModulePath(path) {
+	return posix.normalize(path.replaceAll("\\", "/"));
+}
+function commandPathFromSegments(path, source, entryFileName) {
+	if (path.length < 1) throw new TypeError(`Command module ${source} does not define a path.`);
+	if (entryFileName !== false && path[path.length - 1] === entryFileName) return path.slice(0, -1);
+	return path;
+}
+function commandPathKey(path) {
+	return path.join("\0");
+}
+function displayCommandPath(path) {
+	return path.length < 1 ? "<root>" : path.join(" ");
+}
+function isCommandPath(path) {
+	return Array.isArray(path) && path.every((segment) => typeof segment === "string" && segment.length > 0);
+}
+function rejectDuplicatePaths(commands) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const entry of commands) {
+		const key = commandPathKey(entry.path);
+		const previous = seen.get(key);
+		if (previous != null) {
+			const displayPath = displayCommandPath(entry.path);
+			throw new TypeError(`Duplicate command path "${displayPath}" from ${previous} and ${entry.filePath}.`);
+		}
+		seen.set(key, entry.filePath);
+	}
+}
+function sortCommands(commands) {
+	return commands.toSorted((a, b) => commandPathKey(a.path).localeCompare(commandPathKey(b.path)));
+}
+function isStaticRunProgramOptions(options) {
+	const hasCommands = "commands" in options && options.commands != null;
+	const hasDir = "dir" in options && options.dir != null;
+	if (hasCommands === hasDir) throw new TypeError("runProgram() requires exactly one of dir or commands.");
+	return hasCommands;
+}
+function staticCommandsToEntries(commands) {
+	return commands.map((entry) => {
+		if (isCommandEntry(entry)) return entry;
+		if (!isCommand(entry)) throw new TypeError("Static command entries must be created with defineCommand().");
+		if (!isCommandPath(entry.path)) throw new TypeError("Static command entries must declare a path.");
+		return {
+			path: entry.path,
+			command: entry
+		};
+	});
+}
+function isCommandEntry(value) {
+	return value != null && typeof value === "object" && isCommandPath(value.path) && isCommand(value.command);
+}
+function unwrapCommandExport(value) {
+	let current = value;
+	for (let depth = 0; depth < 3; depth++) {
+		if (isCommand(current)) return current;
+		if (current == null || typeof current !== "object") return void 0;
+		const nestedDefault = current.default;
+		if (Object.is(nestedDefault, current)) return void 0;
+		current = nestedDefault;
+	}
+	return void 0;
+}
+function commandFromModuleExport(source, value) {
+	const commandDefinition = unwrapCommandExport(value);
+	if (commandDefinition == null) throw new TypeError(`Module ${source} default export must be created with defineCommand().`);
+	return commandDefinition;
+}
+function validateDeclaredCommandPath(commandDefinition, path, source, sourcePathLabel) {
+	if (commandDefinition.path != null && commandPathKey(commandDefinition.path) !== commandPathKey(path)) throw new TypeError(`Module ${source} declares command path "${displayCommandPath(commandDefinition.path)}" but ${sourcePathLabel} defines "${displayCommandPath(path)}".`);
+}
+function buildCommandTree(commands) {
+	const root = { children: /* @__PURE__ */ new Map() };
+	for (const entry of commands) {
+		let current = root;
+		for (const segment of entry.path) {
+			let child = current.children.get(segment);
+			if (child == null) {
+				child = { children: /* @__PURE__ */ new Map() };
+				current.children.set(segment, child);
+			}
+			current = child;
+		}
+		current.command = entry.command;
+	}
+	return root;
+}
+function buildNodeParser(node, inheritedHidden) {
+	const childParser = buildChildrenParser(node, inheritedHidden);
+	if (childParser != null && node.command != null) return createExecutableNodeParser(childParser, node.command);
+	if (childParser != null) return childParser;
+	if (node.command != null) return createLeafParser(node.command);
+	throw new TypeError("Command tree node must contain a command.");
+}
+function createExecutableNodeParser(childParser, commandDefinition) {
+	const leafParser = createLeafParser(commandDefinition, true);
+	const branchParsers = [childParser, leafParser];
+	const parser = longestMatch(childParser, leafParser);
+	const phase2SeedHook = findPhase2SeedHook(parser);
+	const executableParser = {
+		...parser,
+		$valueType: [],
+		$stateType: [],
+		initialState: void 0,
+		parse(context) {
+			const activeState = normalizeExecutableNodeState(context.state);
+			if (activeState?.committed === true && activeState.result.success) {
+				const branchParser = branchParsers[activeState.branch];
+				const result$1 = branchParser.parse(withExecutableNodeChildContext(context, activeState.branch, inheritAnnotations(context.state, activeState.result.next.state), branchParser));
+				return mapModeValue(parser.mode, wrapForMode(parser.mode, result$1), (resolved) => wrapBranchParseResult(context, activeState, resolved));
+			}
+			const result = parser.parse({
+				...context,
+				state: toExclusiveState(activeState, context.state)
+			});
+			return mapModeValue(parser.mode, wrapForMode(parser.mode, result), (resolved) => wrapInitialParseResult(context, resolved));
+		},
+		complete(state, exec) {
+			const activeState = normalizeExecutableNodeState(state);
+			if (activeState?.result.success === true) return wrapForMode(parser.mode, branchParsers[activeState.branch].complete(inheritAnnotations(state, activeState.result.next.state), withExecutableNodeChildExecPath(exec, activeState.branch)));
+			if (activeState == null) return wrapForMode(parser.mode, completeExecutableNodeLeaf(state, exec, leafParser));
+			return wrapForMode(parser.mode, parser.complete(toExclusiveState(activeState, state), exec));
+		},
+		suggest(context, prefix) {
+			const activeState = normalizeExecutableNodeState(context.state);
+			if (activeState?.committed === true && activeState.result.success) {
+				const branchParser = branchParsers[activeState.branch];
+				return branchParser.suggest(withExecutableNodeChildContext(context, activeState.branch, inheritAnnotations(context.state, activeState.result.next.state), branchParser), prefix);
+			}
+			return parser.suggest({
+				...context,
+				state: toExclusiveState(activeState, context.state)
+			}, prefix);
+		},
+		getSuggestRuntimeNodes(state, path) {
+			const activeState = normalizeExecutableNodeState(state);
+			if (activeState == null) {
+				const branchPath$1 = [...path, 1];
+				const branchState$1 = inheritAnnotations(state, leafParser.initialState);
+				return getExecutableNodeBranchSuggestRuntimeNodes(leafParser, branchState$1, branchPath$1);
+			}
+			if (activeState?.result.success !== true) return parser.getSuggestRuntimeNodes?.(toExclusiveState(activeState, state), path) ?? [];
+			const branchParser = branchParsers[activeState.branch];
+			const branchPath = [...path, activeState.branch];
+			const branchState = inheritAnnotations(state, activeState.result.next.state);
+			return getExecutableNodeBranchSuggestRuntimeNodes(branchParser, branchState, branchPath);
+		},
+		getDocFragments(state, defaultValue) {
+			const activeState = state.kind === "available" ? normalizeExecutableNodeState(state.state) : void 0;
+			const fragments = parser.getDocFragments(state.kind === "available" ? {
+				kind: "available",
+				state: toExclusiveState(activeState, state.state)
+			} : state, defaultValue);
+			if (activeState == null) return withCommandDocMetadata(fragments, commandDefinition.metadata);
+			return fragments;
+		}
+	};
+	if (phase2SeedHook != null) Object.defineProperty(executableParser, phase2SeedHook.key, {
+		value(state, exec) {
+			return extractExecutableNodePhase2Seed(state, exec, leafParser, phase2SeedHook);
+		},
+		configurable: true,
+		enumerable: true
+	});
+	return executableParser;
+}
+function getExecutableNodeBranchSuggestRuntimeNodes(parser, state, path) {
+	return parser.getSuggestRuntimeNodes?.(state, path) ?? (parser.dependencyMetadata?.source != null ? [{
+		path,
+		parser,
+		state
+	}] : []);
+}
+const phase2SeedSymbolDescription = "@optique/core/extractPhase2Seed";
+function findPhase2SeedHook(parser) {
+	for (const key of Object.getOwnPropertySymbols(parser)) {
+		if (key.description !== phase2SeedSymbolDescription) continue;
+		const value = Reflect.get(parser, key);
+		if (typeof value !== "function") continue;
+		return {
+			key,
+			extract(state, exec) {
+				const seed = Reflect.apply(value, parser, [state, exec]);
+				return seed;
+			}
+		};
+	}
+	return void 0;
+}
+function completeExecutableNodeLeaf(state, exec, leafParser) {
+	const result = parseExecutableNodeLeaf(state, exec, leafParser);
+	return dispatchByMode(leafParser.mode, () => wrapForMode("sync", completeParsedExecutableNodeLeaf(state, exec, leafParser, wrapForMode("sync", result))), () => Promise.resolve(wrapForMode("async", result)).then((resolved) => wrapForMode("async", completeParsedExecutableNodeLeaf(state, exec, leafParser, resolved))));
+}
+function completeParsedExecutableNodeLeaf(state, exec, leafParser, result) {
+	const childExec = withExecutableNodeChildExecPath(exec, 1);
+	const nextExec = result.success ? mergeExecutableNodeChildExec(childExec, result.next.exec) : childExec;
+	const nextState = result.success ? inheritAnnotations(state, result.next.state) : inheritAnnotations(state, leafParser.initialState);
+	return leafParser.complete(nextState, nextExec);
+}
+function extractExecutableNodePhase2Seed(state, exec, leafParser, phase2SeedHook) {
+	const activeState = normalizeExecutableNodeState(state);
+	if (activeState != null) return phase2SeedHook.extract(toExclusiveState(activeState, state), exec);
+	const result = parseExecutableNodeLeaf(state, exec, leafParser);
+	return dispatchByMode(leafParser.mode, () => extractParsedExecutableNodePhase2Seed(state, exec, wrapForMode("sync", result), phase2SeedHook), () => Promise.resolve(wrapForMode("async", result)).then((resolved) => extractParsedExecutableNodePhase2Seed(state, exec, resolved, phase2SeedHook)));
+}
+function extractParsedExecutableNodePhase2Seed(state, exec, result, phase2SeedHook) {
+	if (!result.success) return phase2SeedHook.extract(toExclusiveState(void 0, state), exec);
+	const executableState = inheritAnnotations(state, {
+		branch: 1,
+		result,
+		committed: false
+	});
+	return phase2SeedHook.extract(toExclusiveState(executableState, state), exec);
+}
+function parseExecutableNodeLeaf(state, exec, leafParser) {
+	const childExec = withExecutableNodeChildExecPath(exec, 1);
+	const childContext = {
+		buffer: [],
+		optionsTerminated: false,
+		usage: leafParser.usage,
+		state: inheritAnnotations(state, leafParser.initialState),
+		...childExec != null ? {
+			exec: childExec,
+			dependencyRegistry: childExec.dependencyRegistry
+		} : {}
+	};
+	return leafParser.parse(childContext);
+}
+function normalizeExecutableNodeState(state) {
+	if (state == null || typeof state !== "object" || !("branch" in state) || !("result" in state)) return void 0;
+	const branch = state.branch;
+	if (branch !== 0 && branch !== 1) return void 0;
+	const result = state.result;
+	if (result == null || typeof result !== "object" || typeof result.success !== "boolean") return void 0;
+	return inheritAnnotations(state, {
+		branch,
+		result,
+		committed: state.committed === true
+	});
+}
+function toExclusiveState(state, sourceState = state) {
+	const exclusiveState = state == null ? void 0 : [state.branch, state.result];
+	return inheritAnnotations(sourceState, exclusiveState);
+}
+function fromExclusiveState(state) {
+	if (!Array.isArray(state) || state.length !== 2 || state[0] !== 0 && state[0] !== 1) return void 0;
+	return inheritAnnotations(state, {
+		branch: state[0],
+		result: state[1],
+		committed: isCommittedResult(state[1])
+	});
+}
+function isCommittedResult(result) {
+	return result != null && typeof result === "object" && result.success === true && Array.isArray(result.consumed) && result.consumed.length > 0;
+}
+function wrapInitialParseResult(_context, result) {
+	if (!result.success) return result;
+	return {
+		success: true,
+		consumed: result.consumed,
+		provisional: result.provisional,
+		next: {
+			...result.next,
+			state: fromExclusiveState(result.next.state)
+		}
+	};
+}
+function wrapBranchParseResult(context, activeState, result) {
+	if (!result.success) return result;
+	const mergedExec = mergeExecutableNodeChildExec(context.exec, result.next.exec);
+	const dependencyRegistry = mergedExec?.dependencyRegistry ?? result.next.dependencyRegistry ?? context.dependencyRegistry;
+	const nextState = inheritAnnotations(result.next.state, {
+		branch: activeState.branch,
+		result,
+		committed: activeState.committed || result.consumed.length > 0
+	});
+	return {
+		success: true,
+		consumed: result.consumed,
+		provisional: result.provisional,
+		next: {
+			...context,
+			buffer: result.next.buffer,
+			optionsTerminated: result.next.optionsTerminated,
+			state: inheritAnnotations(context.state, nextState),
+			...mergedExec != null ? {
+				exec: mergedExec,
+				trace: mergedExec.trace
+			} : {},
+			...dependencyRegistry != null ? { dependencyRegistry } : {}
+		}
+	};
+}
+function withExecutableNodeChildContext(context, branch, state, parser) {
+	const exec = withExecutableNodeChildExecPath(context.exec, branch);
+	const dependencyRegistry = context.dependencyRegistry ?? exec?.dependencyRegistry;
+	return {
+		...context,
+		state,
+		usage: parser.usage,
+		...exec != null ? {
+			exec: dependencyRegistry === exec.dependencyRegistry ? exec : {
+				...exec,
+				dependencyRegistry
+			},
+			dependencyRegistry
+		} : {}
+	};
+}
+function withExecutableNodeChildExecPath(exec, branch) {
+	if (exec == null) return void 0;
+	return {
+		...exec,
+		path: [...exec.path ?? [], branch]
+	};
+}
+function mergeExecutableNodeChildExec(parent, child) {
+	if (parent == null) return child;
+	if (child == null) return parent;
+	return {
+		...parent,
+		trace: child.trace ?? parent.trace,
+		dependencyRuntime: child.dependencyRuntime ?? parent.dependencyRuntime,
+		dependencyRegistry: child.dependencyRegistry ?? parent.dependencyRegistry,
+		commandPath: child.commandPath ?? parent.commandPath,
+		preCompletedByParser: child.preCompletedByParser ?? parent.preCompletedByParser,
+		excludedSourceFields: child.excludedSourceFields ?? parent.excludedSourceFields
+	};
+}
+function withCommandDocMetadata(fragments, metadata) {
+	if (metadata == null) return fragments;
+	return {
+		...fragments,
+		brief: fragments.brief ?? metadata.brief,
+		description: fragments.description ?? metadata.description,
+		footer: fragments.footer ?? metadata.footer
+	};
+}
+function buildChildrenParser(node, inheritedHidden) {
+	const parsers = [];
+	for (const [name, child] of node.children) {
+		const childHidden = mergeHidden(inheritedHidden, child.command?.metadata?.hidden);
+		const childParser = buildNodeParser(child, childHidden);
+		if (child.children.size > 0) parsers.push(createNamespaceCommandParser(name, childParser, child.command, inheritedHidden));
+		else parsers.push(command(name, childParser, commandMetadataWithInheritedHidden(child.command?.metadata, inheritedHidden)));
+	}
+	if (parsers.length < 1) return void 0;
+	if (parsers.length === 1) return parsers[0];
+	return or(...parsers);
+}
+function createNamespaceCommandParser(name, childParser, commandDefinition, inheritedHidden) {
+	const metadata = commandDefinition?.metadata;
+	const parser = command(name, childParser, namespaceCommandMetadata(metadata, inheritedHidden));
+	const description = metadata?.brief ?? metadata?.description;
+	if (description == null) return parser;
+	return {
+		...parser,
+		getDocFragments(state, defaultValue) {
+			const fragments = parser.getDocFragments(state, defaultValue);
+			if (state.kind !== "unavailable" && (state.kind !== "available" || !Object.is(state.state, parser.initialState))) return fragments;
+			return withNamespaceListDocDescription(fragments, name, description);
+		}
+	};
+}
+function withNamespaceListDocDescription(fragments, name, description) {
+	return {
+		...fragments,
+		fragments: fragments.fragments.map((fragment) => {
+			if (fragment.type !== "entry" || fragment.term.type !== "command" || fragment.term.name !== name) return fragment;
+			return {
+				...fragment,
+				description: fragment.description ?? description
+			};
+		})
+	};
+}
+function namespaceCommandMetadata(metadata, inheritedHidden) {
+	const hidden = mergeHidden(inheritedHidden, metadata?.hidden);
+	if (metadata?.aliases == null && metadata?.errors == null && hidden == null && metadata?.usageLine == null) return void 0;
+	return {
+		...metadata?.aliases != null && { aliases: metadata.aliases },
+		...metadata?.errors != null && { errors: metadata.errors },
+		...hidden != null && { hidden },
+		...metadata?.usageLine != null && { usageLine: metadata.usageLine }
+	};
+}
+function commandMetadataWithInheritedHidden(metadata, inheritedHidden) {
+	const hidden = mergeHidden(inheritedHidden, metadata?.hidden);
+	if (metadata == null) return hidden == null ? void 0 : { hidden };
+	if (hidden === metadata.hidden) return metadata;
+	return {
+		...metadata,
+		...hidden != null && { hidden }
+	};
+}
+function createLeafParser(commandDefinition, includeMetadata = false) {
+	const parser = map(commandDefinition.parser, (value) => ({
+		command: commandDefinition,
+		value,
+		handler: commandDefinition.handler
+	}));
+	if (!includeMetadata) return parser;
+	return {
+		...parser,
+		getDocFragments(state, defaultValue) {
+			const fragments = parser.getDocFragments(state, defaultValue);
+			return withCommandDocMetadata(fragments, commandDefinition.metadata);
+		}
+	};
+}
+function withRootDocs(parser, commands, metadata) {
+	const rootState = parser.initialState;
+	const rootCommand = commands.find((entry) => entry.path.length < 1);
+	const listedCommands = commands.filter((entry) => entry.path.length > 0);
+	const commandsByPath = new Map(commands.map((entry) => [commandPathKey(entry.path), entry.command]));
+	const rootDocs = () => {
+		const fragments = [...rootCommand?.command.parser.getDocFragments({ kind: "unavailable" }).fragments ?? []];
+		if (listedCommands.length > 0) fragments.push({
+			type: "section",
+			entries: listedCommands.map((entry) => ({
+				term: {
+					type: "command",
+					name: entry.path.join(" "),
+					hidden: commandPathHidden(entry.path, commandsByPath)
+				},
+				description: entry.command.metadata?.brief ?? entry.command.metadata?.description
+			}))
+		});
+		return {
+			brief: metadata.brief,
+			description: metadata.description,
+			footer: metadata.footer,
+			fragments
+		};
+	};
+	return {
+		...parser,
+		getDocFragments(state, defaultValue) {
+			if (state.kind === "unavailable" || state.kind === "available" && Object.is(state.state, rootState)) return rootDocs();
+			return parser.getDocFragments(state, defaultValue);
+		}
+	};
+}
+function commandPathHidden(path, commandsByPath) {
+	let hidden;
+	for (let length = 1; length <= path.length; length++) hidden = mergeHidden(hidden, commandsByPath.get(commandPathKey(path.slice(0, length)))?.metadata?.hidden);
+	return hidden;
+}
+function buildRunOptions(options) {
+	const metadata = options.metadata;
+	const { dir: _dir, commands: _commands, extensions: _extensions, entryFileName: _entryFileName, metadata: _metadata, help, version, completion,...rest } = options;
+	const runOptions = {
+		...rest,
+		contexts: unwrapProgramContexts(rest.contexts),
+		programName: options.programName ?? metadata.name,
+		brief: options.brief ?? metadata.brief,
+		description: options.description ?? metadata.description,
+		examples: options.examples ?? metadata.examples,
+		author: options.author ?? metadata.author,
+		bugs: options.bugs ?? metadata.bugs,
+		footer: options.footer ?? metadata.footer,
+		help: help === false ? void 0 : help ?? "both",
+		version: version === false ? void 0 : version ?? (metadata.version == null ? void 0 : metadata.version),
+		completion: completion === false ? void 0 : completion ?? "both"
+	};
+	return runOptions;
+}
+function unwrapProgramContexts(contexts) {
+	if (contexts == null) return void 0;
+	return contexts.map(wrapProgramContext);
+}
+function wrapProgramContext(context) {
+	const wrapped = {
+		id: context.id,
+		phase: context.phase,
+		getAnnotations(request, options) {
+			return context.getAnnotations(unwrapProgramContextRequest(request), options);
+		}
+	};
+	if (context.getInternalAnnotations != null) wrapped.getInternalAnnotations = (request, annotations) => {
+		return context.getInternalAnnotations(unwrapProgramContextRequest(request) ?? request, annotations);
+	};
+	if (context[Symbol.dispose] != null) wrapped[Symbol.dispose] = () => context[Symbol.dispose]();
+	if (context[Symbol.asyncDispose] != null) wrapped[Symbol.asyncDispose] = () => context[Symbol.asyncDispose]();
+	return wrapped;
+}
+function unwrapProgramContextRequest(request) {
+	if (request?.phase === "phase2" && isProgramInvocation(request.parsed)) return {
+		phase: "phase2",
+		parsed: request.parsed.value
+	};
+	return request;
+}
+function isProgramInvocation(value) {
+	if (value == null || typeof value !== "object") return false;
+	const candidate = value;
+	return "value" in value && isCommand(candidate.command) && typeof candidate.handler === "function";
+}
+
+//#endregion
+export { commandsFromModules, createProgramParser, discoverCommands, getDefaultExtensions, runProgram };