@optique/inquirer 1.0.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/dist/index.cjs

@@ -0,0 +1,272 @@
+//#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 __inquirer_prompts = __toESM(require("@inquirer/prompts"));
+const __optique_core_annotations = __toESM(require("@optique/core/annotations"));
+const __optique_core_message = __toESM(require("@optique/core/message"));
+
+//#region src/index.ts
+/**
+* Wraps a parser with an interactive Inquirer.js prompt fallback.
+*
+* When the inner parser finds a value in the CLI arguments (consumed tokens),
+* that value is used directly. When no CLI value is found, an interactive
+* prompt is shown to the user.
+*
+* The returned parser always has `$mode: "async"` because Inquirer.js prompts
+* are inherently asynchronous.
+*
+* Example:
+*
+* ```typescript
+* import { option } from "@optique/core/primitives";
+* import { string } from "@optique/core/valueparser";
+* import { prompt } from "@optique/inquirer";
+*
+* const nameParser = prompt(option("--name", string()), {
+*   type: "input",
+*   message: "Enter your name:",
+* });
+* ```
+*
+* @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.
+* @since 1.0.0
+*/
+function prompt(parser, config) {
+	const promptBindStateKey = Symbol("@optique/inquirer/promptState");
+	function isPromptBindState(value) {
+		return value != null && typeof value === "object" && promptBindStateKey in value;
+	}
+	const cfg = config;
+	const PromptBindInitialStateClass = class {
+		[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 {
+					success: false,
+					error: __optique_core_message.message`No number provided.`
+				};
+				return {
+					success: true,
+					value: numResult
+				};
+			}
+			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)
+				})
+			};
+		}
+	}
+	return {
+		$mode: "async",
+		$valueType: parser.$valueType,
+		$stateType: parser.$stateType,
+		priority: parser.priority,
+		usage: [{
+			type: "optional",
+			terms: parser.usage
+		}],
+		initialState: promptBindInitialState,
+		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 ? {
+				...context,
+				state: innerState
+			} : context;
+			const processResult = (result$1) => {
+				if (result$1.success) {
+					const cliConsumed = result$1.consumed.length > 0;
+					const nextState$1 = {
+						[promptBindStateKey]: true,
+						hasCliValue: cliConsumed,
+						cliState: result$1.next.state,
+						...annotations != null ? { [__optique_core_annotations.annotationKey]: annotations } : {}
+					};
+					return {
+						success: true,
+						next: {
+							...result$1.next,
+							state: nextState$1
+						},
+						consumed: result$1.consumed
+					};
+				}
+				if (result$1.consumed > 0) return result$1;
+				const nextState = {
+					[promptBindStateKey]: true,
+					hasCliValue: false,
+					...annotations != null ? { [__optique_core_annotations.annotationKey]: annotations } : {}
+				};
+				return {
+					success: true,
+					next: {
+						...innerContext,
+						state: nextState
+					},
+					consumed: []
+				};
+			};
+			const result = 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);
+				if (r instanceof Promise) return r;
+				return Promise.resolve(r);
+			}
+			if (state === promptBindInitialState) {
+				if (promptCache !== null) {
+					const cached = promptCache;
+					promptCache = null;
+					return cached;
+				}
+				promptCache = executePrompt();
+				return promptCache;
+			}
+			return executePrompt();
+		},
+		suggest: (context, prefix) => {
+			const innerState = isPromptBindState(context.state) ? context.state.hasCliValue ? context.state.cliState : parser.initialState : 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 configDefault = "default" in cfg ? cfg.default : void 0;
+			const defaultValue = upperDefaultValue ?? configDefault;
+			return parser.getDocFragments(state, defaultValue);
+		}
+	};
+}
+/** Normalize choices to the format Inquirer.js expects. */
+function normalizeChoices(choices) {
+	return choices.map((c) => {
+		if (typeof c === "string") return {
+			value: c,
+			name: c
+		};
+		if (c instanceof __inquirer_prompts.Separator) return c;
+		return {
+			value: c.value,
+			...c.name !== void 0 ? { name: c.name } : {},
+			..."description" in c && c.description !== void 0 ? { description: c.description } : {},
+			..."short" in c && c.short !== void 0 ? { short: c.short } : {},
+			..."disabled" in c && c.disabled !== void 0 ? { disabled: c.disabled } : {}
+		};
+	});
+}
+
+//#endregion
+exports.Separator = __inquirer_prompts.Separator;
+exports.prompt = prompt;

