@optique/core 1.1.0-dev.2096 → 1.1.0-dev.2148

package/dist/dependency-runtime.d.ts

@@ -49,7 +49,14 @@ interface DependencyResolution {
  * @internal
  * @since 1.0.0
  */
-
+interface SourceDefaultFailure {
+  /** The source that failed. */
+  readonly sourceId: symbol;
+  /** The path of the node. */
+  readonly path: readonly PropertyKey[];
+  /** The failed result or error message. */
+  readonly error: ValueParserResult<unknown>;
+}
 /**
  * A key for caching replayed parse results.
  *
@@ -145,5 +152,193 @@ interface DependencyRuntimeContext {
  * @internal
  * @since 1.0.0
  */
+declare function createDependencyRuntimeContext(registry?: DependencyRegistryLike): DependencyRuntimeContext;
+/**
+ * Creates a stable fingerprint from dependency values.
+ *
+ * @param values The dependency values to fingerprint.
+ * @returns A string fingerprint.
+ * @internal
+ * @since 1.0.0
+ */
+declare function createDependencyFingerprint(values: readonly unknown[]): string;
+declare function createReplayKey(path: readonly PropertyKey[], rawInput: string, dependencyValues: readonly unknown[], replayParse?: Function): ReplayKey;
+/**
+ * Collects explicit source values from parser states and registers them
+ * in the runtime context.
+ *
+ * @param nodes The runtime nodes to inspect.
+ * @param runtime The dependency runtime context.
+ * @throws Propagates synchronous errors thrown by `extractSourceValue()`.
+ * @throws {TypeError} If `extractSourceValue()` returns a promise-like result.
+ *         Use {@link collectExplicitSourceValuesAsync} when async source
+ *         extraction is expected.
+ * @internal
+ * @since 1.0.0
+ */
+declare function collectExplicitSourceValues(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): void;
+/**
+ * Async version of {@link collectExplicitSourceValues}.
+ * Awaits async `extractSourceValue` results instead of rejecting
+ * promise-like values as the synchronous variant does.
+ *
+ * @param nodes The runtime nodes to inspect.
+ * @param runtime The dependency runtime context.
+ * @throws Propagates errors thrown or rejected by `extractSourceValue()`.
+ * @internal
+ * @since 1.0.0
+ */
+declare function collectExplicitSourceValuesAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): Promise<void>;
+/**
+ * Fills missing source defaults for source parsers whose state is
+ * unpopulated.
+ *
+ * Returns an array of failures for sources whose default evaluation
+ * failed (either threw or returned `{ success: false }`).  The caller
+ * should propagate these so that dependent parsers see the real error
+ * instead of silently treating the source as absent.
+ *
+ * @param nodes The runtime nodes to inspect.
+ * @param runtime The dependency runtime context.
+ * @returns Failures from default evaluation (empty if all succeeded).
+ * @throws {TypeError} If `getMissingSourceValue()` returns a promise-like
+ *         result. Use {@link fillMissingSourceDefaultsAsync} when async
+ *         default extraction is expected.
+ * @internal
+ * @since 1.0.0
+ */
+declare function fillMissingSourceDefaults(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): readonly SourceDefaultFailure[];
+/**
+ * Async version of {@link fillMissingSourceDefaults}.
+ * Awaits async `getMissingSourceValue` results.
+ *
+ * @param nodes The runtime nodes to inspect.
+ * @param runtime The dependency runtime context.
+ * @returns Failures from default evaluation (empty if all succeeded).
+ * @internal
+ * @since 1.0.0
+ */
+declare function fillMissingSourceDefaultsAsync(nodes: readonly RuntimeNode[], runtime: DependencyRuntimeContext): Promise<readonly SourceDefaultFailure[]>;
+/**
+ * Replays a derived parser with resolved dependency values (sync).
+ *
+ * Returns `undefined` if dependencies cannot be resolved.
+ *
+ * @param node The runtime node with derived metadata.
+ * @param rawInput The raw input to replay.
+ * @param runtime The dependency runtime context.
+ * @returns The replay result, or `undefined`.
+ * @throws {TypeError} If `replayParse()` returns a promise-like result.
+ *         Use {@link replayDerivedParserAsync} for async replay.
+ * @internal
+ * @since 1.0.0
+ */
+declare function replayDerivedParser(node: RuntimeNode, rawInput: string, runtime: DependencyRuntimeContext): ValueParserResult<unknown> | undefined;
+/**
+ * Replays a derived parser with resolved dependency values (async).
+ *
+ * Returns `undefined` if dependencies cannot be resolved.
+ *
+ * @param node The runtime node with derived metadata.
+ * @param rawInput The raw input to replay.
+ * @param runtime The dependency runtime context.
+ * @returns The replay result, or `undefined`.
+ * @internal
+ * @since 1.0.0
+ */
+declare function replayDerivedParserAsync(node: RuntimeNode, rawInput: string, runtime: DependencyRuntimeContext): Promise<ValueParserResult<unknown> | undefined>;
+/**
+ * Extracts `rawInput` from a parser state that may contain a
+ * {@link DeferredParseState}.  During the transition period, primitives
+ * still produce `DeferredParseState` with `rawInput`.
+ *
+ * Handles direct `DeferredParseState` and array-wrapped
+ * `[DeferredParseState]` (from optional/withDefault wrappers).
+ *
+ * @param state The parser state to inspect.
+ * @returns The raw input string, or `undefined` if the state does not
+ *   contain a `DeferredParseState`.
+ * @internal
+ * @since 1.0.0
+ */
+declare function extractRawInputFromState(state: unknown): string | undefined;
+/**
+ * Recursively collects dependency source values from {@link DependencySourceState}
+ * objects found in the state tree and registers them in the runtime.
+ *
+ * This must run BEFORE deferred resolution so that all source values
+ * are available when replaying derived parsers.
+ *
+ * @param state The state tree to traverse.
+ * @param runtime The dependency runtime context to populate.
+ * @param visited Cycle guard for recursive traversal.
+ * @param excludedFields Optional property keys to skip at the current level.
+ *                       This exclusion set is not propagated recursively.
+ */
+declare function collectSourcesFromState(state: unknown, runtime: DependencyRuntimeContext, visited?: WeakSet<object>, excludedFields?: ReadonlySet<PropertyKey>): void;
+/**
+ * Recursively resolves all {@link DeferredParseState} objects in a state
+ * tree using the dependency runtime (sync).
+ *
+ * Performs a two-pass traversal:
+ *  1. Collect all {@link DependencySourceState} values into the runtime.
+ *  2. Resolve all {@link DeferredParseState} using the populated runtime.
+ *
+ * This replaces the old `resolveDeferredParseStates` with runtime-based
+ * resolution.  Only traverses plain objects and arrays; class instances
+ * and primitives are returned as-is.
+ *
+ * @param state The state tree to resolve.
+ * @param runtime The dependency runtime context.
+ * @returns The resolved state tree.
+ * @throws {TypeError} If a deferred parser returns a promise-like result from
+ *         `parseWithDependency()`. Use {@link resolveStateWithRuntimeAsync}
+ *         for async resolution.
+ * @internal
+ * @since 1.0.0
+ */
+declare function resolveStateWithRuntime(state: unknown, runtime: DependencyRuntimeContext): unknown;
+/**
+ * Async version of {@link resolveStateWithRuntime}.
+ *
+ * @param state The state tree to resolve.
+ * @param runtime The dependency runtime context.
+ * @returns The resolved state tree.
+ * @internal
+ * @since 1.0.0
+ */
+declare function resolveStateWithRuntimeAsync(state: unknown, runtime: DependencyRuntimeContext): Promise<unknown>;
+/**
+ * Builds {@link RuntimeNode}s from field→parser pairs and a state record.
+ *
+ * Used by `object()` and `merge()` constructs.
+ *
+ * @param pairs Field→parser pairs.
+ * @param state The state record keyed by field name.
+ * @param parentPath Optional parent path prefix.
+ * @returns An array of runtime nodes.
+ * @internal
+ * @since 1.0.0
+ */
+declare function buildRuntimeNodesFromPairs(pairs: ReadonlyArray<readonly [PropertyKey, {
+  readonly dependencyMetadata?: ParserDependencyMetadata;
+  readonly initialState?: unknown;
+}]>, state: Record<PropertyKey, unknown>, parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
+/**
+ * Builds {@link RuntimeNode}s from a parser array and a state array.
+ *
+ * Used by `tuple()` and `concat()` constructs.
+ *
+ * @param parsers The child parsers.
+ * @param stateArray The state array (one element per parser).
+ * @param parentPath Optional parent path prefix.
+ * @returns An array of runtime nodes.
+ * @internal
+ * @since 1.0.0
+ */
+declare function buildRuntimeNodesFromArray(parsers: ReadonlyArray<{
+  readonly dependencyMetadata?: ParserDependencyMetadata;
+  readonly initialState?: unknown;
+}>, stateArray: readonly unknown[], parentPath?: readonly PropertyKey[]): readonly RuntimeNode[];
 //#endregion
-export { DependencyRuntimeContext, RuntimeNode };
+export { DependencyRequest, DependencyResolution, DependencyRuntimeContext, DependencyValueOrigin, ReplayKey, RuntimeNode, SourceDefaultFailure, buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };

package/dist/dependency-runtime.js

@@ -457,6 +457,27 @@ async function replayDerivedParserAsync(node, rawInput, runtime) {
 	return result;
 }
 /**
+* Extracts `rawInput` from a parser state that may contain a
+* {@link DeferredParseState}.  During the transition period, primitives
+* still produce `DeferredParseState` with `rawInput`.
+*
+* Handles direct `DeferredParseState` and array-wrapped
+* `[DeferredParseState]` (from optional/withDefault wrappers).
+*
+* @param state The parser state to inspect.
+* @returns The raw input string, or `undefined` if the state does not
+*   contain a `DeferredParseState`.
+* @internal
+* @since 1.0.0
+*/
+function extractRawInputFromState(state) {
+	if (state == null) return void 0;
+	if (typeof state !== "object") return void 0;
+	if (isDeferredParseState(state)) return state.rawInput;
+	if (Array.isArray(state) && state.length === 1 && isDeferredParseState(state[0])) return state[0].rawInput;
+	return void 0;
+}
+/**
 * Checks if a value is a plain object (not a class instance) for the
 * purpose of recursive state traversal.
 */
@@ -696,4 +717,4 @@ function buildRuntimeNodesFromArray(parsers, stateArray, parentPath) {
 }
 
 //#endregion
-export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyRuntimeContext, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };
+export { buildRuntimeNodesFromArray, buildRuntimeNodesFromPairs, collectExplicitSourceValues, collectExplicitSourceValuesAsync, collectSourcesFromState, createDependencyFingerprint, createDependencyRuntimeContext, createReplayKey, extractRawInputFromState, fillMissingSourceDefaults, fillMissingSourceDefaultsAsync, replayDerivedParser, replayDerivedParserAsync, resolveStateWithRuntime, resolveStateWithRuntimeAsync };

