@optique/core 1.3.0-dev.2582 → 1.3.0-dev.2583

package/dist/index.cjs

@@ -105,6 +105,7 @@ exports.optionName = require_message.optionName;
 exports.optionNames = require_message.optionNames;
 exports.optional = require_modifiers.optional;
 exports.or = require_constructs.or;
+exports.origin = require_valueparser.origin;
 exports.parse = require_internal_parser.parse;
 exports.parseAsync = require_internal_parser.parseAsync;
 exports.parseDetailed = require_internal_parser.parseDetailed;

package/dist/index.d.cts

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

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/valueparser.cjs

@@ -2750,6 +2750,178 @@ function url(options = {}) {
 	};
 }
 /**
+* A host name that the WHATWG URL parser has canonicalized into a dotted-quad
+* IPv4 address.  Matching the canonical form is enough, because the parser
+* turns every other spelling (`0x7f.1`, `2130706433`, …) into it.
+*/
+const IPV4_PATTERN = /^\d{1,3}(?:\.\d{1,3}){3}$/u;
+/**
+* Creates a {@link ValueParser} for web origins.
+*
+* An origin is a scheme, a host, and an optional port, and nothing else.  The
+* parser returns a `URL` whose pathname is `/` and which carries no
+* credentials, query, or fragment.
+*
+* Input is canonicalized rather than rejected when it carries more than an
+* origin: the host is lowercased, internationalized names are converted to
+* punycode, and a default port is elided, so `HTTPS://Example.COM/`,
+* `https://example.com:443/path?query#fragment` all parse to
+* `https://example.com`.  Set `extraComponents: "reject"` to fail on a path,
+* query, or fragment instead.  Credentials are always rejected.  Schemes whose
+* origin is opaque (`mailto:`, `data:`, `file:`) are rejected, as is `blob:`,
+* whose origin belongs to the URL it wraps.
+*
+* By default a trailing root-zone dot is stripped, so `example.com.` becomes
+* `example.com`.  This differs from the WHATWG origin, which keeps the dot, so
+* the two strings are not interchangeable when an exact origin comparison
+* matters.  Use `trailingDot: "preserve"` for the WHATWG behavior or
+* `trailingDot: "append"` to force a fully-qualified name.
+*
+* @param options Configuration options for the origin parser.
+* @returns A {@link ValueParser} that converts string input to `URL` objects
+*          that name an origin.
+* @throws {TypeError} If any `allowedProtocols` entry is not a valid protocol
+*   string ending with a colon (e.g., `"https:"`).
+* @since 1.3.0
+*/
+function origin(options = {}) {
+	const metavar$1 = options.metavar ?? "ORIGIN";
+	require_nonempty.ensureNonEmptyString(metavar$1);
+	checkEnumOption(options, "extraComponents", ["strip", "reject"]);
+	checkEnumOption(options, "trailingDot", [
+		"strip",
+		"preserve",
+		"append"
+	]);
+	const extraComponents = options.extraComponents ?? "strip";
+	const trailingDot = options.trailingDot ?? "strip";
+	const originalProtocolsList = [];
+	const normalizedProtocolsList = [];
+	if (options.allowedProtocols != null) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const protocol of options.allowedProtocols) {
+			if (typeof protocol !== "string" || !/^[a-z][a-z0-9+\-.]*:$/i.test(protocol)) {
+				const rendered = typeof protocol === "string" ? JSON.stringify(protocol) : String(protocol);
+				throw new TypeError(`Each allowed protocol must be a valid protocol ending with a colon (e.g., "https:"), got: ${rendered}.`);
+			}
+			const normalized = protocol.toLowerCase();
+			if (seen.has(normalized)) continue;
+			seen.add(normalized);
+			originalProtocolsList.push(protocol);
+			normalizedProtocolsList.push(normalized);
+		}
+		if (originalProtocolsList.length === 0) throw new TypeError("allowedProtocols must not be empty.");
+	}
+	const originalProtocols = options.allowedProtocols != null ? Object.freeze(originalProtocolsList) : void 0;
+	const allowedProtocols = options.allowedProtocols != null ? Object.freeze(normalizedProtocolsList) : void 0;
+	const invalidOrigin = options.errors?.invalidOrigin;
+	const disallowedProtocol = options.errors?.disallowedProtocol;
+	function invalidOriginError(input) {
+		return invalidOrigin ? typeof invalidOrigin === "function" ? invalidOrigin(input) : invalidOrigin : require_message.message`Invalid origin: ${input}.`;
+	}
+	function disallowedProtocolError(protocol) {
+		return disallowedProtocol ? typeof disallowedProtocol === "function" ? disallowedProtocol(protocol, originalProtocols) : disallowedProtocol : [
+			{
+				type: "text",
+				text: "URL protocol "
+			},
+			{
+				type: "value",
+				value: protocol
+			},
+			{
+				type: "text",
+				text: " is not allowed. Allowed protocols: "
+			},
+			...require_message.valueSet(originalProtocols, {
+				fallback: "",
+				locale: "en-US"
+			}),
+			{
+				type: "text",
+				text: "."
+			}
+		];
+	}
+	function withTrailingDot(url$1) {
+		if (trailingDot === "preserve") return url$1;
+		const { hostname: hostname$1 } = url$1;
+		if (hostname$1.startsWith("[") || IPV4_PATTERN.test(hostname$1)) return url$1;
+		if (trailingDot === "strip") {
+			const stripped = hostname$1.replace(/\.+$/u, "");
+			if (stripped !== "") url$1.hostname = stripped;
+		} else if (!hostname$1.endsWith(".")) url$1.hostname = `${hostname$1}.`;
+		return url$1;
+	}
+	function resolve(url$1, label) {
+		if (allowedProtocols != null && !allowedProtocols.includes(url$1.protocol)) return {
+			success: false,
+			error: disallowedProtocolError(url$1.protocol)
+		};
+		if (url$1.protocol === "blob:") return {
+			success: false,
+			error: require_message.message`The URL ${label} wraps another origin. Pass that origin instead.`
+		};
+		if (url$1.origin === "null") return {
+			success: false,
+			error: require_message.message`The URL ${label} has no origin.`
+		};
+		if (url$1.username !== "" || url$1.password !== "") return {
+			success: false,
+			error: require_message.message`An origin must not contain credentials: ${url$1.origin}`
+		};
+		if (extraComponents === "reject" && (url$1.pathname !== "/" || url$1.search !== "" || url$1.hash !== "")) return {
+			success: false,
+			error: require_message.message`Expected only an origin, but got: ${label}`
+		};
+		return {
+			success: true,
+			value: withTrailingDot(new URL(url$1.origin))
+		};
+	}
+	return {
+		mode: "sync",
+		metavar: metavar$1,
+		get placeholder() {
+			return new URL(`${allowedProtocols?.[0] ?? "http:"}//0.invalid`);
+		},
+		parse(input) {
+			if (!URL.canParse(input)) return {
+				success: false,
+				error: invalidOriginError(input)
+			};
+			return resolve(new URL(input), input);
+		},
+		validate(value) {
+			if (!(value instanceof URL)) return {
+				success: false,
+				error: invalidOriginError(String(value))
+			};
+			return resolve(value, value.href);
+		},
+		format(value) {
+			return value.origin;
+		},
+		normalize(value) {
+			if (!(value instanceof URL)) return value;
+			const result = resolve(value, value.href);
+			return result.success ? result.value : value;
+		},
+		*suggest(prefix) {
+			if (allowedProtocols && prefix.length > 0 && !prefix.includes(":")) for (const protocol of allowedProtocols) {
+				const cleanProtocol = protocol.replace(/:+$/, "");
+				if (cleanProtocol.startsWith(prefix.toLowerCase())) {
+					const suffix = SPECIAL_URL_SCHEMES.has(cleanProtocol) ? "://" : ":";
+					yield {
+						kind: "literal",
+						text: `${cleanProtocol}${suffix}`
+					};
+				}
+			}
+		}
+	};
+}
+/**
 * Creates a {@link ValueParser} for locale values.
 *
 * This parser validates that the input is a well-formed locale identifier
@@ -6691,6 +6863,7 @@ exports.json = json;
 exports.keyValue = keyValue;
 exports.locale = locale;
 exports.macAddress = macAddress;
+exports.origin = origin;
 exports.port = port;
 exports.portRange = portRange;
 exports.regExp = regExp;

package/dist/valueparser.d.cts

@@ -1189,6 +1189,91 @@ interface UrlOptions {
  *   string ending with a colon (e.g., `"https:"`).
  */
 declare function url(options?: UrlOptions): ValueParser<"sync", URL>;