package/dist/index.d.cts

@@ -0,0 +1,354 @@
+import { Separator } from "@inquirer/prompts";
+import { Mode, Parser } from "@optique/core/parser";
+
+//#region src/index.d.ts
+
+/**
+ * A choice item for selection-type prompts (`select`, `rawlist`, `expand`,
+ * `checkbox`).
+ *
+ * @since 1.0.0
+ */
+interface Choice {
+  /**
+   * The value returned when this choice is selected.
+   */
+  readonly value: string;
+  /**
+   * Display name shown in the prompt. Defaults to `value`.
+   */
+  readonly name?: string;
+  /**
+   * Additional description shown when this choice is highlighted.
+   */
+  readonly description?: string;
+  /**
+   * Short text shown after selection. Defaults to `name`.
+   */
+  readonly short?: string;
+  /**
+   * If truthy, the choice cannot be selected. A string explains why.
+   */
+  readonly disabled?: boolean | string;
+}
+/**
+ * A choice item for the `expand` prompt type.
+ *
+ * Unlike {@link Choice}, this requires a `key` field (a single lowercase
+ * alphanumeric character) that the user presses to select the item.
+ *
+ * @since 1.0.0
+ */
+interface ExpandChoice {
+  /**
+   * The value returned when this choice is selected.
+   */
+  readonly value: string;
+  /**
+   * Display name shown in the prompt. Defaults to `value`.
+   */
+  readonly name?: string;
+  /**
+   * Single lowercase alphanumeric character used as the keyboard shortcut.
+   */
+  readonly key: string;
+}
+/**
+ * Configuration for a `confirm` prompt (boolean value).
+ *
+ * @since 1.0.0
+ */
+interface ConfirmConfig {
+  readonly type: "confirm";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Default answer when the user just presses Enter.
+   */
+  readonly default?: boolean;
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<boolean>;
+}
+/**
+ * Configuration for a `number` prompt.
+ *
+ * @since 1.0.0
+ */
+interface NumberPromptConfig {
+  readonly type: "number";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Default number shown to the user.
+   */
+  readonly default?: number;
+  /**
+   * Minimum accepted value.
+   */
+  readonly min?: number;
+  /**
+   * Maximum accepted value.
+   */
+  readonly max?: number;
+  /**
+   * Granularity of valid values. Use `"any"` for arbitrary decimals.
+   */
+  readonly step?: number | "any";
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   *
+   * Return `undefined` to simulate the user leaving the field empty (which
+   * results in a parse failure).
+   */
+  readonly prompter?: () => Promise<number | undefined>;
+}
+/**
+ * Configuration for an `input` prompt (free-text string).
+ *
+ * @since 1.0.0
+ */
+interface InputConfig {
+  readonly type: "input";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Default text pre-filled in the prompt.
+   */
+  readonly default?: string;
+  /**
+   * Validation function called when the user submits.
+   * Return `true` or a string error message.
+   */
+  readonly validate?: (value: string) => boolean | string | Promise<boolean | string>;
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<string>;
+}
+/**
+ * Configuration for a `password` prompt (masked input).
+ *
+ * @since 1.0.0
+ */
+interface PasswordConfig {
+  readonly type: "password";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * If `true`, show `*` characters for each keystroke.
+   * If `false` or omitted, input is invisible.
+   */
+  readonly mask?: boolean;
+  /**
+   * Validation function called when the user submits.
+   * Return `true` or a string error message.
+   */
+  readonly validate?: (value: string) => boolean | string | Promise<boolean | string>;
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<string>;
+}
+/**
+ * Configuration for an `editor` prompt (external editor).
+ *
+ * Opens the user's `$VISUAL` or `$EDITOR` for multi-line text input.
+ *
+ * @since 1.0.0
+ */
+interface EditorConfig {
+  readonly type: "editor";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Default content pre-filled in the editor.
+   */
+  readonly default?: string;
+  /**
+   * Validation function called when the editor is closed.
+   * Return `true` or a string error message.
+   */
+  readonly validate?: (value: string) => boolean | string | Promise<boolean | string>;
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<string>;
+}
+/**
+ * Configuration for a `select` prompt (arrow-key single-select).
+ *
+ * @since 1.0.0
+ */
+interface SelectConfig {
+  readonly type: "select";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Available choices. Plain strings and {@link Choice} objects can be mixed.
+   * Use `new Separator(...)` for visual dividers.
+   */
+  readonly choices: readonly (string | Choice | Separator)[];
+  /**
+   * Initially highlighted choice value.
+   */
+  readonly default?: string;
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<string>;
+}
+/**
+ * Configuration for a `rawlist` prompt (numbered list).
+ *
+ * @since 1.0.0
+ */
+interface RawlistConfig {
+  readonly type: "rawlist";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Available choices. Plain strings and {@link Choice} objects can be mixed.
+   */
+  readonly choices: readonly (string | Choice)[];
+  /**
+   * Pre-selected choice value.
+   */
+  readonly default?: string;
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<string>;
+}
+/**
+ * Configuration for an `expand` prompt (keyboard shortcut single-select).
+ *
+ * @since 1.0.0
+ */
+interface ExpandConfig {
+  readonly type: "expand";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Available choices. Each choice requires a `key` field.
+   */
+  readonly choices: readonly ExpandChoice[];
+  /**
+   * Default choice key.
+   */
+  readonly default?: string;
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<string>;
+}
+/**
+ * Configuration for a `checkbox` prompt (multi-select).
+ *
+ * Use with parsers that return `string[]`, typically via
+ * `multiple(option(...))`.
+ *
+ * @since 1.0.0
+ */
+interface CheckboxConfig {
+  readonly type: "checkbox";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Available choices. Plain strings and {@link Choice} objects can be mixed.
+   * Use `new Separator(...)` for visual dividers.
+   */
+  readonly choices: readonly (string | Choice | Separator)[];
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<readonly string[]>;
+}
+/**
+ * A union of all string-input prompt configurations.
+ *
+ * @since 1.0.0
+ */
+type StringPromptConfig = InputConfig | PasswordConfig | EditorConfig | SelectConfig | RawlistConfig | ExpandConfig;
+/**
+ * Type-safe prompt configuration for a given parser value type `T`.
+ *
+ * The available prompt types are constrained by the expected value type:
+ *
+ *  - `boolean` or `boolean | undefined` → {@link ConfirmConfig}
+ *  - `number` or `number | undefined` → {@link NumberPromptConfig}
+ *  - `string` or `string | undefined` → {@link StringPromptConfig}
+ *  - `readonly string[]` → {@link CheckboxConfig}
+ *
+ * @since 1.0.0
+ */
+type PromptConfig<T> = BasePromptConfig<Exclude<T, null | undefined>>;
+type BasePromptConfig<T> = T extends boolean ? ConfirmConfig : T extends number ? NumberPromptConfig : T extends string ? StringPromptConfig : T extends readonly string[] ? CheckboxConfig : never;
+/**
+ * Wraps a parser with an interactive Inquirer.js prompt fallback.
+ *
+ * When the inner parser finds a value in the CLI arguments (consumed tokens),
+ * that value is used directly. When no CLI value is found, an interactive
+ * prompt is shown to the user.
+ *
+ * The returned parser always has `$mode: "async"` because Inquirer.js prompts
+ * are inherently asynchronous.
+ *
+ * Example:
+ *
+ * ```typescript
+ * import { option } from "@optique/core/primitives";
+ * import { string } from "@optique/core/valueparser";
+ * import { prompt } from "@optique/inquirer";
+ *
+ * const nameParser = prompt(option("--name", string()), {
+ *   type: "input",
+ *   message: "Enter your name:",
+ * });
+ * ```
+ *
+ * @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.
+ * @since 1.0.0
+ */
+declare function prompt<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: PromptConfig<TValue>): Parser<"async", TValue, TState>;
+//#endregion
+export { CheckboxConfig, Choice, ConfirmConfig, EditorConfig, ExpandChoice, ExpandConfig, InputConfig, NumberPromptConfig, PasswordConfig, PromptConfig, RawlistConfig, SelectConfig, Separator, StringPromptConfig, prompt };

