@optique/prompt 1.3.0-dev.2456 → 1.3.0-dev.2464

package/README.md

@@ -27,7 +27,8 @@ Documentation
 
 For full documentation, visit the [prompt integration docs].
 The guide covers dependency-derived configurations with
-`derivePromptConfig()` as well as adapter construction.
+`derivePromptConfig()`, shared validation and retries, abort signals, and
+adapter construction.
 
 [prompt integration docs]: https://optique.dev/integrations/prompt
 

package/dist/index.cjs

@@ -179,6 +179,40 @@ function unwrapCompleteResult(result) {
 		value: (0, __optique_core_extension.unwrapInjectedAnnotationState)(result.value)
 	};
 }
+function throwIfPromptAborted(signal) {
+	if (signal?.aborted === true) throw signal.reason;
+}
+function racePromptWorkWithAbort(signal, work) {
+	if (signal == null) try {
+		return work();
+	} catch (error) {
+		return Promise.reject(error);
+	}
+	if (signal.aborted) return Promise.reject(signal.reason);
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			signal.removeEventListener("abort", onAbort);
+			reject(signal.reason);
+		};
+		const cleanup = () => signal.removeEventListener("abort", onAbort);
+		signal.addEventListener("abort", onAbort, { once: true });
+		let outcome;
+		try {
+			outcome = work();
+		} catch (error) {
+			cleanup();
+			reject(error);
+			return;
+		}
+		outcome.then((value) => {
+			cleanup();
+			resolve(value);
+		}, (error) => {
+			cleanup();
+			reject(error);
+		});
+	});
+}
 /**
 * Creates a `prompt()` parser wrapper for a prompt library adapter.
 *
@@ -190,13 +224,16 @@ function unwrapCompleteResult(result) {
 *
 * @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.  The configuration may be a static `TConfig` or a
+* @returns A `prompt(parser, config, options?)` wrapper that always produces
+*          an async parser.  The configuration may be a static `TConfig` or a
 *          {@link DerivedPromptConfig} whose resolver returns `TConfig`.
+* @throws {RangeError} If `maxAttempts` is not a positive integer.
 * @since 1.2.0
 */
 function createPromptAdapter(adapter) {
-	return function prompt(parser, config) {
+	return function prompt(parser, config, options = {}) {
+		if (options.maxAttempts !== void 0 && (!Number.isInteger(options.maxAttempts) || options.maxAttempts < 1)) throw new RangeError("maxAttempts must be an integer greater than or equal to 1.");
+		const { validate, maxAttempts, signal } = options;
 		const promptBindStateKey = Symbol("@optique/prompt/promptState");
 		const completionCacheKeys = /* @__PURE__ */ new Map();
 		const completionCacheSymbolIds = /* @__PURE__ */ new Map();
@@ -246,14 +283,36 @@ function createPromptAdapter(adapter) {
 				success: true,
 				value: config.otherwise
 			};
-			if (!isDerivedPromptConfig(config)) return adapter.execute(config);
-			const source = promptedParser.dependencyMetadata?.source;
-			const resolved = await resolveDerivedPromptConfig(config, exec, source?.sourceId, source?.metavar);
-			if (!resolved.ok) return {
-				success: false,
-				error: resolved.error
-			};
-			return adapter.execute(resolved.config);
+			throwIfPromptAborted(signal);
+			let resolvedConfig;
+			if (!isDerivedPromptConfig(config)) resolvedConfig = config;
+			else {
+				const source = promptedParser.dependencyMetadata?.source;
+				const resolved = await resolveDerivedPromptConfig(config, exec, source?.sourceId, source?.metavar);
+				throwIfPromptAborted(signal);
+				if (!resolved.ok) return {
+					success: false,
+					error: resolved.error
+				};
+				resolvedConfig = resolved.config;
+			}
+			let previousValidationMessage;
+			for (let attempt = 1;; attempt++) {
+				const context = {
+					attempt,
+					...previousValidationMessage === void 0 ? {} : { previousValidationMessage },
+					...signal === void 0 ? {} : { signal }
+				};
+				const result = await racePromptWorkWithAbort(signal, () => adapter.execute(resolvedConfig, context));
+				if (!result.success || validate == null) return result;
+				const validationMessage = await racePromptWorkWithAbort(signal, () => Promise.resolve(validate(result.value)));
+				if (validationMessage === void 0) return result;
+				if (maxAttempts !== void 0 && attempt >= maxAttempts) return {
+					success: false,
+					error: validationMessage
+				};
+				previousValidationMessage = validationMessage;
+			}
 		}
 		const parserInheritsAnnotations = (0, __optique_core_extension.getTraits)(parser).inheritsAnnotations === true;
 		const promptedParser = {

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { AnyDependencySource, DependencyValue, DependencyValues } from "@optique/core/dependency";
+import { Message } from "@optique/core/message";
 import { FluentParser } from "@optique/core/fluent";
 import { Mode, Parser } from "@optique/core/parser";
 import { ValueParserResult } from "@optique/core/valueparser";
@@ -23,13 +24,63 @@ type PromptCondition<TValue> = {
   readonly when: () => boolean | Promise<boolean>;
   readonly otherwise: NoInfer<TValue>;
 };
+/**
+ * Validates a value returned by a prompt adapter.
+ *
+ * Return `undefined` to accept the value, or a structured message to reject it
+ * and ask the adapter to try again.  The validator receives the prompted value
+ * directly; it is not converted back into command-line input or passed through
+ * the wrapped value parser.
+ *
+ * @typeParam TValue Value type produced by the wrapped parser.
+ * @since 1.3.0
+ */
+type PromptValidator<TValue> = (value: TValue) => Message | undefined | Promise<Message | undefined>;
+/**
+ * Shared validation, retry, and cancellation options for a prompt fallback.
+ *
+ * These options are separate from adapter-native validation fields.  They
+ * apply only when the interactive fallback runs; CLI values, source-bound
+ * values, and skipped runtime conditions do not consult them.
+ *
+ * @typeParam TValue Value type produced by the wrapped parser.
+ * @since 1.3.0
+ */
+interface PromptOptions<TValue> {
+  /** Validator applied to each value returned by the adapter. */
+  readonly validate?: PromptValidator<TValue>;
+  /**
+   * Maximum number of adapter executions in one completion.  Must be a
+   * positive integer.  When omitted, validation may retry without a limit.
+   */
+  readonly maxAttempts?: number;
+  /**
+   * Signal that stops the active adapter execution or validator.  Its reason
+   * is propagated to the caller without becoming a parse failure.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Context passed to one execution of a prompt adapter.
+ *
+ * @since 1.3.0
+ */
+interface PromptExecutionContext {
+  /** One-based number of the current adapter execution. */
+  readonly attempt: number;
+  /** Message returned by the validator after the preceding execution. */
+  readonly previousValidationMessage?: Message;
+  /** Signal supplied through the prompt's shared options, when present. */
+  readonly signal?: AbortSignal;
+}
 /**
  * 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*.
+ * usage metadata, validation retries, and abort handling, is handled by
+ * *@optique/prompt*.
  *
  * @typeParam TConfig Prompt configuration accepted by the adapter.
  * @since 1.2.0
@@ -41,10 +92,12 @@ interface PromptAdapter<TConfig> {
    * @typeParam TValue Value type produced by the wrapped parser.
    * @param config Prompt configuration supplied to the generated `prompt()`
    *               wrapper.
+   * @param context Attempt number, preceding validation message, and optional
+   *                abort signal for this execution.
    * @returns The prompted value or a prompt failure.
    * @throws Any unexpected prompt execution failure.
    */
-  readonly execute: <TValue>(config: TConfig) => Promise<ValueParserResult<TValue>>;
+  readonly execute: <TValue>(config: TConfig, context: PromptExecutionContext) => Promise<ValueParserResult<TValue>>;
   /**
    * Returns a default value from the prompt config for documentation purposes.
    *
@@ -238,11 +291,12 @@ type PromptConfigInput<TConfig, TValue> = (TConfig & PromptCondition<TValue>) |
  *
  * @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.  The configuration may be a static `TConfig` or a
+ * @returns A `prompt(parser, config, options?)` wrapper that always produces
+ *          an async parser.  The configuration may be a static `TConfig` or a
  *          {@link DerivedPromptConfig} whose resolver returns `TConfig`.
+ * @throws {RangeError} If `maxAttempts` is not a positive integer.
  * @since 1.2.0
  */
-declare function createPromptAdapter<TConfig>(adapter: PromptAdapter<TConfig>): <M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: PromptConfigInput<TConfig, TValue>) => FluentParser<"async", TValue, TState>;
+declare function createPromptAdapter<TConfig>(adapter: PromptAdapter<TConfig>): <M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: PromptConfigInput<TConfig, TValue>, options?: PromptOptions<NoInfer<TValue>>) => FluentParser<"async", TValue, TState>;
 //#endregion
-export { DerivePromptConfigContext, DerivePromptConfigOptions, DerivePromptConfigsContext, DerivePromptConfigsOptions, DerivedPromptConfig, PromptAdapter, PromptCondition, PromptConfigInput, createPromptAdapter, derivePromptConfig, isDerivedPromptConfig };
+export { DerivePromptConfigContext, DerivePromptConfigOptions, DerivePromptConfigsContext, DerivePromptConfigsOptions, DerivedPromptConfig, PromptAdapter, PromptCondition, PromptConfigInput, PromptExecutionContext, PromptOptions, PromptValidator, createPromptAdapter, derivePromptConfig, isDerivedPromptConfig };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { AnyDependencySource, DependencyValue, DependencyValues } from "@optique/core/dependency";
+import { Message } from "@optique/core/message";
 import { FluentParser } from "@optique/core/fluent";
 import { Mode, Parser } from "@optique/core/parser";
 import { ValueParserResult } from "@optique/core/valueparser";
@@ -23,13 +24,63 @@ type PromptCondition<TValue> = {
   readonly when: () => boolean | Promise<boolean>;
   readonly otherwise: NoInfer<TValue>;
 };
+/**
+ * Validates a value returned by a prompt adapter.
+ *
+ * Return `undefined` to accept the value, or a structured message to reject it
+ * and ask the adapter to try again.  The validator receives the prompted value
+ * directly; it is not converted back into command-line input or passed through
+ * the wrapped value parser.
+ *
+ * @typeParam TValue Value type produced by the wrapped parser.
+ * @since 1.3.0
+ */
+type PromptValidator<TValue> = (value: TValue) => Message | undefined | Promise<Message | undefined>;
+/**
+ * Shared validation, retry, and cancellation options for a prompt fallback.
+ *
+ * These options are separate from adapter-native validation fields.  They
+ * apply only when the interactive fallback runs; CLI values, source-bound
+ * values, and skipped runtime conditions do not consult them.
+ *
+ * @typeParam TValue Value type produced by the wrapped parser.
+ * @since 1.3.0
+ */
+interface PromptOptions<TValue> {
+  /** Validator applied to each value returned by the adapter. */
+  readonly validate?: PromptValidator<TValue>;
+  /**
+   * Maximum number of adapter executions in one completion.  Must be a
+   * positive integer.  When omitted, validation may retry without a limit.
+   */
+  readonly maxAttempts?: number;
+  /**
+   * Signal that stops the active adapter execution or validator.  Its reason
+   * is propagated to the caller without becoming a parse failure.
+   */
+  readonly signal?: AbortSignal;
+}
+/**
+ * Context passed to one execution of a prompt adapter.
+ *
+ * @since 1.3.0
+ */
+interface PromptExecutionContext {
+  /** One-based number of the current adapter execution. */
+  readonly attempt: number;
+  /** Message returned by the validator after the preceding execution. */
+  readonly previousValidationMessage?: Message;
+  /** Signal supplied through the prompt's shared options, when present. */
+  readonly signal?: AbortSignal;
+}
 /**
  * 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*.
+ * usage metadata, validation retries, and abort handling, is handled by
+ * *@optique/prompt*.
  *
  * @typeParam TConfig Prompt configuration accepted by the adapter.
  * @since 1.2.0
@@ -41,10 +92,12 @@ interface PromptAdapter<TConfig> {
    * @typeParam TValue Value type produced by the wrapped parser.
    * @param config Prompt configuration supplied to the generated `prompt()`
    *               wrapper.
+   * @param context Attempt number, preceding validation message, and optional
+   *                abort signal for this execution.
    * @returns The prompted value or a prompt failure.
    * @throws Any unexpected prompt execution failure.
    */
-  readonly execute: <TValue>(config: TConfig) => Promise<ValueParserResult<TValue>>;
+  readonly execute: <TValue>(config: TConfig, context: PromptExecutionContext) => Promise<ValueParserResult<TValue>>;
   /**
    * Returns a default value from the prompt config for documentation purposes.
    *
@@ -238,11 +291,12 @@ type PromptConfigInput<TConfig, TValue> = (TConfig & PromptCondition<TValue>) |
  *
  * @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.  The configuration may be a static `TConfig` or a
+ * @returns A `prompt(parser, config, options?)` wrapper that always produces
+ *          an async parser.  The configuration may be a static `TConfig` or a
  *          {@link DerivedPromptConfig} whose resolver returns `TConfig`.
+ * @throws {RangeError} If `maxAttempts` is not a positive integer.
  * @since 1.2.0
  */
-declare function createPromptAdapter<TConfig>(adapter: PromptAdapter<TConfig>): <M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: PromptConfigInput<TConfig, TValue>) => FluentParser<"async", TValue, TState>;
+declare function createPromptAdapter<TConfig>(adapter: PromptAdapter<TConfig>): <M extends Mode, TValue, TState>(parser: Parser<M, TValue, TState>, config: PromptConfigInput<TConfig, TValue>, options?: PromptOptions<NoInfer<TValue>>) => FluentParser<"async", TValue, TState>;
 //#endregion
-export { DerivePromptConfigContext, DerivePromptConfigOptions, DerivePromptConfigsContext, DerivePromptConfigsOptions, DerivedPromptConfig, PromptAdapter, PromptCondition, PromptConfigInput, createPromptAdapter, derivePromptConfig, isDerivedPromptConfig };
+export { DerivePromptConfigContext, DerivePromptConfigOptions, DerivePromptConfigsContext, DerivePromptConfigsOptions, DerivedPromptConfig, PromptAdapter, PromptCondition, PromptConfigInput, PromptExecutionContext, PromptOptions, PromptValidator, createPromptAdapter, derivePromptConfig, isDerivedPromptConfig };

package/dist/index.js

@@ -156,6 +156,40 @@ function unwrapCompleteResult(result) {
 		value: unwrapInjectedAnnotationState(result.value)
 	};
 }
