@optique/core 1.3.0-dev.2380 → 1.3.0-dev.2383

package/dist/constructs.cjs

@@ -130,7 +130,8 @@ function isDeferredCompletionResult(result) {
 function settledPreCompletedKeys(preCompleted) {
 	const keys = /* @__PURE__ */ new Set();
 	for (const [key, result] of preCompleted) {
-		if (isDeferredCompletionResult(result)) continue;
+		const completion = require_internal_dependency.isDependencySourceState(result) ? result.result : result;
+		if (isDeferredCompletionResult(completion)) continue;
 		keys.add(key);
 	}
 	return keys;
@@ -145,7 +146,10 @@ function settledPreCompletedKeys(preCompleted) {
 * immediately.
 */
 function firstPreCompletedFailure(preCompleted) {
-	for (const result of preCompleted.values()) if (typeof result === "object" && result !== null && "success" in result && result.success === false && "error" in result) return result.error;
+	for (const result of preCompleted.values()) {
+		const completion = require_internal_dependency.isDependencySourceState(result) ? result.result : result;
+		if (typeof completion === "object" && completion !== null && "success" in completion && completion.success === false && "error" in completion) return completion.error;
+	}
 	return void 0;
 }
 async function scheduleEffectfulSourceCompletions(nodes, state, runtime, exec, preCompleted, demandNodes) {

package/dist/constructs.js

@@ -130,7 +130,8 @@ function isDeferredCompletionResult(result) {
 function settledPreCompletedKeys(preCompleted) {
 	const keys = /* @__PURE__ */ new Set();
 	for (const [key, result] of preCompleted) {
-		if (isDeferredCompletionResult(result)) continue;
+		const completion = isDependencySourceState(result) ? result.result : result;
+		if (isDeferredCompletionResult(completion)) continue;
 		keys.add(key);
 	}
 	return keys;
@@ -145,7 +146,10 @@ function settledPreCompletedKeys(preCompleted) {
 * immediately.
 */
 function firstPreCompletedFailure(preCompleted) {
-	for (const result of preCompleted.values()) if (typeof result === "object" && result !== null && "success" in result && result.success === false && "error" in result) return result.error;
+	for (const result of preCompleted.values()) {
+		const completion = isDependencySourceState(result) ? result.result : result;
+		if (typeof completion === "object" && completion !== null && "success" in completion && completion.success === false && "error" in completion) return completion.error;
+	}
 	return void 0;
 }
 async function scheduleEffectfulSourceCompletions(nodes, state, runtime, exec, preCompleted, demandNodes) {

package/dist/dependency-runtime.cjs

@@ -679,15 +679,7 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 * length-prefixed segments so no separator escaping is needed.
 */
 function serializeSchedulingPath(path) {
-	return path.map((segment) => {
-		if (typeof segment === "symbol") {
-			const key = stableSymbolKey(segment);
-			return `y${key.length}:${key}`;
-		}
-		const tag = typeof segment === "number" ? "n" : "s";
-		const text = String(segment);
-		return `${tag}${text.length}:${text}`;
-	}).join("");
+	return path.map(serializePathSegment).join("");
 }
 /**
 * Checks if a value is a plain object (not a class instance) for the

package/dist/dependency-runtime.js

@@ -679,15 +679,7 @@ async function completeEffectfulSourcesAsync(nodes, state, runtime, exec, option
 * length-prefixed segments so no separator escaping is needed.
 */
 function serializeSchedulingPath(path) {
-	return path.map((segment) => {
-		if (typeof segment === "symbol") {
-			const key = stableSymbolKey(segment);
-			return `y${key.length}:${key}`;
-		}
-		const tag = typeof segment === "number" ? "n" : "s";
-		const text = String(segment);
-		return `${tag}${text.length}:${text}`;
-	}).join("");
+	return path.map(serializePathSegment).join("");
 }
 /**
 * Checks if a value is a plain object (not a class instance) for the

package/dist/doc.cjs

@@ -213,7 +213,6 @@ function defaultSectionOrder(a, b) {
 function formatDocPage(programName, page, options = {}) {
 	require_validate.validateProgramName(programName);
 	const termIndent = options.termIndent ?? 2;
-	const termWidth = options.termWidth ?? 26;
 	const showUsage = options.showUsage ?? true;
 	if (options.maxWidth != null && (!Number.isFinite(options.maxWidth) || !Number.isInteger(options.maxWidth))) throw new TypeError(`maxWidth must be a finite integer, got ${options.maxWidth}.`);
 	const filteredSections = page.sections.map((s) => ({
@@ -232,9 +231,32 @@ function formatDocPage(programName, page, options = {}) {
 		if (maxItems < 1) throw new RangeError(`showChoices.maxItems must be at least 1, but got ${maxItems}.`);
 	}
 	const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
+	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices);
+	const automaticTermWidth = () => {
+		let widest;
+		for (const section of page.sections) for (const entry of section.entries) {
+			if (!needsDescriptionColumn(entry)) continue;
+			const rendered = require_usage.formatUsageTerm(entry.term, {
+				colors: options.colors,
+				optionsSeparator: ", ",
+				context: "doc"
+			});
+			const width = Math.max(...rendered.split("\n").map((line) => require_displaywidth.getDisplayWidth(line)));
+			widest = widest == null ? width : Math.max(widest, width);
+		}
+		return widest;
+	};
+	const termWidth = options.termWidth === "auto" ? automaticTermWidth() ?? 26 : options.termWidth ?? 26;
+	const hasEntries = page.sections.some((s) => s.entries.length > 0);
+	const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some(needsDescriptionColumn));
+	let effectiveTermWidth;
+	if (options.maxWidth == null) effectiveTermWidth = termWidth;
+	else {
+		const availableForColumns = options.maxWidth - termIndent - 2;
+		const evenlySplitTermWidth = Math.max(1, Math.floor(availableForColumns / 2));
+		effectiveTermWidth = options.termWidth === "auto" && needsDescColumn ? Math.min(termWidth, evenlySplitTermWidth) : availableForColumns >= termWidth + 1 ? termWidth : evenlySplitTermWidth;
+	}
 	if (options.maxWidth != null) {
-		const hasEntries = page.sections.some((s) => s.entries.length > 0);
-		const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some((e) => hasContent(e.description) || options.showDefault && hasContent(e.default) || options.showChoices && hasContent(e.choices)));
 		let minDescWidth = 1;
 		if (needsDescColumn) {
 			if (options.showDefault && page.sections.some((s) => s.entries.some((e) => hasContent(e.default)))) {
@@ -260,20 +282,13 @@ function formatDocPage(programName, page, options = {}) {
 		if (options.maxWidth < minWidth) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
 		if (needsDescColumn && minDescWidth > 1) {
 			const avail = options.maxWidth - termIndent - 2;
-			const effTW = avail >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(avail / 2));
-			const descW = avail - effTW;
+			const descW = avail - effectiveTermWidth;
 			if (descW < minDescWidth) {
-				const needed = termIndent + termWidth + 2 + minDescWidth;
+				const needed = termIndent + effectiveTermWidth + 2 + minDescWidth;
 				throw new RangeError(`maxWidth must be at least ${needed}, got ${options.maxWidth}.`);
 			}
 		}
 	}
-	let effectiveTermWidth;
-	if (options.maxWidth == null) effectiveTermWidth = termWidth;
-	else {
-		const availableForColumns = options.maxWidth - termIndent - 2;
-		effectiveTermWidth = availableForColumns >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(availableForColumns / 2));
-	}
 	let output = "";
 	if (hasContent(page.brief)) {
 		output += require_message.formatMessage(page.brief, {

package/dist/doc.d.cts

@@ -217,10 +217,14 @@ interface DocPageFormatOptions {
    */
   termIndent?: number;
   /**
-   * Width allocated for terms before descriptions start.
+   * Width allocated for terms before descriptions start.  Set to `"auto"`
+   * to align descriptions after the widest visible term that has content.
+   * Terminal display width is used for automatic measurement.
+   *
    * @default `26`
+   * @since 1.3.0 Added automatic term width.
    */
-  termWidth?: number;
+  termWidth?: number | "auto";
   /**
    * Maximum width of the entire formatted output.
    */

package/dist/doc.d.ts

@@ -217,10 +217,14 @@ interface DocPageFormatOptions {
    */
   termIndent?: number;
   /**
-   * Width allocated for terms before descriptions start.
+   * Width allocated for terms before descriptions start.  Set to `"auto"`
+   * to align descriptions after the widest visible term that has content.
+   * Terminal display width is used for automatic measurement.
+   *
    * @default `26`
+   * @since 1.3.0 Added automatic term width.
    */
-  termWidth?: number;
+  termWidth?: number | "auto";
   /**
    * Maximum width of the entire formatted output.
    */

package/dist/doc.js

@@ -213,7 +213,6 @@ function defaultSectionOrder(a, b) {
 function formatDocPage(programName, page, options = {}) {
 	validateProgramName(programName);
 	const termIndent = options.termIndent ?? 2;
-	const termWidth = options.termWidth ?? 26;
 	const showUsage = options.showUsage ?? true;
 	if (options.maxWidth != null && (!Number.isFinite(options.maxWidth) || !Number.isInteger(options.maxWidth))) throw new TypeError(`maxWidth must be a finite integer, got ${options.maxWidth}.`);
 	const filteredSections = page.sections.map((s) => ({
@@ -232,9 +231,32 @@ function formatDocPage(programName, page, options = {}) {
 		if (maxItems < 1) throw new RangeError(`showChoices.maxItems must be at least 1, but got ${maxItems}.`);
 	}
 	const hasContent = (msg) => Array.isArray(msg) && msg.length > 0;
+	const needsDescriptionColumn = (entry) => hasContent(entry.description) || (options.showDefault === true || typeof options.showDefault === "object") && hasContent(entry.default) || (options.showChoices === true || typeof options.showChoices === "object") && hasContent(entry.choices);
+	const automaticTermWidth = () => {
+		let widest;
+		for (const section of page.sections) for (const entry of section.entries) {
+			if (!needsDescriptionColumn(entry)) continue;
+			const rendered = formatUsageTerm(entry.term, {
+				colors: options.colors,
+				optionsSeparator: ", ",
+				context: "doc"
+			});
+			const width = Math.max(...rendered.split("\n").map((line) => getDisplayWidth(line)));
+			widest = widest == null ? width : Math.max(widest, width);
+		}
+		return widest;
+	};
+	const termWidth = options.termWidth === "auto" ? automaticTermWidth() ?? 26 : options.termWidth ?? 26;
+	const hasEntries = page.sections.some((s) => s.entries.length > 0);
+	const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some(needsDescriptionColumn));
+	let effectiveTermWidth;
+	if (options.maxWidth == null) effectiveTermWidth = termWidth;
+	else {
+		const availableForColumns = options.maxWidth - termIndent - 2;
+		const evenlySplitTermWidth = Math.max(1, Math.floor(availableForColumns / 2));
+		effectiveTermWidth = options.termWidth === "auto" && needsDescColumn ? Math.min(termWidth, evenlySplitTermWidth) : availableForColumns >= termWidth + 1 ? termWidth : evenlySplitTermWidth;
+	}
 	if (options.maxWidth != null) {
-		const hasEntries = page.sections.some((s) => s.entries.length > 0);
-		const needsDescColumn = hasEntries && page.sections.some((s) => s.entries.some((e) => hasContent(e.description) || options.showDefault && hasContent(e.default) || options.showChoices && hasContent(e.choices)));
 		let minDescWidth = 1;
 		if (needsDescColumn) {
 			if (options.showDefault && page.sections.some((s) => s.entries.some((e) => hasContent(e.default)))) {
@@ -260,20 +282,13 @@ function formatDocPage(programName, page, options = {}) {
 		if (options.maxWidth < minWidth) throw new RangeError(`maxWidth must be at least ${minWidth}, got ${options.maxWidth}.`);
 		if (needsDescColumn && minDescWidth > 1) {
 			const avail = options.maxWidth - termIndent - 2;
-			const effTW = avail >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(avail / 2));
-			const descW = avail - effTW;
+			const descW = avail - effectiveTermWidth;
 			if (descW < minDescWidth) {
-				const needed = termIndent + termWidth + 2 + minDescWidth;
+				const needed = termIndent + effectiveTermWidth + 2 + minDescWidth;
 				throw new RangeError(`maxWidth must be at least ${needed}, got ${options.maxWidth}.`);
 			}
 		}
 	}
-	let effectiveTermWidth;
-	if (options.maxWidth == null) effectiveTermWidth = termWidth;
-	else {
-		const availableForColumns = options.maxWidth - termIndent - 2;
-		effectiveTermWidth = availableForColumns >= termWidth + 1 ? termWidth : Math.max(1, Math.floor(availableForColumns / 2));
-	}
 	let output = "";
 	if (hasContent(page.brief)) {
 		output += formatMessage(page.brief, {

package/dist/facade.cjs

@@ -126,6 +126,31 @@ function withEffectfulSessionOption(options, session) {
 		[effectfulSessionOptionsKey]: session
 	};
 }
+/**
+* Creates the run-scoped effectful completion sessions shared by a
+* `runWith()` two-phase run, so an effectful source (e.g., a prompt)
+* runs at most once per invocation.  The seed pass uses the demand-only
+* policy: an effectful source completes there only when a phase-one
+* consumer demands its value; others defer to the final pass.  The
+* final pass shares the run-scoped results cache and demand set, but
+* recomputes structural precedence from scratch: phase-two annotations
+* may introduce environment/configuration values that must win over a
+* cached seed prompt answer, so the effectful-source markers do not
+* carry over.
+*/
+function createRunWithSessions() {
+	const seedSession = require_internal_parser.createEffectfulCompletionSession("demand-only");
+	const finalSession = {
+		...seedSession,
+		policy: "eager",
+		effectfulSources: /* @__PURE__ */ new Set(),
+		completedByPath: /* @__PURE__ */ new Map()
+	};
+	return {
+		seedSession,
+		finalSession
+	};
+}
 function createCompleteExec(exec, context, session) {
 	const runtime = require_dependency_runtime.createDependencyRuntimeContext();
 	return {
@@ -623,7 +648,7 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = []) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = []) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	const callOnError = (code) => onError(code);
@@ -636,6 +661,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			if (doc) stderr(require_doc.formatDocPage(programName, doc, {
 				colors,
 				maxWidth,
+				termWidth,
 				sectionOrder,
 				showUsage
 			}));
@@ -964,7 +990,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	require_validate.validateProgramName(programName);
-	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, maxWidth, termWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const norm = (c) => c === true ? {} : c;
@@ -1102,7 +1128,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				classified.shell,
 				...classified.commandPath ?? [],
 				...classified.args
-			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions);
+			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, termWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions);
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;
@@ -1152,6 +1178,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						stdout(require_doc.formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
+							termWidth,
 							showDefault,
 							showChoices,
 							sectionOrder,
@@ -1224,6 +1251,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						stderr(require_doc.formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
+							termWidth,
 							showDefault,
 							showChoices,
 							sectionOrder,
@@ -1612,13 +1640,7 @@ async function runWithBody(parser, programName, contexts, args, options) {
 		if (parser.mode === "async") return runParser(augmentedParser1, programName, args, options);
 		return Promise.resolve(runParser(augmentedParser1, programName, args, options));
 	}
-	const seedSession = require_internal_parser.createEffectfulCompletionSession("demand-only");
-	const finalSession = {
-		...seedSession,
-		policy: "eager",
-		effectfulSources: /* @__PURE__ */ new Set(),
-		completedByPath: /* @__PURE__ */ new Map()
-	};
+	const { seedSession, finalSession } = createRunWithSessions();
 	const sessionOptions = withEffectfulSessionOption(options, finalSession);
 	const firstPassSeed = await require_mode_dispatch.dispatchByMode(parser.mode, () => extractPhase2SeedSync(augmentedParser1, args, seedSession), () => extractPhase2SeedAsync(augmentedParser1, args, seedSession));
 	if (firstPassSeed == null) {
@@ -1735,13 +1757,7 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 	}
 	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
 	if (!needsTwoPhase) return runParser(augmentedParser1, programName, args, options);
-	const seedSession = require_internal_parser.createEffectfulCompletionSession("demand-only");
-	const finalSession = {
-		...seedSession,
-		policy: "eager",
-		effectfulSources: /* @__PURE__ */ new Set(),
-		completedByPath: /* @__PURE__ */ new Map()
-	};
+	const { seedSession, finalSession } = createRunWithSessions();
 	const sessionOptions = withEffectfulSessionOption(options, finalSession);
 	const firstPassSeed = extractPhase2SeedSync(augmentedParser1, args, seedSession);
 	if (firstPassSeed == null) {

package/dist/facade.d.cts

@@ -89,6 +89,14 @@ interface RunOptions<THelp, TError> {
    * this width.  If not specified, text will not be wrapped.
    */
   readonly maxWidth?: number;
+  /**
+   * Width allocated for help terms before descriptions start.  Set to
+   * `"auto"` to align descriptions after the widest visible term.
+   *
+   * @default `26`
+   * @since 1.3.0
+   */
+  readonly termWidth?: number | "auto";
   /**
    * Whether and how to display default values for options and arguments.
    *

package/dist/facade.d.ts

@@ -89,6 +89,14 @@ interface RunOptions<THelp, TError> {
    * this width.  If not specified, text will not be wrapped.
    */
   readonly maxWidth?: number;
+  /**
+   * Width allocated for help terms before descriptions start.  Set to
+   * `"auto"` to align descriptions after the widest visible term.
+   *
+   * @default `26`
+   * @since 1.3.0
+   */
+  readonly termWidth?: number | "auto";
   /**
    * Whether and how to display default values for options and arguments.
    *

package/dist/facade.js

@@ -126,6 +126,31 @@ function withEffectfulSessionOption(options, session) {
 		[effectfulSessionOptionsKey]: session
 	};
 }
+/**
+* Creates the run-scoped effectful completion sessions shared by a
+* `runWith()` two-phase run, so an effectful source (e.g., a prompt)
+* runs at most once per invocation.  The seed pass uses the demand-only
+* policy: an effectful source completes there only when a phase-one
+* consumer demands its value; others defer to the final pass.  The
+* final pass shares the run-scoped results cache and demand set, but
+* recomputes structural precedence from scratch: phase-two annotations
+* may introduce environment/configuration values that must win over a
+* cached seed prompt answer, so the effectful-source markers do not
+* carry over.
+*/
+function createRunWithSessions() {
+	const seedSession = createEffectfulCompletionSession("demand-only");
+	const finalSession = {
+		...seedSession,
+		policy: "eager",
+		effectfulSources: /* @__PURE__ */ new Set(),
+		completedByPath: /* @__PURE__ */ new Map()
+	};
+	return {
+		seedSession,
+		finalSession
+	};
+}
 function createCompleteExec(exec, context, session) {
 	const runtime = createDependencyRuntimeContext();
 	return {
@@ -623,7 +648,7 @@ function classifyParseFailure(failure, helpOptionNames, helpCommandNames, versio
 * Handles shell completion requests.
 * @since 0.6.0
 */
-function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = []) {
+function handleCompletion(completionArgs, programName, parser, completionParser, stdout, stderr, onCompletion, onError, availableShells, colors, maxWidth, termWidth, completionCommandDisplayName, completionOptionDisplayName, isOptionMode, sectionOrder, showUsage, rootOptionSuggestions = []) {
 	const shellName = completionArgs[0] || "";
 	const args = completionArgs.slice(1);
 	const callOnError = (code) => onError(code);
@@ -636,6 +661,7 @@ function handleCompletion(completionArgs, programName, parser, completionParser,
 			if (doc) stderr(formatDocPage(programName, doc, {
 				colors,
 				maxWidth,
+				termWidth,
 				sectionOrder,
 				showUsage
 			}));
@@ -964,7 +990,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 		options = optionsParam ?? {};
 	}
 	validateProgramName(programName);
-	const { colors, maxWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
+	const { colors, maxWidth, termWidth, showDefault, showChoices, sectionOrder, showUsage, usageLine, commandList = "recursive", aboveError = "usage", onError = () => {
 		throw new RunParserError("Failed to parse command line arguments.");
 	}, stderr = console.error, stdout = console.log, brief, description, examples, author, bugs, footer } = options;
 	const norm = (c) => c === true ? {} : c;
@@ -1102,7 +1128,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 				classified.shell,
 				...classified.commandPath ?? [],
 				...classified.args
-			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions);
+			], programName, parser, classified.source === "command" ? completionParsers.completionCommand : completionParsers.completionOption, stdout, stderr, onCompletionResult, onErrorResult, availableShells, colors, maxWidth, termWidth, completionCommandNames[0], completionOptionNames[0], classified.source === "option", sectionOrder, showUsage, rootOptionSuggestions);
 			case "help": {
 				let helpGeneratorParser;
 				let docGeneratorParser;
@@ -1152,6 +1178,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						stdout(formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
+							termWidth,
 							showDefault,
 							showChoices,
 							sectionOrder,
@@ -1224,6 +1251,7 @@ function runParser(parserOrProgram, programNameOrArgs, argsOrOptions, optionsPar
 						stderr(formatDocPage(programName, renderedDoc, {
 							colors,
 							maxWidth,
+							termWidth,
 							showDefault,
 							showChoices,
 							sectionOrder,
@@ -1612,13 +1640,7 @@ async function runWithBody(parser, programName, contexts, args, options) {
 		if (parser.mode === "async") return runParser(augmentedParser1, programName, args, options);
 		return Promise.resolve(runParser(augmentedParser1, programName, args, options));
 	}
-	const seedSession = createEffectfulCompletionSession("demand-only");
-	const finalSession = {
-		...seedSession,
-		policy: "eager",
-		effectfulSources: /* @__PURE__ */ new Set(),
-		completedByPath: /* @__PURE__ */ new Map()
-	};
+	const { seedSession, finalSession } = createRunWithSessions();
 	const sessionOptions = withEffectfulSessionOption(options, finalSession);
 	const firstPassSeed = await dispatchByMode(parser.mode, () => extractPhase2SeedSync(augmentedParser1, args, seedSession), () => extractPhase2SeedAsync(augmentedParser1, args, seedSession));
 	if (firstPassSeed == null) {
@@ -1735,13 +1757,7 @@ function runWithSyncBody(parser, programName, contexts, args, options) {
 	}
 	const augmentedParser1 = injectAnnotationsIntoParser(parser, phase1Annotations);
 	if (!needsTwoPhase) return runParser(augmentedParser1, programName, args, options);
-	const seedSession = createEffectfulCompletionSession("demand-only");
-	const finalSession = {
-		...seedSession,
-		policy: "eager",
-		effectfulSources: /* @__PURE__ */ new Set(),
-		completedByPath: /* @__PURE__ */ new Map()
-	};
+	const { seedSession, finalSession } = createRunWithSessions();
 	const sessionOptions = withEffectfulSessionOption(options, finalSession);
 	const firstPassSeed = extractPhase2SeedSync(augmentedParser1, args, seedSession);
 	if (firstPassSeed == null) {

package/dist/index.cjs

@@ -108,6 +108,7 @@ exports.passThrough = require_primitives.passThrough;
 exports.port = require_valueparser.port;
 exports.portRange = require_valueparser.portRange;
 exports.pwsh = require_completion.pwsh;
+exports.regExp = require_valueparser.regExp;
 exports.runParser = require_facade.runParser;
 exports.runParserAsync = require_facade.runParserAsync;
 exports.runParserSync = require_facade.runParserSync;

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, 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, 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, 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, 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 { CombineModes, DocState, EffectfulCompletionSession, 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 { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.cjs";
@@ -12,4 +12,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, 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, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, 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, 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, ParserModifiers, 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, 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, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, 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, 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, parseSync, passThrough, port, portRange, pwsh, 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, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, 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, 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, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, 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, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, 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, 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, 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

@@ -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, 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, 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, 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, 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 { CombineModes, DocState, EffectfulCompletionSession, 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 { DeferredValue, DeferredValueOptions, DeferredValueSource, FluentParser, MultipleErrorOptions, MultipleOptions, ParserModifiers, WithDefaultError, WithDefaultOptions, deferredValue, fluent, isDeferredValue, map, multiple, nonEmpty, optional, withDefault } from "./modifiers.js";
@@ -12,4 +12,4 @@ import { ParserValuePlaceholder, SourceContext, SourceContextRequest } from "./c
 import { AnyDependencySource, CombineMode, CombinedDependencyMode, DependencyMode, DependencySource, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, dependency, deriveFrom, deriveFromAsync, deriveFromSync, 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, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, 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, 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, ParserModifiers, 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, 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, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, 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, 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, parseSync, passThrough, port, portRange, pwsh, 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, DependencyValue, DependencyValues, DeriveAsyncOptions, DeriveFromAsyncOptions, DeriveFromOptions, DeriveFromSyncOptions, DeriveOptions, DeriveSyncOptions, DerivedValueParser, DocEntry, DocFragment, DocFragments, DocPage, DocPageFormatOptions, DocSection, DocState, DomainOptions, DuplicateOptionError, EffectfulCompletionSession, EmailOptions, 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, 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, ParserModifiers, ParserResult, ParserValuePlaceholder, PassThroughFormat, PassThroughOptions, PortOptionsBigInt, PortOptionsNumber, PortRangeOptionsBigInt, PortRangeOptionsNumber, PortRangeValueBigInt, PortRangeValueNumber, RegExpOptions, Result, RunOptions, RunParserError, RunWithOptions, SemVer, SemVerOptionsObject, SemVerOptionsString, SemVerString, SeqOptions, ShellCompletion, ShowChoicesOptions, ShowDefaultOptions, SocketAddressOptions, SocketAddressValue, SourceContext, SourceContextRequest, StringOptions, SubstituteParserValue, Suggestion, 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, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, 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, 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, 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

@@ -8,8 +8,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, 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, 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, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, 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, 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, parseSync, passThrough, port, portRange, pwsh, 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, createParserContext, cron, deduplicateDocEntries, deduplicateDocFragments, 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, 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, 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/internal/parser.d.cts

@@ -419,9 +419,9 @@ type ExecutionPhase = "parse" | "precomplete" | "resolve" | "complete" | "sugges
  * run, shared by the phase-two seed pass and the final pass) and threaded
  * through {@link ExecutionContext}.  It guarantees that an effectful source
  * completion runs at most once per run: the completion result is cached by
- * dependency source ID, and a cache hit is returned without repeating the
- * effect.  Results never leak between runs because the session is discarded
- * when the run ends.
+ * completion occurrence (see {@link EffectfulCompletionSession.results}),
+ * and a cache hit is returned without repeating the effect.  Results never
+ * leak between runs because the session is discarded when the run ends.
  *
  * @internal
  * @since 1.3.0

package/dist/internal/parser.d.ts

@@ -419,9 +419,9 @@ type ExecutionPhase = "parse" | "precomplete" | "resolve" | "complete" | "sugges
  * run, shared by the phase-two seed pass and the final pass) and threaded
  * through {@link ExecutionContext}.  It guarantees that an effectful source
  * completion runs at most once per run: the completion result is cached by
- * dependency source ID, and a cache hit is returned without repeating the
- * effect.  Results never leak between runs because the session is discarded
- * when the run ends.
+ * completion occurrence (see {@link EffectfulCompletionSession.results}),
+ * and a cache hit is returned without repeating the effect.  Results never
+ * leak between runs because the session is discarded when the run ends.
  *
  * @internal
  * @since 1.3.0

package/dist/valueparser.cjs

@@ -620,6 +620,71 @@ function string(options = {}) {
 		}
 	};
 }
+/**
+* Creates a {@link ValueParser} that compiles regular expression sources.
+*
+* The entire input is treated as the source.  Slash-delimited notation such
+* as `/pattern/flags` is not interpreted; use {@link RegExpOptions.flags} to
+* configure fixed flags for the parser.
+*
+* **Security note**: Compiling a source does not establish that it is safe to
+* execute.  Patterns from untrusted input can cause Regular Expression Denial
+* of Service (ReDoS) when matched.  Limit pattern and subject lengths, execute
+* matches in an environment that can be terminated, or use a linear-time
+* regular expression engine when accepting untrusted patterns.
+*
+* @param options Configuration options for the regular expression parser.
+* @returns A sync value parser producing JavaScript {@link RegExp} objects.
+* @throws {TypeError} If `options.metavar` is an empty string or
+*   `options.flags` is not a string.
+* @throws {SyntaxError} If `options.flags` contains invalid, duplicate, or
+*   incompatible regular expression flags.
+* @since 1.3.0
+*/
+function regExp(options = {}) {
+	const metavar$1 = options.metavar ?? "REGEXP";
+	require_nonempty.ensureNonEmptyString(metavar$1);
+	if (options.flags !== void 0 && typeof options.flags !== "string") throw new TypeError(`Expected flags to be a string, but got ${typeof options.flags}: ${String(options.flags)}.`);
+	const flags = new RegExp("", options.flags ?? "").flags;
+	const invalidRegExp = options.errors?.invalidRegExp;
+	const parseRegExp = (input) => {
+		try {
+			return {
+				success: true,
+				value: new RegExp(input, flags)
+			};
+		} catch (error) {
+			if (!(error instanceof SyntaxError)) throw error;
+			return {
+				success: false,
+				error: invalidRegExp ? typeof invalidRegExp === "function" ? invalidRegExp(input) : invalidRegExp : require_message.message`Invalid regular expression: ${input}.`
+			};
+		}
+	};
+	return {
+		mode: "sync",
+		metavar: metavar$1,
+		get placeholder() {
+			return new RegExp("", flags);
+		},
+		parse: parseRegExp,
+		validate(value) {
+			if (!(value instanceof RegExp)) return {
+				success: false,
+				error: require_message.message`Expected a RegExp value.`
+			};
+			return parseRegExp(value.source);
+		},
+		normalize(value) {
+			if (!(value instanceof RegExp)) return value;
+			const result = parseRegExp(value.source);
+			return result.success ? result.value : value;
+		},
+		format(value) {
+			return value.source;
+		}
+	};
+}
 function keyValue(options = {}) {
 	const separator = options.separator ?? "=";
 	if (typeof separator !== "string") throw new TypeError(`Expected separator to be a string, but got ${typeof separator}: ${String(separator)}.`);
@@ -6628,6 +6693,7 @@ exports.locale = locale;
 exports.macAddress = macAddress;
 exports.port = port;
 exports.portRange = portRange;
+exports.regExp = regExp;
 exports.semVer = semVer;
 exports.socketAddress = socketAddress;
 exports.string = string;

package/dist/valueparser.d.cts

@@ -498,6 +498,64 @@ declare function checkEnumOption<T extends object>(options: T | undefined, key:
  *         `RegExp` instance.
  */
 declare function string(options?: StringOptions): ValueParser<"sync", string>;
+/**
+ * Options for creating a {@link regExp} value parser.
+ *
+ * @since 1.3.0
+ */
+interface RegExpOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.
+   * @default `"REGEXP"`
+   * @since 1.3.0
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Fixed flags used to compile every input source.
+   * @default `""`
+   * @since 1.3.0
+   */
+  readonly flags?: string;
+  /**
+   * Custom error messages for regular expression parsing failures.
+   * @since 1.3.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not a valid regular expression
+     * source.  Can be a static message or a function that receives the input.
+     *
+     * **Security note**: Successful compilation does not guarantee safe
+     * execution. Vulnerable patterns can cause catastrophic backtracking when
+     * later matched against untrusted data.
+     * @since 1.3.0
+     */
+    readonly invalidRegExp?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Creates a {@link ValueParser} that compiles regular expression sources.
+ *
+ * The entire input is treated as the source.  Slash-delimited notation such
+ * as `/pattern/flags` is not interpreted; use {@link RegExpOptions.flags} to
+ * configure fixed flags for the parser.
+ *
+ * **Security note**: Compiling a source does not establish that it is safe to
+ * execute.  Patterns from untrusted input can cause Regular Expression Denial
+ * of Service (ReDoS) when matched.  Limit pattern and subject lengths, execute
+ * matches in an environment that can be terminated, or use a linear-time
+ * regular expression engine when accepting untrusted patterns.
+ *
+ * @param options Configuration options for the regular expression parser.
+ * @returns A sync value parser producing JavaScript {@link RegExp} objects.
+ * @throws {TypeError} If `options.metavar` is an empty string or
+ *   `options.flags` is not a string.
+ * @throws {SyntaxError} If `options.flags` contains invalid, duplicate, or
+ *   incompatible regular expression flags.
+ * @since 1.3.0
+ */
+declare function regExp(options?: RegExpOptions): ValueParser<"sync", RegExp>;
 interface KeyValueOptionsBase {
   /**
    * The metavariable name for this parser.  Used in help messages to
@@ -3279,4 +3337,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, 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, 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, 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 };

package/dist/valueparser.d.ts

@@ -498,6 +498,64 @@ declare function checkEnumOption<T extends object>(options: T | undefined, key:
  *         `RegExp` instance.
  */
 declare function string(options?: StringOptions): ValueParser<"sync", string>;
+/**
+ * Options for creating a {@link regExp} value parser.
+ *
+ * @since 1.3.0
+ */
+interface RegExpOptions {
+  /**
+   * The metavariable name for this parser.  This is used in help messages to
+   * indicate what kind of value this parser expects.
+   * @default `"REGEXP"`
+   * @since 1.3.0
+   */
+  readonly metavar?: NonEmptyString;
+  /**
+   * Fixed flags used to compile every input source.
+   * @default `""`
+   * @since 1.3.0
+   */
+  readonly flags?: string;
+  /**
+   * Custom error messages for regular expression parsing failures.
+   * @since 1.3.0
+   */
+  readonly errors?: {
+    /**
+     * Custom error message when the input is not a valid regular expression
+     * source.  Can be a static message or a function that receives the input.
+     *
+     * **Security note**: Successful compilation does not guarantee safe
+     * execution. Vulnerable patterns can cause catastrophic backtracking when
+     * later matched against untrusted data.
+     * @since 1.3.0
+     */
+    readonly invalidRegExp?: Message | ((input: string) => Message);
+  };
+}
+/**
+ * Creates a {@link ValueParser} that compiles regular expression sources.
+ *
+ * The entire input is treated as the source.  Slash-delimited notation such
+ * as `/pattern/flags` is not interpreted; use {@link RegExpOptions.flags} to
+ * configure fixed flags for the parser.
+ *
+ * **Security note**: Compiling a source does not establish that it is safe to
+ * execute.  Patterns from untrusted input can cause Regular Expression Denial
+ * of Service (ReDoS) when matched.  Limit pattern and subject lengths, execute
+ * matches in an environment that can be terminated, or use a linear-time
+ * regular expression engine when accepting untrusted patterns.
+ *
+ * @param options Configuration options for the regular expression parser.
+ * @returns A sync value parser producing JavaScript {@link RegExp} objects.
+ * @throws {TypeError} If `options.metavar` is an empty string or
+ *   `options.flags` is not a string.
+ * @throws {SyntaxError} If `options.flags` contains invalid, duplicate, or
+ *   incompatible regular expression flags.
+ * @since 1.3.0
+ */
+declare function regExp(options?: RegExpOptions): ValueParser<"sync", RegExp>;
 interface KeyValueOptionsBase {
   /**
    * The metavariable name for this parser.  Used in help messages to
@@ -3279,4 +3337,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, 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, 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, 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 };

package/dist/valueparser.js

@@ -620,6 +620,71 @@ function string(options = {}) {
 		}
 	};
 }
+/**
+* Creates a {@link ValueParser} that compiles regular expression sources.
+*
+* The entire input is treated as the source.  Slash-delimited notation such
+* as `/pattern/flags` is not interpreted; use {@link RegExpOptions.flags} to
+* configure fixed flags for the parser.
+*
+* **Security note**: Compiling a source does not establish that it is safe to
+* execute.  Patterns from untrusted input can cause Regular Expression Denial
+* of Service (ReDoS) when matched.  Limit pattern and subject lengths, execute
+* matches in an environment that can be terminated, or use a linear-time
+* regular expression engine when accepting untrusted patterns.
+*
+* @param options Configuration options for the regular expression parser.
+* @returns A sync value parser producing JavaScript {@link RegExp} objects.
+* @throws {TypeError} If `options.metavar` is an empty string or
+*   `options.flags` is not a string.
+* @throws {SyntaxError} If `options.flags` contains invalid, duplicate, or
+*   incompatible regular expression flags.
+* @since 1.3.0
+*/
+function regExp(options = {}) {
+	const metavar$1 = options.metavar ?? "REGEXP";
+	ensureNonEmptyString(metavar$1);
+	if (options.flags !== void 0 && typeof options.flags !== "string") throw new TypeError(`Expected flags to be a string, but got ${typeof options.flags}: ${String(options.flags)}.`);
+	const flags = new RegExp("", options.flags ?? "").flags;
+	const invalidRegExp = options.errors?.invalidRegExp;
+	const parseRegExp = (input) => {
+		try {
+			return {
+				success: true,
+				value: new RegExp(input, flags)
+			};
+		} catch (error) {
+			if (!(error instanceof SyntaxError)) throw error;
+			return {
+				success: false,
+				error: invalidRegExp ? typeof invalidRegExp === "function" ? invalidRegExp(input) : invalidRegExp : message`Invalid regular expression: ${input}.`
+			};
+		}
+	};
+	return {
+		mode: "sync",
+		metavar: metavar$1,
+		get placeholder() {
+			return new RegExp("", flags);
+		},
+		parse: parseRegExp,
+		validate(value) {
+			if (!(value instanceof RegExp)) return {
+				success: false,
+				error: message`Expected a RegExp value.`
+			};
+			return parseRegExp(value.source);
+		},
+		normalize(value) {
+			if (!(value instanceof RegExp)) return value;
+			const result = parseRegExp(value.source);
+			return result.success ? result.value : value;
+		},
+		format(value) {
+			return value.source;
+		}
+	};
+}
 function keyValue(options = {}) {
 	const separator = options.separator ?? "=";
 	if (typeof separator !== "string") throw new TypeError(`Expected separator to be a string, but got ${typeof separator}: ${String(separator)}.`);
@@ -6602,4 +6667,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, 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, port, portRange, regExp, semVer, socketAddress, string, transform, url, uuid };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/core",
-  "version": "1.3.0-dev.2380",
+  "version": "1.3.0-dev.2383",
   "description": "Type-safe combinatorial command-line interface parser",
   "keywords": [
     "CLI",
@@ -221,7 +221,7 @@
   },
   "sideEffects": false,
   "devDependencies": {
-    "@optique/env": "1.3.0-dev.2380+4bce39a7",
+    "@optique/env": "1.3.0-dev.2383+4053ebf3",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",

package/skills/optique/SKILL.md

@@ -40,11 +40,12 @@ Core rules
  -  Use `message` from *@optique/core/message* for descriptions, help text, and
     custom errors. Prefer semantic message helpers such as `optionName()` and
     `metavar()` over string concatenation when naming CLI elements.
- -  Use value parsers such as `integer()`, `choice()`, `biject()`, `url()`,
-    and `uuid()` instead of validating raw strings after parsing. Use
-    `biject()` for one-to-one string-to-value choices, and use `transform()`
-    when an existing value parser describes the accepted CLI spelling but your
-    app needs a different result type. Use `path()` from
+ -  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
     `@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.
@@ -63,6 +64,9 @@ Core rules
     brief and command or option sections without the `Usage:` synopsis.
     For deeply nested command trees, add `commandList: "top-level"` when root
     help should list only first-level command groups.
+ -  Use `termWidth: "auto"` in runner options when descriptions should align
+    after the widest visible help term. Optique measures terminal display
+    width after adding built-in help/version/completion entries.
 
 
 Canonical app shape
@@ -96,6 +100,7 @@ const config = run(parser, {
   brief: message`Process a file.`,
   completion: "both",
   showDefault: true,
+  termWidth: "auto",
 });
 
 console.log(`Processing ${config.input} on port ${config.port}.`);