package/dist/index.d.ts

@@ -0,0 +1,354 @@
+import { Separator } from "@inquirer/prompts";
+import { Mode, Parser } from "@optique/core/parser";
+
+//#region src/index.d.ts
+
+/**
+ * A choice item for selection-type prompts (`select`, `rawlist`, `expand`,
+ * `checkbox`).
+ *
+ * @since 1.0.0
+ */
+interface Choice {
+  /**
+   * The value returned when this choice is selected.
+   */
+  readonly value: string;
+  /**
+   * Display name shown in the prompt. Defaults to `value`.
+   */
+  readonly name?: string;
+  /**
+   * Additional description shown when this choice is highlighted.
+   */
+  readonly description?: string;
+  /**
+   * Short text shown after selection. Defaults to `name`.
+   */
+  readonly short?: string;
+  /**
+   * If truthy, the choice cannot be selected. A string explains why.
+   */
+  readonly disabled?: boolean | string;
+}
+/**
+ * A choice item for the `expand` prompt type.
+ *
+ * Unlike {@link Choice}, this requires a `key` field (a single lowercase
+ * alphanumeric character) that the user presses to select the item.
+ *
+ * @since 1.0.0
+ */
+interface ExpandChoice {
+  /**
+   * The value returned when this choice is selected.
+   */
+  readonly value: string;
+  /**
+   * Display name shown in the prompt. Defaults to `value`.
+   */
+  readonly name?: string;
+  /**
+   * Single lowercase alphanumeric character used as the keyboard shortcut.
+   */
+  readonly key: string;
+}
+/**
+ * Configuration for a `confirm` prompt (boolean value).
+ *
+ * @since 1.0.0
+ */
+interface ConfirmConfig {
+  readonly type: "confirm";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Default answer when the user just presses Enter.
+   */
+  readonly default?: boolean;
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<boolean>;
+}
+/**
+ * Configuration for a `number` prompt.
+ *
+ * @since 1.0.0
+ */
+interface NumberPromptConfig {
+  readonly type: "number";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Default number shown to the user.
+   */
+  readonly default?: number;
+  /**
+   * Minimum accepted value.
+   */
+  readonly min?: number;
+  /**
+   * Maximum accepted value.
+   */
+  readonly max?: number;
+  /**
+   * Granularity of valid values. Use `"any"` for arbitrary decimals.
+   */
+  readonly step?: number | "any";
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   *
+   * Return `undefined` to simulate the user leaving the field empty (which
+   * results in a parse failure).
+   */
+  readonly prompter?: () => Promise<number | undefined>;
+}
+/**
+ * Configuration for an `input` prompt (free-text string).
+ *
+ * @since 1.0.0
+ */
+interface InputConfig {
+  readonly type: "input";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Default text pre-filled in the prompt.
+   */
+  readonly default?: string;
+  /**
+   * Validation function called when the user submits.
+   * Return `true` or a string error message.
+   */
+  readonly validate?: (value: string) => boolean | string | Promise<boolean | string>;
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<string>;
+}
+/**
+ * Configuration for a `password` prompt (masked input).
+ *
+ * @since 1.0.0
+ */
+interface PasswordConfig {
+  readonly type: "password";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * If `true`, show `*` characters for each keystroke.
+   * If `false` or omitted, input is invisible.
+   */
+  readonly mask?: boolean;
+  /**
+   * Validation function called when the user submits.
+   * Return `true` or a string error message.
+   */
+  readonly validate?: (value: string) => boolean | string | Promise<boolean | string>;
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<string>;
+}
+/**
+ * Configuration for an `editor` prompt (external editor).
+ *
+ * Opens the user's `$VISUAL` or `$EDITOR` for multi-line text input.
+ *
+ * @since 1.0.0
+ */
+interface EditorConfig {
+  readonly type: "editor";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Default content pre-filled in the editor.
+   */
+  readonly default?: string;
+  /**
+   * Validation function called when the editor is closed.
+   * Return `true` or a string error message.
+   */
+  readonly validate?: (value: string) => boolean | string | Promise<boolean | string>;
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<string>;
+}
+/**
+ * Configuration for a `select` prompt (arrow-key single-select).
+ *
+ * @since 1.0.0
+ */
+interface SelectConfig {
+  readonly type: "select";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Available choices. Plain strings and {@link Choice} objects can be mixed.
+   * Use `new Separator(...)` for visual dividers.
+   */
+  readonly choices: readonly (string | Choice | Separator)[];
+  /**
+   * Initially highlighted choice value.
+   */
+  readonly default?: string;
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<string>;
+}
+/**
+ * Configuration for a `rawlist` prompt (numbered list).
+ *
+ * @since 1.0.0
+ */
+interface RawlistConfig {
+  readonly type: "rawlist";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Available choices. Plain strings and {@link Choice} objects can be mixed.
+   */
+  readonly choices: readonly (string | Choice)[];
+  /**
+   * Pre-selected choice value.
+   */
+  readonly default?: string;
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<string>;
+}
+/**
+ * Configuration for an `expand` prompt (keyboard shortcut single-select).
+ *
+ * @since 1.0.0
+ */
+interface ExpandConfig {
+  readonly type: "expand";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Available choices. Each choice requires a `key` field.
+   */
+  readonly choices: readonly ExpandChoice[];
+  /**
+   * Default choice key.
+   */
+  readonly default?: string;
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<string>;
+}
+/**
+ * Configuration for a `checkbox` prompt (multi-select).
+ *
+ * Use with parsers that return `string[]`, typically via
+ * `multiple(option(...))`.
+ *
+ * @since 1.0.0
+ */
+interface CheckboxConfig {
+  readonly type: "checkbox";
+  /**
+   * The question to display to the user.
+   */
+  readonly message: string;
+  /**
+   * Available choices. Plain strings and {@link Choice} objects can be mixed.
+   * Use `new Separator(...)` for visual dividers.
+   */
+  readonly choices: readonly (string | Choice | Separator)[];
+  /**
+   * Override the prompt execution. When provided, this function is called
+   * instead of launching an interactive Inquirer.js prompt. Useful for
+   * testing.
+   */
+  readonly prompter?: () => Promise<readonly string[]>;
+}
+/**
+ * A union of all string-input prompt configurations.
+ *
+ * @since 1.0.0
+ */
+type StringPromptConfig = InputConfig | PasswordConfig | EditorConfig | SelectConfig | RawlistConfig | ExpandConfig;
+/**
+ * Type-safe prompt configuration for a given parser value type `T`.
+ *
+ * The available prompt types are constrained by the expected value type:
+ *
+ *  - `boolean` or `boolean | undefined` → {@link ConfirmConfig}
+ *  - `number` or `number | undefined` → {@link NumberPromptConfig}
+ *  - `string` or `string | undefined` → {@link StringPromptConfig}
+ *  - `readonly string[]` → {@link CheckboxConfig}
+ *
+ * @since 1.0.0
+ */
+type PromptConfig<T> = BasePromptConfig<Exclude<T, null | undefined>>;
+type BasePromptConfig<T> = T extends boolean ? ConfirmConfig : T extends number ? NumberPromptConfig : T extends string ? StringPromptConfig : T extends readonly string[] ? CheckboxConfig : never;
+/**
+ * Wraps a parser with an interactive Inquirer.js prompt fallback.
+ *
+ * When the inner parser finds a value in the CLI arguments (consumed tokens),
+ * that value is used directly. When no CLI value is found, an interactive
+ * prompt is shown to the user.
+ *
+ * The returned parser always has `$mode: "async"` because Inquirer.js prompts
+ * are inherently asynchronous.
+ *
+ * Example:
+ *
+ * ```typescript
+ * import { option } from "@optique/core/primitives";
+ * import { string } from "@optique/core/valueparser";
+ * import { prompt } from "@optique/inquirer";
+ *
+ * const nameParser = prompt(option("--name", string()), {
+ *   type: "input",
+ *   message: "Enter your name:",
+ * });
+ * ```
+ *
+ * @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.
+ * @since 1.0.0
+ */
+declare function prompt<M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: PromptConfig<TValue>): Parser<"async", TValue, TState>;
+//#endregion
+export { CheckboxConfig, Choice, ConfirmConfig, EditorConfig, ExpandChoice, ExpandConfig, InputConfig, NumberPromptConfig, PasswordConfig, PromptConfig, RawlistConfig, SelectConfig, Separator, StringPromptConfig, prompt };

