@optique/prompt 1.2.0-dev.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright 2025–2026 Hong Minhee
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+@optique/prompt
+===============
+
+Generic prompt adapter support for [Optique].
+
+This package contains the shared machinery used by interactive prompt
+integrations.  Most applications should use a concrete integration such as
+*@optique/inquirer* or *@optique/clack* instead.
+
+[Optique]: https://optique.dev/
+
+
+Installation
+------------
+
+~~~~ bash
+deno add jsr:@optique/prompt
+npm add @optique/prompt
+pnpm add @optique/prompt
+yarn add @optique/prompt
+bun add @optique/prompt
+~~~~
+
+
+Documentation
+-------------
+
+For full documentation, visit <https://optique.dev/integrations/prompt>.
+
+
+Quick start
+-----------
+
+~~~~ typescript
+import { option } from "@optique/core/primitives";
+import { string } from "@optique/core/valueparser";
+import { createPromptAdapter } from "@optique/prompt";
+
+const prompt = createPromptAdapter<{ readonly message: string }>({
+  async execute<TValue>(config) {
+    const value = globalThis.prompt?.(config.message) ?? "";
+    return { success: true, value: value as TValue };
+  },
+});
+
+const name = prompt(option("--name", string()), {
+  message: "Name:",
+});
+~~~~
+
+
+License
+-------
+
+MIT License. See [LICENSE](../../LICENSE) for details.

package/dist/index.cjs