+/**
+ * Options for creating an {@link origin} parser.
+ */
+interface OriginOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `ORIGIN` or `BASE_URL`.
+   * @default `"ORIGIN"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * List of allowed URL protocols (e.g., `["http:", "https:"]`).
+   * If specified, the parsed URL must use one of these protocols.
+   * Protocol names should include the trailing colon (e.g., `"https:"`).
+   * If not specified, any protocol with a tuple origin is allowed.
+   */
+  readonly allowedProtocols?: readonly string[];
+  /**
+   * How to treat a URL that carries more than an origin.
+   *
+   * - `"strip"`: return just the origin, discarding any path, query, or
+   *   fragment.
+   * - `"reject"`: fail when the input has a path other than `/`, a query, or
+   *   a fragment.
+   *
+   * Credentials are always rejected, under either setting.
+   * @default `"strip"`
+   */
+  readonly extraComponents?: "strip" | "reject";
+  /**
+   * How to treat a trailing dot on a domain name, as in `example.com.`.
+   *
+   * - `"strip"`: remove it, so `example.com.` becomes `example.com`.
+   * - `"preserve"`: keep it, matching the WHATWG URL origin exactly.
+   * - `"append"`: force it, so `example.com` becomes `example.com.`.  This
+   *   has no effect on an IP address literal.
+   *
+   * @default `"strip"`
+   */
+  readonly trailingDot?: "strip" | "preserve" | "append";
+  /**
+   * Custom error messages for origin parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid absolute URL.
+     */
+    readonly invalidOrigin?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when URL protocol is not allowed.
+     */
+    readonly disallowedProtocol?: Message | ((protocol: string, allowedProtocols: readonly string[]) => Message);
+  };
+}
+/**
+ * Creates a {@link ValueParser} for web origins.
+ *
+ * An origin is a scheme, a host, and an optional port, and nothing else.  The
+ * parser returns a `URL` whose pathname is `/` and which carries no
+ * credentials, query, or fragment.
+ *
+ * Input is canonicalized rather than rejected when it carries more than an
+ * origin: the host is lowercased, internationalized names are converted to
+ * punycode, and a default port is elided, so `HTTPS://Example.COM/`,
+ * `https://example.com:443/path?query#fragment` all parse to
+ * `https://example.com`.  Set `extraComponents: "reject"` to fail on a path,
+ * query, or fragment instead.  Credentials are always rejected.  Schemes whose
+ * origin is opaque (`mailto:`, `data:`, `file:`) are rejected, as is `blob:`,
+ * whose origin belongs to the URL it wraps.
+ *
+ * By default a trailing root-zone dot is stripped, so `example.com.` becomes
+ * `example.com`.  This differs from the WHATWG origin, which keeps the dot, so
+ * the two strings are not interchangeable when an exact origin comparison
+ * matters.  Use `trailingDot: "preserve"` for the WHATWG behavior or
+ * `trailingDot: "append"` to force a fully-qualified name.
+ *
+ * @param options Configuration options for the origin parser.
+ * @returns A {@link ValueParser} that converts string input to `URL` objects
+ *          that name an origin.
+ * @throws {TypeError} If any `allowedProtocols` entry is not a valid protocol
+ *   string ending with a colon (e.g., `"https:"`).
+ * @since 1.3.0
+ */
+declare function origin(options?: OriginOptions): ValueParser<"sync", URL>;
 /**
  * Options for creating a {@link locale} parser.
  */