package/dist/index.js

@@ -0,0 +1,248 @@
+import { Separator, checkbox, confirm, editor, expand, input, number, password, rawlist, select } from "@inquirer/prompts";
+import { annotationKey, getAnnotations } from "@optique/core/annotations";
+import { message } from "@optique/core/message";
+
+//#region src/index.ts
+/**
+* Wraps a parser with an interactive Inquirer.js prompt fallback.
+*
+* When the inner parser finds a value in the CLI arguments (consumed tokens),
+* that value is used directly. When no CLI value is found, an interactive
+* prompt is shown to the user.
+*
+* The returned parser always has `$mode: "async"` because Inquirer.js prompts
+* are inherently asynchronous.
+*
+* Example:
+*
+* ```typescript
+* import { option } from "@optique/core/primitives";
+* import { string } from "@optique/core/valueparser";
+* import { prompt } from "@optique/inquirer";
+*
+* const nameParser = prompt(option("--name", string()), {
+*   type: "input",
+*   message: "Enter your name:",
+* });
+* ```
+*
+* @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.
+* @since 1.0.0
+*/
+function prompt(parser, config) {
+	const promptBindStateKey = Symbol("@optique/inquirer/promptState");
+	function isPromptBindState(value) {
+		return value != null && typeof value === "object" && promptBindStateKey in value;
+	}
+	const cfg = config;
+	const PromptBindInitialStateClass = class {
+		[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 {
+					success: false,
+					error: message`No number provided.`
+				};
+				return {
+					success: true,
+					value: numResult
+				};
+			}
+			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)
+				})
+			};
+		}
+	}
+	return {
+		$mode: "async",
+		$valueType: parser.$valueType,
+		$stateType: parser.$stateType,
+		priority: parser.priority,
+		usage: [{
+			type: "optional",
+			terms: parser.usage
+		}],
+		initialState: promptBindInitialState,
+		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 ? {
+				...context,
+				state: innerState
+			} : context;
+			const processResult = (result$1) => {
+				if (result$1.success) {
+					const cliConsumed = result$1.consumed.length > 0;
+					const nextState$1 = {
+						[promptBindStateKey]: true,
+						hasCliValue: cliConsumed,
+						cliState: result$1.next.state,
+						...annotations != null ? { [annotationKey]: annotations } : {}
+					};
+					return {
+						success: true,
+						next: {
+							...result$1.next,
+							state: nextState$1
+						},
+						consumed: result$1.consumed
+					};
+				}
+				if (result$1.consumed > 0) return result$1;
+				const nextState = {
+					[promptBindStateKey]: true,
+					hasCliValue: false,
+					...annotations != null ? { [annotationKey]: annotations } : {}
+				};
+				return {
+					success: true,
+					next: {
+						...innerContext,
+						state: nextState
+					},
+					consumed: []
+				};
+			};
+			const result = 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);
+				if (r instanceof Promise) return r;
+				return Promise.resolve(r);
+			}
+			if (state === promptBindInitialState) {
+				if (promptCache !== null) {
+					const cached = promptCache;
+					promptCache = null;
+					return cached;
+				}
+				promptCache = executePrompt();
+				return promptCache;
+			}
+			return executePrompt();
+		},
+		suggest: (context, prefix) => {
+			const innerState = isPromptBindState(context.state) ? context.state.hasCliValue ? context.state.cliState : parser.initialState : 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 configDefault = "default" in cfg ? cfg.default : void 0;
+			const defaultValue = upperDefaultValue ?? configDefault;
+			return parser.getDocFragments(state, defaultValue);
+		}
+	};
+}
+/** Normalize choices to the format Inquirer.js expects. */
+function normalizeChoices(choices) {
+	return choices.map((c) => {
+		if (typeof c === "string") return {
+			value: c,
+			name: c
+		};
+		if (c instanceof Separator) return c;
+		return {
+			value: c.value,
+			...c.name !== void 0 ? { name: c.name } : {},
+			..."description" in c && c.description !== void 0 ? { description: c.description } : {},
+			..."short" in c && c.short !== void 0 ? { short: c.short } : {},
+			..."disabled" in c && c.disabled !== void 0 ? { disabled: c.disabled } : {}
+		};
+	});
+}
+
+//#endregion
+export { Separator, prompt };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "@optique/inquirer",
+  "version": "1.0.0-dev.0",
+  "description": "Interactive prompt support for Optique via Inquirer.js",
+  "keywords": [
+    "CLI",
+    "command-line",
+    "commandline",
+    "parser",
+    "prompt",
+    "interactive",
+    "inquirer"
+  ],
+  "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/inquirer/"
+  },
+  "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"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@inquirer/prompts": "^8.3.0",
+    "@optique/core": "1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.19.9",
+    "tsdown": "^0.13.0",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepublish": "tsdown",
+    "test": "node --experimental-transform-types --test",
+    "test:bun": "bun test",
+    "test:deno": "deno test",
+    "test-all": "tsdown && node --experimental-transform-types --test && bun test && deno test"
+  }
+}