@optique/inquirer 1.0.0-dev.0 → 1.0.0-dev.1116

package/README.md

@@ -0,0 +1,81 @@
+@optique/inquirer
+=================
+
+Interactive prompt support for [Optique] via [Inquirer.js].
+
+This package wraps any Optique parser with an interactive prompt that fires
+when no CLI value is provided.  The fallback priority is:
+
+CLI arguments > interactive prompt.
+
+Because interactive prompts are inherently asynchronous, the returned parser
+always has `$mode: "async"`.
+
+[Optique]: https://optique.dev/
+[Inquirer.js]: https://github.com/SBoudrias/Inquirer.js
+
+
+Installation
+------------
+
+~~~~ bash
+deno add jsr:@optique/inquirer
+npm add @optique/inquirer
+pnpm add @optique/inquirer
+yarn add @optique/inquirer
+bun add @optique/inquirer
+~~~~
+
+
+Quick start
+-----------
+
+~~~~ typescript
+import { object } from "@optique/core/constructs";
+import { option } from "@optique/core/primitives";
+import { integer, string } from "@optique/core/valueparser";
+import { prompt } from "@optique/inquirer";
+import { run } from "@optique/run";
+
+const parser = object({
+  name: prompt(option("--name", string()), {
+    type: "input",
+    message: "Enter your name:",
+  }),
+  port: prompt(option("--port", integer()), {
+    type: "number",
+    message: "Enter the port number:",
+    default: 3000,
+  }),
+});
+
+await run(parser);
+~~~~
+
+When `--name` and `--port` are provided on the command line, the prompts are
+skipped.  When they are absent, the user sees interactive prompts.
+
+
+Features
+--------
+
+ -  *Ten prompt types*: `input`, `password`, `number`, `confirm`, `select`,
+    `rawlist`, `expand`, `checkbox`, `editor`, and a custom `prompter` for
+    testing
+ -  *Transparent composition* with `bindEnv()` and `bindConfig()` — the
+    prompt fires only when no higher-priority source supplies a value
+ -  *Prompt-only values* via `prompt(fail<T>(), …)` when a value should not
+    be exposed as a CLI option
+ -  *TTY-free testing* via the `prompter` escape hatch on every config type
+
+
+Documentation
+-------------
+
+For full documentation, visit <https://optique.dev/integrations/inquirer>.
+
+
+License
+-------
+
+MIT License. See [LICENSE](../../LICENSE) for details.

package/dist/index.cjs

@@ -23,9 +23,87 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 const __inquirer_prompts = __toESM(require("@inquirer/prompts"));
 const __optique_core_annotations = __toESM(require("@optique/core/annotations"));
+const __optique_core_context = __toESM(require("@optique/core/context"));
 const __optique_core_message = __toESM(require("@optique/core/message"));
 
 //#region src/index.ts
