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

package/dist/facade.js

@@ -1,6 +1,5 @@
 import { injectAnnotations, isInjectedAnnotationWrapper, unwrapInjectedAnnotationWrapper } from "./internal/annotations.js";
 import { commandLine, formatMessage, lineBreak, message, optionName, text, value } from "./message.js";
-import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { validateCommandNames, validateContextIds, validateMetaNameCollisions, validateOptionNames, validateProgramName } from "./validate.js";
 import { formatUsage, isSuggestionHidden } from "./usage.js";
 import { formatDocPage } from "./doc.js";
@@ -8,6 +7,8 @@ import { dispatchByMode } from "./internal/mode-dispatch.js";
 import { collectExplicitSourceValues, collectExplicitSourceValuesAsync, createDependencyRuntimeContext } from "./dependency-runtime.js";
 import { createInputTrace } from "./input-trace.js";
 import { createParserContext, getDocPage } from "./internal/parser.js";
+import { bash, fish, nu, pwsh, zsh } from "./completion.js";
+import { allowDuplicateLeadingCommandNamesKey, hiddenCommandAliasesKey } from "./internal/command-alias.js";
 import { completeOrExtractPhase2Seed } from "./phase2-seed.js";
 import { group, longestMatch, object } from "./constructs.js";
 import { multiple, optional, withDefault } from "./modifiers.js";
@@ -15,6 +16,14 @@ import { string } from "./valueparser.js";
 import { argument, command, constant, flag, option } from "./primitives.js";
 
 //#region src/facade.ts