package/dist/dependency.cjs

@@ -1,8 +1,8 @@
-const require_dependency = require('./internal/dependency.cjs');
+const require_internal_dependency = require('./internal/dependency.cjs');
 
-exports.dependency = require_dependency.dependency;
-exports.deriveFrom = require_dependency.deriveFrom;
-exports.deriveFromAsync = require_dependency.deriveFromAsync;
-exports.deriveFromSync = require_dependency.deriveFromSync;
-exports.isDependencySource = require_dependency.isDependencySource;
-exports.isDerivedValueParser = require_dependency.isDerivedValueParser;
+exports.dependency = require_internal_dependency.dependency;
+exports.deriveFrom = require_internal_dependency.deriveFrom;
+exports.deriveFromAsync = require_internal_dependency.deriveFromAsync;
+exports.deriveFromSync = require_internal_dependency.deriveFromSync;
+exports.isDependencySource = require_internal_dependency.isDependencySource;
+exports.isDerivedValueParser = require_internal_dependency.isDerivedValueParser;

package/dist/displaywidth.d.cts

@@ -0,0 +1,12 @@
+//#region src/displaywidth.d.ts
+/**
+ * Computes the terminal display width of a string, accounting for
+ * East Asian wide characters, combining marks, emoji, and ANSI escapes.
+ *
+ * @param text The string to measure.
+ * @returns The number of terminal columns the string occupies.
+ * @internal
+ */
+declare function getDisplayWidth(text: string): number;
+//#endregion
+export { getDisplayWidth };