@@ -0,0 +1,292 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+const __optique_core_annotations = __toESM(require("@optique/core/annotations"));
+const __optique_core_extension = __toESM(require("@optique/core/extension"));
+const __optique_core_fluent = __toESM(require("@optique/core/fluent"));
+
+//#region src/index.ts
+function shouldDeferPrompt(parser, state, exec) {
+	return typeof parser.shouldDeferCompletion === "function" && parser.shouldDeferCompletion(state, exec) === true;
+}
+function deferredPromptResult(placeholderValue) {
+	if (placeholderValue == null || typeof placeholderValue !== "object") return {
+		success: true,
+		value: placeholderValue,
+		deferred: true
+	};
+	const isArray = Array.isArray(placeholderValue);
+	const keys = /* @__PURE__ */ new Map();
+	for (const key of Reflect.ownKeys(placeholderValue)) {
+		if (isArray && key === "length") continue;
+		keys.set(key, null);
+	}
+	return {
+		success: true,
+		value: placeholderValue,
+		deferred: true,
+		deferredKeys: keys
+	};
+}
+function withAnnotatedInnerState(sourceState, innerState, run) {
+	const annotations = (0, __optique_core_annotations.getAnnotations)(sourceState);
+	if (annotations == null || innerState == null || typeof innerState !== "object" || (0, __optique_core_annotations.getAnnotations)(innerState) != null) return run(innerState);
+	const inheritedState = (0, __optique_core_extension.inheritAnnotations)(sourceState, innerState);
+	if (inheritedState !== innerState) return run(inheritedState);
+	return run((0, __optique_core_extension.withAnnotationView)(innerState, annotations));
+}
+function hasSourceBindingMarker(state) {
+	return state != null && typeof state === "object" && "hasCliValue" in state && Object.getOwnPropertySymbols(state).length > 0;
+}
+function readDefaultValue(adapter, config) {
+	if (adapter.getDefaultValue != null) return adapter.getDefaultValue(config);
+	if (config != null && typeof config === "object" && "default" in config) return config.default;
+	return void 0;
+}
+/**
+* Creates a `prompt()` parser wrapper for a prompt library adapter.
+*
+* The generated wrapper tries the inner parser first.  If CLI tokens, source
+* bindings, or defaults satisfy the parser, the prompt is skipped.  Otherwise
+* the adapter runs during the real completion phase and provides a fallback
+* value.
+*
+* @typeParam TConfig Prompt configuration accepted by the adapter.
+* @param adapter Library-specific prompt executor.
+* @returns A `prompt(parser, config)` wrapper that always produces an async
+*          parser.
+* @since 1.2.0
+*/
+function createPromptAdapter(adapter) {
+	return function prompt(parser, config) {
+		const promptBindStateKey = Symbol("@optique/prompt/promptState");
+		function isPromptBindState(value) {
+			return value != null && typeof value === "object" && promptBindStateKey in value;
+		}
+		function shouldAttemptInnerCompletion(cliState, state) {
+			if (cliState == null) return false;
+			const cliStateHasAnnotations = (0, __optique_core_annotations.getAnnotations)(cliState) != null;
+			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;
+		}
+		function shouldCompleteFromSourceBinding(cliState, state) {
+			const cliStateIsInjectedAnnotationWrapper = cliState != null && typeof cliState === "object" && (0, __optique_core_extension.unwrapInjectedAnnotationState)(cliState) !== cliState;
+			const requiresSourceBindingForAnnotationWrapper = (0, __optique_core_extension.getTraits)(parser).requiresSourceBinding === true;
+			const hasNestedSourceBinding = hasSourceBindingMarker(cliState) || Array.isArray(cliState) && cliState.length === 1 && (hasSourceBindingMarker(cliState[0]) || cliState[0] != null && typeof cliState[0] === "object" && (0, __optique_core_annotations.getAnnotations)(cliState[0]) != null);
+			if (cliStateIsInjectedAnnotationWrapper && requiresSourceBindingForAnnotationWrapper) return hasNestedSourceBinding;
+			return shouldAttemptInnerCompletion(cliState, state) || hasNestedSourceBinding;
+		}
+		function executePrompt() {
+			return adapter.execute(config);
+		}
+		const promptedParser = {
+			mode: "async",
+			$valueType: parser.$valueType,
+			$stateType: parser.$stateType,
+			priority: parser.priority,
+			usage: parser.usage.length === 1 && parser.usage[0].type === "optional" ? parser.usage : [{
+				type: "optional",
+				terms: parser.usage
+			}],
+			leadingNames: parser.leadingNames,
+			acceptingAnyToken: parser.acceptingAnyToken,
+			shouldDeferCompletion(state) {
+				return !isPromptBindState(state) || !state.hasCliValue;
+			},
+			getSuggestRuntimeNodes(state, path) {
+				const innerState = isPromptBindState(state) ? state.cliState === void 0 ? parser.initialState : state.cliState : state;
+				return (0, __optique_core_extension.delegateSuggestNodes)(parser, promptedParser, state, path, innerState, "prepend");
+			},
+			initialState: {
+				[promptBindStateKey]: true,
+				hasCliValue: false
+			},
+			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 baseInnerContext = innerState !== context.state ? {
+					...context,
+					state: innerState
+				} : context;
+				const effectiveInnerState = annotations != null && innerState == null && (0, __optique_core_extension.getTraits)(parser).inheritsAnnotations === true ? (0, __optique_core_extension.injectAnnotations)(innerState, annotations) : innerState;
+				const processResult = (result$1) => {
+					if (result$1.success) {
+						const cliState = annotations != null && result$1.next.state != null && typeof result$1.next.state === "object" && (0, __optique_core_annotations.getAnnotations)(result$1.next.state) !== annotations ? (0, __optique_core_extension.injectAnnotations)(result$1.next.state, annotations) : result$1.next.state;
+						const cliConsumed = result$1.consumed.length > 0;
+						const nextState$1 = (0, __optique_core_extension.injectAnnotations)({
+							[promptBindStateKey]: true,
+							hasCliValue: cliConsumed,
+							cliState
+						}, annotations);
+						return {
+							success: true,
+							...result$1.provisional ? { provisional: true } : {},
+							next: {
+								...result$1.next,
+								state: nextState$1
+							},
+							consumed: result$1.consumed
+						};
+					}
+					if (result$1.consumed > 0) return result$1;
+					const nextState = (0, __optique_core_extension.injectAnnotations)({
+						[promptBindStateKey]: true,
+						hasCliValue: false
+					}, annotations);
+					return {
+						success: true,
+						next: {
+							...baseInnerContext,
+							state: nextState
+						},
+						consumed: []
+					};
+				};
+				const result = withAnnotatedInnerState(context.state, effectiveInnerState, (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, exec) => {
+				if (isPromptBindState(state) && state.hasCliValue) {
+					const r = withAnnotatedInnerState(state, state.cliState, (annotatedInnerState) => parser.complete(annotatedInnerState, exec));
+					if (r instanceof Promise) return r;
+					return Promise.resolve(r);
+				}
+				const isProbe = exec != null && exec.phase !== "complete";
+				const annotations = (0, __optique_core_annotations.getAnnotations)(state);
+				const innerInitialState = parser.initialState;
+				const shouldInheritInitialStateAnnotations = annotations != null && (innerInitialState == null || typeof innerInitialState === "object");
+				const effectiveInitialState = shouldInheritInitialStateAnnotations ? (0, __optique_core_extension.inheritAnnotations)(state, innerInitialState) : innerInitialState;
+				const readPlaceholder = () => {
+					try {
+						return "placeholder" in parser ? parser.placeholder : void 0;
+					} catch {
+						return void 0;
+					}
+				};
+				const finalizePrompt = () => {
+					const shouldDefer = withAnnotatedInnerState(state, effectiveInitialState, (annotatedInnerState) => shouldDeferPrompt(parser, annotatedInnerState, exec));
+					if (shouldDefer) return Promise.resolve(deferredPromptResult(readPlaceholder()));
+					if (isProbe) return Promise.resolve({
+						success: true,
+						value: readPlaceholder()
+					});
+					return executePrompt();
+				};
+				const hasDeferHook = typeof parser.shouldDeferCompletion === "function";
+				const decideFromParse = (parseResult) => {
+					const consumed = parseResult.success ? parseResult.consumed.length : 0;
+					const cliState = parseResult.success && consumed === 0 ? parseResult.next.state : void 0;
+					const cliStateIsInjected = cliState != null && typeof cliState === "object" && (0, __optique_core_extension.unwrapInjectedAnnotationState)(cliState) !== cliState;
+					const isSourceBinding = shouldCompleteFromSourceBinding(cliState, state);
+					if (!isSourceBinding) return finalizePrompt();
+					const completeState = parseResult.success ? parseResult.next.state : effectiveInitialState;
+					const innerR = parser.complete(completeState, exec);
+					const handleCompleteResult = (res) => {
+						if (res.success && res.value === void 0 && cliStateIsInjected) return finalizePrompt();
+						if (!res.success) return finalizePrompt();
+						return Promise.resolve(res);
+					};
+					if (innerR instanceof Promise) return innerR.then(handleCompleteResult);
+					return handleCompleteResult(innerR);
+				};
+				if (hasDeferHook) {
+					const innerR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedInnerState) => parser.complete(annotatedInnerState, exec));
+					const handleDeferHookResult = (res) => {
+						if (res.success && res.value === void 0) return finalizePrompt();
+						if (!res.success) return finalizePrompt();
+						return Promise.resolve(res);
+					};
+					if (innerR instanceof Promise) return innerR.then(handleDeferHookResult);
+					return handleDeferHookResult(innerR);
+				}
+				const simParseR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedState) => parser.parse({
+					buffer: [],
+					state: annotatedState,
+					optionsTerminated: false,
+					usage: parser.usage
+				}));
+				if (simParseR instanceof Promise) return simParseR.then(decideFromParse);
+				return decideFromParse(simParseR);
+			},
+			suggest: (context, prefix) => {
+				const innerState = isPromptBindState(context.state) ? context.state.cliState === void 0 ? parser.initialState : context.state.cliState : context.state;
+				const innerContext = innerState !== context.state ? {
+					...context,
+					state: innerState
+				} : context;
+				const innerResult = parser.suggest(innerContext, prefix);
+				return async function* () {
+					yield* innerResult;
+				}();
+			},
+			getDocFragments(state, upperDefaultValue) {
+				const defaultValue = upperDefaultValue ?? readDefaultValue(adapter, config);
+				return parser.getDocFragments(state, defaultValue);
+			}
+		};
+		(0, __optique_core_extension.defineTraits)(promptedParser, { inheritsAnnotations: true });
+		if ("placeholder" in parser) Object.defineProperty(promptedParser, "placeholder", {
+			get() {
+				try {
+					return parser.placeholder;
+				} catch {
+					return void 0;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+		if (typeof parser.normalizeValue === "function") Object.defineProperty(promptedParser, "normalizeValue", {
+			value: parser.normalizeValue.bind(parser),
+			configurable: true,
+			enumerable: false
+		});
+		const dependencyMetadata = (0, __optique_core_extension.mapSourceMetadata)(parser, (source) => ({
+			...source,
+			extractSourceValue: (state) => {
+				if (!isPromptBindState(state)) return source.extractSourceValue(state);
+				return source.extractSourceValue(state.cliState ?? state);
+			}
+		}));
+		if (dependencyMetadata != null) Object.defineProperty(promptedParser, "dependencyMetadata", {
+			value: dependencyMetadata,
+			configurable: true,
+			enumerable: false
+		});
+		return (0, __optique_core_fluent.fluent)(promptedParser);
+	};
+}
+
+//#endregion
+exports.createPromptAdapter = createPromptAdapter;

package/dist/index.d.cts

@@ -0,0 +1,58 @@
+import { FluentParser } from "@optique/core/fluent";
+import { Mode, Parser } from "@optique/core/parser";
+import { ValueParserResult } from "@optique/core/valueparser";
+
+//#region src/index.d.ts
+
+/**
+ * Prompt adapter used by {@link createPromptAdapter}.
+ *
+ * The adapter owns library-specific prompt execution and maps the result into
+ * Optique's value-parser result shape.  The shared parser wrapping behavior,
+ * including CLI priority, source bindings, deferred completion, suggestions,
+ * and usage metadata, is handled by *@optique/prompt*.
+ *
+ * @typeParam TConfig Prompt configuration accepted by the adapter.
+ * @since 1.2.0
+ */
+interface PromptAdapter<TConfig> {
+  /**
+   * Executes the library-specific prompt.
+   *
+   * @typeParam TValue Value type produced by the wrapped parser.
+   * @param config Prompt configuration supplied to the generated `prompt()`
+   *               wrapper.
+   * @returns The prompted value or a prompt failure.
+   * @throws Any unexpected prompt execution failure.
+   */
+  readonly execute: <TValue>(config: TConfig) => Promise<ValueParserResult<TValue>>;
+  /**
+   * Returns a default value from the prompt config for documentation purposes.
+   *
+   * If omitted, *@optique/prompt* reads a `default` property from object-shaped
+   * configs when present.
+   *
+   * @param config Prompt configuration supplied to the generated `prompt()`
+   *               wrapper.
+   * @returns A default value to pass to the wrapped parser's documentation
+   *          fragments.
+   */
+  readonly getDefaultValue?: (config: TConfig) => unknown;
+}
+/**
+ * Creates a `prompt()` parser wrapper for a prompt library adapter.
+ *
+ * The generated wrapper tries the inner parser first.  If CLI tokens, source
+ * bindings, or defaults satisfy the parser, the prompt is skipped.  Otherwise
+ * the adapter runs during the real completion phase and provides a fallback
+ * value.
+ *
+ * @typeParam TConfig Prompt configuration accepted by the adapter.
+ * @param adapter Library-specific prompt executor.
+ * @returns A `prompt(parser, config)` wrapper that always produces an async
+ *          parser.
+ * @since 1.2.0
+ */
+declare function createPromptAdapter<TConfig>(adapter: PromptAdapter<TConfig>): <M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: TConfig) => FluentParser<"async", TValue, TState>;
+//#endregion
+export { PromptAdapter, createPromptAdapter };

package/dist/index.d.ts

@@ -0,0 +1,58 @@
+import { FluentParser } from "@optique/core/fluent";
+import { Mode, Parser } from "@optique/core/parser";
+import { ValueParserResult } from "@optique/core/valueparser";
+
+//#region src/index.d.ts
+
+/**
+ * Prompt adapter used by {@link createPromptAdapter}.
+ *
+ * The adapter owns library-specific prompt execution and maps the result into
+ * Optique's value-parser result shape.  The shared parser wrapping behavior,
+ * including CLI priority, source bindings, deferred completion, suggestions,
+ * and usage metadata, is handled by *@optique/prompt*.
+ *
+ * @typeParam TConfig Prompt configuration accepted by the adapter.
+ * @since 1.2.0
+ */
+interface PromptAdapter<TConfig> {
+  /**
+   * Executes the library-specific prompt.
+   *
+   * @typeParam TValue Value type produced by the wrapped parser.
+   * @param config Prompt configuration supplied to the generated `prompt()`
+   *               wrapper.
+   * @returns The prompted value or a prompt failure.
+   * @throws Any unexpected prompt execution failure.
+   */
+  readonly execute: <TValue>(config: TConfig) => Promise<ValueParserResult<TValue>>;
+  /**
+   * Returns a default value from the prompt config for documentation purposes.
+   *
+   * If omitted, *@optique/prompt* reads a `default` property from object-shaped
+   * configs when present.
+   *
+   * @param config Prompt configuration supplied to the generated `prompt()`
+   *               wrapper.
+   * @returns A default value to pass to the wrapped parser's documentation
+   *          fragments.
+   */
+  readonly getDefaultValue?: (config: TConfig) => unknown;
+}
+/**
+ * Creates a `prompt()` parser wrapper for a prompt library adapter.
+ *
+ * The generated wrapper tries the inner parser first.  If CLI tokens, source
+ * bindings, or defaults satisfy the parser, the prompt is skipped.  Otherwise
+ * the adapter runs during the real completion phase and provides a fallback
+ * value.
+ *
+ * @typeParam TConfig Prompt configuration accepted by the adapter.
+ * @param adapter Library-specific prompt executor.
+ * @returns A `prompt(parser, config)` wrapper that always produces an async
+ *          parser.
+ * @since 1.2.0
+ */
+declare function createPromptAdapter<TConfig>(adapter: PromptAdapter<TConfig>): <M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: TConfig) => FluentParser<"async", TValue, TState>;
+//#endregion
+export { PromptAdapter, createPromptAdapter };