+const promptFunctionsOverrideSymbol = Symbol.for("@optique/inquirer/prompt-functions");
+const defaultPromptFunctions = {
+	confirm: __inquirer_prompts.confirm,
+	number: __inquirer_prompts.number,
+	input: __inquirer_prompts.input,
+	password: __inquirer_prompts.password,
+	editor: __inquirer_prompts.editor,
+	select: __inquirer_prompts.select,
+	rawlist: __inquirer_prompts.rawlist,
+	expand: __inquirer_prompts.expand,
+	checkbox: __inquirer_prompts.checkbox
+};
+function promptFunctionKeys() {
+	return Object.keys(defaultPromptFunctions);
+}
+function assignPromptFunctionOverride(override, key, candidate) {
+	if (typeof candidate === "function") override[key] = candidate;
+}
+/**
+* Extracts valid prompt function overrides from an arbitrary value.
+*/
+function getPromptFunctionsOverride(value) {
+	if (typeof value !== "object" || value == null) return void 0;
+	const override = {};
+	for (const key of promptFunctionKeys()) assignPromptFunctionOverride(override, key, Reflect.get(value, key));
+	return override;
+}
+/**
+* Returns the active prompt function set, applying any global test overrides.
+*/
+function getPromptFunctions() {
+	const override = getPromptFunctionsOverride(Reflect.get(globalThis, promptFunctionsOverrideSymbol));
+	return override != null ? {
+		...defaultPromptFunctions,
+		...override
+	} : defaultPromptFunctions;
+}
+/**
+* Determines whether an error came from an interrupted Inquirer prompt.
+*/
+function isExitPromptError(error) {
+	return typeof error === "object" && error != null && "name" in error && error.name === "ExitPromptError";
+}
+const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
+var DeferredPromptValue = class {
+	[__optique_core_context.placeholder] = true;
+	constructor() {}
+};
+function shouldDeferPrompt(parser, state) {
+	return typeof parser.shouldDeferCompletion === "function" && parser.shouldDeferCompletion(state) === true;
+}
+function deferredPromptResult() {
+	return {
+		success: true,
+		value: new DeferredPromptValue()
+	};
+}
+function withAnnotationView(state, annotations, run) {
+	const annotatedState = new Proxy(state, {
+		get(target, key) {
+			if (key === __optique_core_annotations.annotationKey) return annotations;
+			const value = Reflect.get(target, key, target);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+		has(target, key) {
+			return key === __optique_core_annotations.annotationKey || Reflect.has(target, key);
+		}
+	});
+	return run(annotatedState);
+}
+function withAnnotatedInnerState(sourceState, innerState, run) {
+	const annotations = (0, __optique_core_annotations.getAnnotations)(sourceState);
+	if (annotations == null || innerState == null || typeof innerState !== "object" || typeof innerState === "object" && __optique_core_annotations.annotationKey in innerState) return run(innerState);
+	const inheritedState = (0, __optique_core_annotations.inheritAnnotations)(sourceState, innerState);
+	if (inheritedState !== innerState) return run(inheritedState);
+	return withAnnotationView(innerState, annotations, (annotatedState) => run(annotatedState));
+}
 /**
 * Wraps a parser with an interactive Inquirer.js prompt fallback.
 *
@@ -52,6 +130,8 @@ const __optique_core_message = __toESM(require("@optique/core/message"));
 * @param parser Inner parser that reads CLI values.
 * @param config Type-safe Inquirer.js prompt configuration.
 * @returns A parser with interactive prompt fallback, always in async mode.
+* @throws {Error} If prompt execution fails with an unexpected error or if
+*                 the inner parser throws while parsing or completing.
 * @since 1.0.0
 */
 function prompt(parser, config) {
@@ -64,116 +144,170 @@ function prompt(parser, config) {
 		[promptBindStateKey] = true;
 		hasCliValue = false;
 	};
-	const promptBindInitialState = new PromptBindInitialStateClass();
 	let promptCache = null;
-	async function executePrompt() {
-		if ("prompter" in cfg && cfg.prompter != null) {
-			const value = await cfg.prompter();
-			if (cfg.type === "number" && value === void 0) return {
-				success: false,
-				error: __optique_core_message.message`No number provided.`
-			};
-			return {
-				success: true,
-				value
-			};
-		}
-		switch (cfg.type) {
-			case "confirm": return {
-				success: true,
-				value: await (0, __inquirer_prompts.confirm)({
-					message: cfg.message,
-					...cfg.default !== void 0 ? { default: cfg.default } : {}
-				})
-			};
-			case "number": {
-				const numResult = await (0, __inquirer_prompts.number)({
-					message: cfg.message,
-					...cfg.default !== void 0 ? { default: cfg.default } : {},
-					...cfg.min !== void 0 ? { min: cfg.min } : {},
-					...cfg.max !== void 0 ? { max: cfg.max } : {},
-					...cfg.step !== void 0 ? { step: cfg.step } : {}
-				});
-				if (numResult === void 0) return {
+	function shouldAttemptInnerCompletion(cliState, state) {
+		if (cliState == null || cliState instanceof PromptBindInitialStateClass) return false;
+		const cliStateHasAnnotations = typeof cliState === "object" && __optique_core_annotations.annotationKey in cliState;
+		if (cliStateHasAnnotations) return true;
+		if ((0, __optique_core_annotations.getAnnotations)(state) == null || typeof cliState !== "object") return false;
+		if ("hasCliValue" in cliState) return true;
+		if (Array.isArray(cliState)) return typeof parser.shouldDeferCompletion === "function";
+		const prototype = Object.getPrototypeOf(cliState);
+		return prototype !== Object.prototype && prototype !== null;
+	}
+	/**
+	* Executes the configured prompt and normalizes its result.
+	*
+	* Converts `ExitPromptError` into a parse failure and returns prompt values
+	* in Optique's `ValueParserResult` shape.
+	*
+	* @returns The normalized prompt result.
+	* @throws {Error} Rethrows unexpected prompt failures after converting
+	*                 `ExitPromptError` cancellations into parse failures.
+	*/
+	function validatePromptedValue(result) {
+		return result;
+	}
+	const validPromptTypes = new Set([
+		"confirm",
+		"number",
+		"input",
+		"password",
+		"editor",
+		"select",
+		"rawlist",
+		"expand",
+		"checkbox"
+	]);
+	async function executePromptRaw() {
+		const prompts = getPromptFunctions();
+		try {
+			if (!validPromptTypes.has(cfg.type)) throw new TypeError(`Unsupported prompt type: ${cfg.type}`);
+			if ("prompter" in cfg && cfg.prompter != null) {
+				const value = await cfg.prompter();
+				if (cfg.type === "number" && value === void 0) return {
 					success: false,
 					error: __optique_core_message.message`No number provided.`
 				};
 				return {
 					success: true,
-					value: numResult
+					value
 				};
 			}
-			case "input": return {
-				success: true,
-				value: await (0, __inquirer_prompts.input)({
-					message: cfg.message,
-					...cfg.default !== void 0 ? { default: cfg.default } : {},
-					...cfg.validate !== void 0 ? { validate: cfg.validate } : {}
-				})
-			};
-			case "password": return {
-				success: true,
-				value: await (0, __inquirer_prompts.password)({
-					message: cfg.message,
-					...cfg.mask !== void 0 ? { mask: cfg.mask } : {},
-					...cfg.validate !== void 0 ? { validate: cfg.validate } : {}
-				})
-			};
-			case "editor": return {
-				success: true,
-				value: await (0, __inquirer_prompts.editor)({
-					message: cfg.message,
-					...cfg.default !== void 0 ? { default: cfg.default } : {},
-					...cfg.validate !== void 0 ? { validate: cfg.validate } : {}
-				})
-			};
-			case "select": return {
-				success: true,
-				value: await (0, __inquirer_prompts.select)({
-					message: cfg.message,
-					choices: normalizeChoices(cfg.choices),
-					...cfg.default !== void 0 ? { default: cfg.default } : {}
-				})
-			};
-			case "rawlist": return {
-				success: true,
-				value: await (0, __inquirer_prompts.rawlist)({
-					message: cfg.message,
-					choices: normalizeChoices(cfg.choices),
-					...cfg.default !== void 0 ? { default: cfg.default } : {}
-				})
-			};
-			case "expand": return {
-				success: true,
-				value: await (0, __inquirer_prompts.expand)({
-					message: cfg.message,
-					choices: cfg.choices,
-					...cfg.default !== void 0 ? { default: cfg.default } : {}
-				})
-			};
-			case "checkbox": return {
-				success: true,
-				value: await (0, __inquirer_prompts.checkbox)({
-					message: cfg.message,
-					choices: normalizeChoices(cfg.choices)
-				})
+			switch (cfg.type) {
+				case "confirm": return {
+					success: true,
+					value: await prompts.confirm({
+						message: cfg.message,
+						...cfg.default !== void 0 ? { default: cfg.default } : {}
+					})
+				};
+				case "number": {
+					const numResult = await prompts.number({
+						message: cfg.message,
+						...cfg.default !== void 0 ? { default: cfg.default } : {},
+						...cfg.min !== void 0 ? { min: cfg.min } : {},
+						...cfg.max !== void 0 ? { max: cfg.max } : {},
+						...cfg.step !== void 0 ? { step: cfg.step } : {}
+					});
+					if (numResult === void 0) return {
+						success: false,
+						error: __optique_core_message.message`No number provided.`
+					};
+					return {
+						success: true,
+						value: numResult
+					};
+				}
+				case "input": return {
+					success: true,
+					value: await prompts.input({
+						message: cfg.message,
+						...cfg.default !== void 0 ? { default: cfg.default } : {},
+						...cfg.validate !== void 0 ? { validate: cfg.validate } : {}
+					})
+				};
+				case "password": return {
+					success: true,
+					value: await prompts.password({
+						message: cfg.message,
+						...cfg.mask !== void 0 ? { mask: cfg.mask } : {},
+						...cfg.validate !== void 0 ? { validate: cfg.validate } : {}
+					})
+				};
+				case "editor": return {
+					success: true,
+					value: await prompts.editor({
+						message: cfg.message,
+						...cfg.default !== void 0 ? { default: cfg.default } : {},
+						...cfg.validate !== void 0 ? { validate: cfg.validate } : {}
+					})
+				};
+				case "select": return {
+					success: true,
+					value: await prompts.select({
+						message: cfg.message,
+						choices: normalizeChoices(cfg.choices),
+						...cfg.default !== void 0 ? { default: cfg.default } : {}
+					})
+				};
+				case "rawlist": return {
+					success: true,
+					value: await prompts.rawlist({
+						message: cfg.message,
+						choices: normalizeChoices(cfg.choices),
+						...cfg.default !== void 0 ? { default: cfg.default } : {}
+					})
+				};
+				case "expand": return {
+					success: true,
+					value: await prompts.expand({
+						message: cfg.message,
+						choices: cfg.choices,
+						...cfg.default !== void 0 ? { default: cfg.default } : {}
+					})
+				};
+				case "checkbox": return {
+					success: true,
+					value: await prompts.checkbox({
+						message: cfg.message,
+						choices: normalizeChoices(cfg.choices)
+					})
+				};
+			}
+		} catch (error) {
+			if (isExitPromptError(error)) return {
+				success: false,
+				error: __optique_core_message.message`Prompt cancelled.`
 			};
+			throw error;
 		}
 	}
-	return {
+	async function executePrompt() {
+		const result = await executePromptRaw();
+		return validatePromptedValue(result);
+	}
+	function usePromptOrDefer(state, result) {
+		if (result.success) return Promise.resolve(result);
+		return shouldDeferPrompt(parser, state) ? Promise.resolve(deferredPromptResult()) : executePrompt();
+	}
+	const promptedParser = {
 		$mode: "async",
 		$valueType: parser.$valueType,
 		$stateType: parser.$stateType,
 		priority: parser.priority,
-		usage: [{
+		[inheritParentAnnotationsKey]: true,
+		usage: parser.usage.length === 1 && parser.usage[0].type === "optional" ? parser.usage : [{
 			type: "optional",
 			terms: parser.usage
 		}],
-		initialState: promptBindInitialState,
+		get initialState() {
+			return new PromptBindInitialStateClass();
+		},
 		parse: (context) => {
 			const annotations = (0, __optique_core_annotations.getAnnotations)(context.state);
 			const innerState = isPromptBindState(context.state) ? context.state.hasCliValue ? context.state.cliState : parser.initialState : context.state;
-			const innerContext = innerState !== context.state ? {
+			const baseInnerContext = innerState !== context.state ? {
 				...context,
 				state: innerState
 			} : context;
@@ -204,32 +338,98 @@ function prompt(parser, config) {
 				return {
 					success: true,
 					next: {
-						...innerContext,
+						...baseInnerContext,
 						state: nextState
 					},
 					consumed: []
 				};
 			};
-			const result = parser.parse(innerContext);
+			const result = withAnnotatedInnerState(context.state, innerState, (annotatedInnerState) => {
+				const innerContext = annotatedInnerState !== context.state ? {
+					...context,
+					state: annotatedInnerState
+				} : context;
+				return parser.parse(innerContext);
+			});
 			if (result instanceof Promise) return result.then(processResult);
 			return Promise.resolve(processResult(result));
 		},
 		complete: (state) => {
 			if (isPromptBindState(state) && state.hasCliValue) {
-				const r = parser.complete(state.cliState);
+				const r = withAnnotatedInnerState(state, state.cliState, (annotatedInnerState) => parser.complete(annotatedInnerState));
 				if (r instanceof Promise) return r;
 				return Promise.resolve(r);
 			}
-			if (state === promptBindInitialState) {
-				if (promptCache !== null) {
-					const cached = promptCache;
+			if (state instanceof PromptBindInitialStateClass) {
+				if (promptCache?.state === state) {
+					const cached = promptCache.result;
 					promptCache = null;
 					return cached;
 				}
-				promptCache = executePrompt();
-				return promptCache;
+				const hasDeferHook = typeof parser.shouldDeferCompletion === "function";
+				const annotations = (0, __optique_core_annotations.getAnnotations)(state);
+				const innerInitialState = parser.initialState;
+				const effectiveInitialState = annotations != null && innerInitialState == null ? (0, __optique_core_annotations.injectAnnotations)(innerInitialState, annotations) : innerInitialState;
+				if (hasDeferHook) {
+					const annotatedR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedInnerState) => parser.complete(annotatedInnerState));
+					const usePromptOrDeferSentinel = (res) => {
+						if (res.success && res.value === void 0) return usePromptOrDefer(state, {
+							success: false,
+							error: []
+						});
+						return usePromptOrDefer(state, res);
+					};
+					const cachedResult$1 = annotatedR instanceof Promise ? annotatedR.then(usePromptOrDeferSentinel) : usePromptOrDeferSentinel(annotatedR);
+					promptCache = {
+						state,
+						result: cachedResult$1
+					};
+					return cachedResult$1;
+				}
+				const simParseR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedState) => parser.parse({
+					buffer: [],
+					state: annotatedState,
+					optionsTerminated: false,
+					usage: parser.usage
+				}));
+				const decideFromParse = (parseResult) => {
+					const consumed = parseResult.success ? parseResult.consumed.length : 0;
+					const cliState$1 = parseResult.success && consumed === 0 ? parseResult.next.state : void 0;
+					const hasSourceBindingMarker = (s) => s != null && typeof s === "object" && "hasCliValue" in s && Object.getOwnPropertySymbols(s).length > 0;
+					const cliStateIsPassthrough = cliState$1 != null && typeof cliState$1 === "object" && (0, __optique_core_annotations.unwrapInjectedAnnotationWrapper)(cliState$1) !== cliState$1;
+					const isSourceBinding = shouldAttemptInnerCompletion(cliState$1, state) && !cliStateIsPassthrough || hasSourceBindingMarker(cliState$1) || Array.isArray(cliState$1) && cliState$1.length === 1 && (hasSourceBindingMarker(cliState$1[0]) || typeof cliState$1[0] === "object" && cliState$1[0] != null && __optique_core_annotations.annotationKey in cliState$1[0]);
+					if (isSourceBinding) {
+						const cliStateIsInjected = cliState$1 != null && typeof cliState$1 === "object" && (0, __optique_core_annotations.unwrapInjectedAnnotationWrapper)(cliState$1) !== cliState$1;
+						const handleCompleteResult = (res) => {
+							if (res.success && res.value === void 0 && cliStateIsInjected) return executePrompt();
+							return usePromptOrDefer(state, res);
+						};
+						const completeState = parseResult.success ? parseResult.next.state : effectiveInitialState;
+						const completeR = parser.complete(completeState);
+						if (completeR instanceof Promise) return completeR.then(handleCompleteResult);
+						return handleCompleteResult(completeR);
+					}
+					return executePrompt();
+				};
+				const cachedResult = simParseR instanceof Promise ? simParseR.then(decideFromParse) : decideFromParse(simParseR);
+				promptCache = {
+					state,
+					result: cachedResult
+				};
+				return cachedResult;
+			}
+			const cliState = isPromptBindState(state) ? state.cliState : void 0;
+			const cliStateIsInjectedAnnotationWrapper = cliState != null && typeof cliState === "object" && (0, __optique_core_annotations.unwrapInjectedAnnotationWrapper)(cliState) !== cliState;
+			if (shouldAttemptInnerCompletion(cliState, state)) {
+				const useCompleteResultOrPrompt = (result) => {
+					if (result.success && result.value === void 0 && cliStateIsInjectedAnnotationWrapper) return executePrompt();
+					return usePromptOrDefer(state, result);
+				};
+				const r = withAnnotatedInnerState(state, cliState, (annotatedInnerState) => parser.complete(annotatedInnerState));
+				if (r instanceof Promise) return r.then(useCompleteResultOrPrompt);
+				return useCompleteResultOrPrompt(r);
 			}
-			return executePrompt();
+			return shouldDeferPrompt(parser, state) ? Promise.resolve(deferredPromptResult()) : executePrompt();
 		},
 		suggest: (context, prefix) => {
 			const innerState = isPromptBindState(context.state) ? context.state.hasCliValue ? context.state.cliState : parser.initialState : context.state;
@@ -248,6 +448,7 @@ function prompt(parser, config) {
 			return parser.getDocFragments(state, defaultValue);
 		}
 	};
+	return promptedParser;
 }
 /** Normalize choices to the format Inquirer.js expects. */
 function normalizeChoices(choices) {

package/dist/index.d.cts

@@ -347,6 +347,8 @@ type BasePromptConfig<T> = T extends boolean ? ConfirmConfig : T extends number
  * @param parser Inner parser that reads CLI values.
  * @param config Type-safe Inquirer.js prompt configuration.
  * @returns A parser with interactive prompt fallback, always in async mode.
+ * @throws {Error} If prompt execution fails with an unexpected error or if
+ *                 the inner parser throws while parsing or completing.
  * @since 1.0.0
  */
 declare function prompt<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: PromptConfig<TValue>): Parser<"async", TValue, TState>;

package/dist/index.d.ts

@@ -347,6 +347,8 @@ type BasePromptConfig<T> = T extends boolean ? ConfirmConfig : T extends number
  * @param parser Inner parser that reads CLI values.
  * @param config Type-safe Inquirer.js prompt configuration.
  * @returns A parser with interactive prompt fallback, always in async mode.
+ * @throws {Error} If prompt execution fails with an unexpected error or if
+ *                 the inner parser throws while parsing or completing.
  * @since 1.0.0
  */
 declare function prompt<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: PromptConfig<TValue>): Parser<"async", TValue, TState>;

package/dist/index.js

@@ -1,8 +1,86 @@
 import { Separator, checkbox, confirm, editor, expand, input, number, password, rawlist, select } from "@inquirer/prompts";
-import { annotationKey, getAnnotations } from "@optique/core/annotations";
+import { annotationKey, getAnnotations, inheritAnnotations, injectAnnotations, unwrapInjectedAnnotationWrapper } from "@optique/core/annotations";
+import { placeholder } from "@optique/core/context";
 import { message } from "@optique/core/message";
 
 //#region src/index.ts
+const promptFunctionsOverrideSymbol = Symbol.for("@optique/inquirer/prompt-functions");
+const defaultPromptFunctions = {
+	confirm,
+	number,
+	input,
+	password,
+	editor,
+	select,
+	rawlist,
+	expand,
+	checkbox
+};
+function promptFunctionKeys() {
+	return Object.keys(defaultPromptFunctions);
+}
+function assignPromptFunctionOverride(override, key, candidate) {
+	if (typeof candidate === "function") override[key] = candidate;
+}
+/**
+* Extracts valid prompt function overrides from an arbitrary value.
+*/
+function getPromptFunctionsOverride(value) {
+	if (typeof value !== "object" || value == null) return void 0;
+	const override = {};
+	for (const key of promptFunctionKeys()) assignPromptFunctionOverride(override, key, Reflect.get(value, key));
+	return override;
+}
+/**
+* Returns the active prompt function set, applying any global test overrides.
+*/
+function getPromptFunctions() {
+	const override = getPromptFunctionsOverride(Reflect.get(globalThis, promptFunctionsOverrideSymbol));
+	return override != null ? {
+		...defaultPromptFunctions,
+		...override
+	} : defaultPromptFunctions;
+}
+/**
+* Determines whether an error came from an interrupted Inquirer prompt.
+*/
+function isExitPromptError(error) {
+	return typeof error === "object" && error != null && "name" in error && error.name === "ExitPromptError";
+}
+const inheritParentAnnotationsKey = Symbol.for("@optique/core/inheritParentAnnotations");
+var DeferredPromptValue = class {
+	[placeholder] = true;
+	constructor() {}
+};
+function shouldDeferPrompt(parser, state) {
+	return typeof parser.shouldDeferCompletion === "function" && parser.shouldDeferCompletion(state) === true;
+}
+function deferredPromptResult() {
+	return {
+		success: true,
+		value: new DeferredPromptValue()
+	};
+}
+function withAnnotationView(state, annotations, run) {
+	const annotatedState = new Proxy(state, {
+		get(target, key) {
+			if (key === annotationKey) return annotations;
+			const value = Reflect.get(target, key, target);
+			return typeof value === "function" ? value.bind(target) : value;
+		},
+		has(target, key) {
+			return key === annotationKey || Reflect.has(target, key);
+		}
+	});
+	return run(annotatedState);
+}
+function withAnnotatedInnerState(sourceState, innerState, run) {
+	const annotations = getAnnotations(sourceState);
+	if (annotations == null || innerState == null || typeof innerState !== "object" || typeof innerState === "object" && annotationKey in innerState) return run(innerState);
+	const inheritedState = inheritAnnotations(sourceState, innerState);
+	if (inheritedState !== innerState) return run(inheritedState);
+	return withAnnotationView(innerState, annotations, (annotatedState) => run(annotatedState));
+}
 /**
 * Wraps a parser with an interactive Inquirer.js prompt fallback.
 *
@@ -29,6 +107,8 @@ import { message } from "@optique/core/message";
 * @param parser Inner parser that reads CLI values.
 * @param config Type-safe Inquirer.js prompt configuration.
 * @returns A parser with interactive prompt fallback, always in async mode.
+* @throws {Error} If prompt execution fails with an unexpected error or if
+*                 the inner parser throws while parsing or completing.
 * @since 1.0.0
 */
 function prompt(parser, config) {
@@ -41,116 +121,170 @@ function prompt(parser, config) {
 		[promptBindStateKey] = true;
 		hasCliValue = false;
 	};
-	const promptBindInitialState = new PromptBindInitialStateClass();
 	let promptCache = null;
-	async function executePrompt() {
-		if ("prompter" in cfg && cfg.prompter != null) {
-			const value = await cfg.prompter();
-			if (cfg.type === "number" && value === void 0) return {
-				success: false,
-				error: message`No number provided.`
-			};
-			return {
-				success: true,
-				value
-			};
-		}
-		switch (cfg.type) {
-			case "confirm": return {
-				success: true,
-				value: await confirm({
-					message: cfg.message,
-					...cfg.default !== void 0 ? { default: cfg.default } : {}
-				})
-			};
-			case "number": {
-				const numResult = await number({
-					message: cfg.message,
-					...cfg.default !== void 0 ? { default: cfg.default } : {},
-					...cfg.min !== void 0 ? { min: cfg.min } : {},
-					...cfg.max !== void 0 ? { max: cfg.max } : {},
-					...cfg.step !== void 0 ? { step: cfg.step } : {}
-				});
-				if (numResult === void 0) return {
+	function shouldAttemptInnerCompletion(cliState, state) {
+		if (cliState == null || cliState instanceof PromptBindInitialStateClass) return false;
+		const cliStateHasAnnotations = typeof cliState === "object" && annotationKey in cliState;
+		if (cliStateHasAnnotations) return true;
+		if (getAnnotations(state) == null || typeof cliState !== "object") return false;
+		if ("hasCliValue" in cliState) return true;
+		if (Array.isArray(cliState)) return typeof parser.shouldDeferCompletion === "function";
+		const prototype = Object.getPrototypeOf(cliState);
+		return prototype !== Object.prototype && prototype !== null;
+	}
+	/**
+	* Executes the configured prompt and normalizes its result.
+	*
+	* Converts `ExitPromptError` into a parse failure and returns prompt values
+	* in Optique's `ValueParserResult` shape.
+	*
+	* @returns The normalized prompt result.
+	* @throws {Error} Rethrows unexpected prompt failures after converting
+	*                 `ExitPromptError` cancellations into parse failures.
+	*/
+	function validatePromptedValue(result) {
+		return result;
+	}
+	const validPromptTypes = new Set([
+		"confirm",
+		"number",
+		"input",
+		"password",
+		"editor",
+		"select",
+		"rawlist",
+		"expand",
+		"checkbox"
+	]);
+	async function executePromptRaw() {
+		const prompts = getPromptFunctions();
+		try {
+			if (!validPromptTypes.has(cfg.type)) throw new TypeError(`Unsupported prompt type: ${cfg.type}`);
+			if ("prompter" in cfg && cfg.prompter != null) {
+				const value = await cfg.prompter();
+				if (cfg.type === "number" && value === void 0) return {
 					success: false,
 					error: message`No number provided.`
 				};
 				return {
 					success: true,
-					value: numResult
+					value
 				};
 			}
-			case "input": return {
-				success: true,
-				value: await input({
-					message: cfg.message,
-					...cfg.default !== void 0 ? { default: cfg.default } : {},
-					...cfg.validate !== void 0 ? { validate: cfg.validate } : {}
-				})
-			};
-			case "password": return {
-				success: true,
-				value: await password({
-					message: cfg.message,
-					...cfg.mask !== void 0 ? { mask: cfg.mask } : {},
-					...cfg.validate !== void 0 ? { validate: cfg.validate } : {}
-				})
-			};
-			case "editor": return {
-				success: true,
-				value: await editor({
-					message: cfg.message,
-					...cfg.default !== void 0 ? { default: cfg.default } : {},
-					...cfg.validate !== void 0 ? { validate: cfg.validate } : {}
-				})
-			};
-			case "select": return {
-				success: true,
-				value: await select({
-					message: cfg.message,
-					choices: normalizeChoices(cfg.choices),
-					...cfg.default !== void 0 ? { default: cfg.default } : {}
-				})
-			};
-			case "rawlist": return {
-				success: true,
-				value: await rawlist({
-					message: cfg.message,
-					choices: normalizeChoices(cfg.choices),
-					...cfg.default !== void 0 ? { default: cfg.default } : {}
-				})
-			};
-			case "expand": return {
-				success: true,
-				value: await expand({
-					message: cfg.message,
-					choices: cfg.choices,
-					...cfg.default !== void 0 ? { default: cfg.default } : {}
-				})
-			};
-			case "checkbox": return {
-				success: true,
-				value: await checkbox({
-					message: cfg.message,
-					choices: normalizeChoices(cfg.choices)
-				})
+			switch (cfg.type) {
+				case "confirm": return {
+					success: true,
+					value: await prompts.confirm({
+						message: cfg.message,
+						...cfg.default !== void 0 ? { default: cfg.default } : {}
+					})
+				};
+				case "number": {
+					const numResult = await prompts.number({
+						message: cfg.message,
+						...cfg.default !== void 0 ? { default: cfg.default } : {},
+						...cfg.min !== void 0 ? { min: cfg.min } : {},
+						...cfg.max !== void 0 ? { max: cfg.max } : {},
+						...cfg.step !== void 0 ? { step: cfg.step } : {}
+					});
+					if (numResult === void 0) return {
+						success: false,
+						error: message`No number provided.`
+					};
+					return {
+						success: true,
+						value: numResult
+					};
+				}
+				case "input": return {
+					success: true,
+					value: await prompts.input({
+						message: cfg.message,
+						...cfg.default !== void 0 ? { default: cfg.default } : {},
+						...cfg.validate !== void 0 ? { validate: cfg.validate } : {}
+					})
+				};
+				case "password": return {
+					success: true,
+					value: await prompts.password({
+						message: cfg.message,
+						...cfg.mask !== void 0 ? { mask: cfg.mask } : {},
+						...cfg.validate !== void 0 ? { validate: cfg.validate } : {}
+					})
+				};
+				case "editor": return {
+					success: true,
+					value: await prompts.editor({
+						message: cfg.message,
+						...cfg.default !== void 0 ? { default: cfg.default } : {},
+						...cfg.validate !== void 0 ? { validate: cfg.validate } : {}
+					})
+				};
+				case "select": return {
+					success: true,
+					value: await prompts.select({
+						message: cfg.message,
+						choices: normalizeChoices(cfg.choices),
+						...cfg.default !== void 0 ? { default: cfg.default } : {}
+					})
+				};
+				case "rawlist": return {
+					success: true,
+					value: await prompts.rawlist({
+						message: cfg.message,
+						choices: normalizeChoices(cfg.choices),
+						...cfg.default !== void 0 ? { default: cfg.default } : {}
+					})
+				};
+				case "expand": return {
+					success: true,
+					value: await prompts.expand({
+						message: cfg.message,
+						choices: cfg.choices,
+						...cfg.default !== void 0 ? { default: cfg.default } : {}
+					})
+				};
+				case "checkbox": return {
+					success: true,
+					value: await prompts.checkbox({
+						message: cfg.message,
+						choices: normalizeChoices(cfg.choices)
+					})
+				};
+			}
+		} catch (error) {
+			if (isExitPromptError(error)) return {
+				success: false,
+				error: message`Prompt cancelled.`
 			};
+			throw error;
 		}
 	}
-	return {
+	async function executePrompt() {
+		const result = await executePromptRaw();
+		return validatePromptedValue(result);
+	}
+	function usePromptOrDefer(state, result) {
+		if (result.success) return Promise.resolve(result);
+		return shouldDeferPrompt(parser, state) ? Promise.resolve(deferredPromptResult()) : executePrompt();
+	}
+	const promptedParser = {
 		$mode: "async",
 		$valueType: parser.$valueType,
 		$stateType: parser.$stateType,
 		priority: parser.priority,
-		usage: [{
+		[inheritParentAnnotationsKey]: true,
+		usage: parser.usage.length === 1 && parser.usage[0].type === "optional" ? parser.usage : [{
 			type: "optional",
 			terms: parser.usage
 		}],
-		initialState: promptBindInitialState,
+		get initialState() {
+			return new PromptBindInitialStateClass();
+		},
 		parse: (context) => {
 			const annotations = getAnnotations(context.state);
 			const innerState = isPromptBindState(context.state) ? context.state.hasCliValue ? context.state.cliState : parser.initialState : context.state;
-			const innerContext = innerState !== context.state ? {
+			const baseInnerContext = innerState !== context.state ? {
 				...context,
 				state: innerState
 			} : context;
@@ -181,32 +315,98 @@ function prompt(parser, config) {
 				return {
 					success: true,
 					next: {
-						...innerContext,
+						...baseInnerContext,
 						state: nextState
 					},
 					consumed: []
 				};
 			};
-			const result = parser.parse(innerContext);
+			const result = withAnnotatedInnerState(context.state, innerState, (annotatedInnerState) => {
+				const innerContext = annotatedInnerState !== context.state ? {
+					...context,
+					state: annotatedInnerState
+				} : context;
+				return parser.parse(innerContext);
+			});
 			if (result instanceof Promise) return result.then(processResult);
 			return Promise.resolve(processResult(result));
 		},
 		complete: (state) => {
 			if (isPromptBindState(state) && state.hasCliValue) {
-				const r = parser.complete(state.cliState);
+				const r = withAnnotatedInnerState(state, state.cliState, (annotatedInnerState) => parser.complete(annotatedInnerState));
 				if (r instanceof Promise) return r;
 				return Promise.resolve(r);
 			}
-			if (state === promptBindInitialState) {
-				if (promptCache !== null) {
-					const cached = promptCache;
+			if (state instanceof PromptBindInitialStateClass) {
+				if (promptCache?.state === state) {
+					const cached = promptCache.result;
 					promptCache = null;
 					return cached;
 				}
-				promptCache = executePrompt();
-				return promptCache;
+				const hasDeferHook = typeof parser.shouldDeferCompletion === "function";
+				const annotations = getAnnotations(state);
+				const innerInitialState = parser.initialState;
+				const effectiveInitialState = annotations != null && innerInitialState == null ? injectAnnotations(innerInitialState, annotations) : innerInitialState;
+				if (hasDeferHook) {
+					const annotatedR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedInnerState) => parser.complete(annotatedInnerState));
+					const usePromptOrDeferSentinel = (res) => {
+						if (res.success && res.value === void 0) return usePromptOrDefer(state, {
+							success: false,
+							error: []
+						});
+						return usePromptOrDefer(state, res);
+					};
+					const cachedResult$1 = annotatedR instanceof Promise ? annotatedR.then(usePromptOrDeferSentinel) : usePromptOrDeferSentinel(annotatedR);
+					promptCache = {
+						state,
+						result: cachedResult$1
+					};
+					return cachedResult$1;
+				}
+				const simParseR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedState) => parser.parse({
+					buffer: [],
+					state: annotatedState,
+					optionsTerminated: false,
+					usage: parser.usage
+				}));
+				const decideFromParse = (parseResult) => {
+					const consumed = parseResult.success ? parseResult.consumed.length : 0;
+					const cliState$1 = parseResult.success && consumed === 0 ? parseResult.next.state : void 0;
+					const hasSourceBindingMarker = (s) => s != null && typeof s === "object" && "hasCliValue" in s && Object.getOwnPropertySymbols(s).length > 0;
+					const cliStateIsPassthrough = cliState$1 != null && typeof cliState$1 === "object" && unwrapInjectedAnnotationWrapper(cliState$1) !== cliState$1;
+					const isSourceBinding = shouldAttemptInnerCompletion(cliState$1, state) && !cliStateIsPassthrough || hasSourceBindingMarker(cliState$1) || Array.isArray(cliState$1) && cliState$1.length === 1 && (hasSourceBindingMarker(cliState$1[0]) || typeof cliState$1[0] === "object" && cliState$1[0] != null && annotationKey in cliState$1[0]);
+					if (isSourceBinding) {
+						const cliStateIsInjected = cliState$1 != null && typeof cliState$1 === "object" && unwrapInjectedAnnotationWrapper(cliState$1) !== cliState$1;
+						const handleCompleteResult = (res) => {
+							if (res.success && res.value === void 0 && cliStateIsInjected) return executePrompt();
+							return usePromptOrDefer(state, res);
+						};
+						const completeState = parseResult.success ? parseResult.next.state : effectiveInitialState;
+						const completeR = parser.complete(completeState);
+						if (completeR instanceof Promise) return completeR.then(handleCompleteResult);
+						return handleCompleteResult(completeR);
+					}
+					return executePrompt();
+				};
+				const cachedResult = simParseR instanceof Promise ? simParseR.then(decideFromParse) : decideFromParse(simParseR);
+				promptCache = {
+					state,
+					result: cachedResult
+				};
+				return cachedResult;
+			}
+			const cliState = isPromptBindState(state) ? state.cliState : void 0;
+			const cliStateIsInjectedAnnotationWrapper = cliState != null && typeof cliState === "object" && unwrapInjectedAnnotationWrapper(cliState) !== cliState;
+			if (shouldAttemptInnerCompletion(cliState, state)) {
+				const useCompleteResultOrPrompt = (result) => {
+					if (result.success && result.value === void 0 && cliStateIsInjectedAnnotationWrapper) return executePrompt();
+					return usePromptOrDefer(state, result);
+				};
+				const r = withAnnotatedInnerState(state, cliState, (annotatedInnerState) => parser.complete(annotatedInnerState));
+				if (r instanceof Promise) return r.then(useCompleteResultOrPrompt);
+				return useCompleteResultOrPrompt(r);
 			}
-			return executePrompt();
+			return shouldDeferPrompt(parser, state) ? Promise.resolve(deferredPromptResult()) : executePrompt();
 		},
 		suggest: (context, prefix) => {
 			const innerState = isPromptBindState(context.state) ? context.state.hasCliValue ? context.state.cliState : parser.initialState : context.state;
@@ -225,6 +425,7 @@ function prompt(parser, config) {
 			return parser.getDocFragments(state, defaultValue);
 		}
 	};
+	return promptedParser;
 }
 /** Normalize choices to the format Inquirer.js expects. */
 function normalizeChoices(choices) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/inquirer",
-  "version": "1.0.0-dev.0",
+  "version": "1.0.0-dev.1116+6084dd3a",
   "description": "Interactive prompt support for Optique via Inquirer.js",
   "keywords": [
     "CLI",
@@ -56,12 +56,13 @@
   "sideEffects": false,
   "dependencies": {
     "@inquirer/prompts": "^8.3.0",
-    "@optique/core": "1.0.0"
+    "@optique/core": "1.0.0-dev.1116+6084dd3a"
   },
   "devDependencies": {
     "@types/node": "^20.19.9",
     "tsdown": "^0.13.0",
-    "typescript": "^5.8.3"
+    "typescript": "^5.8.3",
+    "@optique/env": "1.0.0-dev.1116+6084dd3a"
   },
   "scripts": {
     "build": "tsdown",