@@ -3337,4 +3422,4 @@ declare function firstOf<const TParsers extends readonly [ValueParser<"sync", un
  */
 declare function firstOf<const TParsers extends readonly ValueParser<"sync", unknown>[]>(parsers: TParsers, options?: FirstOfOptions): ValueParser<"sync", ValueParserValue<TParsers[number]>>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };

package/dist/valueparser.d.ts

@@ -1189,6 +1189,91 @@ interface UrlOptions {
  *   string ending with a colon (e.g., `"https:"`).
  */
 declare function url(options?: UrlOptions): ValueParser<"sync", URL>;
+/**
+ * Options for creating an {@link origin} parser.
+ */
+interface OriginOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.  Usually a single
+   * word in uppercase, like `ORIGIN` or `BASE_URL`.
+   * @default `"ORIGIN"`
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * List of allowed URL protocols (e.g., `["http:", "https:"]`).
+   * If specified, the parsed URL must use one of these protocols.
+   * Protocol names should include the trailing colon (e.g., `"https:"`).
+   * If not specified, any protocol with a tuple origin is allowed.
+   */
+  readonly allowedProtocols?: readonly string[];
+  /**
+   * How to treat a URL that carries more than an origin.
+   *
+   * - `"strip"`: return just the origin, discarding any path, query, or
+   *   fragment.
+   * - `"reject"`: fail when the input has a path other than `/`, a query, or
+   *   a fragment.
+   *
+   * Credentials are always rejected, under either setting.
+   * @default `"strip"`
+   */
+  readonly extraComponents?: "strip" | "reject";
+  /**
+   * How to treat a trailing dot on a domain name, as in `example.com.`.
+   *
+   * - `"strip"`: remove it, so `example.com.` becomes `example.com`.
+   * - `"preserve"`: keep it, matching the WHATWG URL origin exactly.
+   * - `"append"`: force it, so `example.com` becomes `example.com.`.  This
+   *   has no effect on an IP address literal.
+   *
+   * @default `"strip"`
+   */
+  readonly trailingDot?: "strip" | "preserve" | "append";
+  /**
+   * Custom error messages for origin parsing failures.
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when input is not a valid absolute URL.
+     */
+    readonly invalidOrigin?: Message | ((input: string) => Message);
+    /**
+     * Custom error message when URL protocol is not allowed.
+     */
+    readonly disallowedProtocol?: Message | ((protocol: string, allowedProtocols: readonly string[]) => Message);
+  };
+}
+/**
+ * Creates a {@link ValueParser} for web origins.
+ *
+ * An origin is a scheme, a host, and an optional port, and nothing else.  The
+ * parser returns a `URL` whose pathname is `/` and which carries no
+ * credentials, query, or fragment.
+ *
+ * Input is canonicalized rather than rejected when it carries more than an
+ * origin: the host is lowercased, internationalized names are converted to
+ * punycode, and a default port is elided, so `HTTPS://Example.COM/`,
+ * `https://example.com:443/path?query#fragment` all parse to
+ * `https://example.com`.  Set `extraComponents: "reject"` to fail on a path,
+ * query, or fragment instead.  Credentials are always rejected.  Schemes whose
+ * origin is opaque (`mailto:`, `data:`, `file:`) are rejected, as is `blob:`,
+ * whose origin belongs to the URL it wraps.
+ *
+ * By default a trailing root-zone dot is stripped, so `example.com.` becomes
+ * `example.com`.  This differs from the WHATWG origin, which keeps the dot, so
+ * the two strings are not interchangeable when an exact origin comparison
+ * matters.  Use `trailingDot: "preserve"` for the WHATWG behavior or
+ * `trailingDot: "append"` to force a fully-qualified name.
+ *
+ * @param options Configuration options for the origin parser.
+ * @returns A {@link ValueParser} that converts string input to `URL` objects
+ *          that name an origin.
+ * @throws {TypeError} If any `allowedProtocols` entry is not a valid protocol
+ *   string ending with a colon (e.g., `"https:"`).
+ * @since 1.3.0
+ */
+declare function origin(options?: OriginOptions): ValueParser<"sync", URL>;
 /**
  * Options for creating a {@link locale} parser.
  */