package/dist/index.js

@@ -0,0 +1,269 @@
+import { getAnnotations } from "@optique/core/annotations";
+import { defineTraits, delegateSuggestNodes, getTraits, inheritAnnotations, injectAnnotations, mapSourceMetadata, unwrapInjectedAnnotationState, withAnnotationView } from "@optique/core/extension";
+import { fluent } from "@optique/core/fluent";
+
+//#region src/index.ts
+function shouldDeferPrompt(parser, state, exec) {
+	return typeof parser.shouldDeferCompletion === "function" && parser.shouldDeferCompletion(state, exec) === true;
+}
+function deferredPromptResult(placeholderValue) {
+	if (placeholderValue == null || typeof placeholderValue !== "object") return {
+		success: true,
+		value: placeholderValue,
+		deferred: true
+	};
+	const isArray = Array.isArray(placeholderValue);
+	const keys = /* @__PURE__ */ new Map();
+	for (const key of Reflect.ownKeys(placeholderValue)) {
+		if (isArray && key === "length") continue;
+		keys.set(key, null);
+	}
+	return {
+		success: true,
+		value: placeholderValue,
+		deferred: true,
+		deferredKeys: keys
+	};
+}
+function withAnnotatedInnerState(sourceState, innerState, run) {
+	const annotations = getAnnotations(sourceState);
+	if (annotations == null || innerState == null || typeof innerState !== "object" || getAnnotations(innerState) != null) return run(innerState);
+	const inheritedState = inheritAnnotations(sourceState, innerState);
+	if (inheritedState !== innerState) return run(inheritedState);
+	return run(withAnnotationView(innerState, annotations));
+}
+function hasSourceBindingMarker(state) {
+	return state != null && typeof state === "object" && "hasCliValue" in state && Object.getOwnPropertySymbols(state).length > 0;
+}
+function readDefaultValue(adapter, config) {
+	if (adapter.getDefaultValue != null) return adapter.getDefaultValue(config);
+	if (config != null && typeof config === "object" && "default" in config) return config.default;
+	return void 0;
+}
+/**
+* Creates a `prompt()` parser wrapper for a prompt library adapter.
+*
+* The generated wrapper tries the inner parser first.  If CLI tokens, source
+* bindings, or defaults satisfy the parser, the prompt is skipped.  Otherwise
+* the adapter runs during the real completion phase and provides a fallback
+* value.
+*
+* @typeParam TConfig Prompt configuration accepted by the adapter.
+* @param adapter Library-specific prompt executor.
+* @returns A `prompt(parser, config)` wrapper that always produces an async
+*          parser.
+* @since 1.2.0
+*/
+function createPromptAdapter(adapter) {
+	return function prompt(parser, config) {
+		const promptBindStateKey = Symbol("@optique/prompt/promptState");
+		function isPromptBindState(value) {
+			return value != null && typeof value === "object" && promptBindStateKey in value;
+		}
+		function shouldAttemptInnerCompletion(cliState, state) {
+			if (cliState == null) return false;
+			const cliStateHasAnnotations = getAnnotations(cliState) != null;
+			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;
+		}
+		function shouldCompleteFromSourceBinding(cliState, state) {
+			const cliStateIsInjectedAnnotationWrapper = cliState != null && typeof cliState === "object" && unwrapInjectedAnnotationState(cliState) !== cliState;
+			const requiresSourceBindingForAnnotationWrapper = getTraits(parser).requiresSourceBinding === true;
+			const hasNestedSourceBinding = hasSourceBindingMarker(cliState) || Array.isArray(cliState) && cliState.length === 1 && (hasSourceBindingMarker(cliState[0]) || cliState[0] != null && typeof cliState[0] === "object" && getAnnotations(cliState[0]) != null);
+			if (cliStateIsInjectedAnnotationWrapper && requiresSourceBindingForAnnotationWrapper) return hasNestedSourceBinding;
+			return shouldAttemptInnerCompletion(cliState, state) || hasNestedSourceBinding;
+		}
+		function executePrompt() {
+			return adapter.execute(config);
+		}
+		const promptedParser = {
+			mode: "async",
+			$valueType: parser.$valueType,
+			$stateType: parser.$stateType,
+			priority: parser.priority,
+			usage: parser.usage.length === 1 && parser.usage[0].type === "optional" ? parser.usage : [{
+				type: "optional",
+				terms: parser.usage
+			}],
+			leadingNames: parser.leadingNames,
+			acceptingAnyToken: parser.acceptingAnyToken,
+			shouldDeferCompletion(state) {
+				return !isPromptBindState(state) || !state.hasCliValue;
+			},
+			getSuggestRuntimeNodes(state, path) {
+				const innerState = isPromptBindState(state) ? state.cliState === void 0 ? parser.initialState : state.cliState : state;
+				return delegateSuggestNodes(parser, promptedParser, state, path, innerState, "prepend");
+			},
+			initialState: {
+				[promptBindStateKey]: true,
+				hasCliValue: false
+			},
+			parse: (context) => {
+				const annotations = getAnnotations(context.state);
+				const innerState = isPromptBindState(context.state) ? context.state.hasCliValue ? context.state.cliState : parser.initialState : context.state;
+				const baseInnerContext = innerState !== context.state ? {
+					...context,
+					state: innerState
+				} : context;
+				const effectiveInnerState = annotations != null && innerState == null && getTraits(parser).inheritsAnnotations === true ? injectAnnotations(innerState, annotations) : innerState;
+				const processResult = (result$1) => {
+					if (result$1.success) {
+						const cliState = annotations != null && result$1.next.state != null && typeof result$1.next.state === "object" && getAnnotations(result$1.next.state) !== annotations ? injectAnnotations(result$1.next.state, annotations) : result$1.next.state;
+						const cliConsumed = result$1.consumed.length > 0;
+						const nextState$1 = injectAnnotations({
+							[promptBindStateKey]: true,
+							hasCliValue: cliConsumed,
+							cliState
+						}, annotations);
+						return {
+							success: true,
+							...result$1.provisional ? { provisional: true } : {},
+							next: {
+								...result$1.next,
+								state: nextState$1
+							},
+							consumed: result$1.consumed
+						};
+					}
+					if (result$1.consumed > 0) return result$1;
+					const nextState = injectAnnotations({
+						[promptBindStateKey]: true,
+						hasCliValue: false
+					}, annotations);
+					return {
+						success: true,
+						next: {
+							...baseInnerContext,
+							state: nextState
+						},
+						consumed: []
+					};
+				};
+				const result = withAnnotatedInnerState(context.state, effectiveInnerState, (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, exec) => {
+				if (isPromptBindState(state) && state.hasCliValue) {
+					const r = withAnnotatedInnerState(state, state.cliState, (annotatedInnerState) => parser.complete(annotatedInnerState, exec));
+					if (r instanceof Promise) return r;
+					return Promise.resolve(r);
+				}
+				const isProbe = exec != null && exec.phase !== "complete";
+				const annotations = getAnnotations(state);
+				const innerInitialState = parser.initialState;
+				const shouldInheritInitialStateAnnotations = annotations != null && (innerInitialState == null || typeof innerInitialState === "object");
+				const effectiveInitialState = shouldInheritInitialStateAnnotations ? inheritAnnotations(state, innerInitialState) : innerInitialState;
+				const readPlaceholder = () => {
+					try {
+						return "placeholder" in parser ? parser.placeholder : void 0;
+					} catch {
+						return void 0;
+					}
+				};
+				const finalizePrompt = () => {
+					const shouldDefer = withAnnotatedInnerState(state, effectiveInitialState, (annotatedInnerState) => shouldDeferPrompt(parser, annotatedInnerState, exec));
+					if (shouldDefer) return Promise.resolve(deferredPromptResult(readPlaceholder()));
+					if (isProbe) return Promise.resolve({
+						success: true,
+						value: readPlaceholder()
+					});
+					return executePrompt();
+				};
+				const hasDeferHook = typeof parser.shouldDeferCompletion === "function";
+				const decideFromParse = (parseResult) => {
+					const consumed = parseResult.success ? parseResult.consumed.length : 0;
+					const cliState = parseResult.success && consumed === 0 ? parseResult.next.state : void 0;
+					const cliStateIsInjected = cliState != null && typeof cliState === "object" && unwrapInjectedAnnotationState(cliState) !== cliState;
+					const isSourceBinding = shouldCompleteFromSourceBinding(cliState, state);
+					if (!isSourceBinding) return finalizePrompt();
+					const completeState = parseResult.success ? parseResult.next.state : effectiveInitialState;
+					const innerR = parser.complete(completeState, exec);
+					const handleCompleteResult = (res) => {
+						if (res.success && res.value === void 0 && cliStateIsInjected) return finalizePrompt();
+						if (!res.success) return finalizePrompt();
+						return Promise.resolve(res);
+					};
+					if (innerR instanceof Promise) return innerR.then(handleCompleteResult);
+					return handleCompleteResult(innerR);
+				};
+				if (hasDeferHook) {
+					const innerR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedInnerState) => parser.complete(annotatedInnerState, exec));
+					const handleDeferHookResult = (res) => {
+						if (res.success && res.value === void 0) return finalizePrompt();
+						if (!res.success) return finalizePrompt();
+						return Promise.resolve(res);
+					};
+					if (innerR instanceof Promise) return innerR.then(handleDeferHookResult);
+					return handleDeferHookResult(innerR);
+				}
+				const simParseR = withAnnotatedInnerState(state, effectiveInitialState, (annotatedState) => parser.parse({
+					buffer: [],
+					state: annotatedState,
+					optionsTerminated: false,
+					usage: parser.usage
+				}));
+				if (simParseR instanceof Promise) return simParseR.then(decideFromParse);
+				return decideFromParse(simParseR);
+			},
+			suggest: (context, prefix) => {
+				const innerState = isPromptBindState(context.state) ? context.state.cliState === void 0 ? parser.initialState : context.state.cliState : context.state;
+				const innerContext = innerState !== context.state ? {
+					...context,
+					state: innerState
+				} : context;
+				const innerResult = parser.suggest(innerContext, prefix);
+				return async function* () {
+					yield* innerResult;
+				}();
+			},
+			getDocFragments(state, upperDefaultValue) {
+				const defaultValue = upperDefaultValue ?? readDefaultValue(adapter, config);
+				return parser.getDocFragments(state, defaultValue);
+			}
+		};
+		defineTraits(promptedParser, { inheritsAnnotations: true });
+		if ("placeholder" in parser) Object.defineProperty(promptedParser, "placeholder", {
+			get() {
+				try {
+					return parser.placeholder;
+				} catch {
+					return void 0;
+				}
+			},
+			configurable: true,
+			enumerable: false
+		});
+		if (typeof parser.normalizeValue === "function") Object.defineProperty(promptedParser, "normalizeValue", {
+			value: parser.normalizeValue.bind(parser),
+			configurable: true,
+			enumerable: false
+		});
+		const dependencyMetadata = mapSourceMetadata(parser, (source) => ({
+			...source,
+			extractSourceValue: (state) => {
+				if (!isPromptBindState(state)) return source.extractSourceValue(state);
+				return source.extractSourceValue(state.cliState ?? state);
+			}
+		}));
+		if (dependencyMetadata != null) Object.defineProperty(promptedParser, "dependencyMetadata", {
+			value: dependencyMetadata,
+			configurable: true,
+			enumerable: false
+		});
+		return fluent(promptedParser);
+	};
+}
+
+//#endregion
+export { createPromptAdapter };

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@optique/prompt",
+  "version": "1.2.0-dev.0",
+  "description": "Generic prompt adapter support for Optique",
+  "keywords": [
+    "CLI",
+    "command-line",
+    "commandline",
+    "parser",
+    "prompt",
+    "interactive"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "Hong Minhee",
+    "email": "hong@minhee.org",
+    "url": "https://hongminhee.org/"
+  },
+  "homepage": "https://optique.dev/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dahlia/optique.git",
+    "directory": "packages/prompt/"
+  },
+  "bugs": {
+    "url": "https://github.com/dahlia/optique/issues"
+  },
+  "funding": [
+    "https://github.com/sponsors/dahlia"
+  ],
+  "engines": {
+    "node": ">=20.0.0",
+    "bun": ">=1.2.0",
+    "deno": ">=2.3.0"
+  },
+  "files": [
+    "dist/",
+    "package.json",
+    "README.md"
+  ],
+  "type": "module",
+  "module": "./dist/index.js",
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "imports": {
+    "#src/*.ts": {
+      "node": "./dist/*.js",
+      "default": "./src/*.ts"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@optique/core": "1.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "fast-check": "^4.7.0",
+    "tsdown": "^0.13.0",
+    "typescript": "^5.8.3",
+    "@optique/config": "1.2.0",
+    "@optique/run": "1.2.0",
+    "@optique/env": "1.2.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "node --test",
+    "test:bun": "bun test",
+    "test:deno": "deno test",
+    "test-all": "tsdown && node --test && bun test && deno test"
+  }
+}