@optique/discover 1.1.0 → 1.2.0-dev.2167

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-2HtR3-TV.cjs";
+import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-DSHBTa5c.cjs";
 import { Mode, Parser } from "@optique/core/parser";
 import { Message } from "@optique/core/message";
 import { ProgramMetadata } from "@optique/core/program";
@@ -64,6 +64,16 @@ interface DiscoverCommandsOptions {
    * @default Runtime-aware extension defaults from {@link getDefaultExtensions}
    */
   readonly extensions?: readonly string[];
+  /**
+   * File name that maps to the containing command path after extension
+   * stripping.  For example, `stash/index.ts` maps to `stash`, and root
+   * `index.ts` maps to the root command.  Pass `false` to treat matching files
+   * as ordinary command names.
+   *
+   * @default `"index"`
+   * @since 1.2.0
+   */
+  readonly entryFileName?: string | false;
 }
 /**
  * Runtime hint for {@link getDefaultExtensions}.
@@ -134,6 +144,14 @@ interface RunProgramDiscoveryOptions extends RunProgramBaseOptions {
    * File suffixes to include during discovery.
    */
   readonly extensions?: readonly string[];
+  /**
+   * File name that maps to the containing command path after extension
+   * stripping.
+   *
+   * @default `"index"`
+   * @since 1.2.0
+   */
+  readonly entryFileName?: string | false;
   /**
    * Static commands cannot be used together with `dir`.
    */
@@ -157,6 +175,10 @@ interface RunProgramStaticOptions extends RunProgramBaseOptions {
    * File suffixes are only used with file-system discovery.
    */
   readonly extensions?: never;
+  /**
+   * Entry file names are only used with file-system discovery.
+   */
+  readonly entryFileName?: never;
 }
 /**
  * Options for {@link runProgram}.
@@ -178,8 +200,8 @@ declare function getDefaultExtensions(options?: RuntimeExtensionOptions): readon
  * @param options Discovery options.
  * @returns Discovered commands sorted by command path.
  * @throws {TypeError} If options are invalid, discovery finds no commands,
- *         command paths conflict, or a module does not default-export a
- *         command created with `defineCommand()`.
+ *         command paths are duplicated, or a module does not default-export
+ *         a command created with `defineCommand()`.
  * @since 1.1.0
  */
 declare function discoverCommands(options: DiscoverCommandsOptions): Promise<readonly DiscoveredCommand[]>;
@@ -189,7 +211,8 @@ declare function discoverCommands(options: DiscoverCommandsOptions): Promise<rea
  * @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 conflict.
+ * @throws {TypeError} If no commands are provided or command paths are
+ *         duplicated.
  * @since 1.1.0
  */
 declare function createProgramParser(commands: readonly Pick<DiscoveredCommand, "path" | "command">[], metadata?: ProgramHelpMetadata): Parser<Mode, ProgramInvocation, unknown>;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-BAVhIzfI.js";
+import { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand } from "./command-DyiVIMUh.js";
 import { RunOptions } from "@optique/run";
 import { Mode, Parser } from "@optique/core/parser";
 import { Message } from "@optique/core/message";
@@ -64,6 +64,16 @@ interface DiscoverCommandsOptions {
    * @default Runtime-aware extension defaults from {@link getDefaultExtensions}
    */
   readonly extensions?: readonly string[];
+  /**
+   * File name that maps to the containing command path after extension
+   * stripping.  For example, `stash/index.ts` maps to `stash`, and root
+   * `index.ts` maps to the root command.  Pass `false` to treat matching files
+   * as ordinary command names.
+   *
+   * @default `"index"`
+   * @since 1.2.0
+   */
+  readonly entryFileName?: string | false;
 }
 /**
  * Runtime hint for {@link getDefaultExtensions}.
@@ -134,6 +144,14 @@ interface RunProgramDiscoveryOptions extends RunProgramBaseOptions {
    * File suffixes to include during discovery.
    */
   readonly extensions?: readonly string[];
+  /**
+   * File name that maps to the containing command path after extension
+   * stripping.
+   *
+   * @default `"index"`
+   * @since 1.2.0
+   */
+  readonly entryFileName?: string | false;
   /**
    * Static commands cannot be used together with `dir`.
    */