@@ -3337,4 +3422,4 @@ declare function firstOf<const TParsers extends readonly [ValueParser<"sync", un
  */
 declare function firstOf<const TParsers extends readonly ValueParser<"sync", unknown>[]>(parsers: TParsers, options?: FirstOfOptions): ValueParser<"sync", ValueParserValue<TParsers[number]>>;
 //#endregion
-export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };
+export { ChoiceOptions, ChoiceOptionsBase, ChoiceOptionsNumber, ChoiceOptionsString, CidrOptions, CidrValue, Color, ColorFormat, ColorOptions, CronExpression, CronExpressionForOptions, CronOptions, DeferredMap, DomainOptions, EmailOptions, FileSizeOptions, FileSizeOptionsBigInt, FileSizeOptionsNumber, FileSizeUnit, FirstOfOptions, FloatOptions, HostnameOptions, IntegerOptionsBigInt, IntegerOptionsNumber, IpOptions, Ipv4Options, Ipv6Options, Json, JsonOptions, KeyValueOptions, LocaleOptions, MacAddressOptions, type Mode, type ModeIterable, type ModeValue, type NonEmptyString, OriginOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SocketAddressOptions, SocketAddressValue, StringOptions, TransformMapping, UrlOptions, Uuid, UuidOptions, ValueParser, ValueParserResult, biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };

package/dist/valueparser.js