+/**
+* Combines built-in meta commands while intentionally bypassing duplicate
+* leading command name validation in `createLongestMatch()`.
+*/
+function longestMatchForMetaCommands(...parsers) {
+	const options = { [allowDuplicateLeadingCommandNamesKey]: true };
+	return longestMatch(...parsers, options);
+}
 const SuppressedErrorCtor = typeof SuppressedError === "function" ? SuppressedError : (() => {
 	class SuppressedErrorPolyfill extends Error {
 		error;
@@ -278,6 +287,10 @@ async function extractPhase2SeedAsync(parser, args) {
 	} while (context.buffer.length > 0);
 	return await 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 = multiple(argument(string({ metavar: "COMMAND" }), { description: message`Command name to show help for.` }));
-		const commandParsers = [];
-		for (let i = 0; i < names.length; i++) commandParsers.push(command(names[i], innerParser, {
+		const aliases = getMetaCommandAliases(names);
+		helpCommand = command(names[0], innerParser, {
 			description: message`Show help information.`,
-			hidden: i === 0 ? commandConfig.hidden : true
-		}));
-		helpCommand = commandParsers.length === 1 ? commandParsers[0] : longestMatch(...commandParsers);
+			...aliases != null ? { [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 = object({});
-		const commandParsers = [];
-		for (let i = 0; i < names.length; i++) commandParsers.push(command(names[i], innerParser, {
+		const aliases = getMetaCommandAliases(names);
+		versionCommand = command(names[0], innerParser, {
 			description: message`Show version information.`,
-			hidden: i === 0 ? commandConfig.hidden : true
-		}));
-		versionCommand = commandParsers.length === 1 ? commandParsers[0] : longestMatch(...commandParsers);
+			...aliases != null ? { [hiddenCommandAliasesKey]: aliases } : {},
+			hidden: commandConfig.hidden
+		});
 	}
 	if (optionConfig) {
 		const names = optionConfig.names ?? ["--version"];
@@ -358,12 +371,12 @@ function createCompletionParser(programName, availableShells, commandConfig, opt
 			description: message`Generate shell completion script or provide completions.`,
 			footer: message`Examples:${lineBreak()}  Bash:       ${commandLine(`eval "$(${programName} ${displayName} bash)"`)}${lineBreak()}  zsh:        ${commandLine(`eval "$(${programName} ${displayName} zsh)"`)}${lineBreak()}  fish:       ${commandLine(`eval "$(${programName} ${displayName} fish)"`)}${lineBreak()}  PowerShell: ${commandLine(`${programName} ${displayName} pwsh > ${programName}-completion.ps1; . ./${programName}-completion.ps1`)}${lineBreak()}  Nushell:    ${commandLine(`${programName} ${displayName} nu | save ${programName}-completion.nu; source ./${programName}-completion.nu`)}`
 		};
-		const commandParsers = [];
-		for (let i = 0; i < names.length; i++) commandParsers.push(command(names[i], completionInner, {
+		const aliases = getMetaCommandAliases(names);
+		completionCommand = command(names[0], completionInner, {
 			...completionCommandConfig,
-			hidden: i === 0 ? commandConfig.hidden : true
-		}));
-		completionCommand = commandParsers.length === 1 ? commandParsers[0] : longestMatch(...commandParsers);
+			...aliases != null ? { [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 = longestMatch(parsers[0], parsers[1]);
-	else combined = longestMatch(...parsers);
+	let combined = longestMatchForMetaCommands(...parsers);
 	const topUsage = combined.usage[0];
 	if (topUsage?.type === "exclusive" && mainParserIndex > 0) {
 		const terms = [...topUsage.terms];
@@ -1080,8 +1091,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 					for (const [label, optParsers] of Object.entries(groupedMetaOptions)) if (optParsers.length === 1) commandParsers.push(group(label, optParsers[0]));
 					else commandParsers.push(group(label, longestMatch(...optParsers)));
 					if (commandParsers.length === 1) helpGeneratorParser = commandParsers[0];
-					else if (commandParsers.length === 2) helpGeneratorParser = longestMatch(commandParsers[0], commandParsers[1]);
-					else helpGeneratorParser = longestMatch(...commandParsers);
+					else helpGeneratorParser = longestMatchForMetaCommands(...commandParsers);
 				}
 				const reportInvalidHelpCommand = (validationError) => {
 					stderr(`Usage: ${indentLines(formatUsage(programName, augmentedParser.usage, {

package/dist/index.cjs

@@ -1,10 +1,10 @@
-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_usage = require('./usage.cjs');
 const require_doc = require('./doc.cjs');
-const require_dependency = require('./internal/dependency.cjs');
-const require_parser = require('./internal/parser.cjs');
+const require_internal_dependency = require('./internal/dependency.cjs');
+const require_internal_parser = require('./internal/parser.cjs');
+const require_completion = require('./completion.cjs');
 const require_constructs = require('./constructs.cjs');
 const require_modifiers = require('./modifiers.cjs');
 const require_nonempty = require('./nonempty.cjs');
@@ -30,13 +30,13 @@ exports.commandLine = require_message.commandLine;
 exports.concat = require_constructs.concat;
 exports.conditional = require_constructs.conditional;
 exports.constant = require_primitives.constant;
-exports.createParserContext = require_parser.createParserContext;
+exports.createParserContext = require_internal_parser.createParserContext;
 exports.deduplicateDocEntries = require_doc.deduplicateDocEntries;
 exports.deduplicateDocFragments = require_doc.deduplicateDocFragments;
-exports.dependency = require_dependency.dependency;
-exports.deriveFrom = require_dependency.deriveFrom;
-exports.deriveFromAsync = require_dependency.deriveFromAsync;
-exports.deriveFromSync = require_dependency.deriveFromSync;
+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.domain = require_valueparser.domain;
 exports.email = require_valueparser.email;
 exports.ensureNonEmptyString = require_nonempty.ensureNonEmptyString;
@@ -47,6 +47,7 @@ exports.extractLiteralValues = require_usage.extractLiteralValues;
 exports.extractOptionNames = require_usage.extractOptionNames;
 exports.fail = require_primitives.fail;
 exports.fileSize = require_valueparser.fileSize;
+exports.firstOf = require_valueparser.firstOf;
 exports.fish = require_completion.fish;
 exports.flag = require_primitives.flag;
 exports.float = require_valueparser.float;
@@ -54,18 +55,18 @@ exports.formatDocPage = require_doc.formatDocPage;
 exports.formatMessage = require_message.formatMessage;
 exports.formatUsage = require_usage.formatUsage;
 exports.formatUsageTerm = require_usage.formatUsageTerm;
-exports.getAnnotations = require_annotations.getAnnotations;
-exports.getDocPage = require_parser.getDocPage;
-exports.getDocPageAsync = require_parser.getDocPageAsync;
-exports.getDocPageSync = require_parser.getDocPageSync;
+exports.getAnnotations = require_internal_annotations.getAnnotations;
+exports.getDocPage = require_internal_parser.getDocPage;
+exports.getDocPageAsync = require_internal_parser.getDocPageAsync;
+exports.getDocPageSync = require_internal_parser.getDocPageSync;
 exports.group = require_constructs.group;
 exports.hostname = require_valueparser.hostname;
 exports.integer = require_valueparser.integer;
 exports.ip = require_valueparser.ip;
 exports.ipv4 = require_valueparser.ipv4;
 exports.ipv6 = require_valueparser.ipv6;
-exports.isDependencySource = require_dependency.isDependencySource;
-exports.isDerivedValueParser = require_dependency.isDerivedValueParser;
+exports.isDependencySource = require_internal_dependency.isDependencySource;
+exports.isDerivedValueParser = require_internal_dependency.isDerivedValueParser;
 exports.isDocEntryHidden = require_doc.isDocEntryHidden;
 exports.isDocHidden = require_usage.isDocHidden;
 exports.isNonEmptyString = require_nonempty.isNonEmptyString;
@@ -94,9 +95,9 @@ exports.optionName = require_message.optionName;
 exports.optionNames = require_message.optionNames;
 exports.optional = require_modifiers.optional;
 exports.or = require_constructs.or;
-exports.parse = require_parser.parse;
-exports.parseAsync = require_parser.parseAsync;
-exports.parseSync = require_parser.parseSync;
+exports.parse = require_internal_parser.parse;
+exports.parseAsync = require_internal_parser.parseAsync;
+exports.parseSync = require_internal_parser.parseSync;
 exports.passThrough = require_primitives.passThrough;
 exports.port = require_valueparser.port;
 exports.portRange = require_valueparser.portRange;
@@ -111,9 +112,9 @@ exports.semVer = require_valueparser.semVer;
 exports.seq = require_constructs.seq;
 exports.socketAddress = require_valueparser.socketAddress;
 exports.string = require_valueparser.string;
-exports.suggest = require_parser.suggest;
-exports.suggestAsync = require_parser.suggestAsync;
-exports.suggestSync = require_parser.suggestSync;
+exports.suggest = require_internal_parser.suggest;
+exports.suggestAsync = require_internal_parser.suggestAsync;
+exports.suggestSync = require_internal_parser.suggestSync;
 exports.text = require_message.text;
 exports.tuple = require_constructs.tuple;
 exports.url = require_valueparser.url;

package/dist/index.d.cts

@@ -3,7 +3,7 @@ import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonemp
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.cjs";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.cjs";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.cjs";
-import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.cjs";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.cjs";
 import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.cjs";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.cjs";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.cjs";
@@ -12,4 +12,4 @@ import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMod
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.cjs";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.cjs";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.d.ts

@@ -3,7 +3,7 @@ import { NonEmptyString, ensureNonEmptyString, isNonEmptyString } from "./nonemp
 import { Message, MessageFormatOptions, MessageTerm, ValueSetOptions, commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
 import { HiddenVisibility, OptionName, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, ShowChoicesOptions, ShowDefaultOptions, cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
-import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
+import { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, MacAddressOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
 import { CombineModes, DocState, ExecutionContext, ExecutionPhase, InferMode, InferValue, Mode, ModeIterable, ModeValue, ParseFrame, Parser, ParserContext, ParserResult, Result, Suggestion, createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
 import { ShellCompletion, bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { ConditionalErrorOptions, ConditionalOptions, DuplicateOptionError, GroupOptions, LongestMatchErrorOptions, LongestMatchOptions, MergeOptions, NoMatchContext, ObjectErrorOptions, ObjectOptions, OrErrorOptions, OrOptions, SeqOptions, TupleOptions, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.js";
@@ -12,4 +12,4 @@ import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMod
 import { CommandSubConfig, ContextOptionsParam, ExtractRequiredOptions, OptionSubConfig, RunOptions, RunParserError, RunWithOptions, SubstituteParserValue, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 import { MultipleErrorOptions, MultipleOptions, WithDefaultError, WithDefaultOptions, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ArgumentErrorOptions, ArgumentOptions, CommandErrorOptions, CommandOptions, FlagErrorOptions, FlagOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, OptionErrorOptions, OptionOptions, OptionState, PassThroughFormat, PassThroughOptions, argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
-export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { type Annotations, AnyDependencySource, ArgumentErrorOptions, ArgumentOptions, ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CombineMode, CombineModes, CombinedDependencyMode, CommandErrorOptions, CommandOptions, CommandSubConfig, ConditionalErrorOptions, ConditionalOptions, ContextOptionsParam, DeferredMap, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EmailOptions, ExecutionContext, ExecutionPhase, ExtractRequiredOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FlagErrorOptions, FlagOptions, FloatOptions, GroupOptions, HiddenVisibility, HostnameOptions, InferMode, InferValue, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, LocaleOptions, LongestMatchErrorOptions, LongestMatchOptions, MacAddressOptions, MergeOptions, type Message, type MessageFormatOptions, type MessageTerm, Mode, ModeIterable, ModeValue, MultipleErrorOptions, MultipleOptions, NegatableFlagErrorOptions, NegatableFlagNameList, NegatableFlagNames, NegatableFlagOptions, NegatableFlagState, NoMatchContext, NonEmptyString, ObjectErrorOptions, ObjectOptions, OptionErrorOptions, OptionName, OptionOptions, OptionState, OptionSubConfig, OrErrorOptions, OrOptions, ParseFrame, type ParseOptions, Parser, ParserContext, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, TupleOptions, UrlOptions, Usage, UsageFormatOptions, UsageTerm, UsageTermFormatOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, type ValueSetOptions, WithDefaultError, WithDefaultOptions, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/index.js

@@ -1,15 +1,15 @@
 import { getAnnotations } from "./internal/annotations.js";
 import { commandLine, envVar, formatMessage, lineBreak, link, message, metavar, optionName, optionNames, text, value, valueSet, values } from "./message.js";
-import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { cloneUsage, cloneUsageTerm, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, formatUsage, formatUsageTerm, isDocHidden, isSuggestionHidden, isUsageHidden, mergeHidden, normalizeUsage } from "./usage.js";
 import { cloneDocEntry, deduplicateDocEntries, deduplicateDocFragments, formatDocPage, isDocEntryHidden } from "./doc.js";
 import { dependency, deriveFrom, deriveFromAsync, deriveFromSync, isDependencySource, isDerivedValueParser } from "./internal/dependency.js";
 import { createParserContext, getDocPage, getDocPageAsync, getDocPageSync, parse, parseAsync, parseSync, suggest, suggestAsync, suggestSync } from "./internal/parser.js";
+import { bash, fish, nu, pwsh, zsh } from "./completion.js";
 import { DuplicateOptionError, concat, conditional, group, longestMatch, merge, object, or, seq, tuple } from "./constructs.js";
 import { WithDefaultError, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
 import { ensureNonEmptyString, isNonEmptyString } from "./nonempty.js";
-import { checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
+import { checkBooleanOption, checkEnumOption, choice, cidr, color, domain, email, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isValueParser, json, locale, macAddress, port, portRange, semVer, socketAddress, string, url, uuid } from "./valueparser.js";
 import { argument, command, constant, fail, flag, negatableFlag, option, passThrough } from "./primitives.js";
 import { RunParserError, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync } from "./facade.js";
 
-export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };
+export { DuplicateOptionError, RunParserError, WithDefaultError, argument, bash, checkBooleanOption, checkEnumOption, choice, cidr, cloneDocEntry, cloneUsage, cloneUsageTerm, color, command, commandLine, concat, conditional, constant, createParserContext, deduplicateDocEntries, deduplicateDocFragments, dependency, deriveFrom, deriveFromAsync, deriveFromSync, domain, email, ensureNonEmptyString, envVar, extractArgumentMetavars, extractCommandNames, extractLiteralValues, extractOptionNames, fail, fileSize, firstOf, fish, flag, float, formatDocPage, formatMessage, formatUsage, formatUsageTerm, getAnnotations, getDocPage, getDocPageAsync, getDocPageSync, group, hostname, integer, ip, ipv4, ipv6, isDependencySource, isDerivedValueParser, isDocEntryHidden, isDocHidden, isNonEmptyString, isSuggestionHidden, isUsageHidden, isValueParser, json, lineBreak, link, locale, longestMatch, macAddress, map, merge, mergeHidden, message, metavar, multiple, negatableFlag, nonEmpty, normalizeUsage, nu, object, option, optionName, optionNames, optional, or, parse, parseAsync, parseSync, passThrough, port, portRange, pwsh, runParser, runParserAsync, runParserSync, runWith, runWithAsync, runWithSync, semVer, seq, socketAddress, string, suggest, suggestAsync, suggestSync, text, tuple, url, uuid, value, valueSet, values, withDefault, zsh };

package/dist/input-trace.d.cts

@@ -73,5 +73,6 @@ interface InputTrace {
  * @internal
  * @since 1.0.0
  */
+declare function createInputTrace(): InputTrace;
 //#endregion
-export { InputTrace };
+export { InputTrace, TraceEntry, createInputTrace };

package/dist/input-trace.d.ts

@@ -73,5 +73,6 @@ interface InputTrace {
  * @internal
  * @since 1.0.0
  */
+declare function createInputTrace(): InputTrace;
 //#endregion
-export { InputTrace };
+export { InputTrace, TraceEntry, createInputTrace };

package/dist/internal/annotations.cjs

@@ -306,6 +306,9 @@ function unwrapInjectedAnnotationState(value) {
 //#endregion
 exports.annotateFreshArray = annotateFreshArray;
 exports.annotationKey = annotationKey;
+exports.annotationStateValueKey = annotationStateValueKey;
+exports.annotationWrapperKey = annotationWrapperKey;
+exports.firstPassAnnotationKey = firstPassAnnotationKey;
 exports.getAnnotations = getAnnotations;
 exports.hasMeaningfulAnnotations = hasMeaningfulAnnotations;
 exports.inheritAnnotations = inheritAnnotations;

package/dist/internal/annotations.d.cts

@@ -1,5 +1,38 @@
 //#region src/internal/annotations.d.ts
-
+/**
+ * Runtime context extension system for Optique parsers.
+ *
+ * This module provides the annotations system that allows external runtime data
+ * to be passed to parsers during the parsing session. This enables use cases like
+ * config file fallbacks, environment-based validation, and shared context.
+ *
+ * @module
+ * @since 0.10.0
+ */
+/**
+ * Annotation key symbol for storing data in parser state.
+ * @since 0.10.0
+ */
+declare const annotationKey: unique symbol;
+/**
+ * Internal marker attached during the first pass of `runWith()` so wrappers
+ * with side effects can defer work until two-pass contexts have resolved.
+ *
+ * @internal
+ */
+declare const firstPassAnnotationKey: unique symbol;
+/**
+ * Internal key for preserving primitive parser state values when annotations
+ * are injected into non-object states.
+ * @internal
+ */
+declare const annotationStateValueKey: unique symbol;
+/**
+ * Internal marker key that indicates annotation wrapping was injected by
+ * Optique internals for non-object states.
+ * @internal
+ */
+declare const annotationWrapperKey: unique symbol;
 /**
  * Annotations that can be passed to parsers during execution.
  * Allows external packages to provide additional data that parsers can access
@@ -53,7 +86,7 @@ declare function getAnnotations(state: unknown): Annotations | undefined;
  * @returns The target array, with annotations copied when available.
  * @internal
  */
-
+declare function annotateFreshArray<T>(source: unknown, target: readonly T[]): readonly T[];
 /**
  * Propagates annotations from one parser state to another.
  *
@@ -85,7 +118,7 @@ declare function inheritAnnotations<T>(source: unknown, target: T): T;
  * @returns `true` when the record has at least one own symbol key.
  * @internal
  */
-
+declare function hasMeaningfulAnnotations(annotations: Annotations | null | undefined): annotations is Annotations;
 /**
  * Injects annotations into parser state while preserving state shape.
  *
@@ -111,7 +144,16 @@ declare function injectAnnotations<TState>(state: TState, annotations: Annotatio
  *          otherwise the original value.
  * @internal
  */
-
+declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
+/**
+ * Returns whether the given value is an internal primitive-state annotation
+ * wrapper that was injected by Optique.
+ *
+ * @param value Value to check.
+ * @returns `true` if the value is an injected internal wrapper.
+ * @internal
+ */
+declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 /**
  * Returns whether the given value is an injected annotation state wrapper.
  *
@@ -137,4 +179,4 @@ declare function isInjectedAnnotationState(value: unknown): boolean;
  */
 declare function unwrapInjectedAnnotationState<T>(value: T): T;
 //#endregion
-export { Annotations, ParseOptions, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwrapInjectedAnnotationState };
+export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, isInjectedAnnotationWrapper, unwrapInjectedAnnotationState, unwrapInjectedAnnotationWrapper };

package/dist/internal/annotations.d.ts

@@ -1,5 +1,38 @@
 //#region src/internal/annotations.d.ts
-
+/**
+ * Runtime context extension system for Optique parsers.
+ *
+ * This module provides the annotations system that allows external runtime data
+ * to be passed to parsers during the parsing session. This enables use cases like
+ * config file fallbacks, environment-based validation, and shared context.
+ *
+ * @module
+ * @since 0.10.0
+ */
+/**
+ * Annotation key symbol for storing data in parser state.
+ * @since 0.10.0
+ */
+declare const annotationKey: unique symbol;
+/**
+ * Internal marker attached during the first pass of `runWith()` so wrappers
+ * with side effects can defer work until two-pass contexts have resolved.
+ *
+ * @internal
+ */
+declare const firstPassAnnotationKey: unique symbol;
+/**
+ * Internal key for preserving primitive parser state values when annotations
+ * are injected into non-object states.
+ * @internal
+ */
+declare const annotationStateValueKey: unique symbol;
+/**
+ * Internal marker key that indicates annotation wrapping was injected by
+ * Optique internals for non-object states.
+ * @internal
+ */
+declare const annotationWrapperKey: unique symbol;
 /**
  * Annotations that can be passed to parsers during execution.
  * Allows external packages to provide additional data that parsers can access
@@ -53,7 +86,7 @@ declare function getAnnotations(state: unknown): Annotations | undefined;
  * @returns The target array, with annotations copied when available.
  * @internal
  */
-
+declare function annotateFreshArray<T>(source: unknown, target: readonly T[]): readonly T[];
 /**
  * Propagates annotations from one parser state to another.
  *
@@ -85,7 +118,7 @@ declare function inheritAnnotations<T>(source: unknown, target: T): T;
  * @returns `true` when the record has at least one own symbol key.
  * @internal
  */
-
+declare function hasMeaningfulAnnotations(annotations: Annotations | null | undefined): annotations is Annotations;
 /**
  * Injects annotations into parser state while preserving state shape.
  *
@@ -111,7 +144,16 @@ declare function injectAnnotations<TState>(state: TState, annotations: Annotatio
  *          otherwise the original value.
  * @internal
  */
-
+declare function unwrapInjectedAnnotationWrapper<T>(value: T): T;
+/**
+ * Returns whether the given value is an internal primitive-state annotation
+ * wrapper that was injected by Optique.
+ *
+ * @param value Value to check.
+ * @returns `true` if the value is an injected internal wrapper.
+ * @internal
+ */
+declare function isInjectedAnnotationWrapper(value: unknown): boolean;
 /**
  * Returns whether the given value is an injected annotation state wrapper.
  *
@@ -137,4 +179,4 @@ declare function isInjectedAnnotationState(value: unknown): boolean;
  */
 declare function unwrapInjectedAnnotationState<T>(value: T): T;
 //#endregion
-export { Annotations, ParseOptions, getAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, unwrapInjectedAnnotationState };
+export { Annotations, ParseOptions, annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, isInjectedAnnotationWrapper, unwrapInjectedAnnotationState, unwrapInjectedAnnotationWrapper };

package/dist/internal/annotations.js

@@ -303,4 +303,4 @@ function unwrapInjectedAnnotationState(value) {
 }
 
 //#endregion
-export { annotateFreshArray, annotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, isInjectedAnnotationWrapper, unwrapInjectedAnnotationState, unwrapInjectedAnnotationWrapper };
+export { annotateFreshArray, annotationKey, annotationStateValueKey, annotationWrapperKey, firstPassAnnotationKey, getAnnotations, hasMeaningfulAnnotations, inheritAnnotations, injectAnnotations, isInjectedAnnotationState, isInjectedAnnotationWrapper, unwrapInjectedAnnotationState, unwrapInjectedAnnotationWrapper };

package/dist/internal/command-alias.cjs

@@ -0,0 +1,16 @@
+
+//#region src/internal/command-alias.ts
+/**
+* Internal key used to bypass duplicate leading command name validation when
+* composing built-in meta commands with user parsers.
+*/
+const allowDuplicateLeadingCommandNamesKey = Symbol("allowDuplicateLeadingCommandNames");
+/**
+* Internal command() option key for aliases that are accepted by parsing but
+* omitted from completion and typo-suggestion display.
+*/
+const hiddenCommandAliasesKey = Symbol("hiddenCommandAliases");
+
+//#endregion
+exports.allowDuplicateLeadingCommandNamesKey = allowDuplicateLeadingCommandNamesKey;
+exports.hiddenCommandAliasesKey = hiddenCommandAliasesKey;

package/dist/internal/command-alias.js

@@ -0,0 +1,14 @@
+//#region src/internal/command-alias.ts
+/**
+* Internal key used to bypass duplicate leading command name validation when
+* composing built-in meta commands with user parsers.
+*/
+const allowDuplicateLeadingCommandNamesKey = Symbol("allowDuplicateLeadingCommandNames");
+/**
+* Internal command() option key for aliases that are accepted by parsing but
+* omitted from completion and typo-suggestion display.
+*/
+const hiddenCommandAliasesKey = Symbol("hiddenCommandAliases");
+
+//#endregion
+export { allowDuplicateLeadingCommandNamesKey, hiddenCommandAliasesKey };