+function throwIfPromptAborted(signal) {
+	if (signal?.aborted === true) throw signal.reason;
+}
+function racePromptWorkWithAbort(signal, work) {
+	if (signal == null) try {
+		return work();
+	} catch (error) {
+		return Promise.reject(error);
+	}
+	if (signal.aborted) return Promise.reject(signal.reason);
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			signal.removeEventListener("abort", onAbort);
+			reject(signal.reason);
+		};
+		const cleanup = () => signal.removeEventListener("abort", onAbort);
+		signal.addEventListener("abort", onAbort, { once: true });
+		let outcome;
+		try {
+			outcome = work();
+		} catch (error) {
+			cleanup();
+			reject(error);
+			return;
+		}
+		outcome.then((value) => {
+			cleanup();
+			resolve(value);
+		}, (error) => {
+			cleanup();
+			reject(error);
+		});
+	});
+}
 /**
 * Creates a `prompt()` parser wrapper for a prompt library adapter.
 *
@@ -167,13 +201,16 @@ function unwrapCompleteResult(result) {
 *
 * @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.  The configuration may be a static `TConfig` or a
+* @returns A `prompt(parser, config, options?)` wrapper that always produces
+*          an async parser.  The configuration may be a static `TConfig` or a
 *          {@link DerivedPromptConfig} whose resolver returns `TConfig`.
+* @throws {RangeError} If `maxAttempts` is not a positive integer.
 * @since 1.2.0
 */
 function createPromptAdapter(adapter) {
-	return function prompt(parser, config) {
+	return function prompt(parser, config, options = {}) {
+		if (options.maxAttempts !== void 0 && (!Number.isInteger(options.maxAttempts) || options.maxAttempts < 1)) throw new RangeError("maxAttempts must be an integer greater than or equal to 1.");
+		const { validate, maxAttempts, signal } = options;
 		const promptBindStateKey = Symbol("@optique/prompt/promptState");
 		const completionCacheKeys = /* @__PURE__ */ new Map();
 		const completionCacheSymbolIds = /* @__PURE__ */ new Map();
@@ -223,14 +260,36 @@ function createPromptAdapter(adapter) {
 				success: true,
 				value: config.otherwise
 			};
-			if (!isDerivedPromptConfig(config)) return adapter.execute(config);
-			const source = promptedParser.dependencyMetadata?.source;
-			const resolved = await resolveDerivedPromptConfig(config, exec, source?.sourceId, source?.metavar);
-			if (!resolved.ok) return {
-				success: false,
-				error: resolved.error
-			};
-			return adapter.execute(resolved.config);
+			throwIfPromptAborted(signal);
+			let resolvedConfig;
+			if (!isDerivedPromptConfig(config)) resolvedConfig = config;
+			else {
+				const source = promptedParser.dependencyMetadata?.source;
+				const resolved = await resolveDerivedPromptConfig(config, exec, source?.sourceId, source?.metavar);
+				throwIfPromptAborted(signal);
+				if (!resolved.ok) return {
+					success: false,
+					error: resolved.error
+				};
+				resolvedConfig = resolved.config;
+			}
+			let previousValidationMessage;
+			for (let attempt = 1;; attempt++) {
+				const context = {
+					attempt,
+					...previousValidationMessage === void 0 ? {} : { previousValidationMessage },
+					...signal === void 0 ? {} : { signal }
+				};
+				const result = await racePromptWorkWithAbort(signal, () => adapter.execute(resolvedConfig, context));
+				if (!result.success || validate == null) return result;
+				const validationMessage = await racePromptWorkWithAbort(signal, () => Promise.resolve(validate(result.value)));
+				if (validationMessage === void 0) return result;
+				if (maxAttempts !== void 0 && attempt >= maxAttempts) return {
+					success: false,
+					error: validationMessage
+				};
+				previousValidationMessage = validationMessage;
+			}
 		}
 		const parserInheritsAnnotations = getTraits(parser).inheritsAnnotations === true;
 		const promptedParser = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optique/prompt",
-  "version": "1.3.0-dev.2456",
+  "version": "1.3.0-dev.2464",
   "description": "Generic prompt adapter support for Optique",
   "keywords": [
     "CLI",
@@ -60,12 +60,12 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@optique/core": "1.3.0-dev.2456+d939eb0a"
+    "@optique/core": "1.3.0-dev.2464+e4795e6e"
   },
   "devDependencies": {
-    "@optique/config": "1.3.0-dev.2456+d939eb0a",
-    "@optique/env": "1.3.0-dev.2456+d939eb0a",
-    "@optique/run": "1.3.0-dev.2456+d939eb0a",
+    "@optique/config": "1.3.0-dev.2464+e4795e6e",
+    "@optique/env": "1.3.0-dev.2464+e4795e6e",
+    "@optique/run": "1.3.0-dev.2464+e4795e6e",
     "@types/node": "^24.0.0",
     "fast-check": "^4.7.0",
     "tsdown": "^0.13.0",