@@ -2750,6 +2750,178 @@ function url(options = {}) {
 	};
 }
 /**
+* A host name that the WHATWG URL parser has canonicalized into a dotted-quad
+* IPv4 address.  Matching the canonical form is enough, because the parser
+* turns every other spelling (`0x7f.1`, `2130706433`, …) into it.
+*/
+const IPV4_PATTERN = /^\d{1,3}(?:\.\d{1,3}){3}$/u;
+/**
+* Creates a {@link ValueParser} for web origins.
+*
+* An origin is a scheme, a host, and an optional port, and nothing else.  The
+* parser returns a `URL` whose pathname is `/` and which carries no
+* credentials, query, or fragment.
+*
+* Input is canonicalized rather than rejected when it carries more than an
+* origin: the host is lowercased, internationalized names are converted to
+* punycode, and a default port is elided, so `HTTPS://Example.COM/`,
+* `https://example.com:443/path?query#fragment` all parse to
+* `https://example.com`.  Set `extraComponents: "reject"` to fail on a path,
+* query, or fragment instead.  Credentials are always rejected.  Schemes whose
+* origin is opaque (`mailto:`, `data:`, `file:`) are rejected, as is `blob:`,
+* whose origin belongs to the URL it wraps.
+*
+* By default a trailing root-zone dot is stripped, so `example.com.` becomes
+* `example.com`.  This differs from the WHATWG origin, which keeps the dot, so
+* the two strings are not interchangeable when an exact origin comparison
+* matters.  Use `trailingDot: "preserve"` for the WHATWG behavior or
+* `trailingDot: "append"` to force a fully-qualified name.
+*
+* @param options Configuration options for the origin parser.
+* @returns A {@link ValueParser} that converts string input to `URL` objects
+*          that name an origin.
+* @throws {TypeError} If any `allowedProtocols` entry is not a valid protocol
+*   string ending with a colon (e.g., `"https:"`).
+* @since 1.3.0
+*/
+function origin(options = {}) {
+	const metavar$1 = options.metavar ?? "ORIGIN";
+	ensureNonEmptyString(metavar$1);
+	checkEnumOption(options, "extraComponents", ["strip", "reject"]);
+	checkEnumOption(options, "trailingDot", [
+		"strip",
+		"preserve",
+		"append"
+	]);
+	const extraComponents = options.extraComponents ?? "strip";
+	const trailingDot = options.trailingDot ?? "strip";
+	const originalProtocolsList = [];
+	const normalizedProtocolsList = [];
+	if (options.allowedProtocols != null) {
+		const seen = /* @__PURE__ */ new Set();
+		for (const protocol of options.allowedProtocols) {
+			if (typeof protocol !== "string" || !/^[a-z][a-z0-9+\-.]*:$/i.test(protocol)) {
+				const rendered = typeof protocol === "string" ? JSON.stringify(protocol) : String(protocol);
+				throw new TypeError(`Each allowed protocol must be a valid protocol ending with a colon (e.g., "https:"), got: ${rendered}.`);
+			}
+			const normalized = protocol.toLowerCase();
+			if (seen.has(normalized)) continue;
+			seen.add(normalized);
+			originalProtocolsList.push(protocol);
+			normalizedProtocolsList.push(normalized);
+		}
+		if (originalProtocolsList.length === 0) throw new TypeError("allowedProtocols must not be empty.");
+	}
+	const originalProtocols = options.allowedProtocols != null ? Object.freeze(originalProtocolsList) : void 0;
+	const allowedProtocols = options.allowedProtocols != null ? Object.freeze(normalizedProtocolsList) : void 0;
+	const invalidOrigin = options.errors?.invalidOrigin;
+	const disallowedProtocol = options.errors?.disallowedProtocol;
+	function invalidOriginError(input) {
+		return invalidOrigin ? typeof invalidOrigin === "function" ? invalidOrigin(input) : invalidOrigin : message`Invalid origin: ${input}.`;
+	}
+	function disallowedProtocolError(protocol) {
+		return disallowedProtocol ? typeof disallowedProtocol === "function" ? disallowedProtocol(protocol, originalProtocols) : disallowedProtocol : [
+			{
+				type: "text",
+				text: "URL protocol "
+			},
+			{
+				type: "value",
+				value: protocol
+			},
+			{
+				type: "text",
+				text: " is not allowed. Allowed protocols: "
+			},
+			...valueSet(originalProtocols, {
+				fallback: "",
+				locale: "en-US"
+			}),
+			{
+				type: "text",
+				text: "."
+			}
+		];
+	}
+	function withTrailingDot(url$1) {
+		if (trailingDot === "preserve") return url$1;
+		const { hostname: hostname$1 } = url$1;
+		if (hostname$1.startsWith("[") || IPV4_PATTERN.test(hostname$1)) return url$1;
+		if (trailingDot === "strip") {
+			const stripped = hostname$1.replace(/\.+$/u, "");
+			if (stripped !== "") url$1.hostname = stripped;
+		} else if (!hostname$1.endsWith(".")) url$1.hostname = `${hostname$1}.`;
+		return url$1;
+	}
+	function resolve(url$1, label) {
+		if (allowedProtocols != null && !allowedProtocols.includes(url$1.protocol)) return {
+			success: false,
+			error: disallowedProtocolError(url$1.protocol)
+		};
+		if (url$1.protocol === "blob:") return {
+			success: false,
+			error: message`The URL ${label} wraps another origin. Pass that origin instead.`
+		};
+		if (url$1.origin === "null") return {
+			success: false,
+			error: message`The URL ${label} has no origin.`
+		};
+		if (url$1.username !== "" || url$1.password !== "") return {
+			success: false,
+			error: message`An origin must not contain credentials: ${url$1.origin}`
+		};
+		if (extraComponents === "reject" && (url$1.pathname !== "/" || url$1.search !== "" || url$1.hash !== "")) return {
+			success: false,
+			error: message`Expected only an origin, but got: ${label}`
+		};
+		return {
+			success: true,
+			value: withTrailingDot(new URL(url$1.origin))
+		};
+	}
+	return {
+		mode: "sync",
+		metavar: metavar$1,
+		get placeholder() {
+			return new URL(`${allowedProtocols?.[0] ?? "http:"}//0.invalid`);
+		},
+		parse(input) {
+			if (!URL.canParse(input)) return {
+				success: false,
+				error: invalidOriginError(input)
+			};
+			return resolve(new URL(input), input);
+		},
+		validate(value) {
+			if (!(value instanceof URL)) return {
+				success: false,
+				error: invalidOriginError(String(value))
+			};
+			return resolve(value, value.href);
+		},
+		format(value) {
+			return value.origin;
+		},
+		normalize(value) {
+			if (!(value instanceof URL)) return value;
+			const result = resolve(value, value.href);
+			return result.success ? result.value : value;
+		},
+		*suggest(prefix) {
+			if (allowedProtocols && prefix.length > 0 && !prefix.includes(":")) for (const protocol of allowedProtocols) {
+				const cleanProtocol = protocol.replace(/:+$/, "");
+				if (cleanProtocol.startsWith(prefix.toLowerCase())) {
+					const suffix = SPECIAL_URL_SCHEMES.has(cleanProtocol) ? "://" : ":";
+					yield {
+						kind: "literal",
+						text: `${cleanProtocol}${suffix}`
+					};
+				}
+			}
+		}
+	};
+}
+/**
 * Creates a {@link ValueParser} for locale values.
 *
 * This parser validates that the input is a well-formed locale identifier
@@ -6667,4 +6839,4 @@ function plainObjectsEqual(a, b) {
 }
 
 //#endregion
-export { biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };
+export { biject, checkBooleanOption, checkEnumOption, choice, cidr, color, cron, domain, email, ensureNonEmptyString, fileSize, firstOf, float, hostname, integer, ip, ipv4, ipv6, isNonEmptyString, isValueParser, json, keyValue, locale, macAddress, origin, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0-dev.2582",
+  "version": "1.3.0-dev.2583",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -237,7 +237,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.3.0-dev.2582+e069abd2",
+    "@optique/env": "1.3.0-dev.2583+d30dbb53",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -41,11 +41,11 @@ Core rules
     customize terminal output with `theme` or `messageFormatter`, preserving
     `initialWidth`, quoting, and width options. Keep canonical errors unthemed.
  -  Use value parsers such as `integer()`, `choice()`, `biject()`, `regExp()`,
-    `url()`, and `uuid()` instead of validating raw strings after parsing. Use
-    `regExp({ flags })` for user-supplied regular expression sources,
-    `biject()` for one-to-one string-to-value choices, and `transform()` when
-    an existing value parser describes the accepted CLI spelling but your app
-    needs a different result type. Use `path()` from
+    `url()`, `origin()`, and `uuid()` instead of validating raw strings after
+    parsing. Use `regExp({ flags })` for user-supplied sources, `biject()` for
+    one-to-one string-to-value choices, and `transform()` when an existing
+    value parser describes the accepted CLI spelling but your app needs a
+    different result type. Use `path()` from
     `@optique/run/valueparser` for file-system paths. Write a custom
     `{ mode, metavar, parse, format }` value parser only when the catalog does
     not cover the domain.