@optique/core 1.1.0-dev.2087 → 1.1.0-dev.2146

package/dist/modifiers.js

@@ -12,6 +12,11 @@ function isTerminalMultipleItemState(state) {
 	const unwrapped = unwrapMultipleItemState(state).value;
 	return unwrapped != null && typeof unwrapped === "object" && Object.hasOwn(unwrapped, "success") && typeof unwrapped.success === "boolean";
 }
+function isMatchedCommandParserState(parser, state) {
+	if (Reflect.get(parser, Symbol.for("@optique/core/commandParser")) !== true) return false;
+	const unwrapped = unwrapMultipleItemState(state).value;
+	return Array.isArray(unwrapped) && unwrapped.length === 2 && unwrapped[0] === "matched" && typeof unwrapped[1] === "string";
+}
 function isUnstartedMultipleItemState(state, originalState) {
 	const unwrappedState = unwrapMultipleItemState(state);
 	if (unwrappedState.value == null) return true;
@@ -320,6 +325,11 @@ function optional(parser) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state, exec) {
+			if (!Array.isArray(state)) return true;
+			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			return parser.canSkip?.(innerState, exec) === true;
+		},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser), parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
 			if (optionalParser.dependencyMetadata?.source != null) return [{
@@ -488,6 +498,11 @@ function withDefault(parser, defaultValue, options) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state, exec) {
+			if (!Array.isArray(state)) return true;
+			const innerState = normalizeOptionalLikeInnerState(state, parser.initialState, parser);
+			return parser.canSkip?.(innerState, exec) === true;
+		},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: adaptShouldDeferCompletion(parser.shouldDeferCompletion.bind(parser), parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
 			if (withDefaultParser.dependencyMetadata?.source != null) return [{
@@ -926,9 +941,11 @@ function multiple(parser, options = {}) {
 		parser,
 		state
 	}] : []);
+	const canExtendMultipleItem = (state, itemIndex, exec) => state != null && !isTerminalMultipleItemState(state) && (isMatchedCommandParserState(parser, state) || parser.canSkip?.(state, withChildExecPath(exec, itemIndex)) !== true);
 	const parseSync = (context) => {
 		const currentItemState = context.state.at(-1);
-		const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
+		const currentItemIndex = context.state.length - 1;
+		const canExtendCurrent = canExtendMultipleItem(currentItemState, currentItemIndex, context.exec);
 		const canOpenFreshItem = context.state.length < max;
 		if (!canExtendCurrent && !canOpenFreshItem) return {
 			success: true,
@@ -1008,7 +1025,8 @@ function multiple(parser, options = {}) {
 	};
 	const parseAsync = async (context) => {
 		const currentItemState = context.state.at(-1);
-		const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
+		const currentItemIndex = context.state.length - 1;
+		const canExtendCurrent = canExtendMultipleItem(currentItemState, currentItemIndex, context.exec);
 		const canOpenFreshItem = context.state.length < max;
 		if (!canExtendCurrent && !canOpenFreshItem) return {
 			success: true,
@@ -1099,6 +1117,11 @@ function multiple(parser, options = {}) {
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: min > 0 && (parser.acceptingAnyToken ?? false),
 		initialState: [],
+		canSkip(state, exec) {
+			if (state.length < min) return false;
+			const currentItemState = state.at(-1);
+			return !canExtendMultipleItem(currentItemState, state.length - 1, exec);
+		},
 		getSuggestRuntimeNodes(state, path) {
 			const innerNodes = state.flatMap((item, i) => [...getInnerSuggestRuntimeNodes(item, [...path, i])]);
 			return resultParser.dependencyMetadata?.source != null ? [{
@@ -1198,7 +1221,8 @@ function multiple(parser, options = {}) {
 		},
 		suggest(context, prefix) {
 			const currentItemState = context.state.at(-1);
-			const canExtendCurrent = currentItemState != null && !isTerminalMultipleItemState(currentItemState);
+			const currentItemIndex = context.state.length - 1;
+			const canExtendCurrent = canExtendMultipleItem(currentItemState, currentItemIndex, context.exec);
 			const canOpenNew = context.state.length < max;
 			if (!canExtendCurrent && !canOpenNew) return dispatchIterableByMode(parser.mode, function* () {}, async function* () {});
 			const itemIndex = canExtendCurrent ? context.state.length - 1 : context.state.length;
@@ -1484,6 +1508,7 @@ function multiple(parser, options = {}) {
 */
 function nonEmpty(parser) {
 	const syncParser = parser;
+	const initialState = parser.initialState;
 	const processNonEmptyResult = (result) => {
 		if (!result.success) return result;
 		if (result.consumed.length === 0) return {
@@ -1509,7 +1534,12 @@ function nonEmpty(parser) {
 		usage: parser.usage,
 		leadingNames: parser.leadingNames,
 		acceptingAnyToken: parser.acceptingAnyToken,
-		initialState: parser.initialState,
+		initialState,
+		...typeof parser.canSkip === "function" ? { canSkip(state, exec) {
+			const unwrappedState = unwrapInjectedAnnotationWrapper(state);
+			if (unwrappedState === initialState) return false;
+			return parser.canSkip?.(unwrappedState, exec) === true;
+		} } : {},
 		...typeof parser.shouldDeferCompletion === "function" ? { shouldDeferCompletion: parser.shouldDeferCompletion.bind(parser) } : {},
 		getSuggestRuntimeNodes(state, path) {
 			return parser.getSuggestRuntimeNodes?.(state, path) ?? (parser.dependencyMetadata?.source != null ? [{

package/dist/parser.cjs

@@ -1,12 +1,12 @@
-const require_parser = require('./internal/parser.cjs');
+const require_internal_parser = require('./internal/parser.cjs');
 
-exports.createParserContext = require_parser.createParserContext;
-exports.getDocPage = require_parser.getDocPage;
-exports.getDocPageAsync = require_parser.getDocPageAsync;
-exports.getDocPageSync = require_parser.getDocPageSync;
-exports.parse = require_parser.parse;
-exports.parseAsync = require_parser.parseAsync;
-exports.parseSync = require_parser.parseSync;
-exports.suggest = require_parser.suggest;
-exports.suggestAsync = require_parser.suggestAsync;
-exports.suggestSync = require_parser.suggestSync;
+exports.createParserContext = require_internal_parser.createParserContext;
+exports.getDocPage = require_internal_parser.getDocPage;
+exports.getDocPageAsync = require_internal_parser.getDocPageAsync;
+exports.getDocPageSync = require_internal_parser.getDocPageSync;
+exports.parse = require_internal_parser.parse;
+exports.parseAsync = require_internal_parser.parseAsync;
+exports.parseSync = require_internal_parser.parseSync;
+exports.suggest = require_internal_parser.suggest;
+exports.suggestAsync = require_internal_parser.suggestAsync;
+exports.suggestSync = require_internal_parser.suggestSync;

package/dist/phase2-seed.cjs

@@ -1,4 +1,4 @@
-const require_annotations = require('./internal/annotations.cjs');
+const require_internal_annotations = require('./internal/annotations.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
 
 //#region src/phase2-seed.ts
@@ -15,7 +15,7 @@ const extractPhase2SeedKey = Symbol("@optique/core/extractPhase2Seed");
 */
 function phase2SeedFromValueResult(result) {
 	return {
-		value: require_annotations.unwrapInjectedAnnotationWrapper(result.value),
+		value: require_internal_annotations.unwrapInjectedAnnotationWrapper(result.value),
 		...result.deferred ? { deferred: true } : {},
 		...result.deferredKeys != null ? { deferredKeys: result.deferredKeys } : {}
 	};

package/dist/phase2-seed.d.cts

@@ -0,0 +1,50 @@
+import { DeferredMap, ValueParserResult } from "./valueparser.cjs";
+import { ExecutionContext, Mode, ModeValue, Parser } from "./internal/parser.cjs";
+
+//#region src/phase2-seed.d.ts
+
+/**
+ * Best-effort parser value used for phase-two context collection.
+ *
+ * @internal
+ */
+interface Phase2Seed<T = unknown> {
+  readonly value: T;
+  readonly deferred?: true;
+  readonly deferredKeys?: DeferredMap;
+}
+/**
+ * Internal hook for extracting a best-effort phase-two seed from parser state.
+ *
+ * @internal
+ */
+type Phase2SeedExtractor<M extends Mode = Mode, TState = unknown, TValue = unknown> = (state: TState, exec?: ExecutionContext) => ModeValue<M, Phase2Seed<TValue> | null>;
+/**
+ * Internal parser hook key for phase-two seed extraction.
+ *
+ * @internal
+ */
+declare const extractPhase2SeedKey: unique symbol;
+/**
+ * Converts a successful complete() result into a phase-two seed.
+ *
+ * @internal
+ */
+declare function phase2SeedFromValueResult<T>(result: Extract<ValueParserResult<T>, {
+  readonly success: true;
+}>): Phase2Seed<T>;
+/**
+ * Invokes a parser's internal phase-two seed hook when present.
+ *
+ * @internal
+ */
+declare function extractPhase2Seed<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, state: TState, exec?: ExecutionContext): ModeValue<M, Phase2Seed<TValue> | null>;
+/**
+ * Attempts to complete a parser and falls back to the internal phase-two
+ * seed hook when completion returns an unsuccessful result.
+ *
+ * @internal
+ */
+declare function completeOrExtractPhase2Seed<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, state: TState, exec?: ExecutionContext): ModeValue<M, Phase2Seed<TValue> | null>;
+//#endregion
+export { Phase2Seed, Phase2SeedExtractor, completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult };

package/dist/phase2-seed.d.ts

@@ -0,0 +1,50 @@
+import { DeferredMap, ValueParserResult } from "./valueparser.js";
+import { ExecutionContext, Mode, ModeValue, Parser } from "./internal/parser.js";
+
+//#region src/phase2-seed.d.ts
+
+/**
+ * Best-effort parser value used for phase-two context collection.
+ *
+ * @internal
+ */
+interface Phase2Seed<T = unknown> {
+  readonly value: T;
+  readonly deferred?: true;
+  readonly deferredKeys?: DeferredMap;
+}
+/**
+ * Internal hook for extracting a best-effort phase-two seed from parser state.
+ *
+ * @internal
+ */
+type Phase2SeedExtractor<M extends Mode = Mode, TState = unknown, TValue = unknown> = (state: TState, exec?: ExecutionContext) => ModeValue<M, Phase2Seed<TValue> | null>;
+/**
+ * Internal parser hook key for phase-two seed extraction.
+ *
+ * @internal
+ */
+declare const extractPhase2SeedKey: unique symbol;
+/**
+ * Converts a successful complete() result into a phase-two seed.
+ *
+ * @internal
+ */
+declare function phase2SeedFromValueResult<T>(result: Extract<ValueParserResult<T>, {
+  readonly success: true;
+}>): Phase2Seed<T>;
+/**
+ * Invokes a parser's internal phase-two seed hook when present.
+ *
+ * @internal
+ */
+declare function extractPhase2Seed<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, state: TState, exec?: ExecutionContext): ModeValue<M, Phase2Seed<TValue> | null>;
+/**
+ * Attempts to complete a parser and falls back to the internal phase-two
+ * seed hook when completion returns an unsuccessful result.
+ *
+ * @internal
+ */
+declare function completeOrExtractPhase2Seed<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, state: TState, exec?: ExecutionContext): ModeValue<M, Phase2Seed<TValue> | null>;
+//#endregion
+export { Phase2Seed, Phase2SeedExtractor, completeOrExtractPhase2Seed, extractPhase2Seed, extractPhase2SeedKey, phase2SeedFromValueResult };

package/dist/primitives.cjs

@@ -1,11 +1,12 @@
-const require_annotations = require('./internal/annotations.cjs');
+const require_internal_annotations = require('./internal/annotations.cjs');
 const require_message = require('./message.cjs');
 const require_validate = require('./validate.cjs');
 const require_usage = require('./usage.cjs');
 const require_mode_dispatch = require('./internal/mode-dispatch.cjs');
-const require_dependency = require('./internal/dependency.cjs');
+const require_internal_dependency = require('./internal/dependency.cjs');
 const require_dependency_runtime = require('./dependency-runtime.cjs');
 const require_annotation_state = require('./annotation-state.cjs');
+const require_command_alias = require('./internal/command-alias.cjs');
 const require_execution_context = require('./execution-context.cjs');
 const require_phase2_seed = require('./phase2-seed.cjs');
 const require_suggestion = require('./suggestion.cjs');
@@ -23,6 +24,9 @@ function hasParsedOptionValue(state, valueParser) {
 	if (valueParser != null) return state != null && typeof state === "object" && "success" in state && typeof state.success === "boolean";
 	return state != null && "success" in state && state.success && state.value === true;
 }
+function isTerminalValueState(state) {
+	return state != null && typeof state === "object" && "success" in state && typeof state.success === "boolean";
+}
 /**
 * Helper function to create the stored state for an option or argument value.
 *
@@ -43,8 +47,8 @@ function buildTraceEntry(kind, rawInput, consumed, valueParser, parseResult, opt
 		...optionNames$1 != null ? { optionNames: optionNames$1 } : {},
 		metavar: valueParser.metavar
 	};
-	if (require_dependency.isDerivedValueParser(valueParser)) {
-		const defaults = require_dependency.getSnapshottedDefaultDependencyValues(parseResult);
+	if (require_internal_dependency.isDerivedValueParser(valueParser)) {
+		const defaults = require_internal_dependency.getSnapshottedDefaultDependencyValues(parseResult);
 		if (defaults != null) return {
 			...entry,
 			defaultDependencyValues: defaults
@@ -117,6 +121,9 @@ function constant(value) {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: false,
 		initialState: value,
+		canSkip() {
+			return true;
+		},
 		parse(context) {
 			return {
 				success: true,
@@ -174,6 +181,9 @@ function fail() {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip() {
+			return false;
+		},
 		parse(_context) {
 			return {
 				success: false,
@@ -202,13 +212,13 @@ function fail() {
 */
 function* getSuggestionsWithDependency(valueParser, prefix, dependencyRegistry, exec) {
 	if (!valueParser.suggest) return;
-	if (require_dependency.isDerivedValueParser(valueParser) && require_dependency.suggestWithDependency in valueParser) {
+	if (require_internal_dependency.isDerivedValueParser(valueParser) && require_internal_dependency.suggestWithDependency in valueParser) {
 		const derived = valueParser;
-		const suggestWithDep = derived[require_dependency.suggestWithDependency];
+		const suggestWithDep = derived[require_internal_dependency.suggestWithDependency];
 		if (suggestWithDep && dependencyRegistry) {
 			const dependencyRuntime = exec?.dependencyRuntime;
-			const depIds = require_dependency.getDependencyIds(derived);
-			const defaultsFn = require_dependency.getDefaultValuesFunction(derived);
+			const depIds = require_internal_dependency.getDependencyIds(derived);
+			const defaultsFn = require_internal_dependency.getDefaultValuesFunction(derived);
 			const defaults = defaultsFn?.();
 			const dependencyValues = [];
 			let hasAnyValue = false;
@@ -286,13 +296,13 @@ function* suggestOptionSync(optionNames$1, valueParser, hidden, context, prefix)
 */
 async function* getSuggestionsWithDependencyAsync(valueParser, prefix, dependencyRegistry, exec) {
 	if (!valueParser.suggest) return;
-	if (require_dependency.isDerivedValueParser(valueParser) && require_dependency.suggestWithDependency in valueParser) {
+	if (require_internal_dependency.isDerivedValueParser(valueParser) && require_internal_dependency.suggestWithDependency in valueParser) {
 		const derived = valueParser;
-		const suggestWithDep = derived[require_dependency.suggestWithDependency];
+		const suggestWithDep = derived[require_internal_dependency.suggestWithDependency];
 		if (suggestWithDep && dependencyRegistry) {
 			const dependencyRuntime = exec?.dependencyRuntime;
-			const depIds = require_dependency.getDependencyIds(derived);
-			const defaultsFn = require_dependency.getDefaultValuesFunction(derived);
+			const depIds = require_internal_dependency.getDependencyIds(derived);
+			const defaultsFn = require_internal_dependency.getDefaultValuesFunction(derived);
 			const defaults = defaultsFn?.();
 			const dependencyValues = [];
 			let hasAnyValue = false;
@@ -431,6 +441,9 @@ function option(...args) {
 			success: true,
 			value: false
 		} : void 0,
+		canSkip(state) {
+			return valueParser == null || isTerminalValueState(state);
+		},
 		parse(context) {
 			if (context.optionsTerminated) return {
 				success: false,
@@ -678,7 +691,7 @@ function option(...args) {
 		configurable: true,
 		enumerable: false
 	});
-	else if (!require_dependency.isDerivedValueParser(valueParser)) {
+	else if (!require_internal_dependency.isDerivedValueParser(valueParser)) {
 		const vp = valueParser;
 		const wrapParseResult = (parsed) => parsed.success ? parsed : {
 			success: false,
@@ -686,6 +699,7 @@ function option(...args) {
 		};
 		Object.defineProperty(result, "validateValue", {
 			value(v) {
+				if (typeof vp.validate === "function") return require_mode_dispatch.wrapForMode(mode, wrapParseResult(vp.validate(v)));
 				let stringified;
 				try {
 					stringified = vp.format(v);
@@ -782,6 +796,9 @@ function flag(...args) {
 		leadingNames: new Set(optionNames$1),
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state) {
+			return isTerminalValueState(state);
+		},
 		parse(context) {
 			if (context.optionsTerminated) return {
 				success: false,
@@ -1013,6 +1030,9 @@ function negatableFlag(names, options = {}) {
 		leadingNames: new Set(optionNames$1),
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state) {
+			return state != null;
+		},
 		parse(context) {
 			if (context.optionsTerminated) return {
 				success: false,
@@ -1177,6 +1197,9 @@ function argument(valueParser, options = {}) {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: true,
 		initialState: void 0,
+		canSkip(state) {
+			return isTerminalValueState(state);
+		},
 		parse(context) {
 			const localState = require_annotation_state.normalizeInjectedAnnotationState(context.state);
 			if (context.buffer.length < 1) return {
@@ -1303,7 +1326,7 @@ function argument(valueParser, options = {}) {
 			enumerable: false
 		});
 	}
-	if (!require_dependency.isDerivedValueParser(valueParser)) {
+	if (!require_internal_dependency.isDerivedValueParser(valueParser)) {
 		const vp = valueParser;
 		const vpMode = valueParser.mode;
 		const wrapParseResult = (parsed) => parsed.success ? parsed : {
@@ -1312,6 +1335,7 @@ function argument(valueParser, options = {}) {
 		};
 		Object.defineProperty(result, "validateValue", {
 			value(v) {
+				if (typeof vp.validate === "function") return require_mode_dispatch.wrapForMode(vpMode, wrapParseResult(vp.validate(v)));
 				let stringified;
 				try {
 					stringified = vp.format(v);
@@ -1359,7 +1383,7 @@ function getCommandChildState(commandState, childState, parser) {
 	return require_annotation_state.getWrappedChildState(commandState, childState, parser);
 }
 function createCommandState(sourceState, state) {
-	return require_annotations.annotateFreshArray(sourceState, state);
+	return require_internal_annotations.annotateFreshArray(sourceState, state);
 }
 function appendCommandPath(exec, name) {
 	if (exec == null) return void 0;
@@ -1368,25 +1392,56 @@ function appendCommandPath(exec, name) {
 		commandPath: [...exec.commandPath ?? [], name]
 	};
 }
-function* suggestCommandSync(context, prefix, name, parser, options) {
+function getCommandNames(name, options) {
+	return [
+		name,
+		...getVisibleCommandAliases(options),
+		...getHiddenCommandAliases(options)
+	];
+}
+function getVisibleCommandAliases(options) {
+	const aliases = options.aliases;
+	if (aliases == null) return [];
+	if (!isNonEmptyStringArray(aliases)) throw new TypeError("Command aliases must be a non-empty array of strings.");
+	return aliases;
+}
+function getHiddenCommandAliases(options) {
+	const hiddenAliases = options[require_command_alias.hiddenCommandAliasesKey];
+	if (hiddenAliases == null) return [];
+	if (!isNonEmptyStringArray(hiddenAliases)) throw new TypeError("Hidden command aliases must be a non-empty array of strings.");
+	return hiddenAliases;
+}
+function isNonEmptyStringArray(value) {
+	if (!Array.isArray(value) || value.length === 0) return false;
+	for (let i = 0; i < value.length; i++) if (typeof value[i] !== "string") return false;
+	return true;
+}
+function validateUniqueCommandNames(names) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const name of names) {
+		if (seen.has(name)) throw new TypeError(`Command has a duplicate name: "${name}".`);
+		seen.add(name);
+	}
+}
+function* suggestCommandSync(context, prefix, name, aliases, parser, options) {
 	if (require_usage.isSuggestionHidden(options.hidden)) return;
 	const state = normalizeCommandState(context.state);
 	if (state === void 0) {
-		if (name.startsWith(prefix)) yield {
+		for (const commandName of [name, ...aliases]) if (commandName.startsWith(prefix)) yield {
 			kind: "literal",
-			text: name,
+			text: commandName,
 			...options.description && { description: options.description }
 		};
 	} else if (state[0] === "matched") yield* parser.suggest(require_execution_context.withChildContext(context, name, getCommandChildState(context.state, parser.initialState, parser), parser.usage), prefix);
 	else if (state[0] === "parsing") yield* parser.suggest(require_execution_context.withChildContext(context, name, getCommandChildState(context.state, state[1], parser), parser.usage), prefix);
 }
-async function* suggestCommandAsync(context, prefix, name, parser, options) {
+async function* suggestCommandAsync(context, prefix, name, aliases, parser, options) {
 	if (require_usage.isSuggestionHidden(options.hidden)) return;
 	const state = normalizeCommandState(context.state);
 	if (state === void 0) {
-		if (name.startsWith(prefix)) yield {
+		for (const commandName of [name, ...aliases]) if (commandName.startsWith(prefix)) yield {
 			kind: "literal",
-			text: name,
+			text: commandName,
 			...options.description && { description: options.description }
 		};
 	} else if (state[0] === "matched") {
@@ -1414,7 +1469,11 @@ async function* suggestCommandAsync(context, prefix, name, parser, options) {
 *         embedded whitespace, or contains control characters.
 */
 function command(name, parser, options = {}) {
-	require_validate.validateCommandNames([name], "Command");
+	const commandNames = getCommandNames(name, options);
+	const aliases = getVisibleCommandAliases(options);
+	const hiddenAliases = getHiddenCommandAliases(options);
+	require_validate.validateCommandNames(commandNames, "Command");
+	validateUniqueCommandNames(commandNames);
 	const isAsync = parser.mode === "async";
 	const syncInnerParser = parser;
 	const asyncInnerParser = parser;
@@ -1427,12 +1486,20 @@ function command(name, parser, options = {}) {
 		usage: [{
 			type: "command",
 			name,
+			...aliases.length > 0 && { aliases },
+			...hiddenAliases.length > 0 && { hiddenAliases },
 			...options.usageLine != null && { usageLine: options.usageLine },
 			...options.hidden != null && { hidden: options.hidden }
 		}, ...parser.usage],
-		leadingNames: new Set([name]),
+		leadingNames: new Set(commandNames),
 		acceptingAnyToken: false,
 		initialState: void 0,
+		canSkip(state, exec) {
+			const normalizedState = normalizeCommandState(state);
+			if (normalizedState === void 0) return false;
+			if (normalizedState[0] === "matched") return parser.canSkip?.(getCommandChildState(state, parser.initialState, parser), require_execution_context.withChildExecPath(exec, name)) === true;
+			return parser.canSkip?.(getCommandChildState(state, normalizedState[1], parser), require_execution_context.withChildExecPath(exec, name)) === true;
+		},
 		getSuggestRuntimeNodes(state, path) {
 			const normalizedState = normalizeCommandState(state);
 			if (normalizedState === void 0) return [];
@@ -1447,10 +1514,11 @@ function command(name, parser, options = {}) {
 		parse(context) {
 			const state = normalizeCommandState(context.state);
 			if (state === void 0) {
-				if (context.buffer.length < 1 || context.buffer[0] !== name) {
+				if (context.buffer.length < 1 || !commandNames.includes(context.buffer[0])) {
 					const actual = context.buffer.length > 0 ? context.buffer[0] : null;
 					const leadingCmds = require_usage_internals.extractLeadingCommandNames(context.usage);
-					const suggestions = actual ? require_suggestion.findSimilar(actual, leadingCmds, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS) : [];
+					const rawSuggestions = actual ? require_suggestion.findSimilar(actual, leadingCmds, require_suggestion.DEFAULT_FIND_SIMILAR_OPTIONS) : [];
+					const suggestions = require_suggestion.expandCommandAliasSuggestions(context.usage, rawSuggestions);
 					if (options.errors?.notMatched) {
 						const errorMessage = options.errors.notMatched;
 						return {
@@ -1581,8 +1649,8 @@ function command(name, parser, options = {}) {
 			return require_mode_dispatch.wrapForMode(parser.mode, null);
 		},
 		suggest(context, prefix) {
-			if (isAsync) return suggestCommandAsync(context, prefix, name, parser, options);
-			return suggestCommandSync(context, prefix, name, parser, options);
+			if (isAsync) return suggestCommandAsync(context, prefix, name, aliases, parser, options);
+			return suggestCommandSync(context, prefix, name, aliases, parser, options);
 		},
 		getDocFragments(state, defaultValue) {
 			const commandState = state.kind === "available" ? normalizeCommandState(state.state) : void 0;
@@ -1696,6 +1764,9 @@ function passThrough(options = {}) {
 		leadingNames: EMPTY_LEADING_NAMES,
 		acceptingAnyToken: false,
 		initialState: [],
+		canSkip() {
+			return true;
+		},
 		parse(context) {
 			if (context.buffer.length < 1) return {
 				success: false,
@@ -1710,7 +1781,7 @@ function passThrough(options = {}) {
 					next: {
 						...context,
 						buffer: [],
-						state: require_annotations.annotateFreshArray(context.state, [...context.state, ...captured])
+						state: require_internal_annotations.annotateFreshArray(context.state, [...context.state, ...captured])
 					},
 					consumed: captured
 				};
@@ -1731,7 +1802,7 @@ function passThrough(options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(1),
-						state: require_annotations.annotateFreshArray(context.state, [...context.state, token])
+						state: require_internal_annotations.annotateFreshArray(context.state, [...context.state, token])
 					},
 					consumed: [token]
 				};
@@ -1747,7 +1818,7 @@ function passThrough(options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(1),
-						state: require_annotations.annotateFreshArray(context.state, [...context.state, token])
+						state: require_internal_annotations.annotateFreshArray(context.state, [...context.state, token])
 					},
 					consumed: [token]
 				};
@@ -1757,7 +1828,7 @@ function passThrough(options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(2),
-						state: require_annotations.annotateFreshArray(context.state, [
+						state: require_internal_annotations.annotateFreshArray(context.state, [
 							...context.state,
 							token,
 							nextToken
@@ -1770,7 +1841,7 @@ function passThrough(options = {}) {
 					next: {
 						...context,
 						buffer: context.buffer.slice(1),
-						state: require_annotations.annotateFreshArray(context.state, [...context.state, token])
+						state: require_internal_annotations.annotateFreshArray(context.state, [...context.state, token])
 					},
 					consumed: [token]
 				};
@@ -1782,7 +1853,7 @@ function passThrough(options = {}) {
 			};
 		},
 		complete(state, _exec) {
-			if (require_annotations.getAnnotations(state) == null) return {
+			if (require_internal_annotations.getAnnotations(state) == null) return {
 				success: true,
 				value: state
 			};

package/dist/primitives.d.cts

@@ -448,6 +448,16 @@ interface CommandOptions {
    * @since 0.9.0
    */
   readonly hidden?: HiddenVisibility;
+  /**
+   * Additional names that invoke this command.
+   *
+   * Aliases are functional at runtime and are suggested by shell completion,
+   * but are hidden from usage and documentation output.  The `name` parameter
+   * passed to {@link command} remains the canonical display name.
+   *
+   * @since 1.1.0
+   */
+  readonly aliases?: readonly [string, ...string[]];
   /**
    * Error messages customization.
    * @since 0.5.0

package/dist/primitives.d.ts

@@ -448,6 +448,16 @@ interface CommandOptions {
    * @since 0.9.0
    */
   readonly hidden?: HiddenVisibility;
+  /**
+   * Additional names that invoke this command.
+   *
+   * Aliases are functional at runtime and are suggested by shell completion,
+   * but are hidden from usage and documentation output.  The `name` parameter
+   * passed to {@link command} remains the canonical display name.
+   *
+   * @since 1.1.0
+   */
+  readonly aliases?: readonly [string, ...string[]];
   /**
    * Error messages customization.
    * @since 0.5.0