@@ -157,6 +175,10 @@ interface RunProgramStaticOptions extends RunProgramBaseOptions {
    * File suffixes are only used with file-system discovery.
    */
   readonly extensions?: never;
+  /**
+   * Entry file names are only used with file-system discovery.
+   */
+  readonly entryFileName?: never;
 }
 /**
  * Options for {@link runProgram}.
@@ -178,8 +200,8 @@ declare function getDefaultExtensions(options?: RuntimeExtensionOptions): readon
  * @param options Discovery options.
  * @returns Discovered commands sorted by command path.
  * @throws {TypeError} If options are invalid, discovery finds no commands,
- *         command paths conflict, or a module does not default-export a
- *         command created with `defineCommand()`.
+ *         command paths are duplicated, or a module does not default-export
+ *         a command created with `defineCommand()`.
  * @since 1.1.0
  */
 declare function discoverCommands(options: DiscoverCommandsOptions): Promise<readonly DiscoveredCommand[]>;
@@ -189,7 +211,8 @@ declare function discoverCommands(options: DiscoverCommandsOptions): Promise<rea
  * @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 conflict.
+ * @throws {TypeError} If no commands are provided or command paths are
+ *         duplicated.
  * @since 1.1.0
  */
 declare function createProgramParser(commands: readonly Pick<DiscoveredCommand, "path" | "command">[], metadata?: ProgramHelpMetadata): Parser<Mode, ProgramInvocation, unknown>;

package/dist/index.js

@@ -1,7 +1,9 @@
-import { defineCommand, isCommand } from "./command-y_A3hG0g.js";
-import { or } from "@optique/core/constructs";
+import { defineCommand, isCommand } from "./command-DO5zgkvS.js";
+import { longestMatch, or } from "@optique/core/constructs";
+import { dispatchByMode, inheritAnnotations, mapModeValue, wrapForMode } from "@optique/core/extension";
 import { map } from "@optique/core/modifiers";
 import { command } from "@optique/core/primitives";
+import { mergeHidden } from "@optique/core/usage";
 import { runAsync } from "@optique/run";
 import { readdir, realpath, stat } from "node:fs/promises";
 import { relative, resolve, sep } from "node:path";
@@ -38,37 +40,37 @@ function getDefaultExtensions(options = {}) {
 * @param options Discovery options.
 * @returns Discovered commands sorted by command path.
 * @throws {TypeError} If options are invalid, discovery finds no commands,
-*         command paths conflict, or a module does not default-export a
-*         command created with `defineCommand()`.
+*         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);
+		const path = commandPathFromFile(dir, filePath, extensions, entryFileName);
 		const key = commandPathKey(path);
 		const previous = seen.get(key);
 		if (previous != null) {
-			const displayPath = path.join(" ");
+			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 = unwrapCommandExport(mod.default);
 		if (commandDefinition == null) throw new TypeError(`Module ${filePath} default export must be created with defineCommand().`);
-		if (commandDefinition.path != null && commandPathKey(commandDefinition.path) !== commandPathKey(path)) throw new TypeError(`Module ${filePath} declares command path "${commandDefinition.path.join(" ")}" but file path defines "${path.join(" ")}".`);
+		if (commandDefinition.path != null && commandPathKey(commandDefinition.path) !== commandPathKey(path)) throw new TypeError(`Module ${filePath} declares command path "${displayCommandPath(commandDefinition.path)}" but file path defines "${displayCommandPath(path)}".`);
 		discovered.push({
 			path,
 			filePath,
 			command: commandDefinition
 		});
 	}
-	rejectPathConflicts(discovered);
 	return sortCommands(discovered);
 }
 /**
@@ -77,7 +79,8 @@ async function discoverCommands(options) {
 * @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 conflict.
+* @throws {TypeError} If no commands are provided or command paths are
+*         duplicated.
 * @since 1.1.0
 */
 function createProgramParser(commands, metadata = {}) {
@@ -85,11 +88,7 @@ function createProgramParser(commands, metadata = {}) {
 	const sortedCommands = sortCommands(commands);
 	rejectDuplicatePaths(sortedCommands.map((entry) => ({
 		path: entry.path,
-		filePath: entry.path.join("/")
-	})));
-	rejectPathConflicts(sortedCommands.map((entry) => ({
-		path: entry.path,
-		filePath: entry.path.join("/")
+		filePath: displayCommandPath(entry.path)
 	})));
 	const rootNode = buildCommandTree(sortedCommands);
 	const parser = buildNodeParser(rootNode);
@@ -109,7 +108,8 @@ async function runProgram(options) {
 	if (isStaticRunProgramOptions(options)) commands = staticCommandsToEntries(options.commands);
 	else commands = await discoverCommands({
 		dir: options.dir,
-		extensions: options.extensions
+		extensions: options.extensions,
+		entryFileName: options.entryFileName
 	});
 	const parser = createProgramParser(commands, options.metadata);
 	const invocation = await runAsync(parser, buildRunOptions(options));
@@ -140,6 +140,14 @@ function normalizeExtensions(extensions) {
 	}
 	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;
+}
 async function collectCommandFiles(dir, extensions, activeDirs = /* @__PURE__ */ new Set()) {
 	const canonicalDir = await realpath(dir);
 	if (activeDirs.has(canonicalDir)) return [];
@@ -171,29 +179,24 @@ async function getCommandFileEntryType(path, entry) {
 function isDeclarationFile(fileName) {
 	return /\.d\.[cm]?ts$/.test(fileName);
 }
-function commandPathFromFile(rootDir, filePath, extensions) {
+function commandPathFromFile(rootDir, filePath, extensions, entryFileName) {
 	const matchedExtension = extensions.find((ext) => filePath.endsWith(ext));
 	if (matchedExtension == null) throw new TypeError(`No configured extension matches ${filePath}.`);
 	const withoutExtension = filePath.slice(0, -matchedExtension.length);
 	const relativePath = relative(rootDir, withoutExtension);
 	const path = relativePath.split(sep).filter((segment) => segment.length > 0);
-	const [first, ...rest] = path;
-	if (first == null) throw new TypeError(`Command file ${filePath} does not define a path.`);
-	return [first, ...rest];
+	if (path.length < 1) throw new TypeError(`Command file ${filePath} 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.length > 0 && path.every((segment) => typeof segment === "string" && segment.length > 0);
-}
-function rejectPathConflicts(commands) {
-	const paths = new Map(commands.map((entry) => [commandPathKey(entry.path), entry]));
-	for (const entry of commands) for (let i = 1; i < entry.path.length; i++) {
-		const parent = entry.path.slice(0, i);
-		const parentEntry = paths.get(commandPathKey(parent));
-		if (parentEntry != null) throw new TypeError(`Command path "${parent.join(" ")}" conflicts with nested command "${entry.path.join(" ")}".`);
-	}
+	return Array.isArray(path) && path.every((segment) => typeof segment === "string" && segment.length > 0);
 }
 function rejectDuplicatePaths(commands) {
 	const seen = /* @__PURE__ */ new Map();
@@ -201,7 +204,7 @@ function rejectDuplicatePaths(commands) {
 		const key = commandPathKey(entry.path);
 		const previous = seen.get(key);
 		if (previous != null) {
-			const displayPath = entry.path.join(" ");
+			const displayPath = displayCommandPath(entry.path);
 			throw new TypeError(`Duplicate command path "${displayPath}" from ${previous} and ${entry.filePath}.`);
 		}
 		seen.set(key, entry.filePath);
@@ -219,7 +222,7 @@ function isStaticRunProgramOptions(options) {
 function staticCommandsToEntries(commands) {
 	return commands.map((command$1) => {
 		if (!isCommand(command$1)) throw new TypeError("Static command entries must be created with defineCommand().");
-		if (!isCommandPath(command$1.path)) throw new TypeError("Static command entries must declare a non-empty path.");
+		if (!isCommandPath(command$1.path)) throw new TypeError("Static command entries must declare a path.");
 		return {
 			path: command$1.path,
 			command: command$1
@@ -250,41 +253,354 @@ function buildCommandTree(commands) {
 	}
 	return root;
 }
-function buildNodeParser(node) {
+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 childParser = child.command != null ? createLeafParser(child.command) : buildNodeParser(child);
-		const metadata = child.command?.metadata;
-		parsers.push(command(name, childParser, metadata));
+		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 createLeafParser(commandDefinition) {
-	return map(commandDefinition.parser, (value) => ({
+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 rootDocs = () => ({
-		brief: metadata.brief,
-		description: metadata.description,
-		footer: metadata.footer,
-		fragments: [{
+	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: commands.map((entry) => ({
+			entries: listedCommands.map((entry) => ({
 				term: {
 					type: "command",
 					name: entry.path.join(" "),
-					hidden: entry.command.metadata?.hidden
+					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) {
@@ -293,9 +609,14 @@ function withRootDocs(parser, commands, metadata) {
 		}
 	};
 }
+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, metadata: _metadata, help, version, completion,...rest } = options;
+	const { dir: _dir, commands: _commands, extensions: _extensions, entryFileName: _entryFileName, metadata: _metadata, help, version, completion,...rest } = options;
 	const runOptions = {
 		...rest,
 		contexts: unwrapProgramContexts(rest.contexts),