package/dist/displaywidth.d.ts

@@ -0,0 +1,12 @@
+//#region src/displaywidth.d.ts
+/**
+ * Computes the terminal display width of a string, accounting for
+ * East Asian wide characters, combining marks, emoji, and ANSI escapes.
+ *
+ * @param text The string to measure.
+ * @returns The number of terminal columns the string occupies.
+ * @internal
+ */
+declare function getDisplayWidth(text: string): number;
+//#endregion
+export { getDisplayWidth };

package/dist/execution-context.d.cts

@@ -0,0 +1,23 @@
+import { Usage } from "./usage.cjs";
+import { ExecutionContext, ParserContext } from "./internal/parser.cjs";
+
+//#region src/execution-context.d.ts
+
+/**
+ * Appends a child parser segment to the current execution path.
+ * @internal
+ */
+declare function withChildExecPath(exec: ExecutionContext | undefined, segment: PropertyKey): ExecutionContext | undefined;
+/**
+ * Merges child-owned execution fields back into the parent execution context.
+ * @internal
+ */
+declare function mergeChildExec(parent: ExecutionContext | undefined, child: ExecutionContext | undefined): ExecutionContext | undefined;
+/**
+ * Creates a child parser context while keeping flat and nested execution data
+ * aligned.
+ * @internal
+ */
+declare function withChildContext<TParentState, TChildState>(context: ParserContext<TParentState>, segment: PropertyKey, state: TChildState, usage?: Usage): ParserContext<TChildState>;
+//#endregion
+export { mergeChildExec, withChildContext, withChildExecPath };

package/dist/execution-context.d.ts

@@ -0,0 +1,23 @@
+import { Usage } from "./usage.js";
+import { ExecutionContext, ParserContext } from "./internal/parser.js";
+
+//#region src/execution-context.d.ts
+
+/**
+ * Appends a child parser segment to the current execution path.
+ * @internal
+ */
+declare function withChildExecPath(exec: ExecutionContext | undefined, segment: PropertyKey): ExecutionContext | undefined;
+/**
+ * Merges child-owned execution fields back into the parent execution context.
+ * @internal
+ */
+declare function mergeChildExec(parent: ExecutionContext | undefined, child: ExecutionContext | undefined): ExecutionContext | undefined;
+/**
+ * Creates a child parser context while keeping flat and nested execution data
+ * aligned.
+ * @internal
+ */
+declare function withChildContext<TParentState, TChildState>(context: ParserContext<TParentState>, segment: PropertyKey, state: TChildState, usage?: Usage): ParserContext<TChildState>;
+//#endregion
+export { mergeChildExec, withChildContext, withChildExecPath };

package/dist/extension.cjs

@@ -1,6 +1,6 @@
-const require_annotations = require('./internal/annotations.cjs');
+const require_internal_annotations = require('./internal/annotations.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
-const require_parser = require('./internal/parser.cjs');
+const require_internal_parser = require('./internal/parser.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
 
 //#region src/extension.ts
@@ -14,13 +14,13 @@ const emptyTraits = Object.freeze({});
 * @since 1.0.0
 */
 function defineTraits(parser, traits) {
-	if (traits.inheritsAnnotations === true) require_parser.defineInheritedAnnotationParser(parser);
-	if (traits.completesFromSource === true) Object.defineProperty(parser, require_parser.unmatchedNonCliDependencySourceStateMarker, {
+	if (traits.inheritsAnnotations === true) require_internal_parser.defineInheritedAnnotationParser(parser);
+	if (traits.completesFromSource === true) Object.defineProperty(parser, require_internal_parser.unmatchedNonCliDependencySourceStateMarker, {
 		value: true,
 		configurable: true,
 		enumerable: true
 	});
-	if (traits.requiresSourceBinding === true) Object.defineProperty(parser, require_parser.annotationWrapperRequiresSourceBindingKey, {
+	if (traits.requiresSourceBinding === true) Object.defineProperty(parser, require_internal_parser.annotationWrapperRequiresSourceBindingKey, {
 		value: true,
 		configurable: true,
 		enumerable: false
@@ -35,9 +35,9 @@ function defineTraits(parser, traits) {
 */
 function getTraits(parser) {
 	const traits = {
-		...Reflect.get(parser, require_parser.inheritParentAnnotationsKey) === true ? { inheritsAnnotations: true } : {},
-		...Reflect.get(parser, require_parser.unmatchedNonCliDependencySourceStateMarker) === true ? { completesFromSource: true } : {},
-		...Reflect.get(parser, require_parser.annotationWrapperRequiresSourceBindingKey) === true ? { requiresSourceBinding: true } : {}
+		...Reflect.get(parser, require_internal_parser.inheritParentAnnotationsKey) === true ? { inheritsAnnotations: true } : {},
+		...Reflect.get(parser, require_internal_parser.unmatchedNonCliDependencySourceStateMarker) === true ? { completesFromSource: true } : {},
+		...Reflect.get(parser, require_internal_parser.annotationWrapperRequiresSourceBindingKey) === true ? { requiresSourceBinding: true } : {}
 	};
 	return Object.keys(traits).length > 0 ? traits : emptyTraits;
 }
@@ -55,7 +55,7 @@ function getTraits(parser) {
 * @since 1.0.0
 */
 function delegateSuggestNodes(innerParser, outerParser, state, path, innerState, position = "append") {
-	return require_parser.getDelegatingSuggestRuntimeNodes(innerParser, outerParser, state, path, innerState, position);
+	return require_internal_parser.getDelegatingSuggestRuntimeNodes(innerParser, outerParser, state, path, innerState, position);
 }
 /**
 * Maps the source capability of a parser's dependency metadata while
@@ -69,7 +69,7 @@ function delegateSuggestNodes(innerParser, outerParser, state, path, innerState,
 * @since 1.0.0
 */
 function mapSourceMetadata(parser, mapSource) {
-	return require_parser.composeWrappedSourceMetadata(parser.dependencyMetadata, mapSource);
+	return require_internal_parser.composeWrappedSourceMetadata(parser.dependencyMetadata, mapSource);
 }
 
 //#endregion
@@ -77,11 +77,11 @@ exports.defineTraits = defineTraits;
 exports.delegateSuggestNodes = delegateSuggestNodes;
 exports.dispatchByMode = require_mode_dispatch.dispatchByMode;
 exports.getTraits = getTraits;
-exports.inheritAnnotations = require_annotations.inheritAnnotations;
-exports.injectAnnotations = require_annotations.injectAnnotations;
-exports.isInjectedAnnotationState = require_annotations.isInjectedAnnotationState;
+exports.inheritAnnotations = require_internal_annotations.inheritAnnotations;
+exports.injectAnnotations = require_internal_annotations.injectAnnotations;
+exports.isInjectedAnnotationState = require_internal_annotations.isInjectedAnnotationState;
 exports.mapModeValue = require_mode_dispatch.mapModeValue;
 exports.mapSourceMetadata = mapSourceMetadata;
-exports.unwrapInjectedAnnotationState = require_annotations.unwrapInjectedAnnotationState;
+exports.unwrapInjectedAnnotationState = require_internal_annotations.unwrapInjectedAnnotationState;
 exports.withAnnotationView = require_annotation_state.withAnnotationView;
 exports.wrapForMode = require_mode_dispatch.wrapForMode;

package/dist/facade.cjs

@@ -1,13 +1,14 @@
-const require_annotations = require('./internal/annotations.cjs');
+const require_internal_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
-const require_completion = require('./completion.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_input_trace = require('./input-trace.cjs');
-const require_parser = require('./internal/parser.cjs');
+const require_internal_parser = require('./internal/parser.cjs');
+const require_completion = require('./completion.cjs');
+const require_command_alias = require('./internal/command-alias.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 const require_constructs = require('./constructs.cjs');
 const require_modifiers = require('./modifiers.cjs');
@@ -15,6 +16,14 @@ const require_valueparser = require('./valueparser.cjs');
 const require_primitives = require('./primitives.cjs');
 
 //#region src/facade.ts
+/**
+* Combines built-in meta commands while intentionally bypassing duplicate
+* leading command name validation in `createLongestMatch()`.
+*/
+function longestMatchForMetaCommands(...parsers) {
+	const options = { [require_command_alias.allowDuplicateLeadingCommandNamesKey]: true };
+	return require_constructs.longestMatch(...parsers, options);
+}
 const SuppressedErrorCtor = typeof SuppressedError === "function" ? SuppressedError : (() => {
 	class SuppressedErrorPolyfill extends Error {
 		error;
@@ -119,9 +128,9 @@ function createCompleteExec(exec, context) {
 	};
 }
 function attemptParseSync(parser, args, mode = "complete") {
-	const shouldUnwrapAnnotatedValue = require_annotations.isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = require_internal_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	const exec = createParseExec(parser);
-	let context = require_parser.createParserContext({
+	let context = require_internal_parser.createParserContext({
 		buffer: args,
 		state: parser.initialState,
 		optionsTerminated: false
@@ -168,13 +177,13 @@ function attemptParseSync(parser, args, mode = "complete") {
 	};
 	return {
 		kind: "success",
-		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
+		value: shouldUnwrapAnnotatedValue ? require_internal_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
 	};
 }
 async function attemptParseAsync(parser, args, mode = "complete") {
-	const shouldUnwrapAnnotatedValue = require_annotations.isInjectedAnnotationWrapper(parser.initialState);
+	const shouldUnwrapAnnotatedValue = require_internal_annotations.isInjectedAnnotationWrapper(parser.initialState);
 	const exec = createParseExec(parser);
-	let context = require_parser.createParserContext({
+	let context = require_internal_parser.createParserContext({
 		buffer: args,
 		state: parser.initialState,
 		optionsTerminated: false
@@ -221,7 +230,7 @@ async function attemptParseAsync(parser, args, mode = "complete") {
 	};
 	return {
 		kind: "success",
-		value: shouldUnwrapAnnotatedValue ? require_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
+		value: shouldUnwrapAnnotatedValue ? require_internal_annotations.unwrapInjectedAnnotationWrapper(endResult.value) : endResult.value
 	};
 }
 function createPhase2SeedExec(parser, context) {
@@ -250,7 +259,7 @@ function createPhase2SeedContext(parser, args) {
 		commandPath: [],
 		trace: require_input_trace.createInputTrace()
 	};
-	return require_parser.createParserContext({
+	return require_internal_parser.createParserContext({
 		buffer: args,
 		state: parser.initialState,
 		optionsTerminated: false
@@ -278,6 +287,10 @@ async function extractPhase2SeedAsync(parser, args) {
 	} while (context.buffer.length > 0);
 	return await require_phase2_seed.completeOrExtractPhase2Seed(parser, context.state, createPhase2SeedExec(parser, context));
 }
+function getMetaCommandAliases(names) {
+	const [, firstAlias, ...restAliases] = names;
+	return firstAlias == null ? void 0 : [firstAlias, ...restAliases];
+}
 /**
 * Creates help parsers based on the sub-config.
 */
@@ -287,12 +300,12 @@ function createHelpParser(commandConfig, optionConfig) {
 	if (commandConfig) {
 		const names = commandConfig.names ?? ["help"];
 		const innerParser = require_modifiers.multiple(require_primitives.argument(require_valueparser.string({ metavar: "COMMAND" }), { description: require_message.message`Command name to show help for.` }));
-		const commandParsers = [];
-		for (let i = 0; i < names.length; i++) commandParsers.push(require_primitives.command(names[i], innerParser, {
+		const aliases = getMetaCommandAliases(names);
+		helpCommand = require_primitives.command(names[0], innerParser, {
 			description: require_message.message`Show help information.`,
-			hidden: i === 0 ? commandConfig.hidden : true
-		}));
-		helpCommand = commandParsers.length === 1 ? commandParsers[0] : require_constructs.longestMatch(...commandParsers);
+			...aliases != null ? { [require_command_alias.hiddenCommandAliasesKey]: aliases } : {},
+			hidden: commandConfig.hidden
+		});
 	}
 	if (optionConfig) {
 		const names = optionConfig.names ?? ["--help"];
@@ -315,12 +328,12 @@ function createVersionParser(commandConfig, optionConfig) {
 	if (commandConfig) {
 		const names = commandConfig.names ?? ["version"];
 		const innerParser = require_constructs.object({});
-		const commandParsers = [];
-		for (let i = 0; i < names.length; i++) commandParsers.push(require_primitives.command(names[i], innerParser, {
+		const aliases = getMetaCommandAliases(names);
+		versionCommand = require_primitives.command(names[0], innerParser, {
 			description: require_message.message`Show version information.`,
-			hidden: i === 0 ? commandConfig.hidden : true
-		}));
-		versionCommand = commandParsers.length === 1 ? commandParsers[0] : require_constructs.longestMatch(...commandParsers);
+			...aliases != null ? { [require_command_alias.hiddenCommandAliasesKey]: aliases } : {},
+			hidden: commandConfig.hidden
+		});
 	}
 	if (optionConfig) {
 		const names = optionConfig.names ?? ["--version"];
@@ -358,12 +371,12 @@ function createCompletionParser(programName, availableShells, commandConfig, opt
 			description: require_message.message`Generate shell completion script or provide completions.`,
 			footer: require_message.message`Examples:${require_message.lineBreak()}  Bash:       ${require_message.commandLine(`eval "$(${programName} ${displayName} bash)"`)}${require_message.lineBreak()}  zsh:        ${require_message.commandLine(`eval "$(${programName} ${displayName} zsh)"`)}${require_message.lineBreak()}  fish:       ${require_message.commandLine(`eval "$(${programName} ${displayName} fish)"`)}${require_message.lineBreak()}  PowerShell: ${require_message.commandLine(`${programName} ${displayName} pwsh > ${programName}-completion.ps1; . ./${programName}-completion.ps1`)}${require_message.lineBreak()}  Nushell:    ${require_message.commandLine(`${programName} ${displayName} nu | save ${programName}-completion.nu; source ./${programName}-completion.nu`)}`
 		};
-		const commandParsers = [];
-		for (let i = 0; i < names.length; i++) commandParsers.push(require_primitives.command(names[i], completionInner, {
+		const aliases = getMetaCommandAliases(names);
+		completionCommand = require_primitives.command(names[0], completionInner, {
 			...completionCommandConfig,
-			hidden: i === 0 ? commandConfig.hidden : true
-		}));
-		completionCommand = commandParsers.length === 1 ? commandParsers[0] : require_constructs.longestMatch(...commandParsers);
+			...aliases != null ? { [require_command_alias.hiddenCommandAliasesKey]: aliases } : {},
+			hidden: commandConfig.hidden
+		});
 	}
 	if (optionConfig) {
 		const names = optionConfig.names ?? ["--completion"];
@@ -463,9 +476,7 @@ function combineWithHelpVersion(originalParser, helpParsers, versionParsers, com
 	}));
 	const mainParserIndex = parsers.length - 1;
 	if (parsers.length === 1) return parsers[0];
-	let combined;
-	if (parsers.length === 2) combined = require_constructs.longestMatch(parsers[0], parsers[1]);
-	else combined = require_constructs.longestMatch(...parsers);
+	let combined = longestMatchForMetaCommands(...parsers);
 	const topUsage = combined.usage[0];
 	if (topUsage?.type === "exclusive" && mainParserIndex > 0) {
 		const terms = [...topUsage.terms];
@@ -606,7 +617,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 		stderr("Error: Missing shell name for completion.\n");
 		if (completionParser) {
 			const displayName = isOptionMode ? completionOptionDisplayName ?? "--completion" : completionCommandDisplayName ?? "completion";
-			const doc = require_parser.getDocPage(completionParser, [displayName]);
+			const doc = require_internal_parser.getDocPage(completionParser, [displayName]);
 			if (doc) stderr(require_doc.formatDocPage(programName, doc, {
 				colors,
 				maxWidth,
@@ -774,7 +785,7 @@ function getCompletionSuggestRuntimeNodes(parser, state, path) {
 	}];
 }
 function createCompletionArgumentParserContext(parser, args) {
-	return require_parser.createParserContext({
+	return require_internal_parser.createParserContext({
 		buffer: args,
 		state: parser.initialState,
 		optionsTerminated: false
@@ -1080,8 +1091,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					for (const [label, optParsers] of Object.entries(groupedMetaOptions)) if (optParsers.length === 1) commandParsers.push(require_constructs.group(label, optParsers[0]));
 					else commandParsers.push(require_constructs.group(label, require_constructs.longestMatch(...optParsers)));
 					if (commandParsers.length === 1) helpGeneratorParser = commandParsers[0];
-					else if (commandParsers.length === 2) helpGeneratorParser = require_constructs.longestMatch(commandParsers[0], commandParsers[1]);
-					else helpGeneratorParser = require_constructs.longestMatch(...commandParsers);
+					else helpGeneratorParser = longestMatchForMetaCommands(...commandParsers);
 				}
 				const reportInvalidHelpCommand = (validationError) => {
 					stderr(`Usage: ${indentLines(require_usage.formatUsage(programName, augmentedParser.usage, {
@@ -1152,7 +1162,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 									res = processStep(resolved);
 								}
 								if (res != null) return reportInvalidHelpCommand(res);
-								const docOrPromise$1 = require_parser.getDocPage(helpGeneratorParser, classified.commands);
+								const docOrPromise$1 = require_internal_parser.getDocPage(helpGeneratorParser, classified.commands);
 								return docOrPromise$1 instanceof Promise ? docOrPromise$1.then(displayHelp) : displayHelp(docOrPromise$1);
 							};
 							return stepResult.then(asyncValidate);
@@ -1161,7 +1171,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					}
 					if (validationResult != null) return reportInvalidHelpCommand(validationResult);
 				}
-				const docOrPromise = require_parser.getDocPage(helpGeneratorParser, classified.commands);
+				const docOrPromise = require_internal_parser.getDocPage(helpGeneratorParser, classified.commands);
 				if (docOrPromise instanceof Promise) return docOrPromise.then(displayHelp);
 				return displayHelp(docOrPromise);
 			}
@@ -1200,7 +1210,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				};
 				if (aboveError === "help") {
 					const parserForDoc = args.length < 1 ? augmentedParser : parser;
-					const docOrPromise = require_parser.getDocPage(parserForDoc, args);
+					const docOrPromise = require_internal_parser.getDocPage(parserForDoc, args);
 					if (docOrPromise instanceof Promise) return docOrPromise.then((doc) => displayError(doc, aboveError));
 					return displayError(docOrPromise, aboveError);
 				}
@@ -1734,7 +1744,7 @@ function runWithAsync(parser, programName, contexts, options) {
 * @returns A new parser with annotations in its initial state.
 */
 function injectAnnotationsIntoParser(parser, annotations) {
-	const newInitialState = require_annotations.injectAnnotations(parser.initialState, annotations);
+	const newInitialState = require_internal_annotations.injectAnnotations(parser.initialState, annotations);
 	const descriptors = { ...Object.getOwnPropertyDescriptors(parser) };
 	const initialState = descriptors.initialState;
 	descriptors.initialState = initialState == null ? {