@optique/discover 1.1.0 → 1.2.0-dev.2167

package/README.md

@@ -117,6 +117,10 @@ By default, Deno and Bun discover `.ts`, `.mts`, `.js`, and `.mjs` files.
 Node.js discovers `.js`, `.mjs`, and `.cjs` files, plus `.ts`, `.mts`, and
 `.cts` when it reports native TypeScript support or runs with a recognized
 TypeScript loader.  TypeScript declaration files such as `.d.ts` are ignored.
+Entry files named `index` map to their containing command path, so
+`commands/index.ts` defines the root command and `commands/user/index.ts`
+defines `user`.  Use `entryFileName` to choose another entry name or disable
+this rule.
 
 For more resources, see the [docs] and the [*examples/*](/examples/)
 directory.

package/dist/{command-DZA06E08.cjs → command-B0lV6NBO.cjs}

@@ -21,10 +21,10 @@ function isCommand(value) {
 	return value != null && typeof value === "object" && value[commandBrand] === true && (value.path == null || isCommandPath(value.path)) && isParser(value.parser) && typeof value.handler === "function";
 }
 function validateCommandPath(path) {
-	if (!isCommandPath(path)) throw new TypeError("Command path must be a non-empty array of non-empty strings.");
+	if (!isCommandPath(path)) throw new TypeError("Command path must be an array of non-empty strings.");
 }
 function isCommandPath(path) {
-	return Array.isArray(path) && path.length > 0 && path.every((segment) => typeof segment === "string" && segment.length > 0);
+	return Array.isArray(path) && path.every((segment) => typeof segment === "string" && segment.length > 0);
 }
 function isParser(value) {
 	return value != null && typeof value === "object" && typeof value.parse === "function" && typeof value.complete === "function" && typeof value.suggest === "function" && typeof value.getDocFragments === "function" && (value.mode === "sync" || value.mode === "async");

package/dist/{command-y_A3hG0g.js → command-DO5zgkvS.js}

@@ -20,10 +20,10 @@ function isCommand(value) {
 	return value != null && typeof value === "object" && value[commandBrand] === true && (value.path == null || isCommandPath(value.path)) && isParser(value.parser) && typeof value.handler === "function";
 }
 function validateCommandPath(path) {
-	if (!isCommandPath(path)) throw new TypeError("Command path must be a non-empty array of non-empty strings.");
+	if (!isCommandPath(path)) throw new TypeError("Command path must be an array of non-empty strings.");
 }
 function isCommandPath(path) {
-	return Array.isArray(path) && path.length > 0 && path.every((segment) => typeof segment === "string" && segment.length > 0);
+	return Array.isArray(path) && path.every((segment) => typeof segment === "string" && segment.length > 0);
 }
 function isParser(value) {
 	return value != null && typeof value === "object" && typeof value.parse === "function" && typeof value.complete === "function" && typeof value.suggest === "function" && typeof value.getDocFragments === "function" && (value.mode === "sync" || value.mode === "async");

package/dist/{command-2HtR3-TV.d.cts → command-DSHBTa5c.d.cts}

@@ -14,11 +14,13 @@ declare const commandBrand: unique symbol;
  */
 type CommandMetadata = CommandOptions;
 /**
- * Non-empty command path used by static command registration.
+ * Command path used by static command registration.
+ *
+ * An empty path represents the root command.
  *
  * @since 1.1.0
  */
-type CommandPath = readonly [string, ...string[]];
+type CommandPath = readonly string[];
 /**
  * Input accepted by {@link defineCommand}.
  *
@@ -29,6 +31,7 @@ type CommandPath = readonly [string, ...string[]];
 interface CommandDefinition<M extends Mode, T> {
   /**
    * Command path used when commands are passed directly to `runProgram()`.
+   * Use an empty path (`[]`) to register the root command.
    *
    * File-based discovery derives the command path from the file name and uses
    * this field only to validate that the declared path matches.

package/dist/{command-BAVhIzfI.d.ts → command-DyiVIMUh.d.ts}

@@ -14,11 +14,13 @@ declare const commandBrand: unique symbol;
  */
 type CommandMetadata = CommandOptions;
 /**
- * Non-empty command path used by static command registration.
+ * Command path used by static command registration.
+ *
+ * An empty path represents the root command.
  *
  * @since 1.1.0
  */
-type CommandPath = readonly [string, ...string[]];
+type CommandPath = readonly string[];
 /**
  * Input accepted by {@link defineCommand}.
  *
@@ -29,6 +31,7 @@ type CommandPath = readonly [string, ...string[]];
 interface CommandDefinition<M extends Mode, T> {
   /**
    * Command path used when commands are passed directly to `runProgram()`.
+   * Use an empty path (`[]`) to register the root command.
    *
    * File-based discovery derives the command path from the file name and uses
    * this field only to validate that the declared path matches.

package/dist/command.cjs

@@ -1,4 +1,4 @@
-const require_command = require('./command-DZA06E08.cjs');
+const require_command = require('./command-B0lV6NBO.cjs');
 
 exports.defineCommand = require_command.defineCommand;
 exports.isCommand = require_command.isCommand;

package/dist/command.d.cts

@@ -1,2 +1,2 @@
-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";
 export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand };

package/dist/command.d.ts

@@ -1,2 +1,2 @@
-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";
 export { AnyCommand, AnyStaticCommand, Command, CommandDefinition, CommandMetadata, CommandPath, StaticCommand, defineCommand, isCommand };

package/dist/command.js

@@ -1,3 +1,3 @@
-import { defineCommand, isCommand } from "./command-y_A3hG0g.js";
+import { defineCommand, isCommand } from "./command-DO5zgkvS.js";
 
 export { defineCommand, isCommand };

package/dist/index.cjs

@@ -21,10 +21,12 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 }) : target, mod));
 
 //#endregion
-const require_command = require('./command-DZA06E08.cjs');
+const require_command = require('./command-B0lV6NBO.cjs');
 const __optique_core_constructs = __toESM(require("@optique/core/constructs"));
+const __optique_core_extension = __toESM(require("@optique/core/extension"));
 const __optique_core_modifiers = __toESM(require("@optique/core/modifiers"));
 const __optique_core_primitives = __toESM(require("@optique/core/primitives"));
+const __optique_core_usage = __toESM(require("@optique/core/usage"));
 const __optique_run = __toESM(require("@optique/run"));
 const node_fs_promises = __toESM(require("node:fs/promises"));
 const node_path = __toESM(require("node:path"));
@@ -61,37 +63,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((0, node_url.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);
 }
 /**
@@ -100,7 +102,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 = {}) {
@@ -108,11 +111,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);
@@ -132,7 +131,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 (0, __optique_run.runAsync)(parser, buildRunOptions(options));
@@ -163,6 +163,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 (0, node_fs_promises.realpath)(dir);
 	if (activeDirs.has(canonicalDir)) return [];
@@ -194,29 +202,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 = (0, node_path.relative)(rootDir, withoutExtension);
 	const path = relativePath.split(node_path.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();
@@ -224,7 +227,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);
@@ -242,7 +245,7 @@ function isStaticRunProgramOptions(options) {
 function staticCommandsToEntries(commands) {
 	return commands.map((command$1) => {
 		if (!require_command.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
@@ -273,41 +276,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 = (0, __optique_core_constructs.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, (0, __optique_core_extension.inheritAnnotations)(context.state, activeState.result.next.state), branchParser));
+				return (0, __optique_core_extension.mapModeValue)(parser.mode, (0, __optique_core_extension.wrapForMode)(parser.mode, result$1), (resolved) => wrapBranchParseResult(context, activeState, resolved));
+			}
+			const result = parser.parse({
+				...context,
+				state: toExclusiveState(activeState, context.state)
+			});
+			return (0, __optique_core_extension.mapModeValue)(parser.mode, (0, __optique_core_extension.wrapForMode)(parser.mode, result), (resolved) => wrapInitialParseResult(context, resolved));
+		},
+		complete(state, exec) {
+			const activeState = normalizeExecutableNodeState(state);
+			if (activeState?.result.success === true) return (0, __optique_core_extension.wrapForMode)(parser.mode, branchParsers[activeState.branch].complete((0, __optique_core_extension.inheritAnnotations)(state, activeState.result.next.state), withExecutableNodeChildExecPath(exec, activeState.branch)));
+			if (activeState == null) return (0, __optique_core_extension.wrapForMode)(parser.mode, completeExecutableNodeLeaf(state, exec, leafParser));
+			return (0, __optique_core_extension.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, (0, __optique_core_extension.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 = (0, __optique_core_extension.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 = (0, __optique_core_extension.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 (0, __optique_core_extension.dispatchByMode)(leafParser.mode, () => (0, __optique_core_extension.wrapForMode)("sync", completeParsedExecutableNodeLeaf(state, exec, leafParser, (0, __optique_core_extension.wrapForMode)("sync", result))), () => Promise.resolve((0, __optique_core_extension.wrapForMode)("async", result)).then((resolved) => (0, __optique_core_extension.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 ? (0, __optique_core_extension.inheritAnnotations)(state, result.next.state) : (0, __optique_core_extension.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 (0, __optique_core_extension.dispatchByMode)(leafParser.mode, () => extractParsedExecutableNodePhase2Seed(state, exec, (0, __optique_core_extension.wrapForMode)("sync", result), phase2SeedHook), () => Promise.resolve((0, __optique_core_extension.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 = (0, __optique_core_extension.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: (0, __optique_core_extension.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 (0, __optique_core_extension.inheritAnnotations)(state, {
+		branch,
+		result,
+		committed: state.committed === true
+	});
+}
+function toExclusiveState(state, sourceState = state) {
+	const exclusiveState = state == null ? void 0 : [state.branch, state.result];
+	return (0, __optique_core_extension.inheritAnnotations)(sourceState, exclusiveState);
+}
+function fromExclusiveState(state) {
+	if (!Array.isArray(state) || state.length !== 2 || state[0] !== 0 && state[0] !== 1) return void 0;
+	return (0, __optique_core_extension.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 = (0, __optique_core_extension.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: (0, __optique_core_extension.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((0, __optique_core_primitives.command)(name, childParser, metadata));
+		const childHidden = (0, __optique_core_usage.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((0, __optique_core_primitives.command)(name, childParser, commandMetadataWithInheritedHidden(child.command?.metadata, inheritedHidden)));
 	}
+	if (parsers.length < 1) return void 0;
 	if (parsers.length === 1) return parsers[0];
 	return (0, __optique_core_constructs.or)(...parsers);
 }
-function createLeafParser(commandDefinition) {
-	return (0, __optique_core_modifiers.map)(commandDefinition.parser, (value) => ({
+function createNamespaceCommandParser(name, childParser, commandDefinition, inheritedHidden) {
+	const metadata = commandDefinition?.metadata;
+	const parser = (0, __optique_core_primitives.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 = (0, __optique_core_usage.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 = (0, __optique_core_usage.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 = (0, __optique_core_modifiers.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) {
@@ -316,9 +632,14 @@ function withRootDocs(parser, commands, metadata) {
 		}
 	};
 }
+function commandPathHidden(path, commandsByPath) {
+	let hidden;
+	for (let length = 1; length <= path.length; length++) hidden = (0, __optique_core